Liquibase数据库变更治理工程 - 第2节

2. Gin框架核心回顾

Gin 的路由引擎基于压缩前缀树（Radix Tree / Trie）实现，具备极高的路由匹配性能。路由注册、分组、中间件挂载均围绕 gin.Engine 展开。

2.1.1 路由引擎核心结构

2.1.2 中间件链执行模型

Gin 的中间件链采用“洋葱模型”（Onion Model）。请求进入时按注册顺序依次执行前置逻辑，到达末端处理器后，再逆序执行后置逻辑。每个中间件通过调用 c.Next() 将控制权交给下一个中间件。

// 全局中间件
r.Use(gin.Logger(), gin.Recovery())

// 分组中间件
api := r.Group("/api", AuthMiddleware())
{
    api.GET("/users", GetUsers)          // 继承 AuthMiddleware
    api.POST("/users", CreateUser)
}

// 路由级中间件
r.GET("/health", RateLimitMiddleware(), HealthCheck)

2.2 请求上下文 (Context) 深度解析

gin.Context 是 Gin 框架最核心的抽象，承载一次 HTTP 请求的完整生命周期。它封装了请求解析、参数获取、响应输出、数据传递、错误处理等全部能力。

2.2.1 Context 核心能力矩阵

2.2.2 上下文数据传递模式

在微服务边车模式中，Context 的 Set/Get 机制常用于传递链路追踪 ID、用户身份、请求来源等元数据，避免污染函数签名。

// 中间件：注入追踪 ID
func TraceMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        traceID := c.GetHeader("X-Trace-ID")
        if traceID == "" {
            traceID = uuid.New().String()
        }
        c.Set("trace_id", traceID)
        c.Header("X-Trace-ID", traceID)
        c.Next()
    }
}

// 处理器：读取追踪 ID
func GetUserHandler(c *gin.Context) {
    traceID, _ := c.Get("trace_id")
    userID := c.Param("id")

    // 业务逻辑...
    c.JSON(200, gin.H{
        "trace_id": traceID,
        "user_id":  userID,
    })
}

2.3 Gin 项目标准目录结构设计

合理的目录结构是微服务项目可维护性的基石。以下结构经过生产环境验证，兼顾分层清晰、依赖倒置和边车模式适配。

my-gin-service/
├── cmd/
│   └── server/
│       └── main.go              # 应用入口，初始化 Engine 并启动
├── internal/
│   ├── handler/                 # HTTP 处理器层（Controller）
│   │   ├── user_handler.go
│   │   └── health_handler.go
│   ├── service/                 # 业务逻辑层
│   │   ├── user_service.go
│   │   └── user_service_test.go
│   ├── repository/              # 数据访问层（DAO）
│   │   ├── user_repo.go
│   │   └── mysql/
│   ├── middleware/              # 自定义中间件
│   │   ├── auth.go
│   │   ├── trace.go
│   │   └── ratelimit.go
│   ├── model/                   # 数据模型 / DTO
│   │   ├── user.go
│   │   └── response.go
│   ├── router/                  # 路由注册与分组
│   │   └── router.go
│   └── config/                  # 配置加载与结构体
│       ├── config.go
│       └── config.yaml
├── pkg/                         # 可复用的工具包
│   ├── logger/
│   ├── validator/
│   └── response/
├── api/                         # API 定义（proto / swagger）
│   └── swagger/
├── deployments/                 # 部署配置（Docker / K8s / Sidecar）
│   ├── Dockerfile
│   └── sidecar/
├── go.mod
└── go.sum

2.3.1 各层职责与依赖方向

2.3.2 目录设计原则

• 按职责分层，不按模块分层： 所有用户相关的 handler 放在 internal/handler，而非 internal/user/handler。模块内聚通过包内文件组织实现。
• 依赖倒置： handler 依赖 service 接口，service 依赖 repository 接口。具体实现通过依赖注入（如 wire 或手动构造）注入。
• 内部 vs 外部： internal/ 目录禁止被外部包导入，确保项目边界；pkg/ 目录存放可被外部复用的工具库。
• 配置外置： internal/config 从环境变量或配置文件加载配置，不硬编码任何环境特定值。