有一段时间我一直在排查一个挺诡异的问题服务端接口明明写得没有问题用 Postman 调一切正常可一到前端联调就报错——要么 415要么 body 读出来是空的要么中文变成一堆问号。查到最后问题全部指向一个经常被人忽略的 HTTP 头字段Content-Type。这个问题在后端圈子里太典型了而且如果你和我一样用 Jackson 处理 JSON那么 Content-Type 和你之间的关系比想象中要紧密得多。这篇文章我想从 Jackson 这个 Java 生态里最常用的 JSON 处理库的视角系统地聊一聊 HTTP 报文中的 Content-Type 到底是什么、服务端如何根据它选择解析器、选错之后会出什么故障以及实战中应该怎么配置。适合正在做接口开发的 Java 后端同学也适合想弄明白为什么我 post 过去的数据后端拿不到的前端同学。把这篇文章看完你排查接口问题时能少走很多弯路。1. Content-Type到底在HTTP报文里扮演什么角色1.1 一个字段承担了三种职责先说结论Content-Type 属于 HTTP 报文中的实体头字段它描述的是报文体body里的数据是什么媒体类型。很多人把它的作用范围局限于请求其实响应报文里也有它而且同样重要。请求报文中的 Content-Type直接决定服务器拿到 body 之后用哪套解析逻辑。body 是 JSON 字符串、表单字符串还是二进制文件解析方法完全不同。服务器端一旦按错误的类型去做反序列化轻则数据丢失重则直接报错。响应报文中的 Content-Type则告诉浏览器或客户端应该用什么样的方式去解读返回体。同样是字符串是当成 HTML 渲染成页面还是当成 JSON 给JSON.parse完全依赖这个字段。前端拿到text/html却试图当 JSON 解析自然会出问题。除了这两种职责Content-Type 还参与内容协商。HTTP 协议里客户端可以用Accept头声明自己期望的媒体类型服务端根据Accept结合自身能力返回最合适的 Content-Type。这个机制在 Spring MVC 的produces属性里体现得很明确后面我会展开讲。拿快递打个比方Content-Type 就像快递外包装上贴的物品标签。快递员看到易碎品标签会轻拿轻放收件人看到生鲜标签会尽快处理。如果标签贴错了运输和验收环节全都会出乱子。1.2 结构拆解类型/子类型以及参数Content-Type 的标准结构长这样Content-Type: type/subtype; parametervaluetype是主类型比如application、text、image、multipart。subtype是子类型比如json、html、plain。分号后面可以跟参数最常见的参数是charset指定字符编码。几个开发中最常见的 Content-TypeContent-Type含义典型场景application/json; charsetUTF-8JSON 格式的结构化数据前后端分离接口、REST APIapplication/x-www-form-urlencoded表单键值对keyvaluekey2value2HTML 表单默认提交格式multipart/form-data二进制表单用 boundary 分割文件上传text/plain纯文本无结构化日志上报、简单字符串application/xml/text/xmlXML 格式SOAP 协议、老系统对接application/octet-stream通用二进制流文件下载、字节流接口在 Java 后端里HttpServletRequest.getContentType()拿到的是原始字符串比如application/json;charsetUTF-8。如果要做精确判断别用String.contains(json)这种粗放写法建议用 Spring 提供的MediaType.parseMediaType(contentType)解析成MediaType对象再通过getType()、getSubtype()、getCharset()去精确读取。这个小习惯能在编码判断上帮你省不少事。还有一点很多人会忽略Content-Type 的值不区分大小写但参数名和参数值有规范要求。另外不同的服务器框架可能对缺失 Content-Type 的处理方式不一样——有的默认当成application/octet-stream有的直接返回 415。这就是为什么同一个接口在不同环境下表现可能完全不同。2. Jackson视角什么样的Content-Type才会触发JSON解析2.1 Spring MVC 里的 HttpMessageConverter 选择机制如果你用过 Spring MVC 的RequestBody那底下发生的事情值得弄清楚。请求进来之后RequestResponseBodyMethodProcessor会负责解析RequestBody注解的参数。解析流程不是直接拿 Jackson 去读 body而是先做一轮媒体类型匹配。Spring 维护了一个HttpMessageConverter列表每个转换器都有自己支持的媒体类型。解析器会遍历这个列表找到第一个同时满足两个条件的转换器第一canRead返回 true第二它支持的媒体类型和当前请求的 Content-Type 匹配。关键就在第二步。如果前端发来的是application/json那么MappingJackson2HttpMessageConverter就能接手把 body 里的 JSON 字符串通过 Jackson 的ObjectMapper反序列化成目标对象。如果前端发来的是text/plainJackson 这个转换器根本不认为自己能处理它匹配会落到StringHttpMessageConverter头上于是你RequestBody User user就接收不到数据——因为根本没有转换器能把纯文本变成 User 对象。这几点搞清楚了很多灵异问题就都有了解释不是后端代码写错了而是请求头根本没有引导 Jackson 上场。2.2 常见 Content-Type 在 Spring 里的解析走向我整理了一张表对应不同 Content-Type 下 Spring 会走哪个转换器、最终RequestBody能拿到什么请求 Content-Type命中的转换器RequestBody 效果application/jsonMappingJackson2HttpMessageConverterJackson 反序列化成对象或 Mapapplication/vnd.apijsonMappingJackson2HttpMessageConverter同样走 Jackson支持 json 后缀application/x-www-form-urlencodedFormHttpMessageConverterbody 被解析成表单键值对无法直接变对象multipart/form-dataFormHttpMessageConverter 处理表单字段文件靠 MultipartFile 参数接收text/plainStringHttpMessageConverter拿到原始字符串需要手动转对象缺失或未知类型视具体配置可能 415也可能匹配到通配转换器MappingJackson2HttpMessageConverter默认支持的媒体类型包括application/json和application/*json。也就是说带有json后缀的自定义媒体类型比如很多开放平台喜欢用的application/vnd.examplejsonJackson 也能识别这算是一个比较贴心的设计。2.3 前端框架默认 Content-Type 的差异是最大变量同样是发 POST 请求axios、jQuery、fetch 的默认行为完全不一样。axios 对 JavaScript 对象做序列化时默认会把数据变成 JSON 字符串同时设置application/json所以和后端 Jackson 配合得很顺。jQuery 的$.ajax默认就是application/x-www-form-urlencoded; charsetUTF-8它会把对象序列化成keyvaluekey2value2的形式。而 fetch 如果不在 headers 里手动指定 Content-Type请求体是字符串时会以text/plain发送。这就导致了一个特别常见的场景同一个后端接口用 Postman 测一切正常用 axios 调也正常换 jQuery 一调后端RequestBody直接拿到 null。很多同事第一反应是后端 bug其实真正的差异只在前端库的默认 Content-Type 上。3. 三种Content-Type故障现场与完整排查链路3.1 场景一415 Unsupported Media Type 的根因与排查曾经接手一个某电商项目的登录接口前端同学说接口挂了后端日志里报 415 Unsupported Media Type。我打开浏览器 DevTools 的 Network 面板发现请求头里根本没有 Content-Type 字段。再看前端代码用的是 fetch 发请求body 是JSON.stringify后的字符串但 headers 里没设置 Content-Type。fetch 对字符串 body 默认走text/plain而接口方法上标注的是consumes application/json。服务器一看媒体类型不对直接返回 415。这个问题的排查链路大致是打开浏览器开发者工具切到 Network 面板点击失败的请求。查看 Request Headers确认 Content-Type 的实际值。用 curl 模拟同样的请求复现问题。对比 Postman 中成功请求和失败请求的 headers 差异。锁定根因后修复前端 headers 或后端 consumes 约束。修复方式有两种思路。如果接口确实只接受 JSON前端补上headers: {Content-Type: application/json}。如果接口设计就要兼容不同格式后端可以把consumes去掉或者放宽。大多数情况下我的建议是前者——前后端约定好一个明确的 Content-Type比宽松匹配更利于长期维护。3.2 场景二application/json 响应中文乱码另一个很典型的问题是乱码。现象是接口返回的 JSON 数据一切正常但里面的中文在页面上显示成??或乱码。用curl -i查看响应头发现 Content-Type 是application/json但没有跟着charsetUTF-8。这里要说明一点Spring Boot 2.x 里 Jackson 写 JSON 时默认就是 UTF-8一般不会出现这个问题。乱码多发于老项目或者有人绕过 Spring MVC 直接通过HttpServletResponse.getWriter()输出内容又没有设置编码。排查步骤用curl -i http://localhost:8080/api/user查看响应头确认charset是否存在。如果响应头是Content-Type: application/json没有 charset客户端解码会依赖平台默认编码在中文环境下通常是 UTF-8但某些环境下会变成 ISO-8859-1乱码就出现了。检查代码里是否有response.setContentType(application/json)但没有拼上 charset。检查是否有StringHttpMessageConverter的编码配置被改成了 ISO-8859-1。修复方案是统一设置Content-Type: application/json; charsetUTF-8。在 Spring MVC 里可以通过注解的produces属性强制指定GetMapping(value /user, produces application/json;charsetUTF-8)或者在响应对象上手动setContentType。3.3 场景三前端传 urlencoded后端 RequestBody 拿到 null第三个场景更常见前端用的是 jQuery 的$.ajax默认 Content-Type 是application/x-www-form-urlencoded后端接口写的却是RequestBody User user。结果前端确实把数据传过去了后端也进入了方法但 user 对象里全是 null个别情况下还会直接 400。我之前在某个系统对接中就踩过这个坑。排查链路是这样的先确认前端 Network 面板请求体是userId123userNametest这种表单格式Content-Type 是application/x-www-form-urlencoded。后端方法里RequestBody会因为找不到合适的转换器去解析对象Spring 直接抛异常或者把 body 映射成空对象。用RequestBody MapString, Object代替确实能收到数据但 map 里全是键值对完全不是 JSON 结构。最终确认问题不在后端解析逻辑而在于前后端对数据格式的约定不一致。修这种问题正确的姿势不是强行在后端把表单格式转成 JSON——那是在给前端擦屁股。更好的做法是要么前端把数据改成 JSON 格式发送配合application/json要么后端把入参改成RequestParam逐个接收或者用一个 POJO 加ModelAttribute去接表单字段。从架构角度说新写接口尽量统一用 JSON能少掉一半这种破事。3.4 用 curl 快速验证三种 Content-Type 的差异排查这类问题时与其反复让前端改代码不如先用 curl 做对照实验快速把后端行为摸清楚。下面三个命令分别模拟 JSON、表单和纯文本三种请求# JSON 方式Jackson 会正常工作 curl -X POST http://localhost:8080/api/user \ -H Content-Type: application/json \ -d {name:张三,age:18} # 表单方式RequestBody User 会拿不到数据RequestParam 正常 curl -X POST http://localhost:8080/api/user \ -H Content-Type: application/x-www-form-urlencoded \ -d name张三age18 # 纯文本方式RequestBody String 能拿到字符串RequestBody Object 不行 curl -X POST http://localhost:8080/api/user \ -H Content-Type: text/plain \ --data-raw {name:张三,age:18}三个命令跑完后端行为基本一目了然。工具层面 curl 就是最可靠的判断依据它不会像 Postman 那样帮你自动设置 Content-Type也就不会掩盖问题。4. 响应端的Content-TypeResponseBody和produces的取舍4.1 ResponseBody 返回时 Content-Type 是怎么定下来的ResponseBody的工作机制和请求端的RequestBody是对称的方法执行完拿到返回值Spring 遍历HttpMessageConverter列表找一个既能写当前类型、又能匹配客户端Accept要求的转换器然后由它把对象序列化并设置响应 Content-Type。Spring Boot 项目里对象返回默认走MappingJackson2HttpMessageConverter序列化结果是 JSON 字符串响应头是application/json编码默认 UTF-8这一套组合在实际开发中问题不大。但有个坑经常被忽略当返回值类型是String时Spring 会优先选择StringHttpMessageConverter。这个转换器默认支持的 Content-Type 是text/plain。如果接口设计上希望通过 String 返回 JSON比如手动拼了一段 JSON或者从第三方接口拿到的 JSON 字符串直接透传响应头很可能就是text/plain;charsetUTF-8而不是application/json。前端拿到text/plain时如果代码里有依赖Content-Type判断逻辑的比如判断是不是 JSON 类型就会走错分支。更保险的做法是返回 String 类型的 JSON 数据时主动声明produces。4.2 produces 和 consumes 的正确用法consumes和produces这两个注解属性分别约束请求和响应的媒体类型。PostMapping( value /api/user, consumes application/json, produces application/json;charsetUTF-8 ) public User createUser(RequestBody User user) { return userService.save(user); }consumes application/json的意思是只有请求 Content-Type 是application/json才会进入这个方法。前端如果发text/plainSpring 会直接返回 415。produces application/json;charsetUTF-8的意思是无论返回值是什么类型响应 Content-Type 都按这个来。这能解决两个问题一是强制指定 UTF-8 编码防止乱码二是避免 String 返回时被StringHttpMessageConverter设置成text/plain。这里还要提一个容易误伤的 406 Not Acceptable 问题。当客户端请求头里写了Accept: text/html而接口只能producesJSONSpring 会返回 406 而不是 JSON。排查这类问题时建议先看看客户端有没有设置奇怪的Accept头。4.3 封装 ResponseEntity 是更可控的姿势如果不想在注解上堆属性另一个思路是直接返回ResponseEntity把 Content-Type 显式塞进去GetMapping(value /api/export) public ResponseEntityString export() { HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.parseMediaType(text/plain;charsetUTF-8)); return new ResponseEntity(导出结果, headers, HttpStatus.OK); }这种写法适合响应格式和默认转换器不一致的接口。比如要返回 CSV 文本、纯文本日志、或者自定义媒体类型直接控制响应头反而更直观。但要提醒一句ResponseEntity虽好也别到处乱用。如果一个接口只是正常返回 JSON 对象老老实实写对象返回值、靠默认转换器输出才是最不容易出错的方案。过度设计和缺少设计最终都会体现在线上故障上。5. 实战中我总结的Content-Type规范与检查清单5.1 接口契约先行把 Content-Type 写进接口文档多年联调踩坑之后我的习惯是新项目一开始就要在接口文档里明确每个接口的请求 Content-Type 和响应 Content-Type。这一条看着简单执行到位的团队真不多。一组比较健康的接口约定大概是这样的接口类型请求 Content-Type响应 Content-Type说明标准 JSON APIapplication/jsonapplication/json;charsetUTF-8前后端分离默认登录/表单提交application/x-www-form-urlencodedapplication/json;charsetUTF-8兼容老系统文件上传multipart/form-dataapplication/json;charsetUTF-8返回上传结果文件下载无 bodyapplication/octet-stream二进制流下载第三方回调按对方的文档定义通常是 text/plain 或 application/json特殊接口特殊约定有了这张表前端不用猜后端不用临时改出了问题能快速定位是哪一侧违反约定。5.2 用过滤器打印 Content-Type 日志定位问题快一倍我之前在排查某个第三方接口对接问题时那个系统会在网关层偷偷改写 Content-Type导致内网的 Jackson 反序列化一直失败。这种问题靠直觉完全找不到方向最后还是加了过滤器把请求头完整打出来才看到网关层把application/json改成了application/json;charsetGBK下游用 UTF-8 解析自然乱码。打日志的过滤器写起来很简单Component public class ContentTypeLogFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; String uri httpRequest.getRequestURI(); String method httpRequest.getMethod(); String contentType httpRequest.getContentType(); String accept httpRequest.getHeader(Accept); logger.info(request uri{}, method{}, contentType{}, accept{}, uri, method, contentType, accept); chain.doFilter(request, response); } }每次排查联调问题我第一件事就是拉日志看这三行URI、Content-Type、Accept。一半以上的问题在这一步就能看出端倪根本不用断点调试。5.3 识别工具链带来的假阳性排查 Content-Type 问题的时候要特别注意工具链差异。Postman 会自动帮你设置application/json所以用它测试接口一切正常不代表前端调就正常。原生 XHR 如果不手动设置Content-Type默认发送的是text/plain。Java 自带的HttpURLConnection更激进它默认完全没有 Content-Type 头。Spring 的RestTemplate稍微好一点但它要求开发者主动通过 HttpHeaders 设置请求头HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); HttpEntityString entity new HttpEntity(jsonBody, headers);这类工具差异造成的假阳性测试结果恰恰是最坑人的。我后来定了一条验收规矩任何接口联调前先用 curl 按接口文档发送原始请求确认响应符合预期再让前端开始对接。这一条规矩落地后联调阶段的低级问题明显少了很多。最后分享一个我自己的习惯每次新项目落地我会在公共模块里加上上面那个简单的过滤器把每个请求的 Content-Type、Accept、URI 连同状态码打到日志里。排查问题的时候先看这三行基本能定位一半的接口问题。别小看这一个小小的 HTTP 头字段它帮你挡住的 bug远比你以为的多。
