邹方成
1ab39d2f5a
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 25s
feat(admin): 新增工会管理功能 feat(activity): 添加活动管理相关服务 feat(user): 实现用户道具卡和积分管理 feat(guild): 新增工会成员管理功能 fix: 修复数据库连接配置 fix: 修正jwtoken导入路径 fix: 解决端口冲突问题 style: 统一代码格式和注释风格 style: 更新项目常量命名 docs: 添加项目框架和开发规范文档 docs: 更新接口文档注释 chore: 移除无用代码和文件 chore: 更新Makefile和配置文件 chore: 清理日志文件 test: 添加道具卡测试脚本
2.3 KiB
2.3 KiB
CONSENSUS: 开发规范
1. 需求描述和验收标准
需求描述：
基于对 /internal/api/admin 模块代码的分析，制定一套清晰、统一的 Go API 开发规范。该规范将作为项目后续所有 API 开发的强制标准，以确保代码质量、一致性和可维护性。
验收标准：
- 生成一份完整的
docs/开发规范.md文档。 - 文档内容必须准确反映从
admin模块总结出的最佳实践。 - 规范应覆盖从 API 定义、实现到错误处理的全过程。
- 规范应明确代码风格、目录结构、命名约定等关键要素。
- 所有示例代码必须符合规范本身，并能作为开发者参考的模板。
2. 技术实现方案
将遵循以下步骤来产出最终的规范文档：
- 结构设计：将规范文档分为不同章节，如“目录结构”、“命名规范”、“API Handler 规范”、“数据传输对象 (DTO)”、“错误处理”等。
- 内容撰写：在每个章节中，详细描述具体的规则，并提供从
admin模块中提取的正例代码作为示范。 - 规则提炼：将观察到的模式提炼为必须遵守的规则，例如：
- 每个 API Handler 必须返回
core.HandlerFunc。 - 使用
ctx.ShouldBindJSON()进行参数绑定和基础校验。 - 通过
ctx.AbortWithError()统一处理错误。 - 使用
ctx.Payload()返回成功响应。 - 请求和响应结构体必须包含
jsontag，并提供清晰的字段注释。 - 必须为每个 API 编写完整的 Swagger 注解。
- 每个 API Handler 必须返回
- 文档生成：将所有内容整合到
docs/开发规范.md文件中。
3. 任务边界限制
- 仅限于文档：此任务不涉及任何代码的创建、修改或删除。
- 聚焦于 API 层：规范主要针对
internal/api层的开发，对于service层和repository层的规范，虽然可以借鉴其思想，但不是本次任务的重点。 - 基于现有实践：所有规范都必须源于对现有
admin代码的分析，不允许凭空创造规则。
4. 确认所有不确定性已解决
通过 ALIGNMENT 阶段的分析，所有关于任务目标、范围和方法的不确定性均已解决。现在可以进入 Architect（架构）阶段，设计最终规范文档的详细结构。