自定义异常在项目里并不少见,但真正让人头疼的往往不是抛出异常本身,而是异常身上那堆状态数据怎么管理。错误码、默认提示语、HTTP响应码,如果都靠调用方手动传参,一旦参数顺序不对,线上就会返回一串莫名其妙的错误信息。用枚举类Enum提前把这些状态封装成固定常量,再交给自定义异常使用,可以从源头减少这种低级错误。下面的做法不依赖第三方库,只使用Java标准语法和Spring Web基础能力。

一、用枚举定义稳定的状态数据
枚举非常适合表达有限且固定的状态集合。一个业务异常状态通常由三个核心部分组成:业务错误码、默认提示消息、对应的HTTP响应状态。把这几个字段放到枚举常量里,比在类里写一堆 public static final int 要安全得多,因为枚举天然具备类型检查能力,调用方不能随便塞一个不存在的状态值进去。
下面的枚举把用户不存在、参数校验失败、订单支付超时和系统内部错误四种典型场景封装起来。枚举构造函数是私有的,字段全部使用 final 修饰,一旦初始化完成就不会再变化。这种不可变设计让枚举实例天然线程安全,多个线程同时读取同一个状态对象时不存在竞争问题。
import org.springframework.http.HttpStatus;
public enum ErrorStatus {
USER_NOT_FOUND(10001, "用户不存在", HttpStatus.NOT_FOUND),
PARAM_INVALID(10002, "参数校验失败", HttpStatus.BAD_REQUEST),
ORDER_PAYMENT_TIMEOUT(20001, "订单支付超时", HttpStatus.GATEWAY_TIMEOUT),
INTERNAL_ERROR(50000, "系统内部错误", HttpStatus.INTERNAL_SERVER_ERROR);
private final int code;
private final String message;
private final HttpStatus httpStatus;
ErrorStatus(int code, String message, HttpStatus httpStatus) {
this.code = code;
this.message = message;
this.httpStatus = httpStatus;
}
public int getCode() {
return code;
}
public String getMessage() {
return message;
}
public HttpStatus getHttpStatus() {
return httpStatus;
}
public int getHttpStatusCode() {
return httpStatus.value();
}
}
这里直接引用了 Spring 的 HttpStatus 枚举,这样在 Web 层可以直接拿到标准 HTTP 状态码。如果你的异常模块需要脱离 Spring 使用,也可以把 HttpStatus 换成普通的 int 类型,或者自己再定义一个内部状态枚举。关键是状态数据要集中在一个地方,不要让业务代码去散落定义 code 和 message。
枚举常量还方便做全局检索。当你想知道系统里已经有哪些错误码时,只需要打开这一个文件就能看清全貌,而不是全局搜索某个魔法数字。后续要新增错误码,也只需在枚举里追加一个常量,不会影响已有调用方。
二、让自定义异常持有枚举状态
光有状态枚举还不够,还需要一个自定义异常基类去承接它。这个基类构造时直接接收一个 ErrorStatus 常量,不用再传零散的 code 和 message。这样调用方写出来的代码就变成一句简单明了的 throw new ApiException(ErrorStatus.USER_NOT_FOUND),读起来基本不需要额外解释。
异常基类可以继承 RuntimeException,这样业务异常属于非受检异常,调用方不必在每个方法签名上强制声明 throws。默认构造器直接把枚举里的 message 作为父类 RuntimeException 的 detailMessage,同时把状态枚举保存到自身字段中,方便全局异常处理器后续读取。
public class ApiException extends RuntimeException {
private final ErrorStatus status;
private final transient Object[] args;
public ApiException(ErrorStatus status) {
super(status.getMessage());
this.status = status;
this.args = new Object[0];
}
public ApiException(ErrorStatus status, Object... args) {
super(MessageFormatter.format(status.getMessage(), args));
this.status = status;
this.args = args;
}
public ErrorStatus getStatus() {
return status;
}
public Object[] getArgs() {
return args;
}
public int getCode() {
return status.getCode();
}
public int getHttpStatusCode() {
return status.getHttpStatusCode();
}
}
第二个构造器带了一个 Object... args 变长参数,目的是支持动态消息覆盖。比如枚举里默认消息是“参数校验失败”,但具体哪个字段校验失败可以通过占位符传进来。这里的 MessageFormatter 是一个很小的工具类,它把消息模板里的 {0}、{1} 依次替换成实际参数,类似于 SLF4J 的占位符风格。
之所以把 args 字段标记为 transient,是因为异常对象在某些场景下可能被序列化,而 Object 数组里的元素并不总是可序列化的。如果只是记录排查用的动态参数,通常没有序列化必要,标记 transient 可以避免序列化异常。线程安全方面,枚举状态本身不可变,args 数组也只保存引用,不会被修改,因此这个异常基类在多线程环境下同样安全。
三、全局异常处理器统一输出
有了承载状态的异常之后,还需要把异常转换成前端能读懂的响应结构。Spring Boot 项目里可以借助 @RestControllerAdvice 和 @ExceptionHandler 实现全局拦截。处理器拿到 ApiException 后,读取它携带的枚举状态,再按照统一格式返回 JSON。
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ApiException.class)
public ResponseEntity<ErrorResponse> handleApiException(ApiException ex) {
ErrorResponse body = new ErrorResponse(
ex.getCode(),
ex.getMessage(),
ex.getHttpStatusCode()
);
return ResponseEntity.status(ex.getHttpStatusCode()).body(body);
}
}
ErrorResponse 是一个简单的响应体类,只包含 code、message、httpStatus 三个字段。它的结构要和前端约定一致,前端只需要判断 code 就能确定错误类型,message 用于展示给用户,httpStatus 可以方便运维在网关层识别错误等级。这样一来,从抛出异常到返回响应,整个链路里都没有散落的字符串或数字。
public class ErrorResponse {
private int code;
private String message;
private int httpStatus;
public ErrorResponse(int code, String message, int httpStatus) {
this.code = code;
this.message = message;
this.httpStatus = httpStatus;
}
public int getCode() {
return code;
}
public String getMessage() {
return message;
}
public int getHttpStatus() {
return httpStatus;
}
}
这种设计比直接使用 Spring 自带的 ResponseStatusException 更灵活。ResponseStatusException 虽然也能携带状态码和原因,但它更偏向 Web 层异常,而且错误码体系依然需要自己维护。使用枚举驱动的自定义异常,业务模块不需要依赖 Servlet API,同时又能保留完整的业务错误码维度。
如果项目中已经有大量旧异常,不建议一次性全部推翻重写。可以先在新模块中应用这套枚举状态模式,旧异常保持原有处理逻辑,等新模块稳定后再逐步迁移。这样风险更小,也更容易让团队接受。
四、动态消息与序列化注意事项
枚举里保存的 message 通常只是默认文案,实际业务中往往需要携带动态信息。例如“用户不存在”需要带上具体 userId,“订单支付超时”需要带上订单号。MessageFormatter 可以非常轻量地完成占位符替换。
public final class MessageFormatter {
private MessageFormatter() {
}
public static String format(String template, Object... args) {
if (args == null || args.length == 0) {
return template;
}
String result = template;
for (int i = 0; i < args.length; i++) {
result = result.replace("{" + i + "}", String.valueOf(args[i]));
}
return result;
}
}
使用时只需把枚举默认消息写成带占位符的模板。比如 PARAM_INVALID 的消息可以定义为“参数校验失败,字段:{0}”,然后通过 throw new ApiException(ErrorStatus.PARAM_INVALID, "email") 抛出异常。这样既保留了枚举状态的统一入口,又兼顾了动态信息的表达。
另一个容易忽略的问题是 Jackson 序列化。默认情况下,Jackson 会把枚举序列化成它的名称字符串,比如 ErrorStatus.USER_NOT_FOUND 会输出为 USER_NOT_FOUND,而不是 10001 或“用户不存在”。如果希望接口直接返回枚举状态对象,可以在枚举类上添加 @JsonFormat(shape = JsonFormat.Shape.OBJECT),这样 Jackson 就会读取枚举的 getter 方法,按对象结构输出 code、message 和 httpStatusCode。但要注意,这样也可能把不希望暴露的 httpStatus 枚举对象一并序列化出来,必要时可以在对应 getter 上追加 @JsonIgnore。
从整体架构看,枚举驱动状态初始化最大的收益并不是少写了几个参数,而是让异常状态从口头约定变成了强类型约束。调用方在编译阶段就能发现状态引用错误,而不是等运行时返回了莫名其妙的错误码才发现问题。配合统一响应体、全局异常处理、动态消息占位符,这套模式足以支撑大多数中后台系统的业务异常管理。
错误码体系的维护最终还是要落到团队规范上。枚举文件应当由核心成员负责评审,新增错误码时要避免重复、尽量沿用已有语义,必要时在枚举注释中说明使用场景。这样自定义异常才能真正成为项目里清晰、可维护的基础设施,而不是另一种形式的魔法值堆砌。