外观
16 - 返回值如何变成 JSON:响应写出与统一异常处理
适用版本:Spring MVC 6.x。JSON 示例依赖可用的 Jackson 消息转换器,具体行为还受 Jackson 版本和配置影响。
前置阅读:14 - DispatcherServlet 调度全流程和15 - Controller 参数解析与数据绑定。本文从 Controller 已经返回或抛出异常的位置继续。
摘要
Controller 已经正常 return,客户端却收到 500,故障可能发生在返回值处理或 JSON 序列化阶段。Java 对象不能直接通过 HTTP 发送:框架要先决定如何解释返回值,再选择响应格式,把对象转换成字节并写出。把对象转换为 JSON 等传输格式的过程称为序列化。
本文先解释正常响应的处理链,再说明异常如何转为错误响应,最后讨论响应已提交和数据库事务已提交这两个边界。理解这些阶段,才能判断错误处理器还能做什么,以及客户端重试是否可能重复执行业务。
1. 场景:业务执行成功,响应为什么失败
返回对象含循环引用、懒加载代理或无法序列化字段时,可能在 Controller 返回之后才出现异常。循环引用是对象相互引用,例如订单引用用户、用户又引用订单;序列化器若继续沿引用展开,就可能递归失败。懒加载代理则在访问属性时才读取数据,序列化时访问这些属性可能触发额外查询,或因数据访问环境已不可用而失败。是否发生这些问题取决于对象结构、序列化配置和持久化上下文。
因此,业务方法成功完成并不等于响应成功。数据库操作若已提交,响应失败也不会自动撤销业务结果。
以创建订单请求为例,可以把完整链路分成四个需要分别检查的成功条件。Handler 是框架为请求选中的处理器,在这里通常对应一个 Controller 方法:
text
匹配到 Handler
→ 参数成功解析
→ 业务方法成功完成
→ 返回值成功协商、序列化并写出客户端收到 500 只能证明最终请求失败,不能证明业务方法或数据库事务没有成功。
2. 返回值处理链
HandlerMethodReturnValueHandler 是方法返回值处理器,负责决定返回值的含义:它是要写进响应体的数据,还是用于生成页面的视图信息?HttpMessageConverter 是 HTTP 消息转换器,负责按选定的媒体类型读写消息;在响应阶段,它把 Java 值转换为响应内容。两者分别回答“如何处理返回值”和“如何写出内容”。
下面展示常见同步响应的分支,异步与流式返回值另有处理路径:
图表将在阅读到此处时加载…
@RestController 组合了 @Controller 与 @ResponseBody。@ResponseBody 表示把返回值写入响应体,而不是把它作为视图名称处理;普通对象返回值通常由 RequestResponseBodyMethodProcessor 接管,再选择合适的转换器。它并不保证任何返回值都会变成 JSON,实际格式仍取决于内容协商和可用转换器。
与参数解析类似,返回值处理也是有序责任链:框架按顺序询问处理器,由首个支持当前返回类型和方法声明的处理器接管结果,并非所有处理器依次加工同一个值。ResponseEntity 可同时表达状态码、响应头和响应体;ModelAndView 表达模型数据和视图信息。它们与 @ResponseBody、视图名称、异步返回值和流式响应走的处理路径并不相同。
3. 内容协商
内容协商是客户端与服务端确定响应格式的过程。请求头 Accept 表达客户端可接受的媒体类型,Controller 映射中的 produces 限定接口能提供的类型;响应头 Content-Type 则说明实际发送的内容类型,例如 application/json。
Spring 会结合这些条件、返回类型和可用转换器选择响应媒体类型,再寻找能写出该 Java 类型的转换器。如果双方没有可接受的格式,可能得到 406;如果格式已确定但对象无法写出,则可能出现转换异常。两类问题不能只凭最终状态码区分,还要查看具体异常和异常处理配置。
不要默认所有客户端都接受 JSON;接口契约应明确响应的 Content-Type 和字符编码。
对于 JSON API,至少要同时检查:
- 请求
Accept是否允许服务端提供的媒体类型; - Controller 的
produces是否过度收窄; - Jackson Converter 是否存在并支持返回类型;
- 自定义 Converter 是否改变了默认顺序;
- 响应 Header 是否在写出前被 Filter 或 Advice 改写。
4. 异常解析链
HandlerExceptionResolver 是异常解析器,负责把异常转为 MVC 可处理的结果,例如错误响应或错误页面。Controller 调用或返回值处理中的异常进入 DispatcherServlet 的异常处理流程后,会交给解析器链;这不代表请求链中任何位置的异常都能被 Controller 的异常处理器接住。
常见机制包括:
@ExceptionHandler:声明处理指定异常的方法;@ControllerAdvice:把异常处理等规则应用到一组 Controller,@RestControllerAdvice还带有响应体语义;- 框架标准异常到状态码的映射;
- 默认异常解析。
异常解析器同样有顺序。某个 Resolver 返回了处理结果后,后续 Resolver 通常不会继续处理;若全局 Advice 过宽地捕获 Exception,可能遮蔽框架对 400、405、415 等异常的标准映射。
下面是统一异常处理的类片段,省略 Spring Web 和 ResponseEntity 的导入。应用需定义 OrderNotFoundException,将该 Advice 注册为 Bean,并配置能写出 ApiError 的 JSON 转换器。异常消息应是允许公开给客户端的业务说明。
java
@RestControllerAdvice
class ApiExceptionHandler {
@ExceptionHandler(OrderNotFoundException.class)
ResponseEntity<ApiError> handle(OrderNotFoundException e) {
return ResponseEntity.status(404)
.body(new ApiError("ORDER_NOT_FOUND", e.getMessage()));
}
record ApiError(String code, String message) { }
}预期响应:匹配到 OrderNotFoundException 的处理方法且响应仍可写出时,HTTP 状态为 404,响应体包含 code 和 message,其中 code 为 ORDER_NOT_FOUND。错误响应本身也需要序列化,因此统一异常处理并不能绕过转换器或响应提交的限制。
Spring Framework 6 支持以 ProblemDetail 表达 RFC 7807 风格错误信息,即使用标准化字段描述错误,而非完全自定义错误对象。是否采用它取决于既有 API 契约;迁移时应同时考虑客户端兼容、字段稳定性和敏感信息控制,不能仅因框架提供类型就改变线上响应格式。
5. 不要所有错误都返回 HTTP 200
反例:HTTP 状态为 200,响应体却表示资源不存在:
json
{"success": false, "code": "NOT_FOUND"}只看 HTTP 状态的网关、监控和客户端会把这次请求视为成功,无法按错误类型统计或处理;缓存和重试策略也可能因此作出不合适的决定。业务错误码可以保留,但应与合理的 HTTP 语义配合,例如资源不存在使用 404,而不是让所有错误都返回 200。
6. 响应可能已经提交
响应已提交(committed)指状态码和响应头已经发送,不能再可靠地修改。写入 Servlet 响应缓冲区不一定立即提交,但缓冲区写满或执行刷新(flush)等操作可能使响应提交。这里的“提交”是 HTTP 响应的状态,与数据库事务提交不同。
流式下载、SSE(Server-Sent Events,服务端持续向客户端推送事件)和大响应尤其需要关注这个边界:如果异常发生时响应已提交,就不能再可靠地把它改成带有新状态码的标准 JSON 错误响应。
此时服务端可能关闭连接或结束流,客户端应把“收到部分数据后连接中断”视为一种独立故障。若请求可能已经产生业务副作用,重试需要幂等保护:同一个业务请求重复提交时,不应重复产生订单、扣款等结果。幂等键是用于识别同一业务请求的稳定标识,客户端应在重试时复用它,而不是根据是否收到完整响应猜测服务端是否执行成功。
7. 事务提交与响应失败不是一个边界
在 Controller 调用通过 Spring 事务代理管理的 Service、且该 Service 调用结束时完成事务的常见同步场景中,顺序是:业务方法正常返回,事务代理完成提交,然后 Controller 返回对象,MVC 再序列化响应。事务代理是围绕业务方法执行事务开启、提交或回滚逻辑的组件;若 Service 加入了更外层事务,实际提交点还要由外层边界决定。
当提交发生在序列化之前,可能出现:
text
数据库 COMMIT 成功
→ JSON 序列化失败
→ 客户端收到 500
→ 客户端重试
→ 业务操作重复这不是“事务失效”,而是事务边界早于 HTTP 响应完成。创建订单、扣款等接口应通过业务请求号、唯一约束或状态机保证幂等,相关原则见分布式 13 - 幂等性与重复请求。
反过来,把数据库事务一直保持到响应完全写出通常也不是通用解法:慢客户端和大响应会延长连接及锁占用,并且连接断开仍不能撤销客户端已经收到的部分数据。
8. 最小故障验证
下面是用于构造序列化故障的响应类型片段。Getter 是用于读取对象属性的方法;在 Jackson 将 getBrokenField() 识别为可序列化属性并调用它的条件下,该方法会主动抛出异常。项目需要使用支持 record 的 Java 环境和 Jackson 配置,并让已匹配的 JSON 接口返回这个对象。
java
record OrderResponse(long id) {
public String getBrokenField() {
throw new IllegalStateException("serialization failed");
}
}预期现象:Controller 已返回 OrderResponse,但 Jackson 在读取 brokenField 属性时失败。能否得到完整的 500 或统一错误响应,还取决于异常解析器和响应是否已提交;如果该 Getter 被忽略,就不会触发这个故障。
测试应同时断言:
- Controller 和业务方法已经执行;
- 数据库事务最终是提交还是回滚;
- 实际异常由哪个 Converter/Resolver 处理;
- 响应是否已经 committed;
- 使用同一幂等键重试是否产生重复业务记录。
真实行为受 Jackson 属性发现规则、Controller 返回类型和事务边界影响,应在项目实际配置中验证。
9. 容易踩的坑
- 全局异常处理器捕获
Exception后吞掉关键信息。 - 把堆栈、SQL、路径或敏感参数返回给客户端。
- JSON 序列化触发 ORM(对象关系映射)框架的懒加载,产生额外查询或异常。
- 循环对象图导致序列化递归。
- 响应已提交后再次写错误体。
- 全局 Advice 抢先处理框架异常,导致 HTTP 状态语义退化。
- 把序列化失败误判成业务事务回滚。
- 客户端因响应中断重试,而服务端接口没有幂等保护。
10. 排障清单
- Controller 是否已经正常返回?
- 哪个 ReturnValueHandler 接管返回值?
- 最终媒体类型和 Converter 是什么?
- 序列化异常涉及哪个字段或 Getter?
- 哪个 ExceptionResolver 或 Advice 处理了异常?
- 响应是否已经 committed?
- 业务事务是在序列化前还是序列化后完成?
- Filter(过滤器)、ResponseBodyAdvice(响应体写出前的增强组件)或网关是否改写了响应?
- 客户端重试是否携带稳定幂等键?
11. 总结
Controller 返回只是业务方法结束,真正的 HTTP 响应还要经过返回值处理、内容协商和序列化。
- ReturnValueHandler 决定如何解释返回值,Converter 决定如何写出内容。
- 统一异常处理应同时维护 HTTP 语义、业务错误码和信息安全。
- 响应阶段失败可能发生在事务提交之后,需要单独保证接口幂等。
阅读导航
- 请求如何匹配 Handler:14 - DispatcherServlet 调度全流程
- Controller 参数如何生成:15 - Controller 参数解析与数据绑定
- 事务何时提交:11 - Spring 声明式事务执行链
- 响应失败后的重复请求:分布式 13 - 幂等性与重复请求
- 网关可能如何改写错误:网络 15 - 反向代理与网关错误
- 异步结果、SSE 与流式响应:25 - Spring MVC 异步请求与流式响应
- 跨层故障分诊:20 - Spring 线上问题排查手册