本文系统解析 spring boot 中自定义异常（如 resourcenotfoundexception）无法正确返回 json 响应的核心成因，涵盖全局处理器未生效、响应体为空、逻辑误判等典型问题，并提供可直接落地的分层异常设计、@restcontrolleradvice 规范实现及避坑指南。
本文系统解析 spring boot 中自定义异常（如 resourcenotfoundexception）无法正确返回 json 响应的核心成因，涵盖全局处理器未生效、响应体为空、逻辑误判等典型问题，并提供可直接落地的分层异常设计、@restcontrolleradvice 规范实现及避坑指南。
在 Spring Boot 项目中，当开发者精心定义了 ResourceNotFoundException 并配置了 @RestControllerAdvice 全局异常处理器，却在 Postman 或前端调用中收到空响应、500 错误页或默认 JSON（含 timestamp/status/error 字段），而非预期的 { "code": "NOT_FOUND", "message": "资源不存在" } ——这并非配置遗漏，而是典型的“三重失配”：异常未被正确捕获、响应结构不匹配 HTTP 语义、处理逻辑破坏分层职责。
一、根本原因：为什么你的异常处理器“形同虚设”
✅ 常见错误模式
-
注解位置错误：将
@ExceptionHandler直接写在@RestController的某个@GetMapping方法内 → Spring 完全忽略，回退至默认错误处理器； -
异常类型不匹配：抛出的是
RuntimeException子类，但处理器只监听Exception或具体受检异常； -
响应体序列化失败：
@ResponseStatus(HttpStatus.NOT_FOUND)与返回String或无@ResponseBody的 POJO 混用，导致 Spring 无法自动序列化为 JSON； -
组件扫描遗漏：
@RestControllerAdvice类未被 Spring 容器加载（如包路径不在@SpringBootApplication扫描范围内）。
❌ 典型反模式代码（请立即规避）
// 错误：混用 @GetMapping 与 @ExceptionHandler —— Spring 不识别！
@RestController
public class UserController {
@GetMapping("/users/{id}")
public User getUser(@PathVariable String id) {
// ...业务逻辑
throw new RuntimeException("User not found"); // 抛出原始 RuntimeException
}
@ExceptionHandler(RuntimeException.class) // ❌ 此方法永不执行！
public ResponseEntity<String> handle(RuntimeException e) {
return ResponseEntity.status(404).body(e.getMessage());
}
}二、正确实践：分层设计 + 规范实现
1. 定义语义清晰的业务异常基类
// 关键：继承 RuntimeException，避免强制 try-catch；关闭堆栈填充提升性能
public abstract class BusinessException extends RuntimeException {
private final ErrorCode errorCode;
protected BusinessException(ErrorCode errorCode, Object... args) {
super(String.format(errorCode.getMessage(), args), null, false, false);
this.errorCode = errorCode;
}
// getter...
}
// 具体异常（预期内的 4xx 场景）
public class ResourceNotFoundException extends BusinessException {
public ResourceNotFoundException(String resource, String id) {
super(ErrorCode.RESOURCE_NOT_FOUND, resource, id);
}
}2. 实现规范的全局异常处理器
@RestControllerAdvice
public class GlobalExceptionHandler {
// ✅ 捕获业务异常：返回 4xx + 自定义 JSON
@ExceptionHandler(ResourceNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND) // 语义精准：资源不存在即 404
public ErrorResponse handleResourceNotFound(ResourceNotFoundException e) {
return new ErrorResponse("NOT_FOUND", e.getMessage(), System.currentTimeMillis());
}
// ✅ 捕获系统异常：返回 5xx + 脱敏响应 + 详细日志
@ExceptionHandler(Exception.class) // 捕获所有未处理异常（兜底）
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ErrorResponse handleUnexpectedError(HttpServletRequest request, Exception e) {
// 记录完整堆栈（仅内部日志）
log.error("Unhandled exception on path: {}", request.getRequestURL(), e);
return new ErrorResponse("INTERNAL_ERROR", "系统繁忙，请稍后重试", System.currentTimeMillis());
}
}
// 统一响应结构（确保 Jackson 可序列化）
public class ErrorResponse {
private String code;
private String message;
private long timestamp;
public ErrorResponse(String code, String message, long timestamp) {
this.code = code;
this.message = message;
this.timestamp = timestamp;
}
// 必须提供 public getter！
}3. 在 Service 层“只抛不转”，保持语义纯净
@Service
public class UserService {
public User findById(String id) {
return userRepository.findById(id)
.orElseThrow(() -> new ResourceNotFoundException("User", id)); // ✅ 真实失败，不包装
}
}三、关键注意事项与工程建议
- 禁止在 DAO/Service 层 catch 后返回 Resp.error()：这会掩盖异常、破坏事务回滚、丢失原始堆栈；
-
区分入口层与调用层：API Controller 是入口，必须由
@RestControllerAdvice统一转换；RPC/DB 调用是内部链路，异常应原样向上抛； -
验证处理器是否生效：启动时检查日志中是否有
Mapped "{[/error]}"或GlobalExceptionHandler初始化记录；使用@Order(Ordered.HIGHEST_PRECEDENCE)控制优先级； -
测试覆盖场景：
# curl -i http://localhost:8080/users/999 # 应返回：HTTP/1.1 404 Not Found + {"code":"NOT_FOUND","message":"User not found","timestamp":...}
总结：Spring Boot 异常处理的本质不是“统一捕获”，而是“分层归责”——内部调用层负责真实失败传递，API 入口层负责语义化响应转换。只要遵循
业务异常明确抛、全局处理器精准捕、响应结构标准化三原则，即可彻底解决自定义异常失效问题，构建健壮、可观测、易维护的 REST API 错误处理体系。
