本文介绍如何在 Spring Boot 控制器中捕获并友好响应 JSON 请求体语法错误（如非法 JSON 格式），通过全局异常处理器统一返回标准化的 400 Bad Request 提示，避免暴露底层异常堆栈。
本文介绍如何在 spring boot 控制器中捕获并友好响应 json 请求体语法错误（如非法 json 格式），通过全局异常处理器统一返回标准化的 `400 bad request` 提示，避免暴露底层异常堆栈。
在 Spring Boot 应用中，当客户端提交格式错误的 JSON（例如缺少引号、逗号遗漏、括号不匹配等），Spring MVC 默认会抛出 HttpMessageNotReadableException，并返回 500 Internal Server Error 及完整堆栈——这对前端不友好，也存在安全风险。最简洁可靠的解决方案是使用 @ControllerAdvice 配合 @ExceptionHandler 实现全局异常拦截。
以下是一个生产就绪的处理示例：
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(HttpMessageNotReadableException.class)
public ResponseEntity<Map<String, String>> handleJsonSyntaxError(
HttpMessageNotReadableException e, HttpServletRequest request) {
Map<String, String> errorResponse = new HashMap<>();
errorResponse.put("timestamp", Instant.now().toString());
errorResponse.put("status", "400");
errorResponse.put("error", "Bad Request");
errorResponse.put("message", "Invalid JSON syntax in request body");
errorResponse.put("path", request.getRequestURI());
return ResponseEntity.badRequest().body(errorResponse);
}
}✅ 优势说明：
- @ControllerAdvice 使该处理器自动作用于所有 @RestController，无需重复添加；
- 返回结构化 JSON（而非纯字符串），符合现代 API 设计规范；
- 包含 timestamp 和 path 等上下文字段，便于日志追踪与调试；
- 明确使用 ResponseEntity.badRequest()，HTTP 状态码语义清晰。
⚠️ 注意事项：
- 请确保 GlobalExceptionHandler 类被 Spring 容器扫描到（位于主启动类同包或子包下，或显式添加 @ComponentScan）；
- 若项目已启用 spring-boot-starter-validation，@Valid 注解仅校验 Java Bean 约束（如 @NotNull），无法捕获 JSON 解析失败——它发生在反序列化阶段之前，因此必须依赖 HttpMessageNotReadableException 拦截；
- 如需进一步区分「JSON 语法错误」与「字段类型不匹配」（如字符串传入 Long 字段），可额外捕获 MethodArgumentTypeMismatchException 并定制提示。
综上，该方案轻量、通用、可扩展，是 Spring Boot 项目中处理请求体 JSON 语法错误的标准实践。
