Java自定义业务异常码核心是建立可读、可维护、可扩展的错误码体系，需统一管理、分层分类、携带上下文、与异常类强绑定，推荐枚举+自定义异常实现。
Java中自定义业务异常码，核心是建立**可读、可维护、可扩展的错误码体系**，而不是简单用数字或字符串硬编码。关键在于：统一管理、分层分类、携带上下文、与异常类强绑定。
一、异常码设计基本原则
业务异常码不是随意编号，需遵循以下约定：
- 唯一性：每个业务场景对应唯一错误码（如USER_001表示用户不存在，USER_002表示用户名已存在）
- 可读性：采用“模块_序号”格式（如ORDER_CREATE_FAILED），避免纯数字（如1001）
- 分层性：按系统模块划分前缀（USER_、ORDER_、PAY_），便于定位和归类
- 不变性：上线后错误码语义不可变更，新增用新码，禁用旧码需明确标注废弃
- 可携带信息：异常码本身不传参，但对应异常类应支持动态填充提示文案（如“订单{0}不存在”）
二、推荐实现方式：枚举 + 自定义异常类
用枚举统一管理错误码，再通过自定义异常封装，是最清晰、类型安全的做法。
1. 定义错误码枚举（含描述与HTTP状态码）
立即学习“Java免费学习笔记（深入）”；
public enum BizErrorCode {
USER_NOT_FOUND("USER_001", "用户不存在", HttpStatus.NOT_FOUND),
USER_NAME_DUPLICATED("USER_002", "用户名已存在", HttpStatus.CONFLICT),
ORDER_INVALID_STATUS("ORDER_003", "订单状态非法", HttpStatus.BAD_REQUEST);
private final String code;
private final String message;
private final HttpStatus httpStatus;
BizErrorCode(String code, String message, HttpStatus httpStatus) {
this.code = code;
this.message = message;
this.httpStatus = httpStatus;
}
// getter 省略
}
2. 自定义业务异常类（支持参数化提示）
public class BizException extends RuntimeException {
private final String code;
private final HttpStatus httpStatus;
private final Object[] args; // 用于 MessageFormat 填充
public BizException(BizErrorCode errorCode, Object... args) {
super(errorCode.getMessage()); // 默认用枚举里的基础文案
this.code = errorCode.getCode();
this.httpStatus = errorCode.getHttpStatus();
this.args = args;
}
// 提供带参数的提示文案（如 “订单{0}不存在” → “订单12345不存在”）
public String getDetailMessage() {
return args == null || args.length == 0
? getMessage()
: MessageFormat.format(getMessage(), args);
}
}
3. 使用示例
if (user == null) {
throw new BizException(BizErrorCode.USER_NOT_FOUND, userId);
}
// 抛出时：code=USER_001，message="用户不存在"，detailMessage="用户1001不存在"
三、配套建议：统一异常处理器 & 返回结构
前端需要稳定、结构化的错误响应，因此需配合全局异常处理器：
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(BizException.class)
public ResponseEntity> handleBizException(BizException e) {
return ResponseEntity.status(e.getHttpStatus())
.body(ApiResponse.fail(e.getCode(), e.getDetailMessage()));
}
}
// 统一响应体示例
public class ApiResponse {
private String code; // 如 USER_001
private String message; // 如 “用户1001不存在”
private T data;
// ...
}
四、进阶考虑：国际化与配置化
若需多语言支持，可将错误码描述外置到 properties 文件，通过 ResourceBundle 加载；高频变动的码（如营销活动临时规则）也可考虑从配置中心动态加载，但需权衡一致性与复杂度。
不复杂但容易忽略：错误码必须和日志、监控、告警联动——例如在抛出 PAY_TIMEOUT 时，自动打点+上报，才能真正发挥业务异常码的价值。
