go-gin-example

Go Gin Example - Blog API

A production-ready RESTful blog API example built with Go and Gin framework, demonstrating real-world patterns and best practices.

简体中文

Project Overview

This project is a comprehensive blog backend API system that provides complete article and tag management functionalities, along with features like JWT authentication, image upload, QR code generation, and Excel import/export.

Tech Stack

Category	Technology
Language	Go
Web Framework	Gin
ORM	GORM
Database	MySQL
Cache	Redis (via Redigo)
Authentication	JWT (jwt-go)
Configuration	go-ini
API Documentation	Swagger
Excel Processing	excelize, xlsx
Image Processing	freetype, barcode
Validation	beego/validation

Project Structure

…

Architecture

The project follows a layered architecture pattern:

…

Feature Tree

…

API Endpoints

Public Endpoints

Method	Endpoint	Description
POST	/auth	User authentication, returns JWT token
GET	/swagger/*any	Swagger API documentation
POST	/upload	Image upload
POST	/tags/export	Export tags to Excel
POST	/tags/import	Import tags from Excel

Protected Endpoints (Require JWT Token)

Tags

Method	Endpoint	Description
GET	/api/v1/tags	Get tag list (paginated)
POST	/api/v1/tags	Create new tag
PUT	/api/v1/tags/:id	Update tag by ID
DELETE	/api/v1/tags/:id	Delete tag by ID

Articles

Method	Endpoint	Description
GET	/api/v1/articles	Get article list (paginated)
GET	/api/v1/articles/:id	Get article by ID
POST	/api/v1/articles	Create new article
PUT	/api/v1/articles/:id	Update article by ID
DELETE	/api/v1/articles/:id	Delete article by ID
POST	/api/v1/articles/poster/generate	Generate article poster with QR code

Database Schema

Tables

blog_auth - User authentication

- id: INT (PK, AUTO_INCREMENT)
- username: VARCHAR(50)
- password: VARCHAR(50)

blog_tag - Article tags

- id: INT (PK, AUTO_INCREMENT)
- name: VARCHAR(100) - Tag name
- created_on: INT - Creation timestamp
- created_by: VARCHAR(100) - Creator
- modified_on: INT - Modification timestamp
- modified_by: VARCHAR(100) - Modifier
- deleted_on: INT - Deletion timestamp (soft delete)
- state: TINYINT - Status (0: disabled, 1: enabled)

blog_article - Articles

- id: INT (PK, AUTO_INCREMENT)
- tag_id: INT (FK) - Associated tag ID
- title: VARCHAR(100) - Article title
- desc: VARCHAR(255) - Description
- content: TEXT - Article content
- cover_image_url: VARCHAR(255) - Cover image URL
- created_on: INT - Creation timestamp
- created_by: VARCHAR(100) - Creator
- modified_on: INT - Modification timestamp
- modified_by: VARCHAR(255) - Modifier
- deleted_on: INT - Deletion timestamp (soft delete)
- state: TINYINT - Status

Configuration

Configuration is managed through conf/app.ini:

…

Getting Started

Prerequisites

• Go 1.13+
• MySQL 5.6+
• Redis

Database Setup

1. Create a MySQL database named blog
2. Execute the SQL script:

mysql -u root -p blog < docs/sql/blog.sql

Configuration

1. Edit conf/app.ini to match your environment
2. Update database credentials
3. Update Redis connection settings

Running the Application

# Build
make build

# Run
./go-gin-example

# Or run directly
go run main.go

The server will start at http://localhost:8000

Using Docker

# Build image
docker build -t go-gin-example .

# Run container
docker run -p 8000:8000 go-gin-example

API Usage Examples

1. Get Authentication Token

curl -X POST http://localhost:8000/auth \
  -d "username=test&password=test123"

Response:

{
  "code": 200,
  "msg": "ok",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

2. Create a Tag

curl -X POST "http://localhost:8000/api/v1/tags?token=YOUR_TOKEN" \
  -d "name=Go&created_by=admin&state=1"

3. Get Tags List

curl "http://localhost:8000/api/v1/tags?token=YOUR_TOKEN"

4. Create an Article

curl -X POST "http://localhost:8000/api/v1/articles?token=YOUR_TOKEN" \
  -d "tag_id=1&title=Hello Gin&desc=Introduction to Gin&content=Article content...&created_by=admin&cover_image_url=http://example.com/image.jpg&state=1"

5. Upload an Image

curl -X POST http://localhost:8000/upload \
  -F "image=@/path/to/image.jpg"

6. Export Tags to Excel

curl -X POST http://localhost:8000/tags/export

Key Design Patterns

1. Soft Delete

All models use soft delete by setting deleted_on timestamp instead of actual deletion.

2. Redis Caching

Articles and tags are cached in Redis with 1-hour TTL to reduce database load.

3. Service Layer Pattern

Business logic is separated into service layer, keeping handlers thin and focused on request/response handling.

4. Unified Response Format

All API responses follow consistent format:

{
  "code": 200,
  "msg": "ok",
  "data": {}
}

5. Custom GORM Callbacks

Custom callbacks for automatic timestamp management:

• CreatedOn set on create
• ModifiedOn updated on modifications
• DeletedOn set on soft delete

Error Codes

Code	Description
200	Success
400	Invalid parameters
500	Internal server error
10001	Tag already exists
10003	Tag not found
10011	Article not found
20001	Token validation failed
20002	Token expired
20003	Token generation error
20004	Authentication failed
30001	Image save failed
30002	Image check failed
30003	Invalid image format

Development Commands

# Build
make build

# Run code analysis
make tool

# Run linter
make lint

# Clean build artifacts
make clean

License

MIT License - See LICENSE for details.

Credits

Project by EDDYCJY