Java自定义业务异常应通过@ControllerAdvice全局拦截，返回标准化响应体和精准状态码，避免Controller内try-catch或直接抛出500错误；定义继承RuntimeException的BusinessException携带code和message，统一处理并记录日志、脱敏敏感信息。
Java 自定义业务异常在 Controller 层返回，核心是 **统一拦截 + 标准化响应体 + 精准状态码**。不建议直接 throw 后让 Spring Boot 默认 500 页面，也不推荐每个 Controller 都 try-catch。
1. 定义自定义业务异常类
继承 RuntimeException（非检查异常，调用方无需强制处理），并携带业务错误码和提示信息：
public class BusinessException extends RuntimeException {
private final int code;
public BusinessException(int code, String message) {
super(message);
this.code = code;
}
public int getCode() {
return code;
}
}
可进一步抽象为带枚举错误码的版本（如 ErrorCode.USER_NOT_FOUND(1001, "用户不存在")），便于维护和前端识别。
2. 使用 @ControllerAdvice + @ExceptionHandler 全局捕获
在 Controller 层之外，用全局异常处理器统一响应格式：
立即学习“Java免费学习笔记（深入）”；
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(BusinessException.class)
@ResponseBody
public ResponseEntity<ApiResponse> handleBusinessException(BusinessException e) {
ApiResponse result = ApiResponse.fail(e.getCode(), e.getMessage());
return ResponseEntity.status(HttpStatus.OK).body(result);
}
// 可选：兜底处理其他未预期异常（如 RuntimeException）
@ExceptionHandler(Exception.class)
@ResponseBody
public ResponseEntity<ApiResponse> handleUnexpectedException(Exception e) {
ApiResponse result = ApiResponse.fail(500, "系统繁忙，请稍后再试");
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(result);
}
}
-
注意 HttpStatus：业务异常通常用
200 OK返回（因为不是 HTTP 协议层错误），靠响应体中的code区分成功/失败；若需语义更明确，也可用400 Bad Request表示客户端参数或业务校验失败。 -
ApiResponse 是你定义的标准响应包装类，至少包含
code、message、data字段。
3. Controller 中直接抛出，不捕获
业务逻辑中检测到问题时，直接 throw 自定义异常，保持代码简洁清晰：
@GetMapping("/user/{id}")
public ApiResponse getUser(@PathVariable Long id) {
User user = userService.findById(id);
if (user == null) {
throw new BusinessException(1001, "用户不存在");
}
return ApiResponse.success(user);
}
- 不用 try-catch 包裹，避免模板化代码污染业务逻辑。
- 异常信息和错误码由具体业务决定，Controller 层只负责“触发”和“返回”，不参与错误组装。
4. 补充建议
- 日志记录：在
@ExceptionHandler中加一行log.warn("业务异常: {}", e.getMessage(), e)，方便排查。 - 敏感信息脱敏：不要把数据库字段名、堆栈、内部路径等返回给前端，
message应面向用户友好。 - 国际化支持（进阶）：可通过 Locale + MessageSource 动态解析 message，适配多语言。
- 与 Swagger / OpenAPI 配合：用
@ApiResponses注解标注可能的业务异常响应结构，提升 API 文档完整性。
这样设计后，所有 Controller 方法都只需专注正向流程，异常路径由统一入口接管，响应格式一致，前后端协作更高效。
