必须用自定义BusinessException封装业务异常，含code、message、requestId字段；@RestControllerAdvice统一拦截并返回200状态码JSON响应；日志打warn级且含requestId；异常抛出须在service/controller层，DTO不参与校验。
统一用自定义异常类封装业务错误
Java原生异常（如 RuntimeException）不带状态码、不区分业务语义，直接抛出会丢失关键上下文。必须用自定义异常类承载错误码、提示语、日志标识等字段。
推荐结构：
public class BusinessException extends RuntimeException {
private final int code;
private final String requestId; // 用于链路追踪对齐
public BusinessException(int code, String message, String requestId) {
super(message);
this.code = code;
this.requestId = requestId;
}
// getter 省略
}
-
code必须是整型，方便前端 switch 判断，避免字符串匹配；建议按模块划分区间（如 1000–1999 表示用户模块） - 不要继承
Exception并强制 try-catch——业务异常不是“意外”，而是预期内的流程分支 - 构造时传入
requestId，确保日志、监控、告警能反查完整请求链路
@ControllerAdvice 拦截并标准化响应体
Spring Boot 中，所有 Controller 抛出的 BusinessException 都应被统一捕获，转为 JSON 格式返回，避免堆栈暴露给前端。
关键点：
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(BusinessException.class)
public ResponseEntity handleBusinessException(BusinessException e) {
ApiResponse response = new ApiResponse(e.getCode(), e.getMessage(), null);
// 记录 warn 日志，含 requestId 和堆栈（仅开发/测试环境打印完整堆栈）
log.warn("BusinessException[{}]: {} | requestId={}", e.getCode(), e.getMessage(), e.getRequestId());
return ResponseEntity.status(HttpStatus.OK).body(response);
}
}
-
ResponseEntity显式指定 HTTP 状态码为200，而非500——业务异常不是服务故障，不应触发熔断或告警误报 - 日志级别用
warn，但只在非生产环境打印e.getStackTrace()；生产环境仅打requestId + code + message - 不要在 handler 里吞掉异常或静默失败；若需补偿逻辑（如事务回滚后发消息），应在 service 层显式处理，而非塞进 handler
避免在 DTO 或 VO 中暴露异常细节
常见错误：把 throw new BusinessException(1001, "用户名已存在", reqId) 写在 UserDTO 的 setter 里，导致校验逻辑和数据模型耦合。
- 异常封装必须发生在 service 层或 controller 层，DTO 只负责数据搬运，不参与业务判断
- 不要在 MyBatis 的
@Select注解 SQL 中写IFNULL替代空值检查——空结果应由 service 判定是否构成业务异常 - 数据库唯一约束触发的
SQLIntegrityConstraintViolationException，应在 DAO 层捕获并转为对应BusinessException（如 code=1001），不能让原始 JDBC 异常透传到上层
日志与监控联动的关键字段不能丢
很多团队封装了异常，却在日志中漏掉 requestId 或硬编码 message，导致线上问题无法快速定位。
立即学习“Java免费学习笔记（深入）”；
- 所有
BusinessException构造必须传入requestId，且该 ID 应从网关或 Filter 中注入，而非每次 new UUID() - message 字段禁止拼接敏感信息（如手机号、身份证号），应使用占位符 + 参数化日志：
log.warn("User login failed for uid={}", uid) - 监控系统（如 Prometheus + Grafana）应基于
code维度聚合错误率，而不是靠日志关键字 grep——否则扩容后日志分散，统计失效
code、传对 requestId、选对日志级别。这些细节散落在几十个 service 方法里，靠人盯容易漏，最好用 AOP 或 ArchUnit 做编译期校验。 
