自定义异常类应封装不可变业务字段（如errorCode、bizId），提供多参构造器支持异常链，重写toLogString而非toString以安全输出结构化日志，并通过@ControllerAdvice统一处理响应与日志。

在 Java 中，自定义异常类添加业务状态字段的核心思路是：把关键的上下文信息作为成员变量封装进异常对象，并通过构造器注入、重写 toString 或提供 getter 方法暴露出来。这样既能保持异常语义清晰，又能让日志、监控或前端响应携带足够诊断信息。

设计带业务字段的异常类

不要只继承 Exception 或 RuntimeException 就完事，要主动建模业务失败场景。例如电商下单失败时，需要知道订单号、用户 ID、库存余量、扣减时间等——这些都应作为 final 字段声明：

• 用 final 修饰字段，保证异常抛出后上下文不可变
• 字段类型优先选不可变类（如 String、LocalDateTime、BigDecimal），避免外部修改影响诊断准确性
• 常见字段包括：errorCode（业务码）、traceId（链路追踪 ID）、bizId（业务单据号）、params（原始请求参数快照）、causeDetail（失败原因描述）

提供多参数构造器并兼容标准异常链

构造器既要接收业务字段，也要支持 Throwable cause，否则会丢失原始异常栈。推荐至少提供两个构造器：

• 含 errorCode、bizId、message、cause 的全参构造器
• 兼容 JDK 的 message + cause 构造器，内部自动填充默认 errorCode 和空 bizId

示例片段：

Java Maven Common

Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。

下载

立即学习“Java免费学习笔记（深入）”；

public class OrderException extends RuntimeException {
  private final String errorCode;
  private final String orderId;
  private final String userId;

  public OrderException(String errorCode, String orderId, String userId, String message, Throwable cause) {
    super(message, cause);
    this.errorCode = errorCode;
    this.orderId = orderId;
    this.userId = userId;
  }
}

重写 toString 或提供 toLogString 方法

默认 toString 只打印类名和 message，无法体现业务字段。建议新增 toLogString() 方法，返回结构化字符串（如 JSON 或 key=value 格式），便于日志系统提取字段：

• 避免直接重写 toString 影响调试器显示，单独定义 toLogString 更安全
• 敏感字段（如手机号、身份证）需脱敏处理，不能裸露在日志中
• 可借助 Jackson 或 Gson 序列化，但注意异常对象可能含循环引用，建议手动拼接

配合全局异常处理器统一输出

Spring Boot 项目中，用 @ControllerAdvice 拦截自定义异常，将业务字段映射到响应体：

• 响应体包含 errorCode、message、timestamp、orderId、traceId 等字段
• 日志记录时调用 exception.toLogString()，确保 ELK 或 SLS 能按字段检索
• 对前端返回的 message 做国际化或友好提示转换，而 errorCode 保持不变供后台排查