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

任务清单：Gin 到 Echo 迁移

• 1. 配置文件 (无代码依赖)

  • 修改 config.yml 中 mode 配置项的注释，将 "Gin 运行模式" 改为 "服务运行模式"。
  • 修改 config.example.yml 中 mode 配置项的注释，保持与 config.yml 一致。

• 2. 控制器辅助函数 (最基础的依赖)

  • internal/app/controller/response.go
    • 将 *gin.Context 参数全部替换为 echo.Context。
    • 修改 SendResponse 和 SendErrorResponse 等函数，使其不再直接写入响应，而是返回 error，并在内部调用 c.JSON(...)。
  • internal/app/controller/auth_utils.go
    • 将 *gin.Context 参数全部替换为 echo.Context。
    • 适配 Get...FromContext 系列函数，使用 c.Get("key") 提取数据。

• 3. 中间件 (internal/app/middleware)

  • auth.go
    • 将 import "github.com/gin-gonic/gin" 替换为 import "github.com/labstack/echo/v4"。
    • 将中间件函数签名从 func AuthMiddleware(...) gin.HandlerFunc 更新为 func AuthMiddleware(...) echo.MiddlewareFunc。
    • 适配中间件内部逻辑，将 func(c *gin.Context) 改造为 func(next echo.HandlerFunc) echo.HandlerFunc { return func(c echo.Context) error { ... } } 的结构。
    • 将 c.AbortWithStatusJSON(...) 调用替换为 return controller.SendErrorResponse(...)。
    • 在逻辑正常通过的末尾，调用 return next(c)。
  • audit.go
    • 将 import "github.com/gin-gonic/gin" 替换为 import "github.com/labstack/echo/v4"。
    • 将中间件函数签名从 func AuditMiddleware(...) gin.HandlerFunc 更新为 func AuditMiddleware(...) echo.MiddlewareFunc。
    • 适配中间件内部逻辑，将 func(c *gin.Context) 改造为 func(next echo.HandlerFunc) echo.HandlerFunc { return func(c echo.Context) error { ... } } 的结构。
    • 在调用 next(c) 之前和之后，使用 c.Get(...) 来获取和处理审计信息。
    • 在逻辑正常通过的末尾，调用 return next(c)。

• 4. 控制器 (internal/app/controller/...)

  • 通用修改：对所有控制器文件执行以下操作：
    • 将 import "github.com/gin-gonic/gin" 替换为 import "github.com/labstack/echo/v4"。
    • 将所有处理函数签名从 func(c *gin.Context) 修改为 func(c echo.Context) error。
    • 将 c.ShouldBindJSON(&req) 或 c.ShouldBindQuery(&req) 替换为 if err := c.Bind(&req); err != nil { ... }。
    • 将 c.Param("id") 替换为 c.Param("id") (用法相同，检查返回值即可)。
    • 将 controller.SendResponse(c, ...) 和 controller.SendErrorResponse(c, ...) 调用修改为 return controller.SendResponse(c, ...) 和 return controller.SendErrorResponse(c, ...)。
  • 文件清单 (按依赖顺序建议):
    • internal/app/controller/management/controller_helpers.go
    • internal/app/controller/device/device_controller.go
    • internal/app/controller/management/pig_farm_controller.go
    • internal/app/controller/management/pig_batch_controller.go
    • internal/app/controller/management/pig_batch_health_controller.go
    • internal/app/controller/management/pig_batch_trade_controller.go
    • internal/app/controller/management/pig_batch_transfer_controller.go
    • internal/app/controller/monitor/monitor_controller.go
    • internal/app/controller/plan/plan_controller.go
    • internal/app/controller/user/user_controller.go

• 5. 核心 API 层 (internal/app/api)

  • router.go
    • 将所有 router.GET, router.POST 等 Gin 路由注册方法替换为 Echo 的 e.GET, e.POST 等方法。
    • 将 Swagger 路由 router.GET("/swagger/*", ginSwagger.WrapHandler(swaggerFiles.Handler)) 替换为 e.GET("/swagger/*", echoSwagger.WrapHandler)。
    • 将 pprof 路由的 gin.WrapH 和 gin.WrapF 调用替换为 echo.WrapHandler 和 echo.WrapFunc。
  • api.go
    • 将 engine *gin.Engine 替换为 engine *echo.Echo。
    • 更新 NewAPI 函数：
      • 将 gin.SetMode(cfg.Mode) 替换为 e.Debug = (cfg.Mode == "debug")。
      • 将 gin.New() 替换为 echo.New()。
      • 将 engine.Use(gin.Recovery()) 替换为 e.Use(middleware.Recover())。

• 6. 依赖管理

  • 在 go.mod 中移除 github.com/gin-gonic/gin。
  • 在 go.mod 中移除 github.com/swaggo/gin-swagger。
  • 在 go.mod 中添加 github.com/labstack/echo/v4。
  • 在 go.mod 中添加 github.com/swaggo/echo-swagger。
  • 执行 go mod tidy 清理依赖项。

• 7. 验证

  • 运行 go build ./... 确保项目能够成功编译。
  • 启动服务，手动测试所有 API 端点，验证功能是否与迁移前一致。
  • 访问 /swagger/index.html，确认 Swagger UI 是否正常工作。
  • (可选) 访问 /debug/pprof/，确认 pprof 路由是否正常。