完善 DTO 规范:统一 description 标签并添加 AI 助手自动检查指引
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 4m28s
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 4m28s
- 修复所有 DTO 文件的 description 标签(10 个文件) - 枚举字段统一使用中文说明(用户类型、角色类型、权限类型等) - 状态字段明确说明 0/1 含义 - validate 标签与 OpenAPI 标签保持一致 - 在 AGENTS.md 和 CLAUDE.md 添加 DTO 规范章节 - AI 助手必须执行的 7 项检查清单 - 常见枚举字段标准值参考 - 确保未来 AI 助手自动遵循规范 - 创建规范文档 - docs/code-review-checklist.md(Code Review 检查清单) - docs/dto-improvement-summary.md(DTO 改进总结) - docs/ai-dto-guidelines-update.md(AI 指引更新说明) - 重新生成 OpenAPI 文档(375 个 description 标签) 影响:所有 API 字段现在都有清晰的中文说明,前端开发更友好
This commit is contained in:
40
CLAUDE.md
40
CLAUDE.md
@@ -96,6 +96,46 @@ tests/
|
||||
- Go 文档注释(doc comments for exported APIs)可以使用英文以保持生态兼容性,但中文注释更佳
|
||||
- 变量名、函数名、类型名必须使用英文(遵循 Go 命名规范)
|
||||
|
||||
**DTO 规范(API 文档生成基础):**
|
||||
|
||||
所有 DTO 文件必须严格遵循以下规范,这是 OpenAPI 文档自动生成的基础:
|
||||
|
||||
1. **所有字段必须使用 `description` 标签**(禁止使用行内注释)
|
||||
```go
|
||||
// ✅ 正确
|
||||
Username string `json:"username" description:"用户名"`
|
||||
|
||||
// ❌ 错误
|
||||
Username string `json:"username"` // 用户名
|
||||
```
|
||||
|
||||
2. **枚举字段必须列出所有可能值(使用中文)**
|
||||
```go
|
||||
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
```
|
||||
|
||||
3. **validate 标签必须与 OpenAPI 标签一致**
|
||||
```go
|
||||
Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
|
||||
```
|
||||
|
||||
4. **Query 和 Path 参数必须添加对应标签**
|
||||
```go
|
||||
Page int `json:"page" query:"page" description:"页码"`
|
||||
ID uint `path:"id" description:"ID" required:"true"`
|
||||
```
|
||||
|
||||
5. **AI 助手在创建/修改 DTO 后必须执行以下检查**:
|
||||
- ✅ 所有字段都有 `description` 标签
|
||||
- ✅ 枚举字段列出了所有可能值(中文)
|
||||
- ✅ 状态字段说明了 0 和 1 的含义
|
||||
- ✅ validate 标签与 OpenAPI 标签一致
|
||||
- ✅ 禁止使用英文枚举值
|
||||
- ✅ 重新生成文档验证:`go run cmd/gendocs/main.go`
|
||||
|
||||
详细规范参见:`docs/code-review-checklist.md`
|
||||
|
||||
**Go 代码风格要求:**
|
||||
|
||||
- 必须使用 `gofmt` 格式化所有代码
|
||||
|
||||
Reference in New Issue
Block a user