manta/gofaster/backend/CONTROLLER_DESCRIPTION_STANDARD.md

Controller API描述规范

概述

为了生成准确的路由描述信息，所有Controller方法必须遵循以下注释规范。

规范要求

1. 必须包含的注释

每个Controller方法必须包含以下Swagger注释：

// MethodName 方法功能描述
// @Summary 简短的中文描述
// @Description 详细的中文描述
// @Tags 标签名称
// @Accept json
// @Produce json
// @Param 参数描述
// @Success 200 {object} response.Response
// @Router /api/path [method]
func (c *Controller) MethodName(ctx *gin.Context) {
    // 实现代码
}

2. 描述规范

@Summary 规范

• 必须使用中文
• 简洁明了，不超过20个字符
• 准确描述方法功能

示例：

// @Summary 获取用户列表
// @Summary 创建新用户
// @Summary 更新用户信息
// @Summary 删除用户

@Description 规范

• 必须使用中文
• 详细描述方法功能、参数说明、返回值说明
• 包含业务逻辑说明

示例：

// @Description 获取分页用户列表，支持按用户名、状态等条件筛选
// @Description 创建新用户，自动生成用户ID，设置默认密码策略
// @Description 更新用户基本信息，包括用户名、邮箱、状态等
// @Description 删除用户，同时删除用户相关的角色关联

3. 路径规范

路径命名规范

• 使用RESTful风格
• 资源名使用复数形式
• 路径参数使用:id格式

示例：

// @Router /api/auth/users [get]           // 获取用户列表
// @Router /api/auth/users [post]          // 创建用户
// @Router /api/auth/users/:id [get]       // 获取用户详情
// @Router /api/auth/users/:id [put]       // 更新用户
// @Router /api/auth/users/:id [delete]    // 删除用户

4. 标签规范

@Tags 规范

• 使用中文标签
• 按功能模块分组
• 保持一致性

示例：

// @Tags 用户管理
// @Tags 角色管理
// @Tags 权限管理
// @Tags 认证管理

实施步骤

阶段1：现有Controller改造

1. 检查所有现有Controller方法
2. 补充缺失的@Summary和@Description注释
3. 统一标签命名

阶段2：路由描述生成优化

1. 修改RouteSyncService，优先从Swagger注释提取描述
2. 实现注释解析逻辑
3. 回退机制：注释解析失败时使用原有逻辑

阶段3：代码审查规范

1. 新增Controller方法必须包含完整注释
2. 代码审查时检查注释完整性
3. 建立自动化检查工具

示例代码

完整的Controller方法示例

// ListUsers 获取用户列表
// @Summary 获取用户列表
// @Description 获取分页用户列表，支持按用户名、状态等条件筛选，返回用户基本信息和关联角色
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param page query int false "页码" default(1)
// @Param pageSize query int false "每页数量" default(10)
// @Param username query string false "用户名筛选"
// @Param status query string false "状态筛选"
// @Success 200 {object} response.Response{data=map[string]interface{}} "用户列表"
// @Failure 400 {object} response.Response "请求参数错误"
// @Failure 500 {object} response.Response "服务器内部错误"
// @Router /api/auth/admin/users [get]
func (c *UserController) ListUsers(ctx *gin.Context) {
    // 实现代码
}

// CreateUser 创建用户
// @Summary 创建新用户
// @Description 创建新用户，自动生成用户ID，设置默认密码策略，支持批量创建
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param user body model.CreateUserRequest true "用户创建信息"
// @Success 201 {object} response.Response{data=model.User} "创建成功"
// @Failure 400 {object} response.Response "请求参数错误"
// @Failure 409 {object} response.Response "用户已存在"
// @Failure 500 {object} response.Response "服务器内部错误"
// @Router /api/auth/admin/users [post]
func (c *UserController) CreateUser(ctx *gin.Context) {
    // 实现代码
}

检查清单

新增方法检查

• 包含@Summary注释
• 包含@Description注释
• 包含@Tags注释
• 包含@Router注释
• 描述使用中文
• 路径符合RESTful规范

现有方法检查

• 补充缺失的注释
• 统一标签命名
• 优化描述内容
• 验证路径正确性

工具支持

自动化检查脚本

# 检查Controller注释完整性
go run tools/check_controller_comments.go

# 生成路由描述映射
go run tools/generate_route_descriptions.go

IDE配置

• 配置Go注释模板
• 启用Swagger注释高亮
• 设置注释格式检查