规范说明：Controller 层编码规范-拓冰建站

Controller 层编码规范

1. 总则

职责单一
Controller 只负责：接收参数 → 基础校验 → 调用 Service → 返回统一成功结构。
不编写业务逻辑、不处理异常、不做数据计算。
异常统一
禁止在 Controller 使用try-catch，所有异常直接抛出，由全局异常处理器统一处理。
快速失败（Fail-Fast）
参数非法、数据异常立即抛出异常，不继续执行后续逻辑。
风格统一
命名、注释、日志、结构、返回格式在项目内保持完全一致。
安全规范
不打印敏感信息（密码、密钥、身份证、手机号等）。

2. 命名规范

2.1 类命名

命名格式：XxxController
采用大驼峰，望文知义
示例：AccountController、UserController、DictController

2.2 方法命名

登录：login
新增：add/create
查询单条：get
查询列表：list
分页查询：page
局部更新：updateXxx
全量更新：update
删除：delete/remove
状态修改：updateValid/changeStatus

2.3 变量命名

小驼峰，语义化，禁止拼音、无意义缩写
禁止：data、map、param、str、obj
推荐：encryptedData、passwordParams、currentUser

3. JavaDoc 注释规范

3.1 类注释

必须包含：用途说明、<p>段落。

java

/** * 账号管理 API * * <p>提供用户登录、密码修改、账号状态管理等账号相关操作接口</p> */

3.2 方法注释

必须包含：功能说明、特殊约束、@param、@return。

返回值统一格式：

plaintext

{@link Result}&lt;{@link String}&gt; {@link Result}&lt;{@link Void}&gt; {@link Result}&lt;{@link List}&lt;{@link User}&gt;&gt;

示例：

java

/** * 用户登录 * * <p>前端请求 Content-Type 为 application/x-www-form-urlencoded</p> * * @param account 用户账号 * @param password 登录密码 * @return 登录成功返回认证令牌 {@link Result}&lt;{@link String}&gt; */

4. 参数校验规范

非空、格式等基础校验在 Controller 完成
业务规则校验下沉到 Service
批量非空优先使用：
java
```
StringUtils.isAnyBlank(a, b, c);
```
校验失败抛出：
- 业务校验不通过：BusinessException
- 参数格式 / 类型错误：IllegalArgumentException

5. 异常处理规范

Controller 禁止任何 try-catch
业务异常：throw new BusinessException("提示信息")
参数异常：throw new IllegalArgumentException("格式错误")
空指针、类型转换异常由全局异常兜底
禁止手动返回Result.error(...)

6. 日志规范

6.1 格式

plaintext

【模块】操作描述，关键字段=xxx

示例：

java

log.info("【账号登录】account={}", account); log.warn("【修改密码】加密数据为空");

6.2 级别

正常流程：info
非法请求 / 参数异常：warn
系统异常：error（全局统一打印）

6.3 禁止打印

密码、加密密钥、加密原文
身份证、手机号、地址等隐私信息

7. 代码结构固定模板

java

@XxxMapping("/xxx") public Result<T> method(参数) { // 1. 日志 log.info("【模块】操作，信息={}", ...);  // 2. 基础参数校验 if (StringUtils.isBlank(xxx)) { throw new BusinessException("xxx不能为空"); }  // 3. 参数解析/转换  // 4. 调用 Service  // 5. 返回成功结构 return Result.success(data); }