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,372 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. 移除任务模块占位代码
|
||||
|
||||
### 1.1 删除文件
|
||||
- [x] 删除 `internal/routes/task.go`
|
||||
```bash
|
||||
rm internal/routes/task.go
|
||||
```
|
||||
- [x] 删除 `internal/handler/admin/task.go`
|
||||
```bash
|
||||
rm internal/handler/admin/task.go
|
||||
```
|
||||
|
||||
### 1.2 移除引用
|
||||
- [x] 打开 `internal/routes/routes.go`
|
||||
- [x] 移除 `registerTaskRoutes(...)` 调用
|
||||
- [x] 移除相关 import（如果不再使用）
|
||||
|
||||
### 1.3 验证
|
||||
- [x] 编译检查：`go build -o /tmp/test_api ./cmd/api`
|
||||
- [x] 确认无 TaskHandler 引用：
|
||||
```bash
|
||||
grep -r "TaskHandler" internal/ | grep -v "_test.go"
|
||||
# 应无结果
|
||||
```
|
||||
|
||||
## 2. 清理注释一致性
|
||||
|
||||
### 2.1 扫描残留路径
|
||||
- [x] 查找所有 `/api/v1` 注释：
|
||||
```bash
|
||||
grep -rn "/api/v1" internal/handler/ | grep -v "_test.go" > /tmp/path_comments.txt
|
||||
cat /tmp/path_comments.txt
|
||||
```
|
||||
|
||||
### 2.2 批量修复注释
|
||||
- [x] 根据 `/tmp/path_comments.txt` 逐个修复：
|
||||
- `/api/v1/users` → `/api/admin/users`
|
||||
- `/api/v1/shops` → `/api/admin/shops`
|
||||
- `/api/v1/orders` → `/api/admin/orders` 或 `/api/h5/orders`
|
||||
- 等等
|
||||
|
||||
### 2.3 验证清理结果
|
||||
- [x] 再次扫描：
|
||||
```bash
|
||||
grep -r "/api/v1" internal/handler/ | grep -v "_test.go"
|
||||
# 应无结果
|
||||
```
|
||||
|
||||
## 3. 更新规范文档
|
||||
|
||||
### 3.1 更新错误处理规范
|
||||
- [x] 打开 `openspec/specs/error-handling/spec.md`
|
||||
- [x] 补充 Purpose 说明：
|
||||
```markdown
|
||||
## Purpose
|
||||
|
||||
统一项目的错误处理机制，确保：
|
||||
- 错误码一致性和可追踪性
|
||||
- 客户端能准确识别错误类型
|
||||
- 日志记录完整便于排查
|
||||
- 避免泄露内部实现细节
|
||||
```
|
||||
|
||||
- [x] 新增"错误报错规范"章节：
|
||||
```markdown
|
||||
## 错误报错规范（必须遵守）
|
||||
|
||||
### Handler 层
|
||||
- ❌ 禁止直接返回/拼接底层错误信息给客户端
|
||||
- ✅ 参数校验失败统一返回 `errors.New(CodeInvalidParam)`
|
||||
- ✅ 详细校验错误写日志，对外返回通用消息
|
||||
|
||||
### Service 层
|
||||
- ❌ 禁止对外返回 `fmt.Errorf(...)`
|
||||
- ✅ 业务错误使用 `errors.New(code[, msg])`
|
||||
- ✅ 系统错误使用 `errors.Wrap(code, err[, msg])`
|
||||
|
||||
### 示例
|
||||
[补充实际代码示例]
|
||||
```
|
||||
|
||||
### 3.2 更新 AGENTS.md
|
||||
- [x] 打开 `AGENTS.md`
|
||||
- [x] 在"错误处理"章节补充摘要：
|
||||
```markdown
|
||||
#### 错误报错规范（必须遵守）
|
||||
- Handler 层禁止直接返回/拼接底层错误信息（例如 `"参数验证失败: "+err.Error()`）
|
||||
- 参数校验失败：对外统一返回 `errors.New(CodeInvalidParam)`（详细错误写日志）
|
||||
- Service 层禁止对外返回 `fmt.Errorf(...)`，必须返回 `errors.New(...)` 或 `errors.Wrap(...)`
|
||||
```
|
||||
|
||||
- [x] 补充 Code Review 检查清单：
|
||||
```markdown
|
||||
## Code Review 检查清单
|
||||
|
||||
### 错误处理
|
||||
- [ ] Service 层无 `fmt.Errorf` 对外返回
|
||||
- [ ] Handler 层参数校验不泄露细节
|
||||
- [ ] 错误码使用正确（4xx vs 5xx）
|
||||
- [ ] 错误日志完整（包含上下文）
|
||||
```
|
||||
|
||||
### 3.3 更新使用指南
|
||||
- [x] 打开 `docs/003-error-handling/使用指南.md`
|
||||
- [x] 补充 Service 层错误处理实际案例：
|
||||
```markdown
|
||||
## Service 层错误处理
|
||||
|
||||
### 业务校验错误（4xx）
|
||||
|
||||
#### 示例 1：资源不存在
|
||||
[从实际代码中提取]
|
||||
|
||||
#### 示例 2：状态不允许
|
||||
[从实际代码中提取]
|
||||
|
||||
### 系统依赖错误（5xx）
|
||||
|
||||
#### 示例 3：数据库错误
|
||||
[从实际代码中提取]
|
||||
```
|
||||
|
||||
- [x] 补充 Handler 层参数校验案例：
|
||||
```markdown
|
||||
## Handler 层参数校验
|
||||
|
||||
### 参数解析错误
|
||||
[补充安全加固后的代码示例]
|
||||
|
||||
### 参数验证错误
|
||||
[补充安全加固后的代码示例]
|
||||
```
|
||||
|
||||
- [x] 补充单元测试示例：
|
||||
```markdown
|
||||
## 错误场景单元测试
|
||||
|
||||
### Service 层测试
|
||||
[补充测试代码示例]
|
||||
|
||||
### Handler 层测试
|
||||
[补充集成测试示例]
|
||||
```
|
||||
|
||||
## 4. CI 检查增强
|
||||
|
||||
### 4.1 创建检查脚本
|
||||
- [x] 创建文件：`scripts/check-service-errors.sh`
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 检查 Service 层是否使用 fmt.Errorf 对外返回
|
||||
|
||||
echo "🔍 检查 Service 层错误处理规范..."
|
||||
|
||||
FILES=$(find internal/service -name "*.go" -type f)
|
||||
VIOLATIONS=$(grep -n "fmt\.Errorf" $FILES | grep -v "// whitelist:")
|
||||
|
||||
if [ -n "$VIOLATIONS" ]; then
|
||||
echo ""
|
||||
echo "❌ 发现 Service 层使用 fmt.Errorf："
|
||||
echo "$VIOLATIONS"
|
||||
echo ""
|
||||
echo "请使用以下方式替代："
|
||||
echo " - 业务错误：errors.New(code, msg)"
|
||||
echo " - 系统错误：errors.Wrap(code, err, msg)"
|
||||
echo ""
|
||||
echo "如果某处确实需要使用 fmt.Errorf（如内部调试），请添加注释：// whitelist:"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Service 层错误处理检查通过"
|
||||
```
|
||||
|
||||
- [x] 添加执行权限：
|
||||
```bash
|
||||
chmod +x scripts/check-service-errors.sh
|
||||
```
|
||||
|
||||
### 4.2 创建注释检查脚本（可选）
|
||||
- [x] 创建文件：`scripts/check-comment-paths.sh`
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 检查注释中的 API 路径是否一致
|
||||
|
||||
echo "🔍 检查注释中的 API 路径..."
|
||||
|
||||
VIOLATIONS=$(grep -rn "/api/v1" internal/handler/ | grep -v "_test.go")
|
||||
|
||||
if [ -n "$VIOLATIONS" ]; then
|
||||
echo ""
|
||||
echo "❌ 发现残留的 /api/v1 路径注释："
|
||||
echo "$VIOLATIONS"
|
||||
echo ""
|
||||
echo "请修复为真实路径（/api/admin、/api/h5、/api/c/v1）"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ 注释路径检查通过"
|
||||
```
|
||||
|
||||
- [x] 添加执行权限：
|
||||
```bash
|
||||
chmod +x scripts/check-comment-paths.sh
|
||||
```
|
||||
|
||||
### 4.3 创建统一检查脚本
|
||||
- [x] 创建文件：`scripts/check-all.sh`
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 运行所有代码规范检查
|
||||
|
||||
set -e
|
||||
|
||||
echo "🚀 运行代码规范检查..."
|
||||
echo ""
|
||||
|
||||
bash scripts/check-service-errors.sh
|
||||
bash scripts/check-comment-paths.sh
|
||||
|
||||
echo ""
|
||||
echo "✅ 所有检查通过"
|
||||
```
|
||||
|
||||
- [x] 添加执行权限：
|
||||
```bash
|
||||
chmod +x scripts/check-all.sh
|
||||
```
|
||||
|
||||
### 4.4 测试检查脚本
|
||||
- [x] 运行 Service 错误检查：
|
||||
```bash
|
||||
bash scripts/check-service-errors.sh
|
||||
# 应返回 ✅（假设已完成提案 1 和 2）
|
||||
```
|
||||
|
||||
- [x] 测试脚本能检测违规：
|
||||
```bash
|
||||
echo 'return fmt.Errorf("test")' >> internal/service/test.go
|
||||
bash scripts/check-service-errors.sh # 应返回 ❌
|
||||
rm internal/service/test.go
|
||||
```
|
||||
|
||||
- [x] 运行注释路径检查：
|
||||
```bash
|
||||
bash scripts/check-comment-paths.sh
|
||||
# 应返回 ✅
|
||||
```
|
||||
|
||||
- [x] 运行全部检查：
|
||||
```bash
|
||||
bash scripts/check-all.sh
|
||||
```
|
||||
|
||||
### 4.5 集成到 CI（可选）
|
||||
- [x] 创建/更新 `.github/workflows/lint.yml`：
|
||||
```yaml
|
||||
name: Code Quality Check
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, develop ]
|
||||
pull_request:
|
||||
branches: [ main, develop ]
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v4
|
||||
with:
|
||||
go-version: '1.25'
|
||||
|
||||
- name: Run Code Quality Checks
|
||||
run: bash scripts/check-all.sh
|
||||
```
|
||||
|
||||
## 5. 全量验证
|
||||
|
||||
### 5.1 代码清理验证
|
||||
- [x] 确认文件已删除：
|
||||
```bash
|
||||
ls internal/routes/task.go # 应返回 No such file
|
||||
ls internal/handler/admin/task.go # 应返回 No such file
|
||||
```
|
||||
|
||||
- [x] 确认引用已移除：
|
||||
```bash
|
||||
grep -r "registerTaskRoutes" internal/ # 应无结果
|
||||
grep -r "TaskHandler" internal/ | grep -v "_test.go" # 应无结果
|
||||
```
|
||||
|
||||
### 5.2 注释清理验证
|
||||
- [x] 确认无残留 `/api/v1` 注释：
|
||||
```bash
|
||||
grep -r "/api/v1" internal/handler/ | grep -v "_test.go" # 应无结果
|
||||
```
|
||||
|
||||
### 5.3 编译检查
|
||||
- [x] `go build -o /tmp/test_api ./cmd/api`
|
||||
- [x] `go build -o /tmp/test_worker ./cmd/worker`
|
||||
|
||||
### 5.4 CI 检查验证
|
||||
- [x] 运行所有检查脚本：
|
||||
```bash
|
||||
bash scripts/check-all.sh # 应返回 ✅
|
||||
```
|
||||
|
||||
### 5.5 文档完整性检查
|
||||
- [x] 确认规范文档已更新：
|
||||
```bash
|
||||
grep "错误报错规范" openspec/specs/error-handling/spec.md
|
||||
grep "错误报错规范" AGENTS.md
|
||||
grep "Service 层错误处理" docs/003-error-handling/使用指南.md
|
||||
```
|
||||
|
||||
- [x] 确认文档包含实际案例（非空占位）
|
||||
|
||||
## 6. README 更新（可选）
|
||||
|
||||
### 6.1 补充 CI 检查说明
|
||||
- [x] 在 `README.md` 中补充"代码规范检查"章节：
|
||||
```markdown
|
||||
## 代码规范检查
|
||||
|
||||
运行代码规范检查：
|
||||
|
||||
\`\`\`bash
|
||||
# 检查 Service 层错误处理
|
||||
bash scripts/check-service-errors.sh
|
||||
|
||||
# 检查注释路径一致性
|
||||
bash scripts/check-comment-paths.sh
|
||||
|
||||
# 运行所有检查
|
||||
bash scripts/check-all.sh
|
||||
\`\`\`
|
||||
|
||||
这些检查会在 CI/CD 流程中自动执行。
|
||||
```
|
||||
|
||||
## 验证清单
|
||||
|
||||
- [x] 任务模块文件已删除
|
||||
- [x] 任务模块引用已移除
|
||||
- [x] 注释路径已统一
|
||||
- [x] 错误处理规范已更新（spec.md）
|
||||
- [x] 开发规范已更新（AGENTS.md）
|
||||
- [x] 使用指南已更新（包含实际案例）
|
||||
- [x] CI 检查脚本已创建
|
||||
- [x] CI 检查脚本测试通过
|
||||
- [x] 编译通过，无语法错误
|
||||
- [x] 全量检查脚本通过
|
||||
- [x] 文档完整性验证通过
|
||||
- [x] README 已更新（如需要）
|
||||
|
||||
## 预估工作量
|
||||
|
||||
| 任务 | 预估时间 |
|
||||
|-----|---------|
|
||||
| 1. 移除任务模块 | 0.5h |
|
||||
| 2. 清理注释一致性 | 0.5h |
|
||||
| 3. 更新规范文档 | 1h |
|
||||
| 4. CI 检查增强 | 0.5h |
|
||||
| 5. 全量验证 | 0.5h |
|
||||
| 6. README 更新（可选） | 0.5h |
|
||||
|
||||
**总计**：约 3.5 小时
|
||||
Reference in New Issue
Block a user