pig-farm-controller/openspec/changes/refactor-migrate-gin-to-echo/design.md

Context

当前 API 服务基于 Gin 构建。本次任务的目标是将其完整迁移到 Echo 框架，同时保持功能和接口的完全向后兼容。这包括路由、请求处理、中间件、Swagger 文档和 pprof 分析工具。

Goals / Non-Goals

• Goals:
  • 成功将 Web 框架从 Gin 迁移到 Echo v4。
  • 保持所有现有 API 端点的路径、方法和行为不变。
  • 确保所有自定义中间件（认证、审计日志）功能正常。
  • 确保 Swagger UI 可以在 /swagger/index.html 正常访问。
  • 确保 pprof 调试端点在 /debug/pprof/* 路径下正常工作。
• Non-Goals:
  • 增加任何新的 API 端点或功能。
  • 修改任何现有的 API 请求/响应模型。
  • 在本次变更中引入新的业务逻辑。

Decisions

以下是从 Gin 到 Echo 的关键组件映射决策：

1. 框架实例:

   • From: gin.SetMode(cfg.Mode), engine := gin.New(), engine.Use(gin.Recovery())
   • To: e := echo.New(), e.Debug = (cfg.Mode == "debug"), e.Use(middleware.Recover())
   • Rationale: echo.New() 提供了干净的实例。Echo 的 Debug 属性控制调试模式，可以根据配置设置。Echo 提供了内置的 middleware.Recover() 来替代 Gin 的 Recovery 中间件。
   • Implementation:
     • 在 internal/app/api/api.go 中，将 engine *gin.Engine 替换为 engine *echo.Echo，并更新 NewAPI 方法中的初始化逻辑。
     • 在 config.yml 和 config.example.yml 中, 更新关于 mode 配置项的注释, 将 "Gin 运行模式" 修改为 "服务运行模式", 因为该配置项现在控制 Echo 的调试模式。

2. 上下文对象 (Context) 与处理器签名:

   • From: func(c *gin.Context)
   • To: func(c echo.Context) error
   • Rationale: 这是两个框架的核心区别。所有控制器处理函数签名都需要更新。常见方法映射如下：
     • ctx.ShouldBindJSON(&req) -> c.Bind(&req) (Echo 的 Bind 更通用，能根据 Content-Type 自动选择解析器)
     • ctx.ShouldBindQuery(&req) -> c.Bind(&req)
     • ctx.Param("id") -> c.Param("id") (签名相同)
     • ctx.GetHeader("Authorization") -> c.Request().Header.Get("Authorization")
     • ctx.Set("key", value) -> c.Set("key", value) (签名相同)
     • ctx.Get("key") -> c.Get("key") (签名相同)
     • ctx.ClientIP() -> c.RealIP()
     • controller.SendResponse(ctx, ...) -> return controller.SendResponse(c, ...) (控制器方法需要返回 error，辅助函数也需要修改以返回 error)
     • controller.SendErrorResponse(ctx, ...) -> return controller.SendErrorResponse(c, ...) (同上)
     • ctx.AbortWithStatusJSON(...) -> return c.JSON(...) (在中间件中，通过 return c.JSON(...) 来中断链并响应)

3. 中间件 (Middleware):

   • From: func AuthMiddleware(...) gin.HandlerFunc { return func(c *gin.Context) { ... } }
   • To: func AuthMiddleware(...) echo.MiddlewareFunc { return func(next echo.HandlerFunc) echo.HandlerFunc { return func(c echo.Context) error { ...; return next(c) } } }
   • Rationale: Echo 的中间件是一个包装器模式。我们需要将现有的 AuthMiddleware 和 AuditLogMiddleware 逻辑迁移到这个新的结构中。中断请求链的方式从 c.AbortWithStatusJSON() 变为从处理函数中 return c.JSON(...)。

4. Swagger 集成:

   • From: github.com/swaggo/gin-swagger
   • To: github.com/swaggo/echo-swagger
   • Rationale: 这是 swaggo 官方为 Echo 提供的适配库，可以无缝替换。
   • Implementation: 在 router.go 中使用 e.GET("/swagger/*", echoSwagger.WrapHandler)。

5. Pprof 与其他 net/http 处理器集成:

   • From: gin.WrapH 和 gin.WrapF
   • To: echo.WrapHandler 和 echo.WrapFunc
   • Rationale: Echo 提供了类似的 net/http 处理器包装函数，可以轻松集成 pprof 和项目中的 listenHandler。
   • Implementation: 在 router.go 中替换所有 gin.WrapH 和 gin.WrapF 的调用。

6. 控制器辅助函数:

   • Affected Files:
     • internal/app/controller/response.go
     • internal/app/controller/auth_utils.go
     • internal/app/controller/management/controller_helpers.go
   • Change:
     • 在 response.go 和 auth_utils.go 中, 所有接收 *gin.Context 的辅助函数 (如 SendResponse, GetOperatorIDFromContext 等) 签名都需要修改为接收 echo.Context。
     • 在 controller_helpers.go 中, handle... 系列的泛型辅助函数 (如 handleAPIRequest, handleNoBodyAPIRequest 等) 及其依赖的 extractOperatorAndPrimaryID 和 mapAndSendError 函数, 都需要将其中的 *gin.Context 参数和相关调用 (如 ShouldBindJSON) 替换为 echo.Context 的等效实现。
     • 所有这些辅助函数, 如果它们原本不返回 error, 现在需要修改为返回 error, 以便与 Echo 的处理器错误链兼容。例如, SendResponse 这类函数在调用 c.JSON(...) 后, 最终应 return nil。
   • Rationale: 这些辅助函数封装了请求处理、响应发送和错误处理的核心逻辑, 必须进行适配以兼容 Echo 的 echo.Context 上下文对象和 return error 的错误处理模式。

Risks / Trade-offs

• Risk: 迁移工作量大，可能遗漏某些 Gin 特有的功能或上下文用法，导致运行时错误。
• Mitigation: 采用逐个文件、逐个控制器修改的方式，每修改完一部分就进行编译检查。在完成所有编码后，进行全面的手动 API 测试。
• Risk: AuditLogMiddleware 中间件依赖 bodyLogWriter 捕获响应体，需要验证其与 Echo 的 ResponseWriter 是否兼容或需要寻找替代方案。
• Mitigation: 在迁移中间件时，优先研究 Echo 官方推荐的 Body Dump 或类似中间件，如果不适用，再尝试适配 bodyLogWriter。