本文详解如何设计可序列化的自定义异常类，通过构造函数注入业务字段（如 personid、code、debugger），避免字段丢失，并确保异常能被全局处理器捕获与标准化响应。
本文详解如何设计可序列化的自定义异常类，通过构造函数注入业务字段（如 personid、code、debugger），避免字段丢失，并确保异常能被全局处理器捕获与标准化响应。
在 Spring Boot 等现代 Java Web 应用中，仅继承 RuntimeException 并添加字段是不够的——若未正确初始化父类或未提供合理构造逻辑，异常对象可能无法携带关键上下文，导致下游（如全局异常处理器）无法提取 personId、code 等字段生成符合 API 规范的 JSON 响应（例如 { "personId": "1", "code": "1", "debugger": [...] }）。
✅ 正确做法：显式构造 + 字段封装 + 可选 cause 传递
自定义异常类不能将业务字段“透传”给 super()（因为 RuntimeException 不接受这些参数），而应由子类自身持有并管理。关键在于：
- 提供含全部业务字段的公有构造函数；
- 支持传入原始异常 cause，以保留堆栈和根本原因；
- 避免依赖 Lombok 的 @Builder 单独构建（因 Builder 不调用父类构造逻辑，且易遗漏 super(...) 初始化）；
- 如需 JSON 序列化输出，字段必须为 public 或配备标准 getter（推荐后者，兼顾封装性与 Jackson 兼容性）。
以下是推荐实现：
@NoArgsConstructor // 供框架反序列化/代理等场景使用（非必需但建议）
public class CustomException extends ProductsException {
private final String personId;
private final String code;
private final List<String> debugger;
// 主构造：仅业务字段
public CustomException(String personId, String code, List<String> debugger) {
super(); // 调用 ProductsException 的无参构造（注意：此时 error 为 null，需确保上层不依赖它）
this.personId = personId;
this.code = code;
this.debugger = Collections.unmodifiableList(new ArrayList<>(debugger));
}
// 带 cause 的构造：保留原始异常链
public CustomException(String personId, String code, List<String> debugger, Throwable cause) {
super(cause); // 正确委托给父类带 cause 的构造器
this.personId = personId;
this.code = code;
this.debugger = Collections.unmodifiableList(new ArrayList<>(debugger));
}
// 标准 getter —— Jackson 默认通过 getter 序列化字段
public String getPersonId() { return personId; }
public String getCode() { return code; }
public List<String> getDebugger() { return debugger; }
// （可选）重写 getMessage 用于日志或调试，不影响 JSON 响应结构
@Override
public String getMessage() {
return String.format("CustomException[personId=%s, code=%s, debugger=%s]",
personId, code, debugger);
}
}⚠️ 注意事项与常见陷阱
- 不要仅用 @Builder：CustomException.builder().personId("1").code("ERR_001").build() 会跳过 super() 调用，且 Lombok 默认生成的 Builder 构造器不支持 Throwable cause 注入，极易导致异常链断裂。
-
ProductsException 的兼容性：当前 ProductsException 构造器仅接受 Exception e，但未暴露 getErrorCode() 等方法。若需从 ProductsException 中提取 errorCode，请为其补充 getter：
public class ProductsException extends RuntimeException { private final MyError error; // ... 构造器 public MyError getError() { return error; } // 若 MyError 有 getErrorCode()，则可链式调用 } -
全局异常处理器需识别该类型：确保 @ControllerAdvice 类中包含对 CustomException 的处理逻辑，例如：
@ExceptionHandler(CustomException.class) public ResponseEntity<Map<String, Object>> handleCustomException(CustomException e) { Map<String, Object> body = new HashMap<>(); body.put("personId", e.getPersonId()); body.put("code", e.getCode()); body.put("debugger", e.getDebugger()); return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(body); } - 线程安全与不可变性：使用 Collections.unmodifiableList 包装 debugger，防止外部修改影响异常状态一致性。
✅ 总结
设计面向 API 响应的自定义异常，核心是字段自主管理 + 构造器显式初始化 + 标准化访问接口。摒弃仅靠 Builder 或字段直赋的懒惰方式，通过多态构造函数覆盖不同使用场景（无因异常 / 嵌套异常），并配合全局异常处理器完成从 Java 异常到结构化 JSON 的无缝转换。如此，既满足客户端契约，又保障系统可观测性与可维护性。
