同一个接口,命令行能拿到 JSON,换到 SDK 或经过网关就返回 406 Not Acceptable。先把两次请求的 Accept 抓出来对照。有时 SDK 默认只收 XML,接口却只提供 JSON,路径、参数和业务代码都没变。
下面按 Spring Boot 3.5.x、Spring MVC、JDK 17 及以上说明。示例使用默认 JSON 消息转换器,走本地应用直连,不带网关或自定义异常处理。
只改 Accept,把两次请求放在一起看
Accept 写的是调用方愿意收到的响应格式。请求的 Content-Type 描述这次请求体的格式,响应的 Content-Type 描述服务端实际发回的格式。在 Spring MVC 默认配置里,响应媒体类型协商只检查 Accept。若项目开启了查询参数协商或自定义了策略,要同时看实际策略。HTTP Accept · HTTP 406 · Spring MVC 内容协商配置
在本地测试项目里,把下面的控制器放到启动类的扫描范围内。它用 produces 声明此方法只提供 JSON。
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class FormatExampleController {
@GetMapping(path = "/demo/order-summary", produces = MediaType.APPLICATION_JSON_VALUE)
public OrderSummary summary() {
return new OrderSummary(123L, "PAID");
}
public record OrderSummary(long orderId, String status) {}
}
启动测试应用后,在同一个地址发三次 GET。端口按实际值替换。下面使用 POSIX Shell,Windows PowerShell 可用 curl.exe。
curl -sS -i -H 'Accept: application/json' http://127.0.0.1:8080/demo/order-summary
curl -sS -i -H 'Accept: application/xml' http://127.0.0.1:8080/demo/order-summary
curl -sS -i -H 'Accept: */*' http://127.0.0.1:8080/demo/order-summary
默认配置下,第一条和第三条预期返回 200 与 JSON,第二条预期返回 406。三条请求都没有请求体,改请求 Content-Type 对这个例子没有帮助。如果带请求体的接口返回 415,可沿着 consumes 和请求体读取方式查。curl 请求头选项 · Spring Boot 415 排查
看控制器有没有执行
给方法的第一行打断点,或者在测试环境记录一次方法入口,对照发生 406 的那条请求。这个信号能缩小范围。
方法没有执行。 先确认请求确实到了应用。路径和 HTTP 方法都正确时,看方法和类上的 produces。例子里 Accept: application/xml 和 produces = "application/json" 不匹配,Spring MVC 在选择处理方法时就会抛出 HttpMediaTypeNotAcceptableException。方法上的 produces 会覆盖类级别的声明。Spring MVC 的 produces 规则 · 请求映射源码
方法已经执行。 看真实返回值的 Java 类型,再核对注册的 HttpMessageConverter 实际能写哪些媒体类型。例如去掉上面例子的 produces,只保留 JSON 转换器且没有适用的 XML 转换器时,XML 请求可能在方法返回后才因响应类型不兼容而收到 406。如果日志出现 HttpMessageNotWritableException,则沿转换器和序列化异常查。预设了响应 Content-Type 却找不到可写转换器时,Spring MVC 默认通常会按 500 处理,具体还要看应用的异常处理链。响应写入源码 · 默认异常状态码
如果只在经网关时出现 406,用同一份 Accept 对比分别走网关和直连的结果。核对应用实际收到的头、访问日志状态和网关请求 ID。应用压根没有收到请求时,先查网关自身返回的响应与规则。如果入口日志显示成功,但客户端拿到的是 406,也要核对网关有没有生成或改写响应。
按接口约定修,再复测原调用方
接口本来只提供 JSON,就把客户端实际发出的 Accept 改成 application/json,并确认 SDK 没在拦截器里覆盖请求头。上面的 */* 适合定位问题,保留具体类型能清楚表达客户端确实会解析哪种响应。
接口确实要同时支持 JSON 和 XML,则检查两种响应格式都有对应的转换器、返回对象也能被它们写出,再按约定声明支持范围。只在注解里补一个媒体类型不会让转换器凭空支持它。已有自定义 MVC 配置时,检查 configureMessageConverters 有没有替换默认列表,以及是否可以用 extendMessageConverters 在现有列表上调整。Spring MVC 消息转换器配置
最后用最初报错的客户端、同一条网关路由复测。检查实际状态码、响应 Content-Type 和客户端能否解析响应体。再保留一条只请求不受支持格式的测试,预期按接口约定拒绝。原来的调用恢复了,同时不兼容类型也没有被误当成 JSON 返回,才算对上了问题。
Spring Boot 接口返回 406,先看 Accept
https://java.li/archives/spring-boot-http-406
评论