java 自定义异常映射到前端错误码的核心做法是定义一个包含业务状态码和描述信息的统一异常基类,并在 web 层通过全局异常处理器拦截该异常,将其转换为前端约定的 json 格式响应。具体实现时,需要确保异常对象能携带具体的错误码(如 http 400、500 或自定义业务码),控制器advice 捕获异常后提取这些字段并构建标准返回体,这样前端就能根据统一的 json 结构解析出错误信息。

如何设计支持错误码的自定义异常基类
设计自定义异常的关键在于继承 RuntimeException 并扩展用于存储错误码和消息的字段。通常的做法是创建一个抽象基类 BaseException,它接受错误码、消息以及可选的原始异常作为参数。子类只需调用父类构造函数传入特定的业务错误码即可。这种设计确保了所有业务异常都遵循相同的契约,便于后续的统一处理。例如,定义一个 BusinessException 继承自 BaseException,当业务逻辑出错时抛出该异常,并传入对应的错误码如 1001 表示参数错误。

public class BaseException extends RuntimeException {
private final String errorCode;
private final String message;
public BaseException(String errorCode, String message) {
super(message);
this.errorCode = errorCode;
this.message = message;
}
public String getErrorCode() {
return errorCode;
}
public String getMessage() {
return message;
}
}
上述代码展示了基础结构的实现。在实际使用中,开发者可以定义更具体的异常类,如 UserNotFoundException,其构造函数直接调用 super("USER_NOT_FOUND", "用户不存在")。这样在业务层抛出异常时,就自动携带了前端需要的结构化数据。注意不要在这里处理 HTTP 状态码,因为那是 Web 层的职责,异常类只负责承载业务语义。
如何通过全局异常处理器转换响应格式
在 Spring Boot 等框架中,使用 @RestControllerAdvice 配合 @ExceptionHandler 是实现映射的标准方式。处理器方法接收自定义异常实例,从中提取错误码和消息,然后构造一个包含 code、message 和 data 字段的通用响应对象。对于未捕获的异常,可以提供默认的错误码如 500。这种方式将异常处理逻辑与业务逻辑彻底分离,保证了 Controller 层的整洁。同时,可以根据异常类型设置不同的 HTTP 状态码,例如 BusinessException 通常对应 200 OK 但内部 code 非零,而系统异常可能对应 500。
使用Atmosphere构建通过WebSocket、SSE、gRPC、WebTransport、MCP、A2A和AG-UI流传输的JVM代理网关,并带有治理钩子。

@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(BaseException.class)
public ResponseEntity<apiresponse> handleBaseException(BaseException ex) {
ApiResponse response = new ApiResponse();
response.setCode(ex.getErrorCode());
response.setMessage(ex.getMessage());
response.setData(null);
return ResponseEntity.ok(response);
}
@ExceptionHandler(Exception.class)
public ResponseEntity<apiresponse> handleException(Exception ex) {
ApiResponse response = new ApiResponse();
response.setCode("SYSTEM_ERROR");
response.setMessage("系统内部错误");
response.setData(null);
return ResponseEntity.status(500).body(response);
}
}
class ApiResponse {
private String code;
private String message;
private Object data;
// getters and setters
}</apiresponse></apiresponse>
这段代码展示了完整的处理流程。当抛出 BaseException 时,handleBaseException 会被触发,返回 HTTP 200 但 body 中包含业务错误码。如果抛出其他 Exception,则进入兜底处理,返回 500 状态码。前端接收到响应后,检查 code 字段即可判断是否成功。若 code 为 SYSTEM_ERROR 或自定义业务码,则展示相应提示。这种机制确保了错误信息的标准化传递。
如何处理嵌套异常中的错误码提取
在实际开发中,自定义异常往往是由底层异常包装而成的,例如数据库操作失败导致 DataAccessException,进而被业务层包装为 BusinessException。此时,需要从嵌套的 cause 链中提取最原始的异常信息,或者保留顶层异常的错误码。如果希望保留原始异常的堆栈信息以便调试,可以在 BaseException 中增加 getCause() 的重写,但在映射到前端时,通常只关心顶层异常定义的 errorCode。若底层异常也携带了业务错误码,可以选择合并或优先使用顶层码。例如,当 UserService 捕获 SQLException 并抛出 BusinessException("DB_ERROR", "数据库连接失败") 时,前端看到的是 DB_ERROR,而不是底层的 SQL 异常细节。这种做法保护了系统内部实现细节,同时提供了清晰的业务指引。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南










