邹方成
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: 添加道具卡测试脚本
39 lines
2.3 KiB
Markdown
39 lines
2.3 KiB
Markdown
# CONSENSUS: 开发规范
|
||
|
||
## 1. 需求描述和验收标准
|
||
|
||
**需求描述**：
|
||
基于对 `/internal/api/admin` 模块代码的分析，制定一套清晰、统一的 Go API 开发规范。该规范将作为项目后续所有 API 开发的强制标准，以确保代码质量、一致性和可维护性。
|
||
|
||
**验收标准**：
|
||
1. 生成一份完整的 `docs/开发规范.md` 文档。
|
||
2. 文档内容必须准确反映从 `admin` 模块总结出的最佳实践。
|
||
3. 规范应覆盖从 API 定义、实现到错误处理的全过程。
|
||
4. 规范应明确代码风格、目录结构、命名约定等关键要素。
|
||
5. 所有示例代码必须符合规范本身，并能作为开发者参考的模板。
|
||
|
||
## 2. 技术实现方案
|
||
|
||
将遵循以下步骤来产出最终的规范文档：
|
||
|
||
1. **结构设计**：将规范文档分为不同章节，如“目录结构”、“命名规范”、“API Handler 规范”、“数据传输对象 (DTO)”、“错误处理”等。
|
||
2. **内容撰写**：在每个章节中，详细描述具体的规则，并提供从 `admin` 模块中提取的**正例代码**作为示范。
|
||
3. **规则提炼**：将观察到的模式提炼为必须遵守的规则，例如：
|
||
* 每个 API Handler 必须返回 `core.HandlerFunc`。
|
||
* 使用 `ctx.ShouldBindJSON()` 进行参数绑定和基础校验。
|
||
* 通过 `ctx.AbortWithError()` 统一处理错误。
|
||
* 使用 `ctx.Payload()` 返回成功响应。
|
||
* 请求和响应结构体必须包含 `json` tag，并提供清晰的字段注释。
|
||
* 必须为每个 API 编写完整的 Swagger 注解。
|
||
4. **文档生成**：将所有内容整合到 `docs/开发规范.md` 文件中。
|
||
|
||
## 3. 任务边界限制
|
||
|
||
* **仅限于文档**：此任务不涉及任何代码的创建、修改或删除。
|
||
* **聚焦于 API 层**：规范主要针对 `internal/api` 层的开发，对于 `service` 层和 `repository` 层的规范，虽然可以借鉴其思想，但不是本次任务的重点。
|
||
* **基于现有实践**：所有规范都必须源于对现有 `admin` 代码的分析，不允许凭空创造规则。
|
||
|
||
## 4. 确认所有不确定性已解决
|
||
|
||
通过 `ALIGNMENT` 阶段的分析，所有关于任务目标、范围和方法的不确定性均已解决。现在可以进入 `Architect`（架构）阶段，设计最终规范文档的详细结构。
|