自定义异常类设计最佳实践

本文深入剖析了Java自定义异常类的四大核心实践：精准选择继承Exception（强制处理系统级/可恢复外部故障）还是RuntimeException（灵活应对内部逻辑错误与校验失败），必须提供带Throwable cause的构造器以保留完整调用链便于排查，坚持异常类“瘦模型”原则——杜绝添加业务字段、专注传递错误信号，以及在Spring中严格依赖类型匹配而非名称或message进行异常捕获与统一处理；这些看似细微的设计决策，实则直接决定系统的可观测性、可维护性与故障响应效率，是每位Java开发者绕不开的健壮性必修课。

继承 Exception 还是 RuntimeException？看调用方要不要强制处理

Java 异常分两大类：检查型（checked）和非检查型（unchecked）。Exception 及其子类是检查型异常，编译器会强制要求你 try-catch 或 throws；RuntimeException 是非检查型，抛了就抛了，调用方爱理不理。

选哪个，核心就一条：这个错误是不是业务逻辑里「调用方必须主动应对」的场景？比如读配置文件失败、远程服务超时、数据库连接断开——这些不处理就可能让流程卡死或数据错乱，该继承 Exception。而像参数校验失败（如传了 null 用户 ID）、状态非法（订单已取消却还要发货）——这类属于编程逻辑错误或前端没拦住的脏输入，继承 RuntimeException 更合适，逼开发在写调用代码时就意识到要兜底，而不是靠编译器提醒。

• 继承 Exception：适合系统级、外部依赖失败、可恢复的业务异常（比如重试后可能成功）
• 继承 RuntimeException：适合内部逻辑错误、参数/状态校验失败、不可恢复的程序缺陷
• 别为了“统一”全用 RuntimeException —— 那会让关键错误被静默吞掉
• 也别把所有校验都塞进 Exception 子类——过度检查会让调用代码满屏 try，反而掩盖真正需要关注的故障点

super(message) 不够，得补上 cause 参数构造器

自定义异常类如果只写一个带 String 的构造器，遇到链式异常（比如底层抛了 IOException，你包装成业务异常再往上抛），原始堆栈和根因就丢了。调试时只能看到你的异常，看不到到底哪行 IO 操作挂了。

务必提供接受 Throwable 的构造器，并调用父类对应签名：

public class OrderNotFoundException extends Exception {
    public OrderNotFoundException(String message) {
        super(message);
    }
    public OrderNotFoundException(String message, Throwable cause) {
        super(message, cause); // ← 这句不能少
    }
}

• 没有 cause 构造器 → 日志里看不到嵌套异常，排查成本翻倍
• 写了但没调用 super(message, cause) → 看起来有，实际没透传，等于白写
• 如果同时继承 RuntimeException，也要同步提供两个构造器，否则 Spring 等框架做异常转换时可能出问题

别在异常类里加业务字段或方法

异常对象本质是「错误信号」，不是数据载体。加个 orderId 字段看似方便取值，实则埋雷：序列化时可能出问题；被日志框架捕获时字段不一定被打印；更麻烦的是，一旦异常跨 JVM（比如 Dubbo、gRPC 传输），自定义字段大概率丢失，只剩 message 和 stacktrace。

真正要带上下文信息，应该塞进 message 字符串里，或者用日志 MDC 打点：

// ✅ 推荐：把 orderId 写进 message
throw new OrderNotFoundException("Order not found: " + orderId);

// ❌ 避免：在异常类里定义 orderId 字段并暴露 getter
public class OrderNotFoundException extends Exception {
    private final String orderId; // ← 多数场景下没必要，还增加维护负担
}

• 异常类保持“瘦”——只有构造器和必要重写（比如 toString）
• 需要丰富上下文？用日志框架的 MDC（如 MDC.put("orderId", "123")）比改异常结构靠谱得多
• 真有极少数需透传结构化数据的场景（如网关统一错误码），建议用单独的错误响应 DTO，而不是塞进异常类

Spring 中 @ControllerAdvice 捕获时，类型匹配比名字重要

写全局异常处理器时，经常有人按异常类名字符串去判断，比如 if (e.getClass().getSimpleName().contains("NotFound"))。这既脆弱又难测——类名一改就失效，还绕过了 Java 的多态机制。

正确做法是直接按类型捕获，Spring 的 @ExceptionHandler 支持精确匹配：

@ExceptionHandler(OrderNotFoundException.class)
public ResponseEntity handleOrderNotFound(OrderNotFoundException e) {
    return ResponseEntity.status(404).body(new ErrorResponse(e.getMessage()));
}

• 多个相似异常（如 UserNotFoundException、ProductNotFoundException）可以共用一个父类（如 ResourceNotFoundException），然后统一捕获该父类
• 不要依赖异常 message 做分支逻辑——message 可能被 i18n、被日志脱敏、甚至被人工修改
• 注意 RuntimeException 子类默认会被 Spring 的默认处理器吃掉，若想统一处理，确保 @ControllerAdvice 的方法签名覆盖到它们

最常被忽略的一点：异常类的包路径和模块可见性。如果自定义异常放在启动类扫描不到的 module 或 jar 里，Spring 根本识别不了那个类类型，@ExceptionHandler 就形同虚设。

今天关于《自定义异常类设计最佳实践》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！