Java异常层级设计要点解析

Java异常设计的核心在于通过2–3个语义清晰的顶层业务异常基类（如BusinessException、SystemException、ValidationException）替代杂乱平级的自定义异常，实现精准捕获、日志归类、可恢复性判断与高效测试；自定义异常必须结构化携带code和context等关键上下文，杜绝大对象引用；受检异常仅用于调用方能且应立即干预的场景（如参数校验），非受检异常则覆盖系统级故障；全局异常处理器须极简——只记录带traceId的堆栈、设合理HTTP状态码、返回精简JSON，严禁吞异常、外调告警或兜底运行时错误，让异常真正成为可观测、可治理、可演进的系统能力而非技术债源头。

为什么不应该直接继承 Exception 或 RuntimeException 写一堆平级异常类

常见错误是为每个业务场景新建一个异常，比如 OrderCreateException、PaymentTimeoutException、UserNotFoundException，全部直接继承 RuntimeException。这样会导致：无法按语义分组捕获；日志归类困难；调用方无法预判哪些异常可恢复、哪些该熔断；测试时难以模拟特定异常分支。

合理做法是先定义 2–3 个顶层业务异常基类，再按领域或故障类型向下细化：

• BusinessException（继承 RuntimeException）：表示业务规则不满足，如余额不足、状态非法，调用方可重试或引导用户修正
• SystemException（继承 RuntimeException）：表示下游服务不可用、DB 连接失败等临时性系统问题，需监控+告警
• ValidationException（继承 Exception）：用于入参校验失败，强制上层显式处理，避免脏数据流入

如何让自定义异常携带结构化上下文信息

单纯抛 new BusinessException("订单创建失败") 会丢失关键现场数据，导致排查时反复加日志。应在构造函数中支持传入业务 ID、请求 ID、原始错误码等，并提供统一序列化方法。

示例基类设计要点：

• 所有子类共用带 String code、Map context 的构造函数
• 重写 toString() 或新增 toLogString()，自动拼接 traceId + code + context
• 避免在异常中存大对象（如整个 request body），防止 OOM 或 GC 压力

public class BusinessException extends RuntimeException {
    private final String code;
    private final Map<String, Object> context;

    public BusinessException(String code, String message, Map<String, Object> context) {
        super(message);
        this.code = code;
        this.context = Collections.unmodifiableMap(context);
    }

    public String toLogString(String traceId) {
        return String.format("[%s] %s: %s | context=%s", traceId, code, getMessage(), context);
    }
}

什么时候该用受检异常（Exception），什么时候用非受检（RuntimeException）

Java 的受检异常机制本意是强制处理可恢复的预期异常，但滥用会导致模板代码泛滥。判断标准不是“是否严重”，而是“调用方是否有能力且应该立即处理”：

• 用 Exception：参数合法性校验失败（如身份证格式错）、文件路径不存在但应由用户补填、第三方 API 明确返回 400 且需提示用户修改输入
• 用 RuntimeException：DB 连接超时、Redis 崩溃、NPE、空指针解引用——这些不是业务逻辑能当场修复的，应交由全局异常处理器统一记录、降级或返回友好提示
• 绝对不要把网络超时、SQL 异常包装成受检异常向上抛，这会让 service 层被迫写大量 try-catch 却只做日志+再抛，违背设计初衷

全局异常处理器里不该做什么

Spring 的 @ControllerAdvice 是收口，但容易写过重。以下行为会掩盖问题本质或引入新风险：

• 把所有 RuntimeException 都吞掉并返回 200 + { "code": 500, "msg": "系统繁忙" } —— 前端无法区分是服务宕机还是限流，也无法触发重试逻辑
• 在 handler 里调用外部服务（如发钉钉告警）—— 若告警服务也挂了，会导致异常处理链路卡死，甚至阻塞 Tomcat 线程
• 对 NullPointerException、ArrayIndexOutOfBoundsException 做特殊响应 —— 这些是 bug，应该立刻修复，而不是“优雅兜底”

真正该做的只有三件事：记录带 traceId 的完整堆栈；根据异常类型设置 HTTP 状态码（如 BusinessException → 400，SystemException → 503）；返回精简 JSON（不含堆栈、不含敏感字段）。

今天关于《Java异常层级设计要点解析》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！