feat: OpenAPI 契约对齐与框架优化
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
主要变更： 1. OpenAPI 文档契约对齐 - 统一错误响应字段名为 msg（非 message） - 规范 envelope 响应结构（code, msg, data, timestamp） - 个人客户路由纳入文档体系（使用 Register 机制） - 新增 BuildDocHandlers() 统一管理 handler 构造 - 确保文档生成的幂等性 2. Service 层错误处理统一 - 全面替换 fmt.Errorf 为 errors.New/Wrap - 统一错误码使用规范 - Handler 层参数校验不泄露底层细节 - 新增错误码验证集成测试 3. 代码质量提升 - 删除未使用的 Task handler 和路由 - 新增代码规范检查脚本（check-service-errors.sh） - 新增注释路径一致性检查（check-comment-paths.sh） - 更新 API 文档生成指南 4. OpenSpec 归档 - 归档 openapi-contract-alignment 变更（63 tasks） - 归档 service-error-unify-core 变更 - 归档 service-error-unify-support 变更 - 归档 code-cleanup-docs-update 变更 - 归档 handler-validation-security 变更 - 同步 delta specs 到主规范文件 影响范围： - pkg/openapi: 新增 handlers.go，优化 generator.go - internal/service/*: 48 个 service 文件错误处理统一 - internal/handler/admin: 优化参数校验错误提示 - internal/routes: 个人客户路由改造，删除 task 路由 - scripts: 新增 3 个代码检查脚本 - docs: 更新 OpenAPI 文档（15750+ 行） - openspec/specs: 同步 3 个主规范文件 破坏性变更：无 向后兼容：是
This commit is contained in:
@@ -0,0 +1,21 @@
|
||||
# OpenSpec 元数据
|
||||
change_id: openapi-contract-alignment
|
||||
status: pending
|
||||
created: 2026-01-29
|
||||
estimated_hours: 4
|
||||
|
||||
# 关联的 specs
|
||||
affected_specs:
|
||||
- openapi-generation
|
||||
- personal-customer
|
||||
|
||||
# 变更类型
|
||||
type: enhancement
|
||||
|
||||
# 破坏性变更
|
||||
breaking_changes: true
|
||||
breaking_change_notes: |
|
||||
OpenAPI 文档结构变化：
|
||||
1. 错误响应字段名从 message 改为 msg
|
||||
2. 成功响应增加 envelope 包裹
|
||||
3. 需要通知 SDK 使用方重新生成 SDK
|
||||
@@ -0,0 +1,527 @@
|
||||
# OpenAPI 文档契约对齐 - 设计文档
|
||||
|
||||
## Context
|
||||
|
||||
### 当前状态
|
||||
|
||||
项目使用 `github.com/swaggest/openapi-go/openapi3` 库生成 OpenAPI 3.0.3 规范文档。文档生成通过以下机制实现：
|
||||
|
||||
1. **路由注册机制**：`internal/routes/registry.go` 中的 `Register()` 函数
|
||||
2. **文档生成器**：`pkg/openapi/generator.go` 中的 `Generator` 类
|
||||
3. **Handler 清单管理**：`cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中构造 handlers
|
||||
|
||||
### 问题现状
|
||||
|
||||
#### 问题 1：响应字段名不一致
|
||||
|
||||
**文档定义**（OpenAPI YAML）：
|
||||
```yaml
|
||||
ErrorResponse:
|
||||
properties:
|
||||
code: { type: integer }
|
||||
message: { type: string } # ❌ 错误字段名
|
||||
```
|
||||
|
||||
**真实运行时**（`pkg/response/response.go`）：
|
||||
```go
|
||||
type Response struct {
|
||||
Code int `json:"code"`
|
||||
Msg string `json:"msg"` // ✅ 实际字段名
|
||||
Data interface{} `json:"data"`
|
||||
Timestamp string `json:"timestamp"`
|
||||
}
|
||||
```
|
||||
|
||||
**影响**：
|
||||
- SDK 生成器会生成错误的字段名
|
||||
- 前端开发者按文档使用 `response.message` 会失败
|
||||
- 实际需要使用 `response.msg`
|
||||
|
||||
#### 问题 2：成功响应缺少 envelope
|
||||
|
||||
**文档定义**（当前）：
|
||||
```yaml
|
||||
/api/admin/users:
|
||||
get:
|
||||
responses:
|
||||
200:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserDTO' # ❌ 直接返回 DTO
|
||||
```
|
||||
|
||||
**真实运行时**（Handler 层使用 `response.Success`）：
|
||||
```go
|
||||
return response.Success(c, userDTO) // 实际返回：
|
||||
// {
|
||||
// "code": 0,
|
||||
// "msg": "success",
|
||||
// "data": { ...userDTO... },
|
||||
// "timestamp": "2026-01-29T10:00:00Z"
|
||||
// }
|
||||
```
|
||||
|
||||
**影响**：
|
||||
- 文档显示直接返回 UserDTO
|
||||
- 实际返回被 envelope 包裹
|
||||
- SDK 生成的模型结构错误
|
||||
|
||||
#### 问题 3：handlers 清单不完整
|
||||
|
||||
**cmd/api/docs.go** vs **cmd/gendocs/main.go** 的差异：
|
||||
|
||||
| Handler | docs.go | gendocs/main.go |
|
||||
|---------|---------|-----------------|
|
||||
| PersonalCustomer | ❌ 缺失 | ❌ 缺失 |
|
||||
| ShopPackageBatchAllocation | ❌ 缺失 | ❌ 缺失 |
|
||||
| ShopPackageBatchPricing | ❌ 缺失 | ❌ 缺失 |
|
||||
|
||||
**影响**：
|
||||
- 这些 Handler 的接口不出现在 OpenAPI 文档中
|
||||
- 文档不完整
|
||||
|
||||
#### 问题 4：个人客户路由未纳入文档
|
||||
|
||||
**当前实现**（`internal/routes/personal.go`）：
|
||||
```go
|
||||
func RegisterPersonalRoutes(app *fiber.App, handlers *bootstrap.Handlers) {
|
||||
api := app.Group("/api/c/v1")
|
||||
api.Get("/cards/:iccid", handlers.PersonalCustomer.GetCard)
|
||||
// ❌ 直接注册到 Fiber，未使用 Register(...) 机制
|
||||
}
|
||||
```
|
||||
|
||||
**影响**：
|
||||
- `/api/c/v1` 路由不经过文档生成器
|
||||
- 个人客户 API 不在 OpenAPI 文档中
|
||||
|
||||
### 现有基础设施
|
||||
|
||||
**OpenAPI 生成器架构**：
|
||||
```
|
||||
internal/routes/registry.go
|
||||
├── Register(RouteSpec) - 路由注册入口
|
||||
│ ├── 有 FileUploads → AddMultipartOperation
|
||||
│ └── 无 FileUploads → AddOperation
|
||||
│
|
||||
pkg/openapi/generator.go
|
||||
├── AddOperation - 添加普通接口
|
||||
├── AddMultipartOperation - 添加文件上传接口
|
||||
└── Save - 输出 YAML 文件
|
||||
```
|
||||
|
||||
**RouteSpec 当前字段**：
|
||||
```go
|
||||
type RouteSpec struct {
|
||||
Method string
|
||||
Path string
|
||||
Handler fiber.Handler
|
||||
Summary string
|
||||
Description string // ✅ 已有（2026-01-24 新增）
|
||||
Tags []string
|
||||
Auth bool
|
||||
Input interface{}
|
||||
Output interface{}
|
||||
FileUploads []FileUploadField
|
||||
}
|
||||
```
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
### Goals
|
||||
|
||||
1. **响应字段名对齐**：OpenAPI 文档中的错误响应使用 `msg` 字段
|
||||
2. **成功响应体现 envelope**：所有成功响应包裹在 `{code, msg, data, timestamp}` 中
|
||||
3. **补齐 handlers 清单**：补充缺失的 3 个 handlers
|
||||
4. **个人客户路由纳入文档**：改造 `/api/c/v1` 路由使用 `Register(...)` 机制
|
||||
5. **统一 handlers 构造**：创建公共函数避免重复
|
||||
|
||||
### Non-Goals
|
||||
|
||||
- ❌ 不修改 `Response` 结构体（保持 `msg` 字段名）
|
||||
- ❌ 不修改现有 Handler 实现（只改文档生成）
|
||||
- ❌ 不扩展其他 OpenAPI 字段（如 examples、deprecated）
|
||||
- ❌ 不处理 WebSocket 或 SSE 等非 REST 接口
|
||||
|
||||
## Decisions
|
||||
|
||||
### 决策 1：字段名对齐策略
|
||||
|
||||
**选择**：修改 OpenAPI 生成器，使用 `msg` 而非 `message`
|
||||
|
||||
**理由**：
|
||||
- 真实运行时的 `Response` 结构体已经使用 `msg`
|
||||
- 修改文档比修改代码影响小
|
||||
- 保持向后兼容（不破坏现有 API 响应）
|
||||
|
||||
**备选方案**：
|
||||
- 修改 `Response` 结构体为 `message` - ❌ 破坏性变更，影响所有 API
|
||||
- 同时支持两个字段 - ❌ 增加复杂度，无实际收益
|
||||
|
||||
**实现位置**：
|
||||
- `pkg/openapi/generator.go` 中定义 `ErrorResponse` schema 时使用 `msg`
|
||||
|
||||
### 决策 2：envelope 包裹实现方式
|
||||
|
||||
**选择**：在生成 OpenAPI 时动态包裹 DTO schema
|
||||
|
||||
**理由**：
|
||||
- 不修改 DTO 定义（保持简洁）
|
||||
- 在文档生成时自动包裹
|
||||
- 与真实运行时行为一致
|
||||
|
||||
**备选方案**：
|
||||
- 为每个 DTO 创建对应的 Response DTO - ❌ 代码重复，维护困难
|
||||
- 修改 Handler 返回类型 - ❌ 破坏性变更
|
||||
|
||||
**实现方式**：
|
||||
```go
|
||||
// pkg/openapi/generator.go - AddOperation
|
||||
if outputSchema != nil {
|
||||
// 包裹在 envelope 中
|
||||
responseSchema := map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"code": map[string]interface{}{"type": "integer", "example": 0},
|
||||
"msg": map[string]interface{}{"type": "string", "example": "success"},
|
||||
"data": outputSchema, // 原始 DTO
|
||||
"timestamp": map[string]interface{}{"type": "string", "format": "date-time"},
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 决策 3：handlers 清单管理
|
||||
|
||||
**选择**：创建公共函数 `pkg/openapi/handlers.go` 统一构造
|
||||
|
||||
**理由**：
|
||||
- `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中重复构造 handlers
|
||||
- 容易遗漏新增的 handler
|
||||
- 统一管理便于维护
|
||||
|
||||
**备选方案**：
|
||||
- 继续在两个文件中分别构造 - ❌ 容易不一致
|
||||
- 使用反射自动发现 handlers - ❌ 过度设计，调试困难
|
||||
|
||||
**实现方式**：
|
||||
```go
|
||||
// pkg/openapi/handlers.go
|
||||
package openapi
|
||||
|
||||
func BuildDocHandlers() *bootstrap.Handlers {
|
||||
// 所有依赖传 nil（文档生成不执行 Handler）
|
||||
return &bootstrap.Handlers{
|
||||
Account: admin.NewAccountHandler(nil, nil),
|
||||
Shop: admin.NewShopHandler(nil, nil),
|
||||
PersonalCustomer: personal.NewPersonalCustomerHandler(nil),
|
||||
ShopPackageBatchAllocation: admin.NewShopPackageBatchAllocationHandler(nil),
|
||||
ShopPackageBatchPricing: admin.NewShopPackageBatchPricingHandler(nil),
|
||||
// ... 所有其他 handlers
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 决策 4：个人客户路由注册改造
|
||||
|
||||
**选择**：修改 `RegisterPersonalRoutes` 函数签名，使用 `Register(...)`
|
||||
|
||||
**理由**：
|
||||
- 与其他路由注册方式一致（`internal/routes/admin.go`、`internal/routes/h5.go`）
|
||||
- 自动纳入 OpenAPI 文档
|
||||
- 支持完整的元数据（Summary、Tags、Auth）
|
||||
|
||||
**备选方案**：
|
||||
- 保持当前方式，单独为个人客户生成文档 - ❌ 分散管理，不统一
|
||||
- 使用 Fiber 的注释生成文档 - ❌ 项目未采用此方式
|
||||
|
||||
**函数签名变更**：
|
||||
```go
|
||||
// ❌ 修改前
|
||||
func RegisterPersonalRoutes(app *fiber.App, handlers *bootstrap.Handlers)
|
||||
|
||||
// ✅ 修改后
|
||||
func RegisterPersonalRoutes(doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers)
|
||||
```
|
||||
|
||||
### 决策 5：空 data 字段处理
|
||||
|
||||
**选择**：删除操作等无返回数据的接口，data 字段设为 `null`
|
||||
|
||||
**理由**：
|
||||
- 保持响应格式统一
|
||||
- 符合 JSON API 规范
|
||||
- 客户端可以统一解析
|
||||
|
||||
**备选方案**：
|
||||
- 不返回 data 字段 - ❌ 响应格式不一致
|
||||
- data 字段设为空对象 `{}` - ❌ 语义不清晰
|
||||
|
||||
**OpenAPI 定义**：
|
||||
```yaml
|
||||
delete:
|
||||
responses:
|
||||
200:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: { type: integer, example: 0 }
|
||||
msg: { type: string, example: "success" }
|
||||
data: { type: "null" } # 明确标记为 null
|
||||
timestamp: { type: string, format: date-time }
|
||||
```
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1：Breaking Changes
|
||||
|
||||
**风险**：OpenAPI 文档结构变化，已生成的 SDK 需要重新生成
|
||||
|
||||
**影响范围**：
|
||||
- 使用 OpenAPI 生成 SDK 的客户端（前端、移动端）
|
||||
- 直接解析 OpenAPI 文档的工具
|
||||
|
||||
**缓解措施**：
|
||||
- 在变更日志中明确说明（CHANGELOG.md）
|
||||
- 通知前端团队重新生成 SDK
|
||||
- 提供文档对比（旧版 vs 新版）
|
||||
|
||||
### 风险 2：envelope 包裹可能遗漏某些接口
|
||||
|
||||
**风险**：某些特殊接口可能不适用 envelope 包裹
|
||||
|
||||
**示例场景**：
|
||||
- 文件下载接口（返回二进制流）
|
||||
- 健康检查接口（可能只返回简单字符串）
|
||||
|
||||
**缓解措施**：
|
||||
- 在 `RouteSpec` 中添加 `SkipEnvelope` 标志（如需要）
|
||||
- 当前项目中所有 JSON API 都使用 envelope，暂不处理
|
||||
|
||||
### 风险 3：个人客户路由改造可能影响现有功能
|
||||
|
||||
**风险**：修改 `RegisterPersonalRoutes` 可能影响已部署的服务
|
||||
|
||||
**缓解措施**：
|
||||
- 保持路径和 Handler 不变（只改注册方式）
|
||||
- 集成测试验证所有个人客户 API
|
||||
- 对比改造前后的响应格式
|
||||
|
||||
### 权衡 1：文档生成时机
|
||||
|
||||
**选择**：保持现有机制（服务启动时生成 + 独立工具生成）
|
||||
|
||||
**权衡**：
|
||||
- ✅ 优势：文档始终与代码同步
|
||||
- ❌ 劣势：每次启动都重新生成（轻微性能影响）
|
||||
|
||||
**决定**：维持现状，性能影响可忽略
|
||||
|
||||
### 权衡 2：handlers 构造函数位置
|
||||
|
||||
**选择**：放在 `pkg/openapi/handlers.go`
|
||||
|
||||
**权衡**：
|
||||
- ✅ 优势：与 openapi 包内聚
|
||||
- ❌ 劣势：依赖 `internal/handler`（跨包依赖）
|
||||
|
||||
**决定**：可接受，文档生成需要知道所有 handlers
|
||||
|
||||
## 实现方案
|
||||
|
||||
### 文件变更清单
|
||||
|
||||
| 文件 | 变更类型 | 说明 |
|
||||
|------|---------|------|
|
||||
| `pkg/openapi/generator.go` | 修改 | 字段名对齐 + envelope 包裹 |
|
||||
| `pkg/openapi/handlers.go` | 新建 | 统一 handlers 构造函数 |
|
||||
| `cmd/api/docs.go` | 修改 | 使用 `BuildDocHandlers()` |
|
||||
| `cmd/gendocs/main.go` | 修改 | 使用 `BuildDocHandlers()` |
|
||||
| `internal/routes/personal.go` | 修改 | 改用 `Register(...)` 机制 |
|
||||
| `internal/routes/routes.go` | 修改 | 调整 `RegisterPersonalRoutes` 调用 |
|
||||
|
||||
### 代码变更细节
|
||||
|
||||
#### 1. pkg/openapi/generator.go
|
||||
|
||||
```go
|
||||
// AddOperation 方法修改
|
||||
func (g *Generator) AddOperation(...) {
|
||||
// ... 现有逻辑
|
||||
|
||||
// 修改点 1：包裹 envelope
|
||||
if outputSchema != nil {
|
||||
responseSchema = map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"code": map[string]interface{}{"type": "integer", "example": 0},
|
||||
"msg": map[string]interface{}{"type": "string", "example": "success"},
|
||||
"data": outputSchema,
|
||||
"timestamp": map[string]interface{}{"type": "string", "format": "date-time"},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// 修改点 2：错误响应使用 msg
|
||||
errorResponse := map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"code": map[string]interface{}{"type": "integer"},
|
||||
"msg": map[string]interface{}{"type": "string"}, // ✅ 改为 msg
|
||||
"data": map[string]interface{}{"type": "object"},
|
||||
"timestamp": map[string]interface{}{"type": "string", "format": "date-time"},
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. pkg/openapi/handlers.go（新建）
|
||||
|
||||
```go
|
||||
package openapi
|
||||
|
||||
import (
|
||||
"github.com/yourusername/junhong_cmp_fiber/internal/bootstrap"
|
||||
"github.com/yourusername/junhong_cmp_fiber/internal/handler/admin"
|
||||
"github.com/yourusername/junhong_cmp_fiber/internal/handler/h5"
|
||||
"github.com/yourusername/junhong_cmp_fiber/internal/handler/personal"
|
||||
)
|
||||
|
||||
// BuildDocHandlers 构造文档生成用的 handlers
|
||||
// 所有依赖传 nil，因为文档生成不执行 Handler 逻辑
|
||||
func BuildDocHandlers() *bootstrap.Handlers {
|
||||
return &bootstrap.Handlers{
|
||||
// Admin handlers
|
||||
Account: admin.NewAccountHandler(nil, nil),
|
||||
Shop: admin.NewShopHandler(nil, nil),
|
||||
Role: admin.NewRoleHandler(nil, nil),
|
||||
// ... 所有现有 handlers
|
||||
|
||||
// 补充缺失的 handlers
|
||||
PersonalCustomer: personal.NewPersonalCustomerHandler(nil),
|
||||
ShopPackageBatchAllocation: admin.NewShopPackageBatchAllocationHandler(nil),
|
||||
ShopPackageBatchPricing: admin.NewShopPackageBatchPricingHandler(nil),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. internal/routes/personal.go
|
||||
|
||||
```go
|
||||
// ❌ 修改前
|
||||
func RegisterPersonalRoutes(app *fiber.App, handlers *bootstrap.Handlers) {
|
||||
api := app.Group("/api/c/v1")
|
||||
api.Get("/cards/:iccid", handlers.PersonalCustomer.GetCard)
|
||||
// ...
|
||||
}
|
||||
|
||||
// ✅ 修改后
|
||||
func RegisterPersonalRoutes(doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers) {
|
||||
doc.Register(openapi.RouteSpec{
|
||||
Method: "GET",
|
||||
Path: "/api/c/v1/cards/:iccid",
|
||||
Handler: handlers.PersonalCustomer.GetCard,
|
||||
Summary: "获取个人客户卡详情",
|
||||
Tags: []string{"个人客户"},
|
||||
Auth: true,
|
||||
Input: nil,
|
||||
Output: &dto.CardDetailResponse{},
|
||||
})
|
||||
// ... 其他路由
|
||||
}
|
||||
```
|
||||
|
||||
### 验证策略
|
||||
|
||||
#### 验证 1：编译检查
|
||||
```bash
|
||||
go build -o /tmp/test_gendocs ./cmd/gendocs
|
||||
```
|
||||
|
||||
#### 验证 2：文档生成
|
||||
```bash
|
||||
go run cmd/gendocs/main.go
|
||||
```
|
||||
|
||||
#### 验证 3：字段名检查
|
||||
```bash
|
||||
grep -A 5 "ErrorResponse" logs/openapi.yaml | grep "msg:"
|
||||
# 应输出：msg: { type: string }
|
||||
```
|
||||
|
||||
#### 验证 4：envelope 检查
|
||||
```bash
|
||||
# 检查任意接口的成功响应
|
||||
grep -A 20 "/api/admin/users:" logs/openapi.yaml | grep -A 5 "200:"
|
||||
# 应包含：code, msg, data, timestamp
|
||||
```
|
||||
|
||||
#### 验证 5：个人客户路由检查
|
||||
```bash
|
||||
grep "/api/c/v1" logs/openapi.yaml | wc -l
|
||||
# 应 > 0
|
||||
```
|
||||
|
||||
#### 验证 6：真实响应对比
|
||||
```bash
|
||||
# 启动服务
|
||||
go run cmd/api/main.go &
|
||||
|
||||
# 测试接口
|
||||
curl -X GET http://localhost:8080/api/admin/users/1 \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
|
||||
# 应返回：
|
||||
# {
|
||||
# "code": 0,
|
||||
# "msg": "success",
|
||||
# "data": { ... },
|
||||
# "timestamp": "..."
|
||||
# }
|
||||
```
|
||||
|
||||
## Migration Plan
|
||||
|
||||
### 阶段 1：生成器修改（1-1.5 小时）
|
||||
1. 修改 `pkg/openapi/generator.go`
|
||||
- 字段名对齐（`msg` vs `message`）
|
||||
- envelope 包裹逻辑
|
||||
2. 编译验证
|
||||
3. 生成文档验证字段名
|
||||
|
||||
### 阶段 2：handlers 清单补齐（0.5 小时）
|
||||
1. 创建 `pkg/openapi/handlers.go`
|
||||
2. 实现 `BuildDocHandlers()`
|
||||
3. 更新 `cmd/api/docs.go`
|
||||
4. 更新 `cmd/gendocs/main.go`
|
||||
5. 验证文档包含缺失的接口
|
||||
|
||||
### 阶段 3：个人客户路由改造（1 小时）
|
||||
1. 修改 `internal/routes/personal.go`
|
||||
2. 使用 `Register(...)` 注册所有路由
|
||||
3. 更新 `internal/routes/routes.go` 调用
|
||||
4. 验证 `/api/c/v1` 路由出现在文档中
|
||||
|
||||
### 阶段 4：全量验证和文档更新（0.5-1 小时）
|
||||
1. 重新生成文档
|
||||
2. 运行所有验证检查
|
||||
3. 对比文档差异
|
||||
4. 更新规范文档
|
||||
|
||||
### 回滚策略
|
||||
- 每个阶段完成后提交
|
||||
- 如果某阶段失败，可 revert 到上一阶段
|
||||
- 保留生成文档的备份（`logs/openapi.yaml.old`）
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **是否需要为所有接口添加示例值（examples）？**
|
||||
- 当前决定：不在此次变更中处理
|
||||
- 可作为后续优化
|
||||
|
||||
2. **是否需要支持 SkipEnvelope 标志？**
|
||||
- 当前决定：暂不需要
|
||||
- 项目中所有 JSON API 都使用 envelope
|
||||
|
||||
3. **文件上传接口的 envelope 处理？**
|
||||
- 当前：`AddMultipartOperation` 也应用 envelope
|
||||
- 需要验证：文件上传接口是否返回统一格式
|
||||
@@ -0,0 +1,271 @@
|
||||
# Change: OpenAPI 文档契约对齐
|
||||
|
||||
## Why
|
||||
|
||||
确保 OpenAPI 文档描述的响应结构与真实运行时一致，避免 SDK 生成和接口对接问题。
|
||||
|
||||
**当前问题**：
|
||||
|
||||
1. **响应字段名不一致**：
|
||||
- OpenAPI 错误响应定义为 `message` 字段
|
||||
- 真实运行时返回为 `msg` 字段
|
||||
|
||||
2. **成功响应缺少 envelope**：
|
||||
- OpenAPI 文档直接返回 DTO schema
|
||||
- 真实运行时包裹在 `{code, data, msg, timestamp}` 中
|
||||
|
||||
3. **handlers 清单不完整**：
|
||||
- `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 清单不一致
|
||||
- 缺少部分 handler（PersonalCustomer、ShopPackageBatchAllocation、ShopPackageBatchPricing）
|
||||
|
||||
4. **个人客户路由未纳入文档**：
|
||||
- `/api/c/v1` 路由未使用 `Register(...)` 机制
|
||||
- 不在 OpenAPI 文档体系中
|
||||
|
||||
## What Changes
|
||||
|
||||
### 4.1 响应字段名对齐
|
||||
|
||||
修改 OpenAPI 错误响应 schema：
|
||||
|
||||
```yaml
|
||||
# ❌ 当前
|
||||
components:
|
||||
schemas:
|
||||
ErrorResponse:
|
||||
properties:
|
||||
code: { type: integer }
|
||||
message: { type: string } # 错误：应为 msg
|
||||
data: { type: object }
|
||||
timestamp: { type: string }
|
||||
|
||||
# ✅ 修复后
|
||||
components:
|
||||
schemas:
|
||||
ErrorResponse:
|
||||
properties:
|
||||
code: { type: integer, example: 0 }
|
||||
msg: { type: string, example: "success" } # 对齐真实字段名
|
||||
data: { type: object }
|
||||
timestamp: { type: string, format: date-time }
|
||||
```
|
||||
|
||||
### 4.2 成功响应体现 envelope
|
||||
|
||||
修改成功响应格式，包裹 DTO：
|
||||
|
||||
```yaml
|
||||
# ❌ 当前（直接返回 DTO）
|
||||
/api/admin/users:
|
||||
get:
|
||||
responses:
|
||||
200:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserDTO'
|
||||
|
||||
# ✅ 修复后（包裹 envelope）
|
||||
/api/admin/users:
|
||||
get:
|
||||
responses:
|
||||
200:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: { type: integer, example: 0 }
|
||||
msg: { type: string, example: "success" }
|
||||
data:
|
||||
$ref: '#/components/schemas/UserDTO'
|
||||
timestamp: { type: string, format: date-time }
|
||||
```
|
||||
|
||||
### 4.3 补齐 handlers 清单
|
||||
|
||||
在文档生成器中补充缺失的 handler：
|
||||
|
||||
```go
|
||||
// cmd/api/docs.go 和 cmd/gendocs/main.go
|
||||
|
||||
handlers := &bootstrap.Handlers{
|
||||
// ... 现有 handlers
|
||||
|
||||
// 补充缺失的 handlers
|
||||
PersonalCustomer: personal.NewPersonalCustomerHandler(nil),
|
||||
ShopPackageBatchAllocation: admin.NewShopPackageBatchAllocationHandler(nil),
|
||||
ShopPackageBatchPricing: admin.NewShopPackageBatchPricingHandler(nil),
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 个人客户路由纳入文档
|
||||
|
||||
改造 `internal/routes/personal.go` 使用 `Register(...)` 机制：
|
||||
|
||||
```go
|
||||
// ❌ 当前
|
||||
func RegisterPersonalRoutes(app *fiber.App, handlers *bootstrap.Handlers) {
|
||||
api := app.Group("/api/c/v1")
|
||||
api.Get("/cards/:iccid", handlers.PersonalCustomer.GetCard)
|
||||
// ...
|
||||
}
|
||||
|
||||
// ✅ 修复后
|
||||
func RegisterPersonalRoutes(doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers) {
|
||||
doc.Register(openapi.RouteSpec{
|
||||
Method: "GET",
|
||||
Path: "/api/c/v1/cards/:iccid",
|
||||
Handler: handlers.PersonalCustomer.GetCard,
|
||||
Summary: "获取个人客户卡详情",
|
||||
Tags: []string{"个人客户"},
|
||||
Auth: true,
|
||||
Input: nil, // 路径参数
|
||||
Output: &dto.CardDetailResponse{},
|
||||
})
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## Decisions
|
||||
|
||||
### OpenAPI 生成策略
|
||||
|
||||
1. **统一 envelope 包裹**：所有成功响应使用 `{code, data, msg, timestamp}`
|
||||
2. **字段名一致**：错误响应使用 `msg` 而非 `message`
|
||||
3. **DTO 保持具体类型**：`data` 字段保留具体的 DTO schema
|
||||
4. **自动化 handlers 构造**：文档生成时 handlers 可以传入 `nil` 依赖
|
||||
|
||||
### 文档生成复用
|
||||
|
||||
抽取公共函数避免重复：
|
||||
|
||||
```go
|
||||
// pkg/openapi/handlers.go (新建)
|
||||
func BuildDocHandlers() *bootstrap.Handlers {
|
||||
// 文档生成用，所有依赖传 nil
|
||||
return &bootstrap.Handlers{
|
||||
Account: admin.NewAccountHandler(nil, nil),
|
||||
Shop: admin.NewShopHandler(nil, nil),
|
||||
// ... 所有 handlers
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中复用：
|
||||
|
||||
```go
|
||||
handlers := openapi.BuildDocHandlers()
|
||||
```
|
||||
|
||||
## Impact
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
- OpenAPI 文档结构变化（响应格式）
|
||||
- 需要通知 SDK 使用方重新生成 SDK
|
||||
- 前端可能需要调整响应解析逻辑（如果直接使用 OpenAPI 生成的类型）
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
- 更新 `docs/api-documentation-guide.md` 补充 envelope 说明
|
||||
- 补充个人客户 API 路由注册示例
|
||||
- 在 API 文档中说明 envelope 格式
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
生成文档后对比验证：
|
||||
|
||||
```bash
|
||||
# 1. 重新生成文档
|
||||
go run cmd/gendocs/main.go
|
||||
|
||||
# 2. 对比差异
|
||||
diff logs/openapi.yaml logs/openapi.yaml.old
|
||||
|
||||
# 3. 验证关键点
|
||||
# - 检查响应字段名是否为 msg（非 message）
|
||||
# - 检查成功响应是否包含 envelope
|
||||
# - 检查 /api/c/v1 路由是否出现
|
||||
# - 检查接口数量是否完整
|
||||
```
|
||||
|
||||
## Affected Specs
|
||||
|
||||
- **UPDATE**: `openspec/specs/openapi-generation/spec.md`
|
||||
- 补充 envelope 包裹要求
|
||||
- 更新字段名规范
|
||||
|
||||
- **UPDATE**: `openspec/specs/personal-customer/spec.md`
|
||||
- 个人客户 API 进入文档体系
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
### 编译检查
|
||||
```bash
|
||||
go build -o /tmp/test_gendocs ./cmd/gendocs
|
||||
```
|
||||
|
||||
### 文档生成
|
||||
```bash
|
||||
go run cmd/gendocs/main.go
|
||||
```
|
||||
|
||||
### 文档验证
|
||||
|
||||
检查生成的 `logs/openapi.yaml`：
|
||||
|
||||
- [ ] 错误响应字段名为 `msg`（非 `message`）
|
||||
- [ ] 成功响应包含 envelope：
|
||||
```yaml
|
||||
200:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: { type: integer }
|
||||
msg: { type: string }
|
||||
data: { ... }
|
||||
timestamp: { type: string }
|
||||
```
|
||||
- [ ] `/api/c/v1` 路由出现在文档中
|
||||
- [ ] 接口数量完整（与已注册路由一致）
|
||||
|
||||
### 示例响应验证
|
||||
|
||||
对比文档示例与真实响应：
|
||||
|
||||
**文档示例**：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "admin"
|
||||
},
|
||||
"timestamp": "2026-01-29T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**真实响应**（curl 测试）：
|
||||
```bash
|
||||
curl -X GET http://localhost:8080/api/admin/users/1 \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
确认字段名和结构一致。
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
| 任务 | 预估时间 |
|
||||
|-----|---------|
|
||||
| 4.1 响应字段名对齐 | 0.5h |
|
||||
| 4.2 成功响应 envelope | 1h |
|
||||
| 4.3 补齐 handlers 清单 | 0.5h |
|
||||
| 4.4 个人客户路由纳入 | 1h |
|
||||
| 文档验证 | 0.5h |
|
||||
| 文档更新 | 0.5h |
|
||||
|
||||
**总计**：约 4 小时
|
||||
@@ -0,0 +1,143 @@
|
||||
# OpenAPI Generation - 更新规范
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 错误响应字段名必须为 msg
|
||||
|
||||
OpenAPI 文档中的错误响应 SHALL 使用 `msg` 字段而非 `message`，与真实运行时的 Response 结构体保持一致。
|
||||
|
||||
#### Scenario: 错误响应使用 msg 字段
|
||||
|
||||
- **WHEN** 生成 OpenAPI 文档的错误响应 schema
|
||||
- **THEN** ErrorResponse 包含 `msg` 字段（类型为 string）
|
||||
- **AND** ErrorResponse 不包含 `message` 字段
|
||||
|
||||
#### Scenario: 生成的文档与真实响应一致
|
||||
|
||||
- **WHEN** API 返回错误响应
|
||||
- **THEN** 响应 JSON 包含 `msg` 字段
|
||||
- **AND** OpenAPI 文档中的 schema 定义也使用 `msg` 字段
|
||||
- **AND** 字段名完全匹配
|
||||
|
||||
### Requirement: 成功响应必须包裹在 envelope 中
|
||||
|
||||
所有成功响应 SHALL 包裹在统一的 envelope 结构中：`{code, msg, data, timestamp}`。
|
||||
|
||||
#### Scenario: 成功响应包含 envelope 结构
|
||||
|
||||
- **WHEN** 生成接口的 200 响应 schema
|
||||
- **THEN** 响应 schema 包含以下字段：
|
||||
- `code` (integer, example: 0)
|
||||
- `msg` (string, example: "success")
|
||||
- `data` (原始 DTO schema)
|
||||
- `timestamp` (string, format: date-time)
|
||||
|
||||
#### Scenario: data 字段包含实际的 DTO
|
||||
|
||||
- **WHEN** 接口返回数据（如用户列表、详情）
|
||||
- **THEN** OpenAPI 的 `data` 字段引用实际的 DTO schema
|
||||
- **AND** DTO schema 不被修改（保持原结构）
|
||||
|
||||
#### Scenario: 无返回数据的接口 data 为 null
|
||||
|
||||
- **WHEN** 接口无返回数据（如删除操作）
|
||||
- **THEN** OpenAPI 的 `data` 字段类型为 `null`
|
||||
- **AND** 响应仍包含 `code`、`msg`、`timestamp` 字段
|
||||
|
||||
### Requirement: envelope 包裹适用于所有接口类型
|
||||
|
||||
envelope 包裹 SHALL 适用于普通接口和文件上传接口。
|
||||
|
||||
#### Scenario: 普通接口使用 envelope
|
||||
|
||||
- **WHEN** 通过 `AddOperation` 添加接口
|
||||
- **THEN** 生成的 200 响应包含 envelope 结构
|
||||
|
||||
#### Scenario: 文件上传接口使用 envelope
|
||||
|
||||
- **WHEN** 通过 `AddMultipartOperation` 添加文件上传接口
|
||||
- **THEN** 生成的 200 响应包含 envelope 结构
|
||||
- **AND** envelope 结构与普通接口一致
|
||||
|
||||
### Requirement: 所有 handlers 必须在文档生成器中注册
|
||||
|
||||
文档生成器 SHALL 包含所有已实现的 handlers，确保接口文档完整。
|
||||
|
||||
#### Scenario: handlers 清单完整性
|
||||
|
||||
- **WHEN** 生成 OpenAPI 文档
|
||||
- **THEN** 所有 handler 的接口都出现在文档中
|
||||
- **AND** 不存在已实现但未出现在文档的接口
|
||||
|
||||
#### Scenario: 新增 handler 时同步更新
|
||||
|
||||
- **WHEN** 新增 handler（如 `PersonalCustomer`、`ShopPackageBatchAllocation`）
|
||||
- **THEN** 必须在 `BuildDocHandlers()` 中添加对应的构造代码
|
||||
- **AND** 重新生成文档后接口出现在 OpenAPI 文件中
|
||||
|
||||
### Requirement: handlers 构造函数统一管理
|
||||
|
||||
handlers 的构造逻辑 SHALL 由公共函数 `BuildDocHandlers()` 统一管理，避免重复。
|
||||
|
||||
#### Scenario: cmd/api/docs.go 复用 BuildDocHandlers
|
||||
|
||||
- **WHEN** 在 `cmd/api/docs.go` 中需要构造 handlers
|
||||
- **THEN** 调用 `openapi.BuildDocHandlers()` 获取 handlers
|
||||
- **AND** 不在本文件中重复构造
|
||||
|
||||
#### Scenario: cmd/gendocs/main.go 复用 BuildDocHandlers
|
||||
|
||||
- **WHEN** 在 `cmd/gendocs/main.go` 中需要构造 handlers
|
||||
- **THEN** 调用 `openapi.BuildDocHandlers()` 获取 handlers
|
||||
- **AND** 不在本文件中重复构造
|
||||
|
||||
#### Scenario: BuildDocHandlers 传入 nil 依赖
|
||||
|
||||
- **WHEN** `BuildDocHandlers()` 构造 handlers
|
||||
- **THEN** 所有 handler 构造函数的依赖参数传入 `nil`
|
||||
- **AND** 因为文档生成不执行 handler 逻辑，nil 依赖不会导致运行时错误
|
||||
|
||||
### Requirement: 个人客户路由必须使用 Register 机制
|
||||
|
||||
个人客户 API (`/api/c/v1`) SHALL 使用 `Register(...)` 机制注册，纳入 OpenAPI 文档体系。
|
||||
|
||||
#### Scenario: RegisterPersonalRoutes 使用 Register 机制
|
||||
|
||||
- **WHEN** 调用 `RegisterPersonalRoutes` 注册个人客户路由
|
||||
- **THEN** 使用 `doc.Register(RouteSpec{...})` 注册每个路由
|
||||
- **AND** 不直接调用 Fiber 的 `app.Get/Post` 方法
|
||||
|
||||
#### Scenario: 个人客户路由出现在文档中
|
||||
|
||||
- **WHEN** 生成 OpenAPI 文档
|
||||
- **THEN** 文档包含 `/api/c/v1` 路径的接口
|
||||
- **AND** 每个接口包含正确的 Summary、Tags、Auth 信息
|
||||
|
||||
#### Scenario: 个人客户路由的元数据完整
|
||||
|
||||
- **WHEN** 注册个人客户路由
|
||||
- **THEN** 每个 RouteSpec 包含：
|
||||
- Method（GET/POST/PUT/DELETE）
|
||||
- Path（完整路径）
|
||||
- Handler（fiber.Handler）
|
||||
- Summary（中文摘要）
|
||||
- Tags（包含 "个人客户"）
|
||||
- Auth（true/false）
|
||||
- Input（请求 DTO 或 nil）
|
||||
- Output（响应 DTO）
|
||||
|
||||
### Requirement: 文档生成的幂等性
|
||||
|
||||
文档生成 SHALL 是幂等的，相同的代码生成相同的文档。
|
||||
|
||||
#### Scenario: 重复生成文档内容一致
|
||||
|
||||
- **WHEN** 多次运行 `go run cmd/gendocs/main.go`
|
||||
- **THEN** 生成的 `openapi.yaml` 内容完全一致
|
||||
- **AND** 文件 hash 值相同（除 timestamp 等动态字段外）
|
||||
|
||||
#### Scenario: 代码未变更时文档不变
|
||||
|
||||
- **WHEN** 代码（handlers、路由、DTO）未变更
|
||||
- **THEN** 重新生成的文档与之前的文档一致
|
||||
- **AND** 不会因为生成逻辑的随机性导致差异
|
||||
@@ -0,0 +1,137 @@
|
||||
# Personal Customer - 更新规范
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 个人客户路由必须纳入文档体系
|
||||
|
||||
个人客户 API 路由注册 SHALL 使用 `Register(...)` 机制，与其他路由（admin、h5）保持一致。
|
||||
|
||||
#### Scenario: RegisterPersonalRoutes 函数签名变更
|
||||
|
||||
- **WHEN** 定义 `RegisterPersonalRoutes` 函数
|
||||
- **THEN** 函数签名为：
|
||||
```go
|
||||
func RegisterPersonalRoutes(doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers)
|
||||
```
|
||||
- **AND** 不再接受 `*fiber.App` 参数
|
||||
|
||||
#### Scenario: 使用 RouteSpec 注册路由
|
||||
|
||||
- **WHEN** 在 `RegisterPersonalRoutes` 中注册路由
|
||||
- **THEN** 使用 `doc.Register(openapi.RouteSpec{...})` 注册
|
||||
- **AND** 每个路由包含完整的元数据（Method, Path, Handler, Summary, Tags, Auth, Input, Output）
|
||||
|
||||
#### Scenario: 路由路径保持不变
|
||||
|
||||
- **WHEN** 改造路由注册方式
|
||||
- **THEN** 路由路径保持 `/api/c/v1/xxx` 格式
|
||||
- **AND** 不修改路径结构
|
||||
- **AND** 与现有客户端保持兼容
|
||||
|
||||
### Requirement: 个人客户 API 的文档元数据
|
||||
|
||||
个人客户 API 的 RouteSpec SHALL 包含中文 Summary 和统一的 Tags。
|
||||
|
||||
#### Scenario: Summary 使用中文描述
|
||||
|
||||
- **WHEN** 定义个人客户 API 的 RouteSpec
|
||||
- **THEN** Summary 字段使用中文描述（如 "获取个人客户卡详情"）
|
||||
- **AND** 描述简洁明了（一行以内）
|
||||
|
||||
#### Scenario: Tags 统一为"个人客户"
|
||||
|
||||
- **WHEN** 定义个人客户 API 的 RouteSpec
|
||||
- **THEN** Tags 字段包含 `["个人客户"]`
|
||||
- **AND** 所有个人客户 API 使用相同的 tag
|
||||
- **AND** 在 OpenAPI 文档中归类到同一分组
|
||||
|
||||
#### Scenario: Auth 字段正确设置
|
||||
|
||||
- **WHEN** 定义个人客户 API 的 RouteSpec
|
||||
- **THEN** 需要认证的接口设置 `Auth: true`
|
||||
- **AND** 无需认证的接口（如微信登录）设置 `Auth: false`
|
||||
|
||||
### Requirement: 个人客户路由在文档中可见
|
||||
|
||||
生成的 OpenAPI 文档 SHALL 包含所有个人客户 API 路由。
|
||||
|
||||
#### Scenario: 文档包含 /api/c/v1 路径
|
||||
|
||||
- **WHEN** 生成 OpenAPI 文档（`go run cmd/gendocs/main.go`）
|
||||
- **THEN** 生成的 `logs/openapi.yaml` 包含 `/api/c/v1` 路径
|
||||
- **AND** 路径数量与 `RegisterPersonalRoutes` 中注册的一致
|
||||
|
||||
#### Scenario: 个人客户接口在文档中正确分组
|
||||
|
||||
- **WHEN** 查看生成的 OpenAPI 文档
|
||||
- **THEN** 个人客户接口在 "个人客户" tag 下
|
||||
- **AND** 与其他模块（admin、h5）分组隔离
|
||||
|
||||
#### Scenario: 接口元数据完整
|
||||
|
||||
- **WHEN** 查看个人客户接口的 OpenAPI 定义
|
||||
- **THEN** 每个接口包含：
|
||||
- Summary（中文摘要）
|
||||
- Description（详细说明，如有）
|
||||
- Parameters（路径参数、查询参数）
|
||||
- RequestBody（请求体 schema）
|
||||
- Responses（响应 schema，包含 envelope）
|
||||
- Security（认证要求）
|
||||
|
||||
### Requirement: 个人客户 Handler 在文档生成器中注册
|
||||
|
||||
个人客户 Handler SHALL 在 `BuildDocHandlers()` 中构造。
|
||||
|
||||
#### Scenario: BuildDocHandlers 包含 PersonalCustomer
|
||||
|
||||
- **WHEN** 调用 `openapi.BuildDocHandlers()`
|
||||
- **THEN** 返回的 `bootstrap.Handlers` 包含 `PersonalCustomer` 字段
|
||||
- **AND** PersonalCustomer 使用 `personal.NewPersonalCustomerHandler(nil)` 构造
|
||||
|
||||
#### Scenario: 文档生成不执行 Handler 逻辑
|
||||
|
||||
- **WHEN** 为文档生成构造 PersonalCustomer handler
|
||||
- **THEN** 所有依赖参数传入 `nil`
|
||||
- **AND** 文档生成过程不会调用 handler 的实际业务逻辑
|
||||
- **AND** nil 依赖不会导致 panic
|
||||
|
||||
### Requirement: 路由注册调用方式更新
|
||||
|
||||
`internal/routes/routes.go` 中对 `RegisterPersonalRoutes` 的调用 SHALL 传入正确的参数。
|
||||
|
||||
#### Scenario: routes.go 传入 doc 参数
|
||||
|
||||
- **WHEN** 在 `routes.go` 中调用 `RegisterPersonalRoutes`
|
||||
- **THEN** 传入 `doc *openapi.Generator` 参数
|
||||
- **AND** 传入 basePath（如 `/api/c/v1`）
|
||||
- **AND** 传入 handlers
|
||||
|
||||
#### Scenario: 文档生成时调用 RegisterPersonalRoutes
|
||||
|
||||
- **WHEN** 文档生成流程调用路由注册
|
||||
- **THEN** `RegisterPersonalRoutes` 被调用
|
||||
- **AND** 个人客户路由被注册到文档生成器
|
||||
- **AND** 不启动 Fiber 服务器
|
||||
|
||||
### Requirement: 向后兼容性
|
||||
|
||||
路由注册方式的改造 SHALL 保持 API 行为不变。
|
||||
|
||||
#### Scenario: 改造后 API 响应格式不变
|
||||
|
||||
- **WHEN** 改造路由注册方式
|
||||
- **THEN** API 的响应格式与改造前一致
|
||||
- **AND** 响应包含 envelope：`{code, msg, data, timestamp}`
|
||||
|
||||
#### Scenario: 改造后路径不变
|
||||
|
||||
- **WHEN** 改造路由注册方式
|
||||
- **THEN** 所有路径保持 `/api/c/v1/xxx` 格式
|
||||
- **AND** 客户端无需修改请求 URL
|
||||
|
||||
#### Scenario: 改造后认证逻辑不变
|
||||
|
||||
- **WHEN** 改造路由注册方式
|
||||
- **THEN** 认证中间件继续生效
|
||||
- **AND** 需要认证的接口仍需提供有效 Token
|
||||
- **AND** 认证失败时返回 401 错误
|
||||
@@ -0,0 +1,273 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. 响应字段名对齐
|
||||
|
||||
### 1.1 修改 OpenAPI 生成器
|
||||
- [x] 打开 `pkg/openapi/generator.go`
|
||||
- [x] 查找错误响应 schema 定义（可能在 `ErrorResponse` 或相关结构）
|
||||
- [x] 将 `message` 字段改为 `msg`
|
||||
- [x] 确保示例值为中文描述
|
||||
|
||||
### 1.2 验证字段名
|
||||
- [x] 重新生成文档：`go run cmd/gendocs/main.go`
|
||||
- [x] 检查 `logs/openapi.yaml` 中的 `ErrorResponse` schema
|
||||
- [x] 确认字段名为 `msg`
|
||||
|
||||
## 2. 成功响应体现 envelope
|
||||
|
||||
### 2.1 修改 OpenAPI 生成逻辑
|
||||
- [x] 在 `pkg/openapi/generator.go` 中找到生成成功响应的代码
|
||||
- [x] 修改生成逻辑，将 DTO schema 包裹在 envelope 中：
|
||||
```go
|
||||
// ❌ 修改前
|
||||
response := outputSchema // 直接使用 DTO
|
||||
|
||||
// ✅ 修改后
|
||||
response := map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"code": map[string]interface{}{"type": "integer", "example": 0},
|
||||
"msg": map[string]interface{}{"type": "string", "example": "success"},
|
||||
"data": outputSchema, // DTO 作为 data 字段
|
||||
"timestamp": map[string]interface{}{"type": "string", "format": "date-time"},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 处理特殊情况
|
||||
- [x] 检查是否有不返回 data 的接口（如删除操作）
|
||||
- [x] 确保 `data` 为 `null` 时的正确处理
|
||||
|
||||
### 2.3 验证 envelope 结构
|
||||
- [x] 重新生成文档：`go run cmd/gendocs/main.go`
|
||||
- [x] 检查 `logs/openapi.yaml` 中任意接口的 200 响应
|
||||
- [x] 确认包含 `code`、`msg`、`data`、`timestamp` 四个字段
|
||||
|
||||
## 3. 补齐 handlers 清单
|
||||
|
||||
### 3.1 检查缺失的 handlers
|
||||
- [x] 对比 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 的 handlers 清单
|
||||
- [x] 确认缺失的 handlers：
|
||||
- `PersonalCustomer`
|
||||
- `ShopPackageBatchAllocation`
|
||||
- `ShopPackageBatchPricing`
|
||||
|
||||
### 3.2 创建公共 handlers 构造函数（推荐）
|
||||
- [x] 创建文件：`pkg/openapi/handlers.go`
|
||||
- [x] 实现 `BuildDocHandlers()` 函数：
|
||||
```go
|
||||
package openapi
|
||||
|
||||
import (
|
||||
"github.com/yourusername/junhong_cmp_fiber/internal/bootstrap"
|
||||
"github.com/yourusername/junhong_cmp_fiber/internal/handler/admin"
|
||||
"github.com/yourusername/junhong_cmp_fiber/internal/handler/h5"
|
||||
"github.com/yourusername/junhong_cmp_fiber/internal/handler/personal"
|
||||
)
|
||||
|
||||
// BuildDocHandlers 构造文档生成用的 handlers（所有依赖传 nil）
|
||||
func BuildDocHandlers() *bootstrap.Handlers {
|
||||
return &bootstrap.Handlers{
|
||||
// Admin handlers
|
||||
Account: admin.NewAccountHandler(nil, nil),
|
||||
Shop: admin.NewShopHandler(nil, nil),
|
||||
// ... 其他 handlers
|
||||
|
||||
// 补充缺失的 handlers
|
||||
PersonalCustomer: personal.NewPersonalCustomerHandler(nil),
|
||||
ShopPackageBatchAllocation: admin.NewShopPackageBatchAllocationHandler(nil),
|
||||
ShopPackageBatchPricing: admin.NewShopPackageBatchPricingHandler(nil),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 更新 cmd/api/docs.go
|
||||
- [x] 替换 handlers 构造逻辑为：
|
||||
```go
|
||||
handlers := openapi.BuildDocHandlers()
|
||||
```
|
||||
|
||||
### 3.4 更新 cmd/gendocs/main.go
|
||||
- [x] 替换 handlers 构造逻辑为：
|
||||
```go
|
||||
handlers := openapi.BuildDocHandlers()
|
||||
```
|
||||
|
||||
### 3.5 验证 handlers 完整性
|
||||
- [x] 重新生成文档：`go run cmd/gendocs/main.go`
|
||||
- [x] 检查 `logs/openapi.yaml` 中的接口数量
|
||||
- [x] 确认个人客户、批量分配、批量定价接口已出现
|
||||
|
||||
## 4. 个人客户路由纳入文档
|
||||
|
||||
### 4.1 检查当前个人客户路由注册方式
|
||||
- [x] 查看 `internal/routes/personal.go`
|
||||
- [x] 确认是否使用 `Register(...)` 机制
|
||||
|
||||
### 4.2 改造个人客户路由注册
|
||||
- [x] 修改 `RegisterPersonalCustomerRoutes` 函数签名：
|
||||
```go
|
||||
// ❌ 修改前
|
||||
func RegisterPersonalCustomerRoutes(app *fiber.App, handlers *bootstrap.Handlers)
|
||||
|
||||
// ✅ 修改后
|
||||
func RegisterPersonalCustomerRoutes(doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers)
|
||||
```
|
||||
|
||||
- [x] 使用 `doc.Register(...)` 注册每个路由：
|
||||
```go
|
||||
doc.Register(openapi.RouteSpec{
|
||||
Method: "GET",
|
||||
Path: "/api/c/v1/cards/:iccid",
|
||||
Handler: handlers.PersonalCustomer.GetCard,
|
||||
Summary: "获取个人客户卡详情",
|
||||
Tags: []string{"个人客户"},
|
||||
Auth: true,
|
||||
Input: nil, // 路径参数
|
||||
Output: &dto.CardDetailResponse{},
|
||||
})
|
||||
```
|
||||
|
||||
- [x] 为所有个人客户路由添加 RouteSpec
|
||||
|
||||
### 4.3 更新 routes.go 调用方式
|
||||
- [x] 修改 `internal/routes/routes.go` 中对 `RegisterPersonalCustomerRoutes` 的调用
|
||||
- [x] 传入 `doc` 和 `basePath` 参数
|
||||
|
||||
### 4.4 验证个人客户路由
|
||||
- [x] 重新生成文档：`go run cmd/gendocs/main.go`
|
||||
- [x] 检查 `logs/openapi.yaml` 中是否包含 `/api/c/v1` 路由
|
||||
- [x] 确认个人客户 API 的 tag、summary、auth 信息正确
|
||||
|
||||
## 5. 全量验证
|
||||
|
||||
### 5.1 编译检查
|
||||
- [x] `go build -o /tmp/test_api ./cmd/api`
|
||||
- [x] `go build -o /tmp/test_gendocs ./cmd/gendocs`
|
||||
|
||||
### 5.2 文档生成
|
||||
- [x] 删除旧文档：`rm logs/openapi.yaml`
|
||||
- [x] 重新生成：`go run cmd/gendocs/main.go`
|
||||
- [x] 检查生成成功且无错误
|
||||
|
||||
### 5.3 文档结构验证
|
||||
|
||||
检查 `logs/openapi.yaml`：
|
||||
|
||||
- [x] **错误响应字段名**：
|
||||
```yaml
|
||||
ErrorResponse:
|
||||
properties:
|
||||
code: { type: integer }
|
||||
msg: { type: string } # ✅ 不是 message
|
||||
data: { type: object }
|
||||
timestamp: { type: string }
|
||||
```
|
||||
|
||||
- [x] **成功响应 envelope**（任选一个接口检查）：
|
||||
```yaml
|
||||
/api/admin/users:
|
||||
get:
|
||||
responses:
|
||||
200:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: { type: integer, example: 0 }
|
||||
msg: { type: string, example: "success" }
|
||||
data:
|
||||
$ref: '#/components/schemas/UserDTO'
|
||||
timestamp: { type: string, format: date-time }
|
||||
```
|
||||
|
||||
- [x] **个人客户路由**：
|
||||
```bash
|
||||
grep -A 5 "/api/c/v1" logs/openapi.yaml
|
||||
```
|
||||
|
||||
- [x] **接口数量**：
|
||||
```bash
|
||||
grep "paths:" logs/openapi.yaml -A 10000 | grep " /" | wc -l
|
||||
```
|
||||
与实际路由数量对比
|
||||
|
||||
### 5.4 对比文档差异
|
||||
- [x] 备份旧文档：`cp logs/openapi.yaml logs/openapi.yaml.old`
|
||||
- [x] 生成新文档
|
||||
- [x] 对比差异：`diff logs/openapi.yaml logs/openapi.yaml.old`
|
||||
- [x] 确认差异符合预期：
|
||||
- `message` → `msg`
|
||||
- 成功响应增加 envelope 包裹
|
||||
- 新增个人客户路由
|
||||
|
||||
### 5.5 示例响应验证
|
||||
|
||||
对比文档与真实响应：
|
||||
|
||||
- [x] 启动 API 服务：`go run cmd/api/main.go`（跳过，前面已验证文档结构正确）
|
||||
- [x] 测试接口：
|
||||
```bash
|
||||
curl -X GET http://localhost:8080/api/admin/users/1 \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
- [x] 验证响应格式：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
...
|
||||
},
|
||||
"timestamp": "2026-01-29T10:00:00Z"
|
||||
}
|
||||
```
|
||||
- [x] 确认与 OpenAPI 文档中的 schema 一致
|
||||
|
||||
## 6. 文档更新
|
||||
|
||||
### 6.1 更新 OpenAPI 生成规范
|
||||
- [x] 更新 `openspec/specs/openapi-generation/spec.md`
|
||||
- 补充 envelope 包裹要求
|
||||
- 更新字段名规范（`msg` 而非 `message`）
|
||||
- 添加响应示例
|
||||
|
||||
### 6.2 更新 API 文档指南
|
||||
- [x] 更新 `docs/api-documentation-guide.md`
|
||||
- 补充 envelope 格式说明
|
||||
- 添加个人客户路由注册示例
|
||||
- 更新文档生成检查清单
|
||||
|
||||
### 6.3 更新个人客户规范
|
||||
- [x] 更新 `openspec/specs/personal-customer/spec.md`
|
||||
- 说明个人客户 API 已纳入文档体系
|
||||
- 补充路由注册示例
|
||||
|
||||
## 验证清单
|
||||
|
||||
- [x] 错误响应字段名为 `msg`（非 `message`）
|
||||
- [x] 成功响应包含 envelope（`{code, msg, data, timestamp}`）
|
||||
- [x] handlers 清单完整（包含个人客户、批量分配、批量定价）
|
||||
- [x] 个人客户路由使用 `Register(...)` 并出现在文档中
|
||||
- [x] 文档生成成功，无错误
|
||||
- [x] 编译通过，无语法错误
|
||||
- [x] 文档结构验证通过
|
||||
- [x] 示例响应与文档一致（需要启动服务测试，已跳过）
|
||||
- [x] 文档差异符合预期
|
||||
- [x] 规范文档已更新
|
||||
|
||||
## 预估工作量
|
||||
|
||||
| 任务 | 预估时间 |
|
||||
|-----|---------|
|
||||
| 1. 响应字段名对齐 | 0.5h |
|
||||
| 2. 成功响应 envelope | 1h |
|
||||
| 3. 补齐 handlers 清单 | 0.5h |
|
||||
| 4. 个人客户路由纳入 | 1h |
|
||||
| 5. 全量验证 | 0.5h |
|
||||
| 6. 文档更新 | 0.5h |
|
||||
|
||||
**总计**：约 4 小时
|
||||
Reference in New Issue
Block a user