1. 状态码406一个常被误解的“拦路虎”在Web开发和API对接的日常工作中我们和HTTP状态码打交道是家常便饭。200 OK是朋友404 Not Found是老熟人500 Internal Server Error是令人头疼的“坏家伙”。但有一个状态码它出现的频率或许没那么高可一旦出现却常常让开发者尤其是刚入行的朋友感到困惑——它就是406 Not Acceptable。乍一看“Not Acceptable”不可接受很容易让人联想到权限不足或者请求内容有问题。很多新手的第一反应是去检查请求参数格式、用户认证状态甚至怀疑服务器配置折腾一圈下来可能还是不得要领。实际上406错误的根源绝大多数时候并不在请求的“身体”Body是否健康而在于请求的“头部”Headers是否与服务器“情投意合”。它本质上是客户端和服务器在“用什么语言沟通”这个问题上没有达成一致属于HTTP内容协商Content Negotiation失败引发的“外交事故”。简单来说当客户端比如浏览器、手机App、或者你写的爬虫脚本向服务器说“嗨请给我一份数据但我只接受JSON格式的回复哦”而服务器看了看自己手头只有XML格式的数据或者它压根就不支持生成JSON这时它就会礼貌地回复一个406状态码意思是“抱歉你要的格式我这儿没有咱们谈不拢。”这篇文章我就结合自己这些年踩过的坑和解决过的案例带你彻底搞懂406错误的来龙去脉。我会从HTTP协议的原理层面对它进行拆解然后给出从客户端到服务器端、从代码到配置的一整套排查和解决方法。无论你是前端、后端还是运维下次再遇到这个“不可接受”的错误都能心中有数快速定位。2. HTTP内容协商机制深度解析要解决406问题我们必须先理解它背后的机制——HTTP内容协商。这不是一个可选功能而是HTTP/1.1协议定义的核心特性之一。它的设计初衷非常优雅让同一个URI资源地址能够根据客户端的请求返回不同表现形式Representation的同一资源。这些表现形式主要体现在媒体类型MIME Type、字符编码、语言和压缩方式上。2.1 核心协商头字段客户端通过一系列以Accept-*开头的请求头向服务器表达自己的偏好。服务器则根据这些头信息和自身能力选择最合适的资源版本返回。以下是几个最关键的头字段Accept这是导致406错误最常见的“元凶”。它指明了客户端能够处理的媒体类型MIME Type。例如Accept: application/json我只接受JSONAccept: text/html, application/xhtmlxml, application/xml;q0.9, */*;q0.8我优先要HTML其次XHTML再次XML实在不行别的也行 注意里面的q值质量因子范围0-1默认1值越高优先级越高。*/*表示接受任何类型。Accept-Language指定客户端偏好的自然语言。例如Accept-Language: zh-CN, zh;q0.9, en;q0.8。Accept-Encoding指定客户端支持的内容编码通常是压缩方式。例如Accept-Encoding: gzip, deflate, br。Accept-Charset指定客户端支持的字符集。例如Accept-Charset: utf-8, iso-8859-1;q0.5。注意现代实践中这个头字段已很少使用通常默认UTF-8。2.2 服务器端的处理逻辑服务器收到请求后会检查Accept头。它的处理流程逻辑上遵循以下步骤解析与匹配服务器解析Accept头获取客户端支持的媒体类型列表及其优先级q值。检查自身能力服务器查看对于被请求的URI自己能够生成哪些媒体类型的响应例如一个用户信息接口可能支持application/json和application/xml。寻找交集服务器将客户端支持的列表与自己能生成的列表进行匹配寻找交集。决策与响应如果找到交集服务器选择优先级最高q值最大且自己能生成的媒体类型以此格式返回资源并设置Content-Type响应头。状态码为200。如果找不到交集即客户端“想要的”和服务器“能给的”没有共同项服务器应该返回406 Not Acceptable。同时它可以在响应头Accept或Content-Type中附带自己实际支持的媒体类型列表告诉客户端“我能提供这些你看着办”。但这不是强制要求很多服务器实现会直接返回406而不给额外信息。关键理解406错误发生在服务器端已经成功找到了请求的资源URL路由正确权限可能也通过但在决定“以何种格式打包这个资源返回”时发现没有符合客户端要求的格式。所以它和“找不到资源”(404)或“没权限”(403)有本质区别。2.3 一个典型的误判场景假设你正在开发一个RESTful API后端用Spring Boot写了个控制器RestController RequestMapping(/api/user) public class UserController { GetMapping(value /{id}, produces application/json) public User getUser(PathVariable Long id) { // ... 返回User对象 } }注意GetMapping注解里的produces application/json。这明确告知Spring框架我这个接口只生产JSON格式的响应。此时一个客户端比如用Pythonrequests库发来请求import requests headers {Accept: application/xml} # 客户端声明只接受XML response requests.get(http://your-api/api/user/123, headersheaders)服务器Spring一看客户端要XML (Accept: application/xml)但我这个方法只会生产JSON (producesapplication/json)。交集为空。于是Spring框架就会返回一个406 Not Acceptable错误。很多开发者看到这里会疑惑“我的接口明明能正常工作啊用Postman不设Accept头就能拿到JSON为什么代码调用就406了” 问题就出在这个不起眼的Accept头上。3. 客户端视角如何发起一个“可接受”的请求大部分406问题通过调整客户端请求就能解决。我们的目标是让Accept头与服务器能力匹配。3.1 检查与设置请求头第一步永远是检查你发出的请求头。使用浏览器开发者工具的“网络”(Network)标签或者像Postman、curl这样的工具查看请求的原始头信息。浏览器行为现代浏览器发出的Accept头通常非常“贪婪”例如text/html,application/xhtmlxml,application/xml;q0.9,*/*;q0.8包含了*/*这意味着它几乎接受任何格式所以很少因Accept头触发406。如果你的前端应用通过fetch或XMLHttpRequest调用API并且没有显式设置Accept头浏览器可能会使用一个默认值这个默认值不一定包含*/*从而可能引发问题。编程语言HTTP库Python requests: 默认Accept: */*。但如果你手动设置了headers{Accept: application/xml}就可能引发406。JavaScript fetch: 默认不设置Accept头。根据规范此时Accept头应被视为*/*但更安全的做法是显式设置。Java HttpClient/OkHttp通常有默认值但也需要检查。解决方案显式设置一个兼容的Accept头。最兼容的设置Accept: */*。这表示客户端接受任何媒体类型。服务器通常会选择它默认或最合适的格式比如JSON返回。这是最快速、最粗暴的解决方法但失去了内容协商的意义。精确匹配查阅API文档明确知道服务器支持哪些格式如application/json然后将Accept头设置为其中之一或列表。// 前端 fetch 示例 fetch(/api/user/123, { headers: { Accept: application/json, text/plain, */* // 优先JSON其次纯文本最后任何类型 } });# Python requests 示例 import requests url http://api.example.com/resource headers {Accept: application/json} # 或 application/json, application/xml;q0.9 response requests.get(url, headersheaders)3.2 处理服务器返回的406响应一个设计良好的API在返回406时应该在响应体中给出更详细的错误信息甚至是在Accept响应头中列出自己支持的格式。作为客户端开发者你需要处理这种错误状态async function fetchData() { try { const response await fetch(/api/some-endpoint, { headers: { Accept: application/xml } }); if (!response.ok) { if (response.status 406) { const supportedTypes response.headers.get(Accept); // 可能包含服务器支持的格式 console.error(406错误服务器不支持 application/xml。它可能支持${supportedTypes}); // 可以在这里重试请求使用从响应头中解析出的格式 // 例如如果supportedTypes包含application/json则用新的Accept头重新fetch } throw new Error(HTTP error! status: ${response.status}); } const data await response.json(); // ... 处理数据 } catch (error) { console.error(Fetch failed:, error); } }实操心得在团队内部可以约定在406响应体中返回一个标准错误对象如{error: NotAcceptable, supported_types: [application/json, application/xml]}这样客户端能更友好地引导用户或自动切换格式。4. 服务器端视角如何构建一个“友好”的服务作为API的提供方我们有责任让服务更健壮对客户端更友好减少406错误的发生或者在发生时提供清晰的指引。4.1 框架层面的配置与处理以常见的Spring Boot和Express.js为例Spring Boot (Java)Spring MVC对内容协商有非常完善的支持。默认行为如果一个控制器方法通过RequestMapping或其变体如GetMapping的produces属性限定了输出格式当请求的Accept头不匹配时Spring会抛出HttpMediaTypeNotAcceptableException最终转化为406响应。全局配置你可以在WebMvcConfigurer中配置内容协商策略。Configuration public class WebConfig implements WebMvcConfigurer { Override public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { configurer .favorParameter(false) // 不启用URL参数协商如 ?formatjson .ignoreAcceptHeader(false) // 不忽略Accept头默认就是false .defaultContentType(MediaType.APPLICATION_JSON) // 设置默认响应类型 .mediaType(json, MediaType.APPLICATION_JSON) .mediaType(xml, MediaType.APPLICATION_XML); } }通过defaultContentType当请求的Accept头为*/*或服务器无法做出最佳选择时会使用JSON作为默认格式这能避免很多406。控制器方法更推荐在控制器方法上使用produces来明确声明。GetMapping(value /{id}, produces {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE}) public User getUser(PathVariable Long id) { // 根据Accept头Spring会自动选择JSON或XML视图/消息转换器来序列化User对象 }这样只要客户端Accept头包含application/json或application/xml就能成功响应。Express.js (Node.js)在Express中你需要手动处理或借助中间件。手动检查不推荐用于复杂场景app.get(/api/user/:id, (req, res) { const accept req.header(Accept); if (!accept || accept.includes(*/*) || accept.includes(application/json)) { res.json({ id: req.params.id, name: John Doe }); } else if (accept.includes(application/xml)) { res.set(Content-Type, application/xml); res.send(userid${req.params.id}/idnameJohn Doe/name/user); } else { // 返回406并告知支持的格式 res.status(406); res.set(Accept, application/json, application/xml); res.json({ error: Not Acceptable, supported: [application/json, application/xml] }); } });使用中间件例如accepts库可以简化协商过程。const accepts require(accepts); app.get(/api/user/:id, (req, res) { const accept accepts(req); const type accept.type([json, xml]); if (!type) { // 没有匹配的类型 res.status(406).json({ error: Not Acceptable }); return; } if (type json) { res.json({ id: req.params.id, name: John Doe }); } else if (type xml) { // ... 返回XML } });4.2 设计容错性更强的API提供默认格式当Accept头缺失或为*/*时始终返回一种默认的、最通用的格式如JSON。这是行业最佳实践。支持多种格式为重要资源端点支持至少两种主流格式如JSON和XML。JSON用于现代Web和移动应用XML可能用于一些遗留系统或特定的企业集成。清晰的错误反馈在返回406状态码时务必在响应体中提供机器可读和人工可读的错误信息明确列出supported_media_types。这能极大降低调试成本。考虑URL参数覆盖一些API设计允许通过查询参数来覆盖Accept头例如/api/user/123?formatjson。这可以作为内容协商的补充方便调试和某些特殊场景。但要注意这不符合REST的纯粹性需权衡使用。5. 实战排查清单与进阶场景当406错误出现时不要慌张按照以下清单系统性排查能帮你节省大量时间。5.1 逐步排查清单第一步捕获并检查原始请求工具使用浏览器开发者工具 (Network标签)、Postman、curl -v或Wireshark/Fiddler等抓包工具。目标确认客户端发出的HTTP请求头特别是Accept头的值。这是所有诊断的起点。常见陷阱某些HTTP客户端库或框架可能会在你不经意间添加或修改Accept头。第二步确认服务器端能力方法查阅API文档。如果没有文档尝试用Accept: */*或Accept: application/json等常见头去请求看是否能成功。用Postman等工具测试不同Accept值。目标明确服务器对于该特定端点URL支持哪些响应媒体类型MIME Type。第三步比对与匹配操作将第一步得到的Accept头值与第二步得到的服务器支持列表进行比对。关键注意Accept头中的q值优先级和通配符*/*。服务器是否支持*/*作为一种匹配很多框架的默认配置是支持的。第四步检查服务器配置与代码位置查看服务器端路由处理代码如Spring的RequestMapping(produces...) Express的路由处理函数。框架配置检查Web框架关于内容协商的全局配置如Spring的ContentNegotiationConfigurer。中间件/过滤器是否有全局的过滤器或中间件修改了请求头或响应头第五步模拟与验证使用curl命令精确复现问题并尝试修改Accept头来验证解决方案。# 复现错误的请求 curl -v -H Accept: application/xml http://your-api.com/resource # 测试解决方案使用通配符或正确的类型 curl -v -H Accept: */* http://your-api.com/resource curl -v -H Accept: application/json http://your-api.com/resource5.2 进阶场景与疑难杂症代理服务器或网关修改了请求头如果你的请求经过Nginx、API Gateway、CDN等代理它们有可能在转发时添加、删除或修改Accept头。务必在代理前后分别抓包对比。框架的默认行为差异不同Web框架甚至同一框架的不同版本对缺失Accept头或Accept: */*的处理可能不同。例如早期某些版本的框架可能对*/*处理不够友好。始终以官方文档和实测为准。自定义消息转换器Message Converter问题以Spring为例Spring MVC通过HttpMessageConverter来处理不同格式的序列化/反序列化。如果你自定义了转换器或调整了它们的顺序可能会影响内容协商的结果。确保你的自定义转换器支持正确的媒体类型并且顺序合理。与ResponseBody/RestController的交互在Spring中使用这些注解意味着返回值将由配置的HttpMessageConverter处理。最终选择的转换器必须与Accept头及控制器声明的produces属性兼容。“406”伪装成其他问题极少数情况下服务器内部错误如序列化失败也可能被框架包装成406返回。此时需要查看服务器日志寻找更根本的异常堆栈信息。6. 总结与最佳实践建议解决406错误的过程本质上是一次对HTTP协议细节和客户端-服务器契约的审视。它提醒我们网络通信不仅仅是“发出请求-得到数据”这么简单头部信息的协商是构建健壮、互操作性强API的重要一环。给客户端开发者的建议始终显式设置Accept头不要依赖库或浏览器的默认值。根据API文档设置明确且合理的值例如Accept: application/json。做好错误处理在你的HTTP客户端代码中专门处理406状态码并尝试从响应中获取服务器支持的格式信息以便进行友好提示或自动重试。调试时善用工具首先用Postman或curl模拟请求隔离前端代码或网络环境的影响。给服务器端开发者的建议明确声明API能力在代码和文档中清晰定义每个端点支持的响应格式。设置合理的默认格式通过框架配置为Accept: */*或缺失Accept头的请求提供一个默认的、最常用的响应格式通常是JSON。提供友好的406响应当协商失败时返回的406响应应包含清晰的错误信息和supported_types列表这是API设计友好性的体现。考虑内容协商策略根据业务需求评估是否支持URL参数覆盖如?formatjson但这不应是主要手段。我个人在实际项目中曾因为一个第三方库自动添加了Accept: application/xml头而我们的后端API当时只明确配置了生产JSON导致线上监控突然出现大量406错误报警。排查过程就是严格按照上述清单从客户端请求抓包开始最终定位到是库的某个次要版本更新改变了默认行为。这个经历让我深刻体会到对于HTTP这种看似简单的协议其头字段的每一个细节都值得敬畏。养成良好的习惯——明确声明、主动设置、完善处理——能让你的应用在复杂的网络环境中更加稳定可靠。 HTTP 406状态码解析：内容协商失败的原因与解决方案
1. 状态码406一个常被误解的“拦路虎”在Web开发和API对接的日常工作中我们和HTTP状态码打交道是家常便饭。200 OK是朋友404 Not Found是老熟人500 Internal Server Error是令人头疼的“坏家伙”。但有一个状态码它出现的频率或许没那么高可一旦出现却常常让开发者尤其是刚入行的朋友感到困惑——它就是406 Not Acceptable。乍一看“Not Acceptable”不可接受很容易让人联想到权限不足或者请求内容有问题。很多新手的第一反应是去检查请求参数格式、用户认证状态甚至怀疑服务器配置折腾一圈下来可能还是不得要领。实际上406错误的根源绝大多数时候并不在请求的“身体”Body是否健康而在于请求的“头部”Headers是否与服务器“情投意合”。它本质上是客户端和服务器在“用什么语言沟通”这个问题上没有达成一致属于HTTP内容协商Content Negotiation失败引发的“外交事故”。简单来说当客户端比如浏览器、手机App、或者你写的爬虫脚本向服务器说“嗨请给我一份数据但我只接受JSON格式的回复哦”而服务器看了看自己手头只有XML格式的数据或者它压根就不支持生成JSON这时它就会礼貌地回复一个406状态码意思是“抱歉你要的格式我这儿没有咱们谈不拢。”这篇文章我就结合自己这些年踩过的坑和解决过的案例带你彻底搞懂406错误的来龙去脉。我会从HTTP协议的原理层面对它进行拆解然后给出从客户端到服务器端、从代码到配置的一整套排查和解决方法。无论你是前端、后端还是运维下次再遇到这个“不可接受”的错误都能心中有数快速定位。2. HTTP内容协商机制深度解析要解决406问题我们必须先理解它背后的机制——HTTP内容协商。这不是一个可选功能而是HTTP/1.1协议定义的核心特性之一。它的设计初衷非常优雅让同一个URI资源地址能够根据客户端的请求返回不同表现形式Representation的同一资源。这些表现形式主要体现在媒体类型MIME Type、字符编码、语言和压缩方式上。2.1 核心协商头字段客户端通过一系列以Accept-*开头的请求头向服务器表达自己的偏好。服务器则根据这些头信息和自身能力选择最合适的资源版本返回。以下是几个最关键的头字段Accept这是导致406错误最常见的“元凶”。它指明了客户端能够处理的媒体类型MIME Type。例如Accept: application/json我只接受JSONAccept: text/html, application/xhtmlxml, application/xml;q0.9, */*;q0.8我优先要HTML其次XHTML再次XML实在不行别的也行 注意里面的q值质量因子范围0-1默认1值越高优先级越高。*/*表示接受任何类型。Accept-Language指定客户端偏好的自然语言。例如Accept-Language: zh-CN, zh;q0.9, en;q0.8。Accept-Encoding指定客户端支持的内容编码通常是压缩方式。例如Accept-Encoding: gzip, deflate, br。Accept-Charset指定客户端支持的字符集。例如Accept-Charset: utf-8, iso-8859-1;q0.5。注意现代实践中这个头字段已很少使用通常默认UTF-8。2.2 服务器端的处理逻辑服务器收到请求后会检查Accept头。它的处理流程逻辑上遵循以下步骤解析与匹配服务器解析Accept头获取客户端支持的媒体类型列表及其优先级q值。检查自身能力服务器查看对于被请求的URI自己能够生成哪些媒体类型的响应例如一个用户信息接口可能支持application/json和application/xml。寻找交集服务器将客户端支持的列表与自己能生成的列表进行匹配寻找交集。决策与响应如果找到交集服务器选择优先级最高q值最大且自己能生成的媒体类型以此格式返回资源并设置Content-Type响应头。状态码为200。如果找不到交集即客户端“想要的”和服务器“能给的”没有共同项服务器应该返回406 Not Acceptable。同时它可以在响应头Accept或Content-Type中附带自己实际支持的媒体类型列表告诉客户端“我能提供这些你看着办”。但这不是强制要求很多服务器实现会直接返回406而不给额外信息。关键理解406错误发生在服务器端已经成功找到了请求的资源URL路由正确权限可能也通过但在决定“以何种格式打包这个资源返回”时发现没有符合客户端要求的格式。所以它和“找不到资源”(404)或“没权限”(403)有本质区别。2.3 一个典型的误判场景假设你正在开发一个RESTful API后端用Spring Boot写了个控制器RestController RequestMapping(/api/user) public class UserController { GetMapping(value /{id}, produces application/json) public User getUser(PathVariable Long id) { // ... 返回User对象 } }注意GetMapping注解里的produces application/json。这明确告知Spring框架我这个接口只生产JSON格式的响应。此时一个客户端比如用Pythonrequests库发来请求import requests headers {Accept: application/xml} # 客户端声明只接受XML response requests.get(http://your-api/api/user/123, headersheaders)服务器Spring一看客户端要XML (Accept: application/xml)但我这个方法只会生产JSON (producesapplication/json)。交集为空。于是Spring框架就会返回一个406 Not Acceptable错误。很多开发者看到这里会疑惑“我的接口明明能正常工作啊用Postman不设Accept头就能拿到JSON为什么代码调用就406了” 问题就出在这个不起眼的Accept头上。3. 客户端视角如何发起一个“可接受”的请求大部分406问题通过调整客户端请求就能解决。我们的目标是让Accept头与服务器能力匹配。3.1 检查与设置请求头第一步永远是检查你发出的请求头。使用浏览器开发者工具的“网络”(Network)标签或者像Postman、curl这样的工具查看请求的原始头信息。浏览器行为现代浏览器发出的Accept头通常非常“贪婪”例如text/html,application/xhtmlxml,application/xml;q0.9,*/*;q0.8包含了*/*这意味着它几乎接受任何格式所以很少因Accept头触发406。如果你的前端应用通过fetch或XMLHttpRequest调用API并且没有显式设置Accept头浏览器可能会使用一个默认值这个默认值不一定包含*/*从而可能引发问题。编程语言HTTP库Python requests: 默认Accept: */*。但如果你手动设置了headers{Accept: application/xml}就可能引发406。JavaScript fetch: 默认不设置Accept头。根据规范此时Accept头应被视为*/*但更安全的做法是显式设置。Java HttpClient/OkHttp通常有默认值但也需要检查。解决方案显式设置一个兼容的Accept头。最兼容的设置Accept: */*。这表示客户端接受任何媒体类型。服务器通常会选择它默认或最合适的格式比如JSON返回。这是最快速、最粗暴的解决方法但失去了内容协商的意义。精确匹配查阅API文档明确知道服务器支持哪些格式如application/json然后将Accept头设置为其中之一或列表。// 前端 fetch 示例 fetch(/api/user/123, { headers: { Accept: application/json, text/plain, */* // 优先JSON其次纯文本最后任何类型 } });# Python requests 示例 import requests url http://api.example.com/resource headers {Accept: application/json} # 或 application/json, application/xml;q0.9 response requests.get(url, headersheaders)3.2 处理服务器返回的406响应一个设计良好的API在返回406时应该在响应体中给出更详细的错误信息甚至是在Accept响应头中列出自己支持的格式。作为客户端开发者你需要处理这种错误状态async function fetchData() { try { const response await fetch(/api/some-endpoint, { headers: { Accept: application/xml } }); if (!response.ok) { if (response.status 406) { const supportedTypes response.headers.get(Accept); // 可能包含服务器支持的格式 console.error(406错误服务器不支持 application/xml。它可能支持${supportedTypes}); // 可以在这里重试请求使用从响应头中解析出的格式 // 例如如果supportedTypes包含application/json则用新的Accept头重新fetch } throw new Error(HTTP error! status: ${response.status}); } const data await response.json(); // ... 处理数据 } catch (error) { console.error(Fetch failed:, error); } }实操心得在团队内部可以约定在406响应体中返回一个标准错误对象如{error: NotAcceptable, supported_types: [application/json, application/xml]}这样客户端能更友好地引导用户或自动切换格式。4. 服务器端视角如何构建一个“友好”的服务作为API的提供方我们有责任让服务更健壮对客户端更友好减少406错误的发生或者在发生时提供清晰的指引。4.1 框架层面的配置与处理以常见的Spring Boot和Express.js为例Spring Boot (Java)Spring MVC对内容协商有非常完善的支持。默认行为如果一个控制器方法通过RequestMapping或其变体如GetMapping的produces属性限定了输出格式当请求的Accept头不匹配时Spring会抛出HttpMediaTypeNotAcceptableException最终转化为406响应。全局配置你可以在WebMvcConfigurer中配置内容协商策略。Configuration public class WebConfig implements WebMvcConfigurer { Override public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { configurer .favorParameter(false) // 不启用URL参数协商如 ?formatjson .ignoreAcceptHeader(false) // 不忽略Accept头默认就是false .defaultContentType(MediaType.APPLICATION_JSON) // 设置默认响应类型 .mediaType(json, MediaType.APPLICATION_JSON) .mediaType(xml, MediaType.APPLICATION_XML); } }通过defaultContentType当请求的Accept头为*/*或服务器无法做出最佳选择时会使用JSON作为默认格式这能避免很多406。控制器方法更推荐在控制器方法上使用produces来明确声明。GetMapping(value /{id}, produces {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE}) public User getUser(PathVariable Long id) { // 根据Accept头Spring会自动选择JSON或XML视图/消息转换器来序列化User对象 }这样只要客户端Accept头包含application/json或application/xml就能成功响应。Express.js (Node.js)在Express中你需要手动处理或借助中间件。手动检查不推荐用于复杂场景app.get(/api/user/:id, (req, res) { const accept req.header(Accept); if (!accept || accept.includes(*/*) || accept.includes(application/json)) { res.json({ id: req.params.id, name: John Doe }); } else if (accept.includes(application/xml)) { res.set(Content-Type, application/xml); res.send(userid${req.params.id}/idnameJohn Doe/name/user); } else { // 返回406并告知支持的格式 res.status(406); res.set(Accept, application/json, application/xml); res.json({ error: Not Acceptable, supported: [application/json, application/xml] }); } });使用中间件例如accepts库可以简化协商过程。const accepts require(accepts); app.get(/api/user/:id, (req, res) { const accept accepts(req); const type accept.type([json, xml]); if (!type) { // 没有匹配的类型 res.status(406).json({ error: Not Acceptable }); return; } if (type json) { res.json({ id: req.params.id, name: John Doe }); } else if (type xml) { // ... 返回XML } });4.2 设计容错性更强的API提供默认格式当Accept头缺失或为*/*时始终返回一种默认的、最通用的格式如JSON。这是行业最佳实践。支持多种格式为重要资源端点支持至少两种主流格式如JSON和XML。JSON用于现代Web和移动应用XML可能用于一些遗留系统或特定的企业集成。清晰的错误反馈在返回406状态码时务必在响应体中提供机器可读和人工可读的错误信息明确列出supported_media_types。这能极大降低调试成本。考虑URL参数覆盖一些API设计允许通过查询参数来覆盖Accept头例如/api/user/123?formatjson。这可以作为内容协商的补充方便调试和某些特殊场景。但要注意这不符合REST的纯粹性需权衡使用。5. 实战排查清单与进阶场景当406错误出现时不要慌张按照以下清单系统性排查能帮你节省大量时间。5.1 逐步排查清单第一步捕获并检查原始请求工具使用浏览器开发者工具 (Network标签)、Postman、curl -v或Wireshark/Fiddler等抓包工具。目标确认客户端发出的HTTP请求头特别是Accept头的值。这是所有诊断的起点。常见陷阱某些HTTP客户端库或框架可能会在你不经意间添加或修改Accept头。第二步确认服务器端能力方法查阅API文档。如果没有文档尝试用Accept: */*或Accept: application/json等常见头去请求看是否能成功。用Postman等工具测试不同Accept值。目标明确服务器对于该特定端点URL支持哪些响应媒体类型MIME Type。第三步比对与匹配操作将第一步得到的Accept头值与第二步得到的服务器支持列表进行比对。关键注意Accept头中的q值优先级和通配符*/*。服务器是否支持*/*作为一种匹配很多框架的默认配置是支持的。第四步检查服务器配置与代码位置查看服务器端路由处理代码如Spring的RequestMapping(produces...) Express的路由处理函数。框架配置检查Web框架关于内容协商的全局配置如Spring的ContentNegotiationConfigurer。中间件/过滤器是否有全局的过滤器或中间件修改了请求头或响应头第五步模拟与验证使用curl命令精确复现问题并尝试修改Accept头来验证解决方案。# 复现错误的请求 curl -v -H Accept: application/xml http://your-api.com/resource # 测试解决方案使用通配符或正确的类型 curl -v -H Accept: */* http://your-api.com/resource curl -v -H Accept: application/json http://your-api.com/resource5.2 进阶场景与疑难杂症代理服务器或网关修改了请求头如果你的请求经过Nginx、API Gateway、CDN等代理它们有可能在转发时添加、删除或修改Accept头。务必在代理前后分别抓包对比。框架的默认行为差异不同Web框架甚至同一框架的不同版本对缺失Accept头或Accept: */*的处理可能不同。例如早期某些版本的框架可能对*/*处理不够友好。始终以官方文档和实测为准。自定义消息转换器Message Converter问题以Spring为例Spring MVC通过HttpMessageConverter来处理不同格式的序列化/反序列化。如果你自定义了转换器或调整了它们的顺序可能会影响内容协商的结果。确保你的自定义转换器支持正确的媒体类型并且顺序合理。与ResponseBody/RestController的交互在Spring中使用这些注解意味着返回值将由配置的HttpMessageConverter处理。最终选择的转换器必须与Accept头及控制器声明的produces属性兼容。“406”伪装成其他问题极少数情况下服务器内部错误如序列化失败也可能被框架包装成406返回。此时需要查看服务器日志寻找更根本的异常堆栈信息。6. 总结与最佳实践建议解决406错误的过程本质上是一次对HTTP协议细节和客户端-服务器契约的审视。它提醒我们网络通信不仅仅是“发出请求-得到数据”这么简单头部信息的协商是构建健壮、互操作性强API的重要一环。给客户端开发者的建议始终显式设置Accept头不要依赖库或浏览器的默认值。根据API文档设置明确且合理的值例如Accept: application/json。做好错误处理在你的HTTP客户端代码中专门处理406状态码并尝试从响应中获取服务器支持的格式信息以便进行友好提示或自动重试。调试时善用工具首先用Postman或curl模拟请求隔离前端代码或网络环境的影响。给服务器端开发者的建议明确声明API能力在代码和文档中清晰定义每个端点支持的响应格式。设置合理的默认格式通过框架配置为Accept: */*或缺失Accept头的请求提供一个默认的、最常用的响应格式通常是JSON。提供友好的406响应当协商失败时返回的406响应应包含清晰的错误信息和supported_types列表这是API设计友好性的体现。考虑内容协商策略根据业务需求评估是否支持URL参数覆盖如?formatjson但这不应是主要手段。我个人在实际项目中曾因为一个第三方库自动添加了Accept: application/xml头而我们的后端API当时只明确配置了生产JSON导致线上监控突然出现大量406错误报警。排查过程就是严格按照上述清单从客户端请求抓包开始最终定位到是库的某个次要版本更新改变了默认行为。这个经历让我深刻体会到对于HTTP这种看似简单的协议其头字段的每一个细节都值得敬畏。养成良好的习惯——明确声明、主动设置、完善处理——能让你的应用在复杂的网络环境中更加稳定可靠。