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,543 @@
|
||||
# 设计文档：代码清理和规范文档更新
|
||||
|
||||
## 概述
|
||||
|
||||
本变更旨在清理项目中的临时代码和不一致的注释，完善规范文档，并增强 CI 检查，确保代码质量和规范一致性。
|
||||
|
||||
## 设计目标
|
||||
|
||||
1. **代码清理**：移除未使用的占位代码，避免潜在的安全风险
|
||||
2. **注释一致性**：确保代码注释与实际路由路径一致
|
||||
3. **规范完善**：补充缺失的规范文档和实际案例
|
||||
4. **自动化检查**：通过 CI 脚本自动检测规范违规
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 1. 任务模块清理
|
||||
|
||||
#### 现状分析
|
||||
|
||||
```
|
||||
internal/
|
||||
├── routes/
|
||||
│ ├── routes.go
|
||||
│ └── task.go # 占位路由，未接入业务
|
||||
└── handler/
|
||||
└── admin/
|
||||
└── task.go # 占位 Handler，空实现
|
||||
```
|
||||
|
||||
**问题**：
|
||||
- 占位代码可能被误用，导致鉴权不一致
|
||||
- 增加代码维护成本
|
||||
- 没有实际业务价值
|
||||
|
||||
#### 解决方案
|
||||
|
||||
**完全移除策略**：
|
||||
- 删除 `internal/routes/task.go`
|
||||
- 删除 `internal/handler/admin/task.go`
|
||||
- 从 `internal/routes/routes.go` 移除 `registerTaskRoutes()` 调用
|
||||
- 清理相关 import
|
||||
|
||||
**不采用保留注释/TODO 的原因**：
|
||||
- 如需任务功能，应重新设计实现
|
||||
- 避免遗留代码污染代码库
|
||||
|
||||
### 2. 注释路径清理
|
||||
|
||||
#### 现状分析
|
||||
|
||||
Handler 层注释中存在已弃用的路径：
|
||||
|
||||
```go
|
||||
// 错误示例
|
||||
// @Summary 获取用户列表
|
||||
// @Router /api/v1/users [get] // ❌ 已不存在
|
||||
func ListUsers(c *fiber.Ctx) error { ... }
|
||||
|
||||
// 正确示例
|
||||
// @Summary 获取用户列表
|
||||
// @Router /api/admin/users [get] // ✅ 与真实路由一致
|
||||
func ListUsers(c *fiber.Ctx) error { ... }
|
||||
```
|
||||
|
||||
**真实路由体系**：
|
||||
- `/api/admin/*`：后台管理接口
|
||||
- `/api/h5/*`：H5 端接口
|
||||
- `/api/c/v1/*`：个人客户接口
|
||||
|
||||
#### 解决方案
|
||||
|
||||
**扫描和修复流程**：
|
||||
|
||||
```bash
|
||||
# 1. 扫描所有残留路径
|
||||
grep -rn "/api/v1" internal/handler/ | grep -v "_test.go" > /tmp/path_comments.txt
|
||||
|
||||
# 2. 根据模块修复
|
||||
# - internal/handler/admin/*.go → /api/admin/*
|
||||
# - internal/handler/h5/*.go → /api/h5/*
|
||||
# - internal/handler/personal/*.go → /api/c/v1/*
|
||||
|
||||
# 3. 验证清理结果
|
||||
grep -r "/api/v1" internal/handler/ | grep -v "_test.go" # 应无结果
|
||||
```
|
||||
|
||||
### 3. 规范文档更新
|
||||
|
||||
#### 3.1 错误处理规范（openspec/specs/error-handling/spec.md）
|
||||
|
||||
**新增内容**：
|
||||
|
||||
##### Purpose 章节
|
||||
|
||||
```markdown
|
||||
## Purpose
|
||||
|
||||
统一项目的错误处理机制，确保：
|
||||
- 错误码一致性和可追踪性
|
||||
- 客户端能准确识别错误类型
|
||||
- 日志记录完整便于排查
|
||||
- 避免泄露内部实现细节
|
||||
```
|
||||
|
||||
##### 错误报错规范章节
|
||||
|
||||
```markdown
|
||||
## 错误报错规范（必须遵守）
|
||||
|
||||
### Handler 层
|
||||
|
||||
**禁止行为**：
|
||||
- ❌ 直接返回/拼接底层错误信息给客户端
|
||||
```go
|
||||
// 错误示例
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数验证失败: "+err.Error())
|
||||
```
|
||||
|
||||
**正确做法**：
|
||||
- ✅ 参数校验失败统一返回 `errors.New(CodeInvalidParam)`
|
||||
- ✅ 详细校验错误写日志，对外返回通用消息
|
||||
```go
|
||||
// 正确示例
|
||||
if err := c.BodyParser(&req); err != nil {
|
||||
logger.Error("参数解析失败", zap.Error(err))
|
||||
return errors.New(errors.CodeInvalidParam)
|
||||
}
|
||||
```
|
||||
|
||||
### Service 层
|
||||
|
||||
**禁止行为**：
|
||||
- ❌ 对外返回 `fmt.Errorf(...)`
|
||||
```go
|
||||
// 错误示例
|
||||
return fmt.Errorf("用户不存在: %w", err)
|
||||
```
|
||||
|
||||
**正确做法**：
|
||||
- ✅ 业务错误使用 `errors.New(code[, msg])`
|
||||
- ✅ 系统错误使用 `errors.Wrap(code, err[, msg])`
|
||||
```go
|
||||
// 正确示例
|
||||
if user == nil {
|
||||
return errors.New(errors.CodeUserNotFound, "用户不存在")
|
||||
}
|
||||
if err := db.Save(&user).Error; err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "保存用户失败")
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
#### 3.2 开发规范（AGENTS.md）
|
||||
|
||||
**新增 Code Review 检查清单**：
|
||||
|
||||
```markdown
|
||||
## Code Review 检查清单
|
||||
|
||||
### 错误处理
|
||||
- [ ] Service 层无 `fmt.Errorf` 对外返回
|
||||
- [ ] Handler 层参数校验不泄露细节
|
||||
- [ ] 错误码使用正确（4xx vs 5xx）
|
||||
- [ ] 错误日志完整（包含上下文）
|
||||
|
||||
### 代码质量
|
||||
- [ ] 遵循 Handler → Service → Store → Model 分层
|
||||
- [ ] 函数长度 ≤ 100 行（核心逻辑 ≤ 50 行）
|
||||
- [ ] 常量定义在 `pkg/constants/`
|
||||
- [ ] 使用 Go 惯用法（非 Java 风格）
|
||||
|
||||
### 测试覆盖
|
||||
- [ ] 核心业务逻辑测试覆盖率 ≥ 90%
|
||||
- [ ] 所有 API 端点有集成测试
|
||||
- [ ] 测试验证真实功能（不绕过核心逻辑）
|
||||
|
||||
### 文档和注释
|
||||
- [ ] 所有注释使用中文
|
||||
- [ ] 导出函数/类型有文档注释
|
||||
- [ ] API 路径注释与真实路由一致
|
||||
```
|
||||
|
||||
#### 3.3 使用指南（docs/003-error-handling/使用指南.md）
|
||||
|
||||
**补充实际案例**：
|
||||
|
||||
从现有代码库中提取真实案例：
|
||||
- Service 层业务校验错误示例
|
||||
- Service 层系统依赖错误示例
|
||||
- Handler 层参数校验示例
|
||||
- 单元测试示例
|
||||
|
||||
### 4. CI 检查增强
|
||||
|
||||
#### 4.1 Service 层错误检查脚本
|
||||
|
||||
**文件**：`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 层错误处理检查通过"
|
||||
```
|
||||
|
||||
**设计考虑**：
|
||||
- 仅检查 `internal/service` 目录
|
||||
- 跳过带有 `// whitelist:` 注释的行（特殊场景）
|
||||
- 返回非零退出码以集成到 CI
|
||||
|
||||
#### 4.2 注释路径检查脚本
|
||||
|
||||
**文件**：`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 "✅ 注释路径检查通过"
|
||||
```
|
||||
|
||||
#### 4.3 统一检查脚本
|
||||
|
||||
**文件**：`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 "✅ 所有检查通过"
|
||||
```
|
||||
|
||||
**用途**：
|
||||
- 本地开发：`bash scripts/check-all.sh`
|
||||
- CI 集成：在 `.github/workflows/lint.yml` 中调用
|
||||
|
||||
#### 4.4 CI 集成（可选）
|
||||
|
||||
**文件**：`.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
|
||||
```
|
||||
|
||||
## 数据流设计
|
||||
|
||||
### 注释清理流程
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 注释清理流程 │
|
||||
└────────────────────────────┬────────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 1. 扫描残留路径 │
|
||||
│ grep -rn "/api/v1" │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 2. 分析文件模块 │
|
||||
│ - admin/ → /api/admin │
|
||||
│ - h5/ → /api/h5 │
|
||||
│ - personal/ → /api/c │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 3. 批量修复注释 │
|
||||
│ - 手动编辑文件 │
|
||||
│ - 或使用 sed 批量替换 │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 4. 验证清理结果 │
|
||||
│ grep -r "/api/v1" │
|
||||
│ 应无结果 │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
### CI 检查流程
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ CI 检查流程 │
|
||||
└────────────────────────────┬────────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 1. 代码提交/PR │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 2. 触发 GitHub Actions │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 3. 运行 check-all.sh │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────────────┼────────────────────┐
|
||||
│ │ │
|
||||
┌───────▼────────┐ ┌────────▼────────┐ ┌───────▼────────┐
|
||||
│ Service 错误检查│ │ 注释路径检查 │ │ 其他检查... │
|
||||
└───────┬────────┘ └────────┬────────┘ └───────┬────────┘
|
||||
│ │ │
|
||||
└────────────────────┼────────────────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ 4. 汇总结果 │
|
||||
│ - ✅ 全部通过 │
|
||||
│ - ❌ 有违规 │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 5. 反馈结果到 PR │
|
||||
│ - 通过：允许合并 │
|
||||
│ - 失败：阻止合并 │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
## 技术决策
|
||||
|
||||
### 1. 为什么完全删除任务模块而非保留注释？
|
||||
|
||||
**决策**：完全删除占位代码
|
||||
|
||||
**理由**：
|
||||
- **避免误用**：占位代码可能被后续开发者误用
|
||||
- **代码简洁**：减少维护成本和认知负担
|
||||
- **版本控制**：Git 历史保留了代码，需要时可恢复
|
||||
- **重新设计**：如需任务功能，应基于实际需求设计
|
||||
|
||||
### 2. 为什么只检查 Service 层的 fmt.Errorf？
|
||||
|
||||
**决策**：只强制检查 Service 层
|
||||
|
||||
**理由**：
|
||||
- **影响范围**：Service 层错误直接影响客户端体验
|
||||
- **降低噪音**：Handler 层有时需要拼接调试信息（不对外返回）
|
||||
- **测试文件**：测试代码可以使用 `fmt.Errorf` 构造错误
|
||||
|
||||
**特殊场景处理**：
|
||||
- 内部调试需要 `fmt.Errorf`：添加 `// whitelist:` 注释跳过检查
|
||||
|
||||
### 3. 为什么文档案例从实际代码提取？
|
||||
|
||||
**决策**：使用真实代码案例而非虚构示例
|
||||
|
||||
**理由**：
|
||||
- **实用性**：开发者可直接参考实际实现
|
||||
- **一致性**：确保文档与代码同步
|
||||
- **可信度**：真实案例更有说服力
|
||||
|
||||
### 4. CI 集成为什么设为可选？
|
||||
|
||||
**决策**：CI 集成为可选任务
|
||||
|
||||
**理由**：
|
||||
- **灵活性**：本地开发可直接运行脚本
|
||||
- **渐进式**：项目可选择何时启用 CI
|
||||
- **成本考虑**：小型项目可能不需要 CI
|
||||
|
||||
## 非功能性需求
|
||||
|
||||
### 性能考虑
|
||||
|
||||
- **脚本性能**：检查脚本应在 10 秒内完成
|
||||
- **CI 耗时**：代码检查不应显著增加 CI 时间（< 30 秒）
|
||||
|
||||
### 可维护性
|
||||
|
||||
- **脚本可读性**：使用清晰的错误消息和帮助文本
|
||||
- **规则扩展**：易于添加新的检查规则
|
||||
- **白名单机制**：支持特殊场景豁免
|
||||
|
||||
### 兼容性
|
||||
|
||||
- **Shell 兼容性**：脚本使用 Bash 标准语法（兼容 Linux/macOS）
|
||||
- **工具依赖**：仅依赖标准工具（grep、find），无需额外安装
|
||||
|
||||
## 验证策略
|
||||
|
||||
### 1. 代码清理验证
|
||||
|
||||
```bash
|
||||
# 确认文件已删除
|
||||
test ! -f internal/routes/task.go
|
||||
test ! -f internal/handler/admin/task.go
|
||||
|
||||
# 确认引用已移除
|
||||
! grep -r "registerTaskRoutes" internal/
|
||||
! grep -r "TaskHandler" internal/ | grep -v "_test.go"
|
||||
|
||||
# 编译检查
|
||||
go build -o /tmp/test_api ./cmd/api
|
||||
go build -o /tmp/test_worker ./cmd/worker
|
||||
```
|
||||
|
||||
### 2. 注释清理验证
|
||||
|
||||
```bash
|
||||
# 确认无残留 /api/v1 注释
|
||||
! grep -r "/api/v1" internal/handler/ | grep -v "_test.go"
|
||||
```
|
||||
|
||||
### 3. CI 脚本验证
|
||||
|
||||
```bash
|
||||
# 运行检查（应通过）
|
||||
bash scripts/check-all.sh
|
||||
|
||||
# 测试能检测违规（应失败）
|
||||
echo 'return fmt.Errorf("test")' >> internal/service/test_violation.go
|
||||
bash scripts/check-service-errors.sh # 应返回退出码 1
|
||||
rm internal/service/test_violation.go
|
||||
|
||||
# 测试白名单机制（应通过）
|
||||
echo 'return fmt.Errorf("debug") // whitelist:' >> internal/service/test.go
|
||||
bash scripts/check-service-errors.sh # 应返回退出码 0
|
||||
rm internal/service/test.go
|
||||
```
|
||||
|
||||
### 4. 文档完整性验证
|
||||
|
||||
```bash
|
||||
# 确认规范文档已更新
|
||||
grep -q "错误报错规范" openspec/specs/error-handling/spec.md
|
||||
grep -q "错误报错规范" AGENTS.md
|
||||
grep -q "Service 层错误处理" docs/003-error-handling/使用指南.md
|
||||
|
||||
# 确认文档包含实际案例（非空占位）
|
||||
test $(wc -l < docs/003-error-handling/使用指南.md) -gt 100
|
||||
```
|
||||
|
||||
## 实施计划
|
||||
|
||||
### 阶段 1：代码清理（0.5h）
|
||||
|
||||
1. 删除任务模块文件
|
||||
2. 移除路由注册调用
|
||||
3. 编译验证
|
||||
|
||||
### 阶段 2：注释清理（0.5h）
|
||||
|
||||
1. 扫描残留路径
|
||||
2. 批量修复注释
|
||||
3. 验证清理结果
|
||||
|
||||
### 阶段 3：文档更新（1h）
|
||||
|
||||
1. 更新错误处理规范
|
||||
2. 更新开发规范
|
||||
3. 补充使用指南案例
|
||||
|
||||
### 阶段 4：CI 增强（0.5h）
|
||||
|
||||
1. 创建检查脚本
|
||||
2. 测试脚本功能
|
||||
3. 更新 README
|
||||
|
||||
### 阶段 5：全量验证（0.5h）
|
||||
|
||||
1. 运行所有验证命令
|
||||
2. 确认文档完整性
|
||||
3. 更新 README
|
||||
|
||||
## 风险和缓解
|
||||
|
||||
| 风险 | 影响 | 缓解措施 |
|
||||
|------|------|---------|
|
||||
| 误删有用代码 | 高 | 仔细审查 Git 历史，确认代码未被引用 |
|
||||
| 注释修复遗漏 | 中 | 使用自动化脚本扫描，手动验证结果 |
|
||||
| CI 脚本误报 | 中 | 提供白名单机制，允许特殊场景豁免 |
|
||||
| 文档案例过时 | 低 | 从当前代码库提取，确保时效性 |
|
||||
|
||||
## 总结
|
||||
|
||||
本设计通过系统化的方法清理代码、完善文档、增强 CI 检查，确保项目代码质量和规范一致性。关键设计决策包括：
|
||||
|
||||
1. **完全删除**占位代码而非保留注释
|
||||
2. **自动化检查** Service 层错误处理规范
|
||||
3. **真实案例**补充文档使用指南
|
||||
4. **渐进式集成** CI 检查（可选）
|
||||
|
||||
预计总工作量约 3 小时，无 Breaking Changes，对现有功能无影响。
|
||||
Reference in New Issue
Block a user