优雅处理Java异常，状态码与消息模板方案

本文深入剖析了Java业务异常处理中的常见反模式，指出硬编码字符串异常（如`throw new RuntimeException("订单不存在")`）带来的维护困境、国际化障碍、监控失效与前端体验恶化等问题，并系统性提出以领域化错误码枚举为核心、配合动态参数化`BizException`和统一响应结构的优雅解决方案——通过5位分域错误码、i18n消息键、精准HTTP状态绑定及全局异常处理器协同，实现异常可追溯、可监控、可本地化、可演进，真正让错误处理从“救火式”走向工程化、标准化与协作友好型实践。

为什么不能直接 throw new RuntimeException("订单不存在")

这是最典型的反模式——字符串散落各处，改文案要全局搜，加多语言根本没法做，前端也难做精准交互。更麻烦的是，日志里只有一句“订单不存在”，查问题时连是哪个订单、哪个接口抛的都得翻代码。

• 错误码缺失 → 无法按 code 聚合监控告警
• 消息硬编码 → i18n 支持为零，国际化项目直接卡死
• HTTP 状态混用 → 业务异常（如参数错）和系统异常（如 DB 连不上）全扔 500，前端统一弹“服务器开小差”，体验极差

用枚举定义 ErrorCode 是最稳的起点

不是随便建个 ErrorCode 接口就完事，关键在结构约束和分域管理。推荐直接用 enum 实现，编译期类型安全，IDE 自动补全，还杜绝重复码值。

• 码值建议 5 位以上，前两位代表领域：如 10001（10=订单）、20001（20=用户）
• message 字段只存 i18n key，比如 "order.not.found"，不是中文文本
• 必须带 HttpStatus：业务校验失败用 HttpStatus.BAD_REQUEST，资源未找到用 HttpStatus.NOT_FOUND
• 禁止跨模块复用枚举：订单模块不能直接引用 UserErrorCode.USER_LOCKED，共用逻辑提成 CommonErrorCode

public enum OrderErrorCode implements ErrorCode {
    ORDER_NOT_FOUND(10001, "order.not.found", HttpStatus.NOT_FOUND),
    ORDER_STATUS_INVALID(10002, "order.status.invalid", HttpStatus.CONFLICT);

    private final int code;
    private final String messageKey;
    private final HttpStatus httpStatus;

    OrderErrorCode(int code, String messageKey, HttpStatus httpStatus) {
        this.code = code;
        this.messageKey = messageKey;
        this.httpStatus = httpStatus;
    }
    // getter 省略
}

BizException 必须支持动态参数填充

真实业务里，“订单不存在”后面往往要带 ID，比如“订单 ORD-20260227001 不存在”。靠枚举里写死字符串肯定不行，得靠 MessageFormat 或 String.format 在运行时插值。

• 构造 BizException 时传入参数数组：new BizException(OrderErrorCode.ORDER_NOT_FOUND, "ORD-20260227001")
• getDetailMessage() 内部调用 MessageFormat.format(messageTemplate, args)，模板写成 "订单{0}不存在"
• 注意：参数顺序和模板占位符必须严格对应，否则运行时报 IllegalArgumentException

全局异常处理器要区分 HTTP 状态码与业务 code

Spring 的 @ControllerAdvice 不是把所有异常都塞进 ResponseEntity.status(500) 就完事。它得从 BizException 里准确抽出两层信息：HTTP 层状态（由枚举自带），和业务层 code/message（供前端判断逻辑分支）。

• 响应体结构必须含 code（如 "10001"）、message（已解析好的多语言文案）、requestId（方便日志串联）
• 别用 ResponseEntity.status(ex.getHttpStatus()).body(...) 直接返回字符串，body 应该是统一的 Result 对象
• 对非 BizException（如 NullPointerException）要兜底转成 SYSTEM_ERROR 枚举项，避免把堆栈暴露给前端

实际落地最难的不是写代码，是让所有人——后端、前端、测试、甚至产品——真正按约定用 code 而不是看 message 做判断。一旦有人在 if 里写 if (e.getMessage().contains("余额"))，整套体系就垮了一半。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《优雅处理Java异常，状态码与消息模板方案》文章吧，也可关注golang学习网公众号了解相关技术文章。