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}<{@link String}> {@link Result}<{@link Void}> {@link Result}<{@link List}<{@link User}>>示例：
java
/** * 用户登录 * * <p>前端请求 Content-Type 为 application/x-www-form-urlencoded</p> * * @param account 用户账号 * @param password 登录密码 * @return 登录成功返回认证令牌 {@link Result}<{@link String}> */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); }8. HTTP 方法使用规范
查询：
@GetMapping新增：
@PostMapping局部更新：
@PatchMapping全量覆盖更新：
@PutMapping删除：
@DeleteMapping
9. 返回值规范
统一返回
Result<T>无返回数据使用
Result<Void>泛型必须明确，便于文档识别
禁止自定义错误返回结构
10. 工具方法规范
必须编写完整 JavaDoc
明确声明抛出异常
类型安全，避免不安全强转
通用方法设为
public static
11. 禁止行为（红线）
❌ 禁止在 Controller 编写业务逻辑
❌ 禁止使用
try-catch❌ 禁止返回
Result.error()❌ 禁止无意义变量名（data、map、param）
❌ 禁止打印敏感信息
❌ 禁止冗余 null 判断
❌ 禁止缺失 JavaDoc 注释
