Java自定义异常在Controller层统一处理的核心是@ControllerAdvice+@ExceptionHandler，通过继承RuntimeException定义业务异常类并携带错误码与消息，再由全局异常处理器分类拦截、封装为统一Result响应体返回。
Java 中自定义异常在 Controller 层统一转换，核心是通过 @ControllerAdvice + @ExceptionHandler 实现全局异常拦截与标准化响应封装，避免每个 Controller 重复 try-catch。
定义业务自定义异常类
继承 RuntimeException（非检查异常，使用更灵活），并携带错误码、消息、可选的扩展字段：
public class BusinessException extends RuntimeException {
private final int code;
private final String message;
public BusinessException(int code, String message) {
super(message);
this.code = code;
this.message = message;
}
// getter 方法略
}
也可按场景细分，如 ParamException、AuthException，便于分类处理。
编写全局异常处理器
创建一个被 @ControllerAdvice 注解的类，在其中用 @ExceptionHandler 拦截对应异常类型：
sc-java-to-ts-interface
下载
将后端 Java 接口文档转换为前端 TypeScript 类型定义（interface / type）。输入：飞书文档、Spring Boot 接口文档、Swagger/OpenAPI、手写 API 文档等。输出：包含请求参数与响应结果的 .md 文件，含完整 JSDoc 注释。触发关键词：Java 转 TS、接口转换、生成前端类型、接口文档转 TypeScript、DTO/VO/BO 转 interface、后端文档转前端类型、生成接口类型、类型定义生成。
立即学习“Java免费学习笔记（深入）”；
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(BusinessException.class)
@ResponseBody
@ResponseStatus(HttpStatus.OK) // 通常返回 200，由 body 中 code 标识业务状态
public Result<?> handleBusinessException(BusinessException e) {
return Result.fail(e.getCode(), e.getMessage());
}
@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseBody
public Result<?> handleValidationException(MethodArgumentNotValidException e) {
String msg = e.getBindingResult().getFieldErrors().get(0).getDefaultMessage();
return Result.fail(400, "参数校验失败: " + msg);
}
@ExceptionHandler(Exception.class)
@ResponseBody
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public Result<?> handleUnexpectedException(Exception e) {
log.error("未预期异常", e);
return Result.fail(500, "系统繁忙，请稍后再试");
}
}
- 注意：多个
@ExceptionHandler的匹配顺序遵循“子类优先”，所以具体异常（如AuthException）要写在通用异常（如Exception.class）之前 -
@ResponseStatus可按需设置 HTTP 状态码；业务异常常用 200 + 自定义 code，技术异常才用 4xx/5xx - 返回统一响应体（如
Result<t></t>），包含code、message、data字段，前端可统一解析
在 Service 或 Controller 中直接抛出自定义异常
无需捕获，让异常自然向上抛出，交由全局处理器处理：
@Service
public class UserService {
public User getUserById(Long id) {
if (id == null || id <= 0) {
throw new BusinessException(1001, "用户 ID 不合法");
}
User user = userMapper.selectById(id);
if (user == null) {
throw new BusinessException(1002, "用户不存在");
}
return user;
}
}
Controller 层调用时完全无感知，代码干净，关注点分离清晰。
补充：配合统一返回体与日志增强
可在异常处理器中记录关键日志（如错误码、用户 ID、请求路径），方便排查；同时确保 Result 类支持泛型、空 data 安全序列化，并与前端约定好字段名（如 success、errCode）。
- 建议对敏感异常信息（如数据库报错）做脱敏，生产环境不暴露堆栈或内部类名
- 可引入
@Order控制多个@ControllerAdvice的执行顺序 - 若用 WebFlux，需改用
@ControllerAdvice配合WebExceptionHandler或全局过滤器
