huang
6fc90abeb6
主要变更: 1. 新增 cmd/api/docs.go 实现文档自动生成逻辑 2. 修改 cmd/api/main.go 在服务启动时调用文档生成 3. 重构 cmd/gendocs/main.go 提取生成函数 4. 更新 .gitignore 忽略自动生成的 openapi.yaml 5. 新增 Makefile 支持 make docs 命令 6. OpenSpec 框架更新和变更归档 功能特性: - 服务启动时自动生成 OpenAPI 文档到项目根目录 - 保留独立的文档生成工具 (make docs) - 生成失败时记录错误但不影响服务启动 - 所有代码已通过 openspec validate --strict 验证 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2.9 KiB
2.9 KiB
Why
当前框架存在多处设计冲突和代码冗余，影响可维护性和开发效率：
- 存在两套 Auth 实现，错误返回格式不一致
- Handler/Service/Store 需要在 main.go 中手动注册，难以扩展
- 示例业务代码（user/order）未被清理，与真实 RBAC 代码混杂
- pkg/errors 和 pkg/response 职责重叠，使用方式不统一
- GORM 数据权限过滤已实现但未集成，自动化程度为 0%
What Changes
Phase 1: 清理和统一
- BREAKING: 删除所有示例业务代码（user/order 相关的 handler、service、store、model）
- 删除重复的
internal/middleware/auth.go，重新设计合并版本到pkg/middleware/auth.go - 简化 AppError 结构：删除 HTTPStatus 字段和 WithHTTPStatus() 方法
- 确认错误响应格式已统一（code, msg, data, timestamp 四个字段）
- 删除
pkg/response/response.go中的Error()函数，Handler 统一返回 error
Phase 2: 组件注册解耦（按模块拆分）
- 将
main.go中的initServices()逻辑提取到internal/bootstrap/包 - 按层次拆分 bootstrap 包：
stores.go,services.go,handlers.go - 创建统一的组件工厂，使 main.go 不需要了解具体业务模块
- 每个文件添加 TODO 标记用于未来扩展点
- 避免单文件臃肿，每个文件保持 < 100 行
Phase 3: 数据权限自动化
- 实现 GORM Callback 机制自动注入数据权限过滤
- 支持通过 Context 绕过权限过滤（SkipDataPermission）
- 删除未使用的
scopes.go中的手动 Scope 函数
Phase 4: 代码规范化
- 删除错误码别名，统一使用标准错误码
- 删除重复的 validator 实例，在启动时创建单例
Impact
Affected specs
- auth（新建）：统一认证中间件规范
- dependency-injection（新建）：组件注册和依赖注入规范
- data-permission（新建）：数据权限自动过滤规范
- error-handling（新建）：统一错误处理规范
Affected code
- 删除文件（10+）：
internal/handler/user.go,internal/handler/order.gointernal/model/user.go,internal/model/user_dto.gointernal/model/order.go,internal/model/order_dto.gointernal/service/user/,internal/service/order/internal/store/postgres/user_store.go,internal/store/postgres/order_store.gointernal/middleware/auth.go
- 重构文件：
cmd/api/main.go→ 简化，提取初始化逻辑pkg/middleware/auth.go→ 重新设计，统一错误格式pkg/errors/handler.go→ 统一 JSON 字段名pkg/response/response.go→ 删除 Error() 函数internal/store/postgres/→ 添加 GORM Callback 支持
- 新建文件：
internal/bootstrap/bootstrap.go→ 组件工厂和初始化逻辑pkg/gorm/callback.go→ 数据权限 GORM Callback
Migration
- 这是框架搭建阶段，无生产数据需要迁移
- 示例代码删除不影响任何现有功能