junhong_cmp_fiber/docs/code-review-checklist.md

Code Review 检查清单

📋 DTO 规范检查清单

在提交 Pull Request 前，请确保所有 DTO 文件遵循以下规范。

---

✅ 必须项（MUST）

1. Description 标签规范

所有字段必须使用 description 标签，禁止使用行内注释

❌ 错误示例：

type CreateUserRequest struct {
    Username string `json:"username"` // 用户名
    Status   int    `json:"status"`   // 状态
}

✅ 正确示例：

type CreateUserRequest struct {
    Username string `json:"username" description:"用户名"`
    Status   int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
}

---

2. 枚举字段必须列出所有可能值（中文说明）

所有枚举类型字段必须在 description 中列出所有可能值和对应的中文含义

用户类型

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端)"`

---

3. 验证标签与 OpenAPI 标签一致

所有验证约束必须同时在 validate 和 OpenAPI 标签中声明

✅ 正确示例：

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 参数必须添加对应标签

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:"用户类型"`
}

Path 参数

type IDReq struct {
    ID uint `path:"id" description:"ID" required:"true"`
}

---

5. 响应 DTO 完整性

所有响应 DTO 的字段都必须有完整的 description 标签

✅ 正确示例：

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:"更新时间"`
}

---

🔍 推荐项（SHOULD）

6. 字段顺序规范

建议按以下顺序组织字段：

1. 主键字段（ID）
2. 业务核心字段（名称、编号等）
3. 关联字段（外键）
4. 状态字段
5. 审计字段（Creator、Updater、CreatedAt、UpdatedAt）

---

7. 中文注释完整性

所有导出的结构体、方法、常量必须有中文 godoc 注释

✅ 正确示例：

// CreateAccountRequest 创建账号请求
type CreateAccountRequest struct {
    // ...
}

// AccountResponse 账号响应
type AccountResponse struct {
    // ...
}

---

8. 必填字段和可选字段区分

使用指针类型标识可选字段

type UpdateRequest struct {
    Username *string `json:"username" description:"用户名（可选）"`        // 可选
    Status   *int    `json:"status" description:"状态（可选）"`            // 可选
}

type CreateRequest struct {
    Username string `json:"username" required:"true" description:"用户名"`  // 必填
    Status   int    `json:"status" required:"true" description:"状态"`     // 必填
}

---

🚫 禁止项（MUST NOT）

9. 禁止使用英文枚举值说明

❌ 错误：

UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform, 3:Agent, 4:Enterprise)"`

✅ 正确：

UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`

---

10. 禁止缺失枚举值说明

❌ 错误：

Status int `json:"status" description:"状态"`

✅ 正确：

Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`

---

11. 禁止不一致的 description

同一字段在不同 DTO 中必须使用一致的 description

✅ 正确示例：

// CreateAccountRequest
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`

// AccountListRequest
UserType *int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`

// AccountResponse
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`

---

📝 常见枚举字段参考

用户类型（UserType）

description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"

角色类型（RoleType）

description:"角色类型 (1:平台角色, 2:客户角色)"

权限类型（PermType）

description:"权限类型 (1:菜单, 2:按钮)"

适用端口（Platform）

description:"适用端口 (all:全部, web:Web后台, h5:H5端)"

状态（Status）

description:"状态 (0:禁用, 1:启用)"

店铺层级（Level）

description:"店铺层级 (1-7级)"

---

🔧 检查工具

手动检查

在提交前运行以下命令检查 DTO 文件：

# 查找没有 description 标签的 json 字段
grep -rn 'json:"[^"]*"' internal/model/*_dto.go | grep -v 'description:'

# 查找使用行内注释的字段（应该改为 description 标签）
grep -rn '`json:.*`.*//\s' internal/model/*_dto.go

# 查找可能缺少枚举值说明的 status 字段
grep -rn 'Status.*json:"status".*description:"状态"$' internal/model/*_dto.go

自动生成文档验证

# 生成 OpenAPI 文档
go run cmd/gendocs/main.go

# 检查生成的文档中是否包含完整的枚举值说明
grep -A 3 "user_type:" docs/admin-openapi.yaml
grep -A 3 "status:" docs/admin-openapi.yaml

---

📚 相关文档

• 项目开发规范
• OpenAPI 文档生成说明
• RBAC 用户类型定义

---

✅ Code Review 检查清单（用于审查者）

在审查 Pull Request 时，请逐项检查：

• 所有新增/修改的 DTO 字段都有 description 标签
• 所有枚举字段的 description 包含完整的可能值和中文说明
• 所有状态字段明确说明了 0 和 1 的含义
• validate 标签与 OpenAPI 标签（required、minLength、maximum 等）一致
• Query 参数添加了 query 标签
• Path 参数添加了 path 标签
• 响应 DTO 的所有字段都有完整说明
• 同一字段在不同 DTO 中使用一致的 description
• 所有枚举值使用中文说明，禁止使用英文
• 没有使用行内注释替代 description 标签
• 所有导出的结构体有中文 godoc 注释

---

🎯 完成标准

当所有检查项都通过时，才能合并 PR。

文档生成验证：

go run cmd/gendocs/main.go
# 检查 docs/admin-openapi.yaml 中所有字段都有清晰的中文说明

---

最后更新: 2026-01-20
维护者: 开发团队