在Java中如何统一封装异常信息_Java异常封装设计思路_技术教程

必须用自定义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，导致线上问题无法快速定位。

所有 BusinessException 构造必须传入 requestId，且该 ID 应从网关或 Filter 中注入，而非每次 new UUID()
message 字段禁止拼接敏感信息（如手机号、身份证号），应使用占位符 + 参数化日志：log.warn("User login failed for uid={}", uid)
监控系统（如 Prometheus + Grafana）应基于 code 维度聚合错误率，而不是靠日志关键字 grep——否则扩容后日志分散，统计失效