在Java项目开发过程中，业务异常的处理是系统健壮性的重要组成部分，而自定义业务异常码能够让异常信息更具辨识度，方便开发者和运维人员快速定位问题。合理的异常码规范可以避免不同模块异常码冲突，提升团队协作效率。
业务异常码的设计原则
设计业务异常码需要遵循几个核心原则，确保异常码的可读性和扩展性：
- 唯一性：每个异常码对应唯一的业务场景，避免重复定义
- 可分类性：异常码需要包含模块、错误类型等信息，方便快速归类
- 可读性：异常码格式清晰，开发者看到码就能大致判断错误来源
- 可扩展性：预留足够的编码空间，支持后续业务扩展
常见异常码格式定义
通常业务异常码可以采用分段式结构，比如采用模块编码-错误类型-具体错误序号的格式，不同段之间用分隔符隔开。常见的模块编码可以用2位数字表示，错误类型用1位数字表示，具体错误序号用2位数字表示，整体结构如下：
| 分段 | 长度 | 说明 | 示例 |
|---|---|---|---|
| 模块编码 | 2位 | 对应系统不同业务模块 | 01代表用户模块，02代表订单模块 |
| 错误类型 | 1位 | 标识错误的大类 | 1代表参数错误，2代表业务校验错误，3代表系统错误 |
| 具体错误序号 | 2位 | 同一类型下的具体错误 | 01代表用户不存在，02代表密码错误 |
按照这个格式，用户模块密码错误的异常码就可以定义为01-2-02，清晰明确。
自定义业务异常的实现
首先我们需要定义一个异常码枚举，统一管理所有的业务异常码和对应的描述信息：
/**
* 业务异常码枚举
*/
public enum BusinessErrorCodeEnum {
// 用户模块 参数错误
USER_PARAM_NULL(01, 1, 01, "用户参数为空"),
// 用户模块 业务校验错误
USER_NOT_EXIST(01, 2, 01, "用户不存在"),
USER_PASSWORD_ERROR(01, 2, 02, "用户密码错误"),
// 订单模块 业务校验错误
ORDER_NOT_EXIST(02, 2, 01, "订单不存在"),
ORDER_STATUS_ERROR(02, 2, 02, "订单状态异常");
/**
* 模块编码
*/
private final int moduleCode;
/**
* 错误类型
*/
private final int errorType;
/**
* 具体错误序号
*/
private final int errorNo;
/**
* 错误描述
*/
private final String description;
BusinessErrorCodeEnum(int moduleCode, int errorType, int errorNo, String description) {
this.moduleCode = moduleCode;
this.errorType = errorType;
this.errorNo = errorNo;
this.description = description;
}
/**
* 获取完整异常码
* @return 格式为 moduleCode-errorType-errorNo 的字符串
*/
public String getFullErrorCode() {
return String.format("%02d-%d-%02d", moduleCode, errorType, errorNo);
}
public String getDescription() {
return description;
}
}
接下来定义自定义业务异常类，继承RuntimeException，方便在业务代码中抛出：
/**
* 自定义业务异常
*/
public class BusinessException extends RuntimeException {
/**
* 异常码
*/
private final String errorCode;
/**
* 异常描述
*/
private final String errorMsg;
public BusinessException(BusinessErrorCodeEnum errorCodeEnum) {
super(errorCodeEnum.getDescription());
this.errorCode = errorCodeEnum.getFullErrorCode();
this.errorMsg = errorCodeEnum.getDescription();
}
public BusinessException(String errorCode, String errorMsg) {
super(errorMsg);
this.errorCode = errorCode;
this.errorMsg = errorMsg;
}
public String getErrorCode() {
return errorCode;
}
public String getErrorMsg() {
return errorMsg;
}
}
业务异常的使用示例
在业务代码中，当遇到业务校验不通过的情况，可以直接抛出自定义业务异常：
public class UserService {
/**
* 用户登录方法
* @param username 用户名
* @param password 密码
*/
public void login(String username, String password) {
// 参数校验
if (username == null || username.trim().isEmpty()) {
throw new BusinessException(BusinessErrorCodeEnum.USER_PARAM_NULL);
}
// 模拟用户不存在场景
User user = getUserByUsername(username);
if (user == null) {
throw new BusinessException(BusinessErrorCodeEnum.USER_NOT_EXIST);
}
// 模拟密码错误场景
if (!user.getPassword().equals(password)) {
throw new BusinessException(BusinessErrorCodeEnum.USER_PASSWORD_ERROR);
}
// 登录成功逻辑
System.out.println("用户登录成功");
}
private User getUserByUsername(String username) {
// 模拟查询用户逻辑
return null;
}
static class User {
private String username;
private String password;
public String getPassword() {
return password;
}
}
}
全局异常处理配置
为了让业务异常返回统一的格式给前端，可以配置全局异常处理器，捕获BusinessException并返回标准化的响应：
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
/**
* 全局异常处理器
*/
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(BusinessException.class)
public ResultVO handleBusinessException(BusinessException e) {
return new ResultVO(e.getErrorCode(), e.getErrorMsg(), null);
}
/**
* 统一响应结构
*/
static class ResultVO {
private String code;
private String message;
private Object data;
public ResultVO(String code, String message, Object data) {
this.code = code;
this.message = message;
this.data = data;
}
public String getCode() {
return code;
}
public String getMessage() {
return message;
}
public Object getData() {
return data;
}
}
}
通过这样的设计，所有的业务异常都会有统一的码和描述，前端可以根据异常码做对应的提示处理，后端也可以通过异常码快速定位问题所在的模块和场景，提升开发和运维效率。