KO
|
EN
gitlite โ search
Search
#python
#cli
#html
#reactjs
#rust
#react
#mysql
#php
#tailwindcss
#android
#golang
#cryptography
go-gin-example
โ 7,197
Open GitHub โ
An example of gin
Download README (.md)
Explore Similar Repositories
python-machine-learning-book-2nd-edition
:
The "Python Machine Learning (2nd edition)" book code repository and info resource
openevolve
:
Open-source implementation of AlphaEvolve
sd-scripts
:
No description available.
colyseus
:
โ Multiplayer Framework for Node.js
pull
:
๐ค Keep your forks up-to-date via automated PRs
// repository documentation
Was this content helpful?
โ 0
(0 ratings)
Select Rating:
โ
โ
โ
โ
โ
Submit Feedback
Recent Feedback
×
Download README
Do you want to download the
README.md
file for
go-gin-example
?
Download (.md)
# Go Gin Example - Blog API[](https://goreportcard.com/report/github.com/EDDYCJY/go-gin-example) [](https://godoc.org/github.com/EDDYCJY/go-gin-example) [](https://raw.githubusercontent.com/EDDYCJY/go-gin-example/master/LICENSE) A production-ready RESTful blog API example built with Go and Gin framework, demonstrating real-world patterns and best practices. [็ฎไฝไธญๆ](https://github.com/EDDYCJY/go-gin-example/blob/master/README_ZH.md) ## 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](https://github.com/gin-gonic/gin) | | ORM | [GORM](https://github.com/jinzhu/gorm) | | Database | MySQL | | Cache | Redis (via [Redigo](https://github.com/gomodule/redigo)) | | Authentication | JWT ([jwt-go](https://github.com/dgrijalva/jwt-go)) | | Configuration | [go-ini](https://github.com/go-ini/ini) | | API Documentation | [Swagger](https://github.com/swaggo/gin-swagger) | | Excel Processing | [excelize](https://github.com/360EntSecGroup-Skylar/excelize), [xlsx](https://github.com/tealeg/xlsx) | | Image Processing | [freetype](https://github.com/golang/freetype), [barcode](https://github.com/boombuler/barcode) | | Validation | [beego/validation](https://github.com/astaxie/beego/validation) | ## Project Structure ``` go-gin-example/ โโโ conf/ # Configuration files โ โโโ app.ini # Application configuration โโโ docs/ # Documentation โ โโโ sql/ # Database scripts โ โ โโโ blog.sql # Database schema โ โโโ swagger/ # Swagger documentation โโโ middleware/ # Middleware โ โโโ jwt/ # JWT authentication middleware โ โโโ jwt.go โโโ models/ # Data models (ORM) โ โโโ article.go # Article model โ โโโ auth.go # Auth model โ โโโ models.go # Database initialization โ โโโ tag.go # Tag model โโโ pkg/ # Shared packages โ โโโ app/ # Application utilities โ โ โโโ form.go # Form binding โ โ โโโ request.go # Request handling โ โ โโโ response.go # Response formatting โ โโโ e/ # Error codes โ โ โโโ cache.go # Cache key constants โ โ โโโ code.go # Error code definitions โ โ โโโ msg.go # Error messages โ โโโ export/ # Excel export utilities โ โ โโโ excel.go โ โโโ file/ # File utilities โ โ โโโ file.go โ โโโ gredis/ # Redis client โ โ โโโ redis.go โ โโโ logging/ # Logging utilities โ โ โโโ file.go โ โ โโโ log.go โ โโโ qrcode/ # QR code generation โ โ โโโ qrcode.go โ โโโ setting/ # Configuration management โ โ โโโ setting.go โ โโโ upload/ # Image upload utilities โ โ โโโ image.go โ โโโ util/ # Common utilities โ โโโ jwt.go # JWT utilities โ โโโ md5.go # MD5 hashing โ โโโ pagination.go # Pagination helper โ โโโ util.go โโโ routers/ # Route definitions โ โโโ api/ # API handlers โ โ โโโ v1/ # API v1 handlers โ โ โ โโโ article.go # Article endpoints โ โ โ โโโ tag.go # Tag endpoints โ โ โโโ auth.go # Authentication endpoint โ โ โโโ upload.go # Image upload endpoint โ โโโ router.go # Route initialization โโโ runtime/ # Runtime resources โ โโโ fonts/ # Font files โ โโโ qrcode/ # QR code resources โโโ service/ # Business logic layer โ โโโ article_service/ # Article services โ โ โโโ article.go # Article CRUD operations โ โ โโโ article_poster.go # Poster generation โ โโโ auth_service/ # Auth services โ โ โโโ auth.go โ โโโ cache_service/ # Cache key generation โ โ โโโ article.go โ โ โโโ tag.go โ โโโ tag_service/ # Tag services โ โโโ tag.go โโโ Dockerfile # Docker build file โโโ Makefile # Build automation โโโ go.mod # Go module definition โโโ go.sum # Dependency checksums โโโ main.go # Application entry point ``` ## Architecture The project follows a layered architecture pattern: ``` โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ HTTP Requests โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โผ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ Middleware Layer โ โ (JWT Authentication) โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โผ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ Router Layer โ โ (routers/api/v1/*.go) โ โ - Request validation โ โ - Parameter binding โ โ - Response formatting โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โผ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ Service Layer โ โ (service/*/*.go) โ โ - Business logic โ โ - Cache management โ โ - Cross-model operations โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โผ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ Model Layer โ โ (models/*.go) โ โ - Database operations โ โ - CRUD methods โ โ - Data structures โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โผ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ Storage Layer โ โ MySQL (Primary) + Redis (Cache) โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ ``` ## Feature Tree ``` Go Gin Blog API โโโ Authentication โ โโโ JWT Login Validation โ โโโ Token Generation (3-hour expiry) โ โโโ Token Validation โ โโโ Token Refresh โโโ Article Management โ โโโ Create Article โ โโโ Read Article (with Redis caching) โ โโโ Update Article โ โโโ Delete Article (soft delete) โ โโโ List Articles (paginated) โ โโโ Count Articles โ โโโ Generate Article Poster โ โโโ Embed QR Code โ โโโ Apply Background Image โ โโโ Render Text Overlay โ โโโ Save Merged Image โโโ Tag Management โ โโโ CRUD Operations โ โ โโโ Create Tag โ โ โโโ Read Tags (paginated, cached) โ โ โโโ Update Tag โ โ โโโ Delete Tag (soft delete) โ โโโ Export Tags to Excel โ โโโ Import Tags from Excel โโโ File Upload โ โโโ Image Upload โ โโโ Format validation (.jpg, .jpeg, .png) โ โโโ Size validation (max 5MB) โ โโโ MD5-based naming โโโ API Documentation โ โโโ Swagger UI (/swagger/*any) โโโ Static File Serving โโโ Exported Excel files (/export) โโโ Uploaded images (/upload/images) โโโ Generated QR codes (/qrcode) ``` ## 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 ```sql - id: INT (PK, AUTO_INCREMENT) - username: VARCHAR(50) - password: VARCHAR(50) ``` **blog_tag** - Article tags ```sql - 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 ```sql - 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`: ```ini [app] PageSize = 10 # Pagination page size JwtSecret = 233 # JWT signing secret PrefixUrl = http://127.0.0.1:8000 RuntimeRootPath = runtime/ ImageSavePath = upload/images/ ImageMaxSize = 5 # Max image size in MB ImageAllowExts = .jpg,.jpeg,.png ExportSavePath = export/ QrCodeSavePath = qrcode/ FontSavePath = fonts/ LogSavePath = logs/ [server] RunMode = debug # debug or release HttpPort = 8000 ReadTimeout = 60 # seconds WriteTimeout = 60 # seconds [database] Type = mysql User = root Password = rootroot Host = 127.0.0.1:3306 Name = blog TablePrefix = blog_ [redis] Host = 127.0.0.1:6379 Password = MaxIdle = 30 MaxActive = 30 IdleTimeout = 200 ``` ## Getting Started ### Prerequisites - Go 1.13+ - MySQL 5.6+ - Redis ### Database Setup 1. Create a MySQL database named `blog` 2. Execute the SQL script: ```bash 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 ```bash # Build make build # Run ./go-gin-example # Or run directly go run main.go ``` The server will start at `http://localhost:8000` ### Using Docker ```bash # 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 ```bash curl -X POST http://localhost:8000/auth \ -d "username=test&password=test123" ``` Response: ```json { "code": 200, "msg": "ok", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } ``` ### 2. Create a Tag ```bash curl -X POST "http://localhost:8000/api/v1/tags?token=YOUR_TOKEN" \ -d "name=Go&created_by=admin&state=1" ``` ### 3. Get Tags List ```bash curl "http://localhost:8000/api/v1/tags?token=YOUR_TOKEN" ``` ### 4. Create an Article ```bash 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 ```bash curl -X POST http://localhost:8000/upload \ -F "image=@/path/to/image.jpg" ``` ### 6. Export Tags to Excel ```bash 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: ```json { "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 ```bash # Build make build # Run code analysis make tool # Run linter make lint # Clean build artifacts make clean ``` ## License MIT License - See [LICENSE](LICENSE) for details. ## Credits Project by [EDDYCJY](https://github.com/EDDYCJY/go-gin-example)
