manta/gofaster/backend/CONTROLLER_DESCRIPTION_STANDARD.md

# Controller API描述规范

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

## 规范要求

### 1. 必须包含的注释
每个Controller方法必须包含以下Swagger注释：

```go
// 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个字符
- 准确描述方法功能

**示例：**
```go
// @Summary 获取用户列表
// @Summary 创建新用户
// @Summary 更新用户信息
// @Summary 删除用户
```

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

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

### 3. 路径规范

#### 路径命名规范
- 使用RESTful风格
- 资源名使用复数形式
- 路径参数使用`:id`格式

**示例：**
```go
// @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 规范
- 使用中文标签
- 按功能模块分组
- 保持一致性

**示例：**
```go
// @Tags 用户管理
// @Tags 角色管理
// @Tags 权限管理
// @Tags 认证管理
```

## 实施步骤

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

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

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

## 示例代码

### 完整的Controller方法示例
```go
// 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规范

### 现有方法检查
- [ ] 补充缺失的注释
- [ ] 统一标签命名
- [ ] 优化描述内容
- [ ] 验证路径正确性

## 工具支持

### 自动化检查脚本
```bash
# 检查Controller注释完整性
go run tools/check_controller_comments.go

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

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