上周一个老朋友在群里发了个问题他们线上有个接口前端收到的响应永远是乱码而且整个JSON被一对双引号包着看起来像一串字符串。Controller用得很标准类上加了RestController返回的是一个DTO对象代码翻来覆去看了好几遍都看不出问题在哪。最后一步一步查才发现罪魁祸首是Spring MVC里那个平时根本不会被注意到的组件——HttpMessageConverter。说白了HttpMessageConverter就是HTTP报文和Java对象之间的翻译官。请求进来时它把字节流变成你方法签名里的DTO响应出去时它把方法返回值变成前端能认的JSON、XML或者纯文本。这个环节对绝大多数业务开发是透明的——你写一个RequestBody OrderDTO order前端传过来的JSON怎么变成OrderDTO你不关心你return一个对象它怎么变成JSON响应你也不关心。Spring默默做完了这一切。但这种看不见恰恰是最容易出问题的地方。我这些年排查过不少接口怪象返回String被当成纯文本输出、Long型ID变成一串精度丢失的数字、自定义转换器死活不生效、上传文件大小限制配了没用、下载文件名中文乱码……根子几乎都出在转换链路上。所以这篇把我对HttpMessageConverter的理解和文件上传下载的实战经验整理出来希望能帮后来的人少踩几个坑。1. 转换发生的位置一次请求从报文到对象的完整旅程要说清楚HttpMessageConverter得先看它在Spring MVC整个请求链路里待在什么位置。不然你只知道它是个转换器但搞不懂它什么时候被调用、为什么有的参数能转换有的不能。DispatcherServlet收到请求后先通过HandlerMapping找到处理这个请求的HandlerMethod也就是你Controller里那个方法。真正的执行逻辑在InvocableHandlerMethod里它对方法签名上的每一个参数逐个调用HandlerMethodArgumentResolver去解析。这里面有个分岔路口如果参数上有RequestBody注解走的是RequestResponseBodyMethodProcessor如果没有这个注解走的是其他普通参数解析器比如处理RequestParam、PathVariable那批。RequestResponseBodyMethodProcessor内部做的事就是根据请求头里的Content-Type去当前应用注册的所有HttpMessageConverter里找一个canRead返回true的转换器然后调用它的read方法从HttpServletRequest的InputStream里读出字节转换成方法参数对应的Java类型。这个read的动作把你看到的前端传了个JSON字符串变成了后端拿到一个OrderDTO对象。响应方向对称。方法执行完拿到返回值之后HandlerMethodReturnValueHandler会判断这个返回值需不需要写进响应体。如果方法或类上有ResponseBody或者类上标了RestController就会走RequestResponseBodyMethodProcessor的handleReturnValue方法在HttpMessageConverter列表里找一个canWrite返回true的调用write方法把Java对象序列化写到HttpServletResponse的OutputStream里。整个流程可以用一句话概括HTTP请求报文InputStream - read - Java对象 - 业务方法执行 - 返回值 - write - HTTP响应报文OutputStreamHttpMessageConverter接口本身不复杂就四个核心方法和一个获取媒体类型的方法canRead(Class? clazz, MediaType mediaType)判断能不能把给定媒体类型的请求体转换成目标类型。canWrite(Class? clazz, MediaType mediaType)判断能不能把给定类型序列化成目标媒体类型。read(Class? clazz, HttpInputMessage inputMessage)从输入流读取并转换。write(T t, MediaType contentType, HttpOutputMessage outputMessage)把对象写到输出流。getSupportedMediaTypes()返回这个转换器支持的Content-Type列表。读方法拿到的是HttpInputMessage你可以通过它获取请求体的InputStream、Content-Type、Content-Length这些信息写方法拿到的是HttpOutputMessage你可以往它的OutputStream里写字节也可以往它的headers里塞响应头。HttpMessageConverter这个名字起得很朴素但它是整个Spring MVC HTTP语义和Java类型系统之间的翻译层理解了这一点后面所有问题都好解释。2. 谁的转换器说了算默认注册表与优先级引发的经典事故Spring Boot在启动的时候WebMvcConfigurationSupport的addDefaultHttpMessageConverters方法会往容器里塞一长串默认转换器。只要classpath下有对应的第三方库对应的转换器就会被注册。我见过最常见的一批ByteArrayHttpMessageConverter、StringHttpMessageConverter、ResourceHttpMessageConverter、ResourceRegionHttpMessageConverter以及最常见的MappingJackson2HttpMessageConverter。这个顺序不是随便排的注册顺序直接决定了同一个请求会被谁处理。Spring MVC在挑选转换器时会遍历整个列表按顺序找第一个canRead/canWrite返回true的转换器。注意是第一个不是最合适的一个。一旦找到了后面的人根本没机会上场。这也是很多诡异问题的根源。最典型的事故就是String和Jackson的竞争。StringHttpMessageConverter排在Jackson前面它支持的MediaType包括text/plain和*/。/*意思是任何响应类型它都认。所以你一个RestController方法返回String类型时Spring一检查canWrite返回类型确实是StringStringHttpMessageConverter支持于是它直接接手了——Content-Type被设置成text/plain响应体就是那对双引号包起来的字符串。前端拿着这个当JSON解析自然是一脸懵。这个不算bug算设计如此。但你如果不知道这个机制排查起来会非常痛苦。我见过不少人为了修这个在方法上硬加produces application/json折腾半天才想起去配置全局转换器。另一个经常翻车的点是自定义转换器的注册位置。很多人的第一反应是在WebMvcConfigurer里写Override public void extendMessageConverters(ListHttpMessageConverter? converters) { converters.add(new MyCustomHttpMessageConverter()); }注意extendMessageConverters是在默认转换器列表构造完之后执行的。add方法把自定义转换器加到了列表末尾。而列表前面的MappingJackson2HttpMessageConverter已经能处理application/json了你的自定义转换器如果也是处理application/json的就会变成永远轮不到执行的幽灵转换器。你测试时发现加了等于没加代码检查了三遍都没看出来问题出在列表顺序上。针对这个问题有两个接口需要分清configureMessageConverters清空Spring默认注册的所有转换器完全由你提供的列表接管。这个动作很大一个不小心就把Spring内部依赖的转换器删没了一般不建议用。extendMessageConverters在默认列表基础上追加或调整。推荐优先考虑这个。想让自定义转换器优先直接插到列表头部就行converters.add(0, new MyCustomHttpMessageConverter());如果想把某些默认转换器踢掉也可以在for循环里根据instanceof判断后remove。总之要记住一条经验转换器这个列表是先到先得顺序即优先级所有涉及自定义转换器的调整第一件事永远是确认它在列表里的位置而不是确认逻辑写没写对。3. 文件上传multipart 解析模式与 HttpMessageConverter 的分界线很多人以为文件上传也是HttpMessageConverter干的活其实不是。这是两条完全不同的技术路线搞清楚这条分界线比背一堆API参数重要得多。回想一下日常写法。前端用multipart/form-data提交一个文件Controller方法签名是upload(RequestParam(file) MultipartFile file)。这个file是怎么被解析出来的真实流程是DispatcherServlet在处理请求之前有一个checkMultipart方法它会检查当前Spring容器里有没有配置MultipartResolver同时判断当前请求是不是multipart/form-data或multipart/mixed。两个条件都满足它就把原始的HttpServletRequest包装成一个StandardMultipartHttpServletRequest这个包装后的request才进入后面的参数解析流程。等到参数解析器处理RequestParam(file)时发现参数类型是MultipartFile它会从request里取multipart相关的参数——这时的数据源是已经被MultipartResolver解析好的文件对象而不是原始HTTP字节流。整个过程中Spring MVC用的是MultipartResolver这套机制HttpMessageConverter根本没参与。那什么时候文件上传会跟HttpMessageConverter扯上关系当你非要用RequestBody去接收MultipartFile时。此时Spring走的是RequestResponseBodyMethodProcessor它会拿着multipart/form-data这个MediaType去转换器列表里找canRead的转换器但默认注册的转换器里没有谁能处理multipart/form-data结果就是直接抛415 Unsupported Media Type。我在项目里见过有人对着这个错误排查了一下午最后发现是吃了文件上传当然也是转换器处理的这个认知亏。Spring Boot 2.x默认使用的是StandardServletMultipartResolver它是基于Servlet 3.0的Part API实现的配置上非常简洁spring: servlet: multipart: max-file-size: 10MB max-request-size: 20MB file-size-threshold: 2KB location: /tmp/upload这里几个参数的含义要理清楚。max-file-size是单个文件的大小上限max-request-size是整个multipart请求的总大小上限——注意这个总大小包含文本字段在内所以max-request-size通常要大于max-file-size否则就会出现每个文件都没超限提交时却报文件过大的怪现象。file-size-threshold是文件在磁盘临时文件之前在内存中允许缓存的最大字节数。location是临时文件目录这个在生产环境非常关键很多Linux服务器重启后会把/tmp清空如果上传过程中依赖临时目录且目录不存在就会遇到诡异的IO异常。另一种常用方案是CommonsMultipartResolver底层走Apache Commons FileUpload在Servlet 3.0之前的旧容器时代是主流选择。两者的取舍大致如下维度StandardServletMultipartResolverCommonsMultipartResolver依赖Servlet 3.0 内建Spring Boot默认需额外引入commons-fileupload配置方式spring.servlet.multipart.*配置项手动声明Bean并设置属性性能容器原生轻量功能成熟但多一层封装适用场景大多数现代Spring Boot项目老系统迁移、需要深度控制解析细节文件保存的代码我看过太多版本踩坑最多的就两个点。第一个是路径穿越。有些人喜欢直接用用户传的原始文件名拼路径File dest new File(uploadDir / file.getOriginalFilename());如果原文件名里带了../这样的路径片段文件就可能被写到上传目录之外。稳妥的做法是用UUID生成存储名或者至少做路径规范化校验String originalFilename file.getOriginalFilename(); String suffix StringUtils.getFilenameExtension(originalFilename); String storedName UUID.randomUUID().toString().replace(-, ) . suffix; Path targetPath Paths.get(uploadDir, storedName).normalize(); if (!targetPath.startsWith(uploadDir)) { throw new IllegalStateException(非法路径); } file.transferTo(targetPath);第二个坑是transferTo的相对路径问题。transferTo里如果传的是相对路径Spring会把它解析到临时目录去处理经常出现代码本地能跑部署到服务器就报错的情况。建议总是传绝对路径确保行为可预期。4. 文件下载从 byte[] 到 Resource流式响应的正确姿势文件下载这头有一个类似的经典思维定式拿到文件内容塞进byte[]包一个ResponseEntity返回。这在文件很小的时候没有任何问题但一旦你开始下载大文件比如几百MB甚至GB级别的日志、视频byte[]方式就是一个内存炸弹——整个文件被加载进堆内存并发一上来直接OutOfMemoryError。所以文件下载的第一个选择课题就是想清楚你的文件有多大。小文件几十MB以内用byte[]简洁直观GetMapping(/download/small) public ResponseEntitybyte[] downloadSmall() { byte[] data fileService.loadFileBytes(); return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filenamereport.pdf) .body(data); }大文件就不能这么干了。Spring提供了一个天生的流式方案——返回Resource类型。Spring MVC在处理返回值时ResourceHttpMessageConverter会直接把Resource以流的方式写出去内部按8KB缓冲循环读写不会把整个文件加载进内存GetMapping(/download/large) public ResponseEntityResource downloadLarge() throws IOException { Path path Paths.get(/data/files/big-file.zip); Resource resource new InputStreamResource(Files.newInputStream(path)); return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filename*UTF-8 encodeFileName(大文件.zip)) .body(resource); }这里的encodeFileName是处理中文文件名的关键后面细说。如果你需要完全掌控输出过程比如要上报下载进度、做权限拦截后的加密流可以直接操作HttpServletResponseGetMapping(/download/raw) public void downloadRaw(HttpServletResponse response) throws IOException { response.setContentType(application/octet-stream); response.setHeader(HttpHeaders.CONTENT_DISPOSITION, attachment; filenamereport.pdf); try (InputStream in new FileInputStream(filePath); OutputStream out response.getOutputStream()) { byte[] buffer new byte[8192]; int len; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); } out.flush(); } }这三种方式可以简单对比如下方式内存占用推荐场景缺点ResponseEntitybyte[]高文件全量入内存小文件、临时下载大文件OOM风险ResponseEntityResource低按缓冲流式写绝大多数文件下载文件名编码需自己处理HttpServletResponse直接写低完全可控加密流、进度上报、复杂响应头代码量多需要手动管理流文件名编码这个问题必须单独拿出来讲。Content-Disposition响应头里写filename中文.pdf这种老写法在大部分浏览器里都会导致乱码或者下载失败。正确姿势是HTTP 1.1标准定义的filename*参数格式是Content-Disposition: attachment; filenamereport.pdf; filename*UTF-8%E4%B8%AD%E6%96%87.pdffilename给一个ASCII的兜底名filename*给UTF-8编码之后的真实文件名。Java侧的实现很直接private String encodeFileName(String fileName) { return URLEncoder.encode(fileName, StandardCharsets.UTF_8).replace(, %20); }注意那个replace(, %20)——URLEncoder会把空格编码成加号但在Content-Disposition的filename*里加号不会被浏览器正确还原成空格所以必须手动替换成%20。这个细节我不知道见过多少人踩。再往深走一步大文件下载如果要求断点续传就要涉及Range请求。客户端请求头里带Range: bytes0-1023服务端返回206 Partial Content并在响应里带Content-Range。Spring MVC对这块有内建支持可以用ResourceRegionGetMapping(/download/range) public ResponseEntityResourceRegion downloadRange(RequestHeader HttpHeaders headers, Path path) { Resource resource new FileSystemResource(path); long fileLength resource.contentLength(); ListRange ranges headers.getRange(); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filenamebig.zip) .body(new ResourceRegion(resource, ranges.isEmpty() ? 0 : ranges.get(0).getStart(), fileLength)); }如果你们的架构里有Nginx这类反向代理我更建议把Range支持交给Nginx应用层只做权限校验和文件名下发这样实现成本低性能还更好。5. 实战避坑五个线上才会暴露的转换与传输问题这一节把我这些年真实踩过、以及帮别人排查过的几个高频问题集中写出来。每个都是线上环境才容易暴露的本地写demo很难触发。第一个是StringHttpMessageConverter的编码问题。Spring Framework在5.2之前默认注册的StringHttpMessageConverter使用ISO-8859-1编码编译器没警告、测试环境不报错但只要响应体里有中文前端拿到就是乱码。更隐蔽的是如果你返回的是String类型Content-Type被设置成text/plain;charsetISO-8859-1那这个响应就彻底没法看了。解决方案是显式注册一个UTF-8的StringHttpMessageConverter并且有条件的话尽量让接口返回对象而不是String从源头避开text/plain这条路。第二个是Jackson的Long精度丢失。数据库主键用雪花ID或者自增Long超过2^53时前端JavaScript数字类型无法精确表示会出现ID最后几位变成0的情况。这个在联调阶段很难发现往往要等页面操作某条记录报错回头一对ID才发现变了。后端全局处理最省心Bean public Jackson2ObjectMapperBuilderCustomizer longToStringCustomizer() { return builder - builder .serializerByType(Long.class, ToStringSerializer.instance) .serializerByType(Long.TYPE, ToStringSerializer.instance); }这样Long统一序列化成字符串前端用字符串接收不会再丢精度。要注意的是如果你用String接收Long数据库排序、比较这些操作就不方便了所以通常只在序列化层处理。第三个是上传大小限制配了没生效。这通常是因为项目里同时存在多个MultipartResolver。比如Spring Boot自动配置了StandardServletMultipartResolver你又为了用Commons FileUpload手动声明了一个CommonsMultipartResolver的Bean两个解析器并存时DispatcherServlet只会认名字叫multipartResolver的那个Bean——如果名字不对比如叫fileUploadResolverSpring就找不到解析器直接按普通请求处理你配的所有大小限制全都不生效。排查这类问题最快的方式是启动时看日志找org.springframework.web.multipart相关的初始化输出确认当前用的到底是哪个解析器。第四个是自定义转换器加了没反应。这个我在前面已经详细解释过根因几乎都是列表顺序。你自定义了一个处理application/json的转换器但Jackson排在前面你的永远轮不到。还有一种情况是自定义转换器的supportedMediaTypes写得不够宽比如只写了application/custom但实际请求的Content-Type带了charset参数媒体类型严格匹配时就会匹配失败。处理办法是用mediaType.includes或isCompatibleWith这类宽容匹配而不是equals。第五个是下载文件名中文乱码。前面已经讲了filename*的方案这里补充一个容易被忽略的细节如果你的Controller方法同时返回了Resource且方法上有ResponseBodySpring MVC会选择ResourceHttpMessageConverter来处理它这个转换器会基于Resource的内容类型自动设置Content-Type。但如果你想强制让浏览器走下载而不是预览Content-Type要设置成application/octet-stream并且在Content-Disposition里明确写attachment。这样浏览器才会弹出下载框而不是傻乎乎地尝试打开PDF预览。6. 写一个自定义 HttpMessageConverter加密响应体的落地过程最后说一个进阶场景。标准转换器解决的是JSON、XML、文本这些常见格式但真实业务里总有一些特殊协议——比如你和某个老系统对接约定请求体整体做一遍AES加密然后Base64编码成字符串再以application/encrypted-json这个Content-Type发过来。这种场景下标准Jackson转换器完全不适用你需要自己写一个HttpMessageConverter。实现思路不复杂。继承AbstractHttpMessageConverter实现supports、readInternal、writeInternal三个方法public class EncryptedJsonMessageConverter extends AbstractHttpMessageConverterObject { private final ObjectMapper objectMapper new ObjectMapper(); private final CryptoService cryptoService; public EncryptedJsonMessageConverter(CryptoService cryptoService) { super(new MediaType(application, encrypted-json)); this.cryptoService cryptoService; } Override protected boolean supports(Class? clazz) { // 只处理业务DTO避免把所有类型都吸进来 return AbstractEncryptedDTO.class.isAssignableFrom(clazz); } Override protected Object readInternal(Class? clazz, HttpInputMessage inputMessage) throws IOException { String encrypted new String(inputMessage.getBody().readAllBytes(), StandardCharsets.UTF_8); String json cryptoService.decrypt(encrypted); return objectMapper.readValue(json, clazz); } Override protected void writeInternal(Object value, HttpOutputMessage outputMessage) throws IOException { String json objectMapper.writeValueAsString(value); String encrypted cryptoService.encrypt(json); outputMessage.getBody().write(encrypted.getBytes(StandardCharsets.UTF_8)); } }这个例子里有几个值得注意的决策点。supports方法不要盲目return true。我见过有人图省事全放行结果所有类型的响应都被这个转换器拦截加密Debug半天才发现某些不该加密的接口也被保护了。按类型过滤是更安全的设计——要么限定接口的基类要么用自定义注解标记。readInternal里我直接用readAllBytes。对加密请求体来说CT体量一般不会太大这么写没问题但如果你的场景是解密一个大文件流就不能这么粗暴得改用流式处理。写方向有个隐蔽问题AbstractHttpMessageConverter的write方法会在调用writeInternal之后设置Content-Length。如果你的加密过程是等writeInternal执行完才算出密文长度那Content-Length就可能不准确导致客户端解析异常。解决方案是重写write方法在拿到输出流后先自己算出密文长度并设置Header再写入或者接受不设置Content-Length让客户端走分块传输。注册方式和前面说的一样放到列表最前面确保它能拿到优先处理权Override public void extendMessageConverters(ListHttpMessageConverter? converters) { converters.add(0, new EncryptedJsonMessageConverter(cryptoService)); }自测的时候可以用Spring的MockHttpInputMessage和MockHttpOutputMessage构造输入输出不启动Web容器就能验证加解密转换的正确性。这类自定义转换器适用的范围很广加密协议、自定义压缩格式、旧系统私有报文格式都可以用同一套思路扩展。核心就是理解转换器是一个可插拔组件Spring MVC允许你在标准格式之外自由定义自己的语义这个弹性是它这么多年还活跃在生产一线的重要原因。我在实际项目中处理完这几个坑之后最大的感受是Spring MVC的这套转换机制本质上就是一套协议翻译管线理解它是怎么挑选转换器、怎么决定顺序、怎么跟multipart解析器分界比记住某个具体配置项有用得多。文件上传下载也好自定义加密格式也罢只要你能画出请求从进来到出去走了哪条路问题就已经解决一半了。