openspec归档

openspec/changes/archive/2025-10-30-refactor-migrate-gin-to-echo/design.md

@@ -0,0 +1,81 @@
+## 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 中间件。
+
+2.  **上下文对象 (Context) 与处理器签名**:
+    - **From**: `func(c *gin.Context)`
+    - **To**: `func(c echo.Context) error`
+    - **Rationale**: 这是两个框架的核心区别。所有控制器处理函数签名都需要更新。常见方法映射如下：
+        - `ctx.ShouldBindJSON(&req)` -> `c.Bind(&req)` (Echo 的 `Bind` 更通用)
+        - `ctx.Param("id")` -> `c.Param("id")`
+        - `ctx.GetHeader("Authorization")` -> `c.Request().Header.Get("Authorization")`
+        - `ctx.Set/Get("key", value)` -> `c.Set/Get("key")`
+        - `ctx.ClientIP()` -> `c.RealIP()`
+        - `controller.SendResponse(ctx, ...)` -> `return controller.SendResponse(c, ...)`
+        - `ctx.AbortWithStatusJSON(...)` -> 对于需要返回特定HTTP状态码的场景（如认证中间件），将使用一个专门的辅助函数 `return controller.SendErrorWithStatus(c, http.StatusUnauthorized, ...)`。
+
+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` 逻辑迁移到这个新的结构中。
+
+4.  **Swagger 集成**:
+    - **From**: `github.com/swaggo/gin-swagger`
+    - **To**: `github.com/swaggo/echo-swagger`
+    - **Rationale**: 这是 `swaggo` 官方为 Echo 提供的适配库，可以无缝替换。
+
+5.  **Pprof 与其他 `net/http` 处理器集成**:
+    - **From**: `gin.WrapH` 和 `gin.WrapF`
+    - **To**: `echo.WrapHandler` 和 `echo.WrapFunc`
+    - **Rationale**: Echo 提供了类似的 `net/http` 处理器包装函数。
+
+6.  **控制器辅助函数与审计逻辑重构**:
+    - **Affected Files**: `response.go`, `auth_utils.go`, `controller_helpers.go`
+    - **Change**:
+        - 所有辅助函数中的 `*gin.Context` 都将替换为 `echo.Context`。
+        - **`response.go` 将被重构**：`setAuditDetails` 函数将成为设置所有审计信息（包括操作状态和失败详情）的唯一入口。`SendSuccessWithAudit` 和 `SendErrorWithAudit` 会调用它来将最终结果存入 `echo.Context`。
+        - `controller_helpers.go` 中的泛型辅助函数将修改为返回 `error`，以适配 Echo 的错误处理链。
+    - **Rationale**: 这种重构使得审计逻辑更加清晰和内聚，避免了在中间件中进行复杂的响应体捕获。
+
+7.  **DTO 注解 (Annotations)**:
+    - **From**: Gin 相关的注解，主要包括 `binding:"..."` 和 `form:"..."`。
+    - **To**: Echo 兼容的注解，主要包括 `validate:"..."` 和 `query:"..."`。
+    - **Rationale**: Gin 使用 `binding` 标签进行请求参数绑定和验证，`form` 标签用于表单或查询参数绑定。Echo 框架通常结合 `go-playground/validator` 库进行验证，其对应的标签为 `validate`。对于查询参数，Echo 默认使用 `query` 标签。
+    - **通用修改规则**：
+        - `json:"..."` 标签保持不变。
+        - `example:"..."` 标签保持不变。
+        - 将 `binding:"required"` 替换为 `validate:"required"`。
+        - 将 `form:"field,default=value"` 替换为 `query:"field"`。`default` 行为需在代码中手动实现（如在 DTO 构造函数中设置默认值），标签中不再需要。
+        - 将 `form:"field"` 替换为 `query:"field"`。
+        - 对于 `json:"...,omitempty"` 的字段，在 `validate` 标签中也添加 `omitempty`。
+        - 对于结构体切片或数组字段，在 `validate` 标签中添加 `dive` 以递归验证切片元素。
+        - 根据字段的业务含义，添加更具体的 `validate` 规则（例如 `min=0`, `cron` 等）。
+
+## Risks / Trade-offs
+
+- **Risk**: 迁移工作量大，可能遗漏某些 Gin 特有的功能或上下文用法，导致运行时错误。
+- **Mitigation**: 采用逐个文件、逐个控制器修改的方式，每修改完一部分就进行编译检查。在完成所有编码后，进行全面的手动 API 测试。
+- **Risk (Resolved)**: `AuditLogMiddleware` 中间件最初的设计依赖于捕获响应体，这在 Echo 中难以实现。
+- **Resolution**: 我们通过重构 `response.go` 解决了这个问题。现在，控制器在调用响应函数时，会将最终的操作状态（成功/失败）和结果详情直接存入 `echo.Context`。`AuditLogMiddleware` 只需从上下文中读取这些信息即可，**完全消除了捕获和解析响应体的需要**，使得设计更加清晰和高效。