huang
9795bb9ace
- 新增 6 个 Skill 文件：api-routing, db-migration, db-validation, doc-management, dto-standards, model-standards - 简化 AGENTS.md 和 CLAUDE.md，保留核心规范，详细内容移至 Skills - 添加 Skills 触发表格，说明各规范的加载时机 - 优化规范文档结构，提升可维护性和可读性
150 lines
4.7 KiB
Markdown
150 lines
4.7 KiB
Markdown
---
|
||
name: dto-standards
|
||
description: DTO 数据传输对象规范。创建或修改 DTO 文件、请求/响应结构时使用。包含 description 标签、枚举字段、验证标签等规范。
|
||
---
|
||
|
||
# DTO 规范
|
||
|
||
**所有 DTO 文件必须遵循以下规范，这是 API 文档生成的基础。**
|
||
|
||
## 触发条件
|
||
|
||
在以下情况下必须遵守本规范：
|
||
- 创建或修改 `internal/model/` 下的请求/响应 DTO
|
||
- 创建 `XXXRequest`、`XXXResponse`、`XXXReq`、`XXXResp` 结构体
|
||
- 添加或修改 API 接口的输入输出参数
|
||
|
||
## 必须项（MUST）
|
||
|
||
### 1. Description 标签规范
|
||
|
||
**所有字段必须使用 `description` 标签，禁止使用行内注释**
|
||
|
||
❌ **错误**：
|
||
```go
|
||
type CreateUserRequest struct {
|
||
Username string `json:"username"` // 用户名
|
||
Status int `json:"status"` // 状态
|
||
}
|
||
```
|
||
|
||
✅ **正确**：
|
||
```go
|
||
type CreateUserRequest struct {
|
||
Username string `json:"username" description:"用户名"`
|
||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||
}
|
||
```
|
||
|
||
### 2. 枚举字段必须列出所有可能值（中文）
|
||
|
||
**所有枚举类型字段必须在 `description` 中列出所有可能值和对应的中文含义**
|
||
|
||
```go
|
||
// 用户类型
|
||
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||
|
||
// 角色类型
|
||
RoleType int `json:"role_type" description:"角色类型 (1:平台角色, 2:客户角色)"`
|
||
|
||
// 权限类型
|
||
PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`
|
||
|
||
// 状态字段
|
||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||
|
||
// 适用端口
|
||
Platform string `json:"platform" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
|
||
```
|
||
|
||
❌ **禁止使用英文枚举值**：
|
||
```go
|
||
UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform)"` // 错误！
|
||
```
|
||
|
||
### 3. 验证标签与 OpenAPI 标签一致
|
||
|
||
**所有验证约束必须同时在 `validate` 和 OpenAPI 标签中声明**
|
||
|
||
```go
|
||
Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
|
||
```
|
||
|
||
**标签对照表**：
|
||
|
||
| validate 标签 | OpenAPI 标签 | 说明 |
|
||
|--------------|--------------|------|
|
||
| `required` | `required:"true"` | 必填字段 |
|
||
| `min=N,max=M` | `minimum:"N" maximum:"M"` | 数值范围 |
|
||
| `min=N,max=M` (字符串) | `minLength:"N" maxLength:"M"` | 字符串长度 |
|
||
| `len=N` | `minLength:"N" maxLength:"N"` | 固定长度 |
|
||
| `oneof=A B C` | `description` 中说明 | 枚举值 |
|
||
|
||
### 4. 请求参数类型标签
|
||
|
||
**Query 参数和 Path 参数必须添加对应标签**
|
||
|
||
```go
|
||
// Query 参数
|
||
type ListRequest struct {
|
||
Page int `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
|
||
UserType *int `json:"user_type" query:"user_type" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||
}
|
||
|
||
// Path 参数
|
||
type IDReq struct {
|
||
ID uint `path:"id" description:"ID" required:"true"`
|
||
}
|
||
```
|
||
|
||
### 5. 响应 DTO 完整性
|
||
|
||
**所有响应 DTO 的字段都必须有完整的 `description` 标签**
|
||
|
||
```go
|
||
type AccountResponse struct {
|
||
ID uint `json:"id" description:"账号ID"`
|
||
Username string `json:"username" description:"用户名"`
|
||
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||
UpdatedAt string `json:"updated_at" description:"更新时间"`
|
||
}
|
||
```
|
||
|
||
## AI 助手必须执行的检查
|
||
|
||
**在创建或修改任何 DTO 文件后，必须执行以下检查：**
|
||
|
||
1. ✅ 检查所有字段是否有 `description` 标签
|
||
2. ✅ 检查枚举字段是否列出了所有可能值（中文）
|
||
3. ✅ 检查状态字段是否说明了 0 和 1 的含义
|
||
4. ✅ 检查 validate 标签与 OpenAPI 标签是否一致
|
||
5. ✅ 检查是否禁止使用行内注释替代 description
|
||
6. ✅ 检查枚举值是否使用中文而非英文
|
||
7. ✅ 重新生成 OpenAPI 文档验证：`go run cmd/gendocs/main.go`
|
||
|
||
**详细检查清单**: 参见 `docs/code-review-checklist.md`
|
||
|
||
## 常见枚举字段标准值
|
||
|
||
```go
|
||
// 用户类型
|
||
description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"
|
||
|
||
// 角色类型
|
||
description:"角色类型 (1:平台角色, 2:客户角色)"
|
||
|
||
// 权限类型
|
||
description:"权限类型 (1:菜单, 2:按钮)"
|
||
|
||
// 适用端口
|
||
description:"适用端口 (all:全部, web:Web后台, h5:H5端)"
|
||
|
||
// 状态
|
||
description:"状态 (0:禁用, 1:启用)"
|
||
|
||
// 店铺层级
|
||
description:"店铺层级 (1-7级)"
|
||
```
|