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,354 @@
|
||||
# 后续工作建议
|
||||
|
||||
基于当前已完成的工作，建议将剩余任务拆分为 4 个独立的 OpenSpec 变更，按优先级顺序执行。
|
||||
|
||||
---
|
||||
|
||||
## 提案 1：Service 层错误语义统一 - 核心业务模块
|
||||
|
||||
**优先级**：🔴 高
|
||||
|
||||
### Why
|
||||
完成核心业务模块的错误语义统一，确保订单、套餐、分佣等关键流程的错误处理一致性。
|
||||
|
||||
### What Changes
|
||||
统一以下 10 个核心模块的错误处理（约 70-80 处）：
|
||||
|
||||
**订单与套餐管理**：
|
||||
- `package/service.go` (14 处)
|
||||
- `package_series/service.go` (9 处)
|
||||
- `order/service.go` (已完成)
|
||||
|
||||
**分佣系统**：
|
||||
- `commission_withdrawal/service.go` (7 处)
|
||||
- `commission_stats/service.go` (3 处)
|
||||
- `my_commission/service.go` (9 处)
|
||||
|
||||
**店铺与企业**：
|
||||
- `shop/service.go` (8 处)
|
||||
- `enterprise/service.go` (7 处)
|
||||
- `shop_account/service.go` (11 处)
|
||||
- `customer_account/service.go` (6 处)
|
||||
|
||||
### Decisions
|
||||
- 数据库/Redis/队列错误统一为 `errors.Wrap(CodeInternalError, err, msg)`
|
||||
- 业务校验错误（如状态不允许、资源不存在）为 `errors.New(Code4xx, msg)`
|
||||
- 每完成 2-3 个文件运行一次相关测试
|
||||
|
||||
### Impact
|
||||
- **Breaking Changes**：部分接口错误码从 500 调整为 4xx
|
||||
- **测试要求**：每个模块补充错误场景测试
|
||||
- **文档更新**：更新 API 文档中的错误码说明
|
||||
|
||||
---
|
||||
|
||||
## 提案 2：Service 层错误语义统一 - 支持模块
|
||||
|
||||
**优先级**：🟡 中
|
||||
|
||||
### Why
|
||||
完成剩余支持模块的错误语义统一，实现全局一致性。
|
||||
|
||||
### What Changes
|
||||
统一以下 14 个支持模块的错误处理（约 140-150 处）：
|
||||
|
||||
**套餐分配系统**：
|
||||
- `shop_package_allocation/service.go` (17 处)
|
||||
- `shop_series_allocation/service.go` (24 处)
|
||||
- `shop_package_batch_allocation/service.go` (6 处)
|
||||
- `shop_package_batch_pricing/service.go` (3 处)
|
||||
|
||||
**权限与账号**：
|
||||
- `account/service.go` (24 处)
|
||||
- `role/service.go` (15 处)
|
||||
- `permission/service.go` (10 处)
|
||||
|
||||
**卡与设备管理**：
|
||||
- `enterprise_card/service.go` (9 处)
|
||||
- `enterprise_device/service.go` (20 处)
|
||||
- `iot_card_import/service.go` (2 处)
|
||||
- `device_import/service.go` (已完成)
|
||||
|
||||
**其他支持服务**：
|
||||
- `carrier/service.go` (9 处)
|
||||
- `shop_commission/service.go` (7 处)
|
||||
- `commission_withdrawal_setting/service.go` (4 处)
|
||||
- `email/service.go` (6 处)
|
||||
- `sync/service.go` (4 处)
|
||||
|
||||
### Decisions
|
||||
- 同提案 1 的错误处理规则
|
||||
- 可以分批次提交（如每 5 个文件一个 commit）
|
||||
|
||||
---
|
||||
|
||||
## 提案 3：Handler 层参数校验安全加固
|
||||
|
||||
**优先级**：🟡 中
|
||||
|
||||
### Why
|
||||
防止参数校验错误泄露内部实现细节（validator 规则、字段名等），提升安全性。
|
||||
|
||||
### What Changes
|
||||
|
||||
**修复模式**：
|
||||
|
||||
```go
|
||||
// ❌ 当前（泄露细节）
|
||||
if err := c.BodyParser(&req); err != nil {
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败: "+err.Error())
|
||||
}
|
||||
|
||||
if err := validate.Struct(&req); err != nil {
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数验证失败: "+err.Error())
|
||||
}
|
||||
|
||||
// ✅ 修复后（安全）
|
||||
if err := c.BodyParser(&req); err != nil {
|
||||
logger.GetAppLogger().Warn("参数解析失败",
|
||||
zap.String("path", c.Path()),
|
||||
zap.Error(err),
|
||||
)
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败")
|
||||
}
|
||||
|
||||
if err := validate.Struct(&req); err != nil {
|
||||
logger.GetAppLogger().Warn("参数验证失败",
|
||||
zap.String("path", c.Path()),
|
||||
zap.Error(err),
|
||||
)
|
||||
return errors.New(errors.CodeInvalidParam) // 使用默认 msg
|
||||
}
|
||||
```
|
||||
|
||||
**影响范围**：
|
||||
- `internal/handler/admin/**` (约 20-25 个文件)
|
||||
- `internal/handler/h5/**` (约 5-8 个文件)
|
||||
- `internal/handler/personal/**` (约 3-5 个文件)
|
||||
|
||||
### Decisions
|
||||
- 详细校验错误只写日志，不返回给客户端
|
||||
- 统一返回 `CodeInvalidParam` + 通用消息
|
||||
- 为关键 Handler 补充参数校验测试
|
||||
|
||||
### Testing
|
||||
```go
|
||||
func TestHandler_InvalidParam(t *testing.T) {
|
||||
// 测试参数缺失
|
||||
resp := testRequest(t, "POST", "/api/admin/users", `{}`)
|
||||
assert.Equal(t, 400, resp.StatusCode)
|
||||
|
||||
var result map[string]interface{}
|
||||
json.Unmarshal(resp.Body, &result)
|
||||
|
||||
// 验证不包含 validator 内部细节
|
||||
assert.NotContains(t, result["msg"], "Field validation")
|
||||
assert.NotContains(t, result["msg"], "required")
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 提案 4：OpenAPI 文档契约对齐
|
||||
|
||||
**优先级**：🟡 中
|
||||
|
||||
### Why
|
||||
确保 OpenAPI 文档描述的响应结构与真实运行时一致，避免 SDK 生成和接口对接问题。
|
||||
|
||||
### What Changes
|
||||
|
||||
#### 4.1 响应字段名对齐
|
||||
```yaml
|
||||
# ❌ 当前
|
||||
components:
|
||||
schemas:
|
||||
ErrorResponse:
|
||||
properties:
|
||||
code: integer
|
||||
message: string # 错误：应为 msg
|
||||
data: object
|
||||
timestamp: string
|
||||
|
||||
# ✅ 修复后
|
||||
components:
|
||||
schemas:
|
||||
ErrorResponse:
|
||||
properties:
|
||||
code: integer
|
||||
msg: string # 对齐真实字段名
|
||||
data: object
|
||||
timestamp: string
|
||||
```
|
||||
|
||||
#### 4.2 成功响应体现 envelope
|
||||
```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 清单
|
||||
在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中补充：
|
||||
- `PersonalCustomer` handler
|
||||
- `ShopPackageBatchAllocation` handler
|
||||
- `ShopPackageBatchPricing` handler
|
||||
|
||||
#### 4.4 个人客户路由纳入文档
|
||||
修改 `internal/routes/personal.go` 使用 `Register(...)` 并添加 RouteSpec。
|
||||
|
||||
### Impact
|
||||
- OpenAPI 文档结构变化（需通知 SDK 使用方）
|
||||
- 文档生成后需要对比差异确认
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# 1. 重新生成文档
|
||||
go run cmd/gendocs/main.go
|
||||
|
||||
# 2. 对比差异
|
||||
diff logs/openapi.yaml logs/openapi.yaml.old
|
||||
|
||||
# 3. 验证关键接口
|
||||
# - 检查响应是否包含 envelope
|
||||
# - 检查字段名是否为 msg（非 message）
|
||||
# - 检查 /api/c/v1 路由是否出现
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 提案 5：代码清理和规范文档更新
|
||||
|
||||
**优先级**：🟢 低
|
||||
|
||||
### Why
|
||||
清理临时代码和不一致的注释，更新项目规范文档，完善 CI 检查。
|
||||
|
||||
### What Changes
|
||||
|
||||
#### 5.1 移除任务模块占位代码
|
||||
- 删除 `internal/routes/task.go`
|
||||
- 删除 `internal/handler/admin/task.go`
|
||||
- 更新 `internal/routes/routes.go` 移除 `registerTaskRoutes` 调用
|
||||
|
||||
#### 5.2 清理注释一致性
|
||||
扫描 `internal/handler/**` 中残留的 `/api/v1` 注释，统一为真实路径。
|
||||
|
||||
#### 5.3 更新规范文档
|
||||
- 更新 `openspec/specs/error-handling/spec.md` 补充"错误报错规范"
|
||||
- 更新 `AGENTS.md` 增加错误处理检查清单
|
||||
- 更新 `docs/003-error-handling/使用指南.md` 补充实际案例
|
||||
|
||||
#### 5.4 CI 检查增强
|
||||
```bash
|
||||
# 添加脚本检查 Service 层禁止 fmt.Errorf
|
||||
#!/bin/bash
|
||||
# scripts/check-service-errors.sh
|
||||
|
||||
FILES=$(find internal/service -name "*.go" -type f)
|
||||
VIOLATIONS=$(grep -n "fmt\.Errorf" $FILES | grep -v "// whitelist:")
|
||||
|
||||
if [ -n "$VIOLATIONS" ]; then
|
||||
echo "❌ 发现 Service 层使用 fmt.Errorf："
|
||||
echo "$VIOLATIONS"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Service 层错误处理检查通过"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 执行顺序建议
|
||||
|
||||
```
|
||||
提案 1 (核心业务) → 提案 2 (支持模块) → 提案 3 (Handler 层) → 提案 4 (OpenAPI) → 提案 5 (清理)
|
||||
```
|
||||
|
||||
**原因**：
|
||||
1. 优先修复核心业务错误语义（影响用户体验）
|
||||
2. 完成全量 Service 层统一后再处理 Handler 层
|
||||
3. OpenAPI 文档对齐可以独立进行
|
||||
4. 代码清理和规范更新最后进行
|
||||
|
||||
---
|
||||
|
||||
## 每个提案的验证清单
|
||||
|
||||
### 编译检查
|
||||
```bash
|
||||
go build -o /tmp/test_api ./cmd/api
|
||||
go build -o /tmp/test_worker ./cmd/worker
|
||||
```
|
||||
|
||||
### 单元测试
|
||||
```bash
|
||||
source .env.local && go test -v ./internal/service/[模块名]/...
|
||||
```
|
||||
|
||||
### 集成测试
|
||||
```bash
|
||||
source .env.local && go test -v ./tests/integration/...
|
||||
```
|
||||
|
||||
### 错误码验证
|
||||
手动测试关键接口，确认：
|
||||
- 业务错误返回 4xx（如参数错误、状态不允许）
|
||||
- 系统错误返回 5xx（如数据库连接失败）
|
||||
- 错误消息不泄露内部细节
|
||||
|
||||
---
|
||||
|
||||
## 预估工作量
|
||||
|
||||
| 提案 | 文件数 | 错误点数 | 预估时间 | 优先级 |
|
||||
|-----|-------|---------|---------|-------|
|
||||
| 提案 1 | 10 | 70-80 | 2-3 小时 | 高 |
|
||||
| 提案 2 | 14 | 140-150 | 3-4 小时 | 中 |
|
||||
| 提案 3 | 30-40 | N/A | 2-3 小时 | 中 |
|
||||
| 提案 4 | 5-6 | N/A | 1-2 小时 | 中 |
|
||||
| 提案 5 | 3-4 | N/A | 1 小时 | 低 |
|
||||
|
||||
**总计**：约 9-13 小时（分 5 次完成）
|
||||
|
||||
---
|
||||
|
||||
## 风险提示
|
||||
|
||||
1. **Breaking Changes**：错误码变更可能影响现有客户端
|
||||
2. **测试覆盖**：每个模块需要补充错误场景测试
|
||||
3. **文档同步**：OpenAPI 文档变更需通知 SDK 使用方
|
||||
4. **Code Review**：每个提案需要充分的代码审查
|
||||
|
||||
建议每个提案完成后：
|
||||
- 运行全量测试
|
||||
- 在测试环境验证
|
||||
- 通过 Code Review 后再合并
|
||||
Reference in New Issue
Block a user