对接过第三方接口的人都懂那种感觉Postman 里点一下 Send200一切正常转头用 Java 发送 POST 请求把同一份文件换成代码传上去400、415、500 轮着来日志里还看不出所以然。这次要聊的就是这个高频场景——用 Java 以 multipart/form-data 格式把文件数据连同业务字段一起推给接口。它本质上解决的是文件二进制流 普通表单字段混在同一个请求体里传输的问题常见于档案归档、票据影像上传、批量导入、图像处理回调这类业务。适合三类人看刚接手对接任务、只想找一段能跑的代码的新手已经能跑通但偶尔被乱码、截断、超时折磨的中级开发者以及需要把上传通道做成通用组件、考虑并发和大文件的资深同学。下面我按自己的实际踩坑顺序来拆代码都能直接抄。1. 先把格式这件事说透方案选型与整体设计1.1 multipart/form-data 在字节层面到底长什么样很多人卡在这一步是因为把 multipart/form-data 当成了一个设置一下就完事的请求头。它不是。它是一种请求体的组织约定整个 body 被一串边界符boundary切成若干段每一段就是一个字段段与段之间靠--boundary分隔最后以--boundary--收尾。文件字段和普通文本字段在结构上完全一样区别只在于段头里多了一个filename以及段体是二进制而不是可读文本。我习惯用一个类比把请求体想成一份装了多个信封的快递包裹boundary 就是每个信封上那道封口胶带。收件方服务端只认胶带的样式不认你在信封上写什么。所以只要胶带样式对不上——多一个空格、少一个回车、用了服务端解析器不认的字符——整份包裹就会被判定为格式错误返回 400。这也是为什么手写拼接的代码经常在本地好好的、换个服务端就挂。关键的格式硬规则有三条后面代码里我会反复强调第一每一行结束必须是CRLF\r\n不是\n\n在宽容的解析器上能过严格的解析器直接拒第二段头和段体之间必须有一个空行也就是连续两个 CRLF第三开头第一个 boundary 前面也要有--结尾的 boundary 后面要有--且通常再跟一个 CRLF。这三条只要错一条表现就是字段全丢或者文件大小是 0。1.2 四套实现方案的横向对比与选型逻辑Java 侧做这件事至少有四条路选哪条不看流行度看你项目的依赖现状和约束条件。方案依赖成本代码量大文件友好度适合场景HttpURLConnection 手写拼接零依赖JDK 自带多约 60~80 行好可控流式写出老项目、SDK 内部、不能引三方包Apache HttpClient需引入 httpclient少十几行好支持 chunked传统后端服务、需要连接池和重试OkHttp需引入 okhttp少好Android、轻量客户端、需要拦截器Spring RestTemplate / WebClientSpring 环境自带极少中等需注意内存已有 Spring 体系的服务我一般的判断顺序是如果项目已经是 Spring Boot优先RestTemplate同步或WebClient异步代码最短、维护成本最低如果是给外部提供的 SDK 或者跑在受限环境里比如某些只允许 JDK 原生类的沙箱就走HttpURLConnection手写如果是高频、高并发的内部服务用HttpClient配连接池配合重试策略。这里有个容易忽略的点RestTemplate默认用的是 JDK 的HttpURLConnection或者HttpComponents取决于你引入了什么。如果项目里同时存在两个 HTTP 客户端实现可能出现你配的超时没生效的情况。我踩过一次配了setReadTimeout结果 30 秒就断后来发现底层被换成了另一套实现超时得在连接工厂上设。所以选型之后要确认配置到底落在哪个实现上。1.3 什么情况下必须手写以及手写的底线要求有一种场景绕不开手写对接方对 body 的顺序、boundary 的字符集、甚至对每个段的 header 顺序都有要求。我遇到过一个归档接口它要求普通字段必须排在文件字段之前且 boundary 不能包含-以外的特殊字符用现成的构建器反而不好控制顺序。这种情况下手写更省事。但手写有底线绝对不要把整个文件读成 byte[] 再拼字符串。我见过有人这么写本地测 2MB 的图片没问题上线遇到 80MB 的视频直接 OOM。正确做法是把OutputStream拿到手先写段头再用Files.copy或者循环read/write把文件流直接怼进去。这样内存占用只跟缓冲区大小有关跟文件大小无关。另外一个底线是不要自己造Content-Length。手写时如果坚持要设得把每个段头的字节数、文件字节数、CRLF 全部算进去一个字符都不能差算错了服务端会一直等数据直到超时。用HttpURLConnection时默认走chunked传输更省心除非对方明确要求定长。2. 请求体核心细节编码、字段、文件流三处最容易埋雷2.1 boundary 的选取与那几行 CRLF 的脾气boundary 不是随便一串字符都行。按规范它由 1~70 个字符组成允许的字符集是字母、数字和()_,-./:?以及空格但末尾不能是空格。实际使用中最稳的是字母数字 连字符长度 20~40 位足够。我惯用的格式是----JavaFormBoundary加一段 UUID 去掉横线既能保证唯一性又不会踩字符集的坑。为什么不建议用固定 boundary因为理论上如果文件内容里恰好出现了--你的boundary这一串字节服务端就会误判成段结束导致文件被截断。这个概率极低但不是零尤其是上传文本类文件比如 CSV、日志、源码包时。用 UUID 生成一次一换风险基本归零。还有一处特别隐蔽Content-Type: multipart/form-data; boundaryxxx里分号后面有一个空格这是习惯写法但如果你在 body 里写段分隔符写成-- xxx多了一个空格就全错了。分隔符必须是--直接接 boundary中间不能有空格。我自己就在调试时因为复制粘贴多带了个空格查了整整一个下午。2.2 普通文本字段与文件字段的段头差异普通字段的段头只有一行Content-Disposition形如Content-Disposition: form-data; namebizType然后空行然后值。文件字段则是Content-Disposition: form-data; namefile; filenamereport.pdf后面还可以跟一行Content-Type: application/pdf。这里的第一个坑是name 的值必须和服务端声明的参数名完全一致。服务端用RequestPart(file)接收你传的 name 是files或者uploadFile结果就是 400 或者拿到 null。这个错误在日志里几乎看不出来因为请求确实发出去了、也确实有内容。第二个坑是文本字段的值不要做 URL 编码。multipart 里不存在 URL 编码概念你如果按application/x-www-form-urlencoded的习惯把中文值encode一遍服务端拿到的就是%E4%B8%AD%E6%96%87这样的字符串。我见过一个项目因此把用户备注全变成了乱码排查了两天才定位到是客户端多做了一次编码。第三个坑是文本字段的字符集。段头里如果不声明Content-Type: text/plain; charsetUTF-8某些服务端实现尤其是非 Java 的会按 ISO-8859-1 解析中文直接变问号。稳妥做法是给每个文本字段显式带上 charset而不是只在整体请求头里指望它生效。2.3 文件名编码中文名为什么总是出问题文件名的处理是整个流程里最分裂的地方。RFC 里建议对非 ASCII 文件名用filename*UTF-8xxx的扩展写法但大量服务端只认filenamexxx。于是就有了两种策略要么按 UTF-8 原样写进去指望对方按 UTF-8 解要么按对方要求的编码常见是 GBK转一遍再写。我的经验是先问对接方问不到就依次试。顺序是 UTF-8 原样 → RFC 5987 的filename*写法 → 对方文档指定的编码。测试方法很简单传一个叫测试文件.txt的文件看服务端落盘后的名字对不对。如果变成??.txt或者测试.txt就是编码不匹配。还有一个更省事的思路服务端只拿文件名做展示真正的业务标识应该走独立字段。所以我通常会在表单里额外带一个fileName文本字段UTF-8文件段里的 filename 只作为一个兜底。这样即使对方解析文件名出问题业务侧也能拿到正确的名字。这个做法在跨语言对接时救过我很多次。2.4 流式写出、长度计算与内存控制的实操判断关于内存有一个粗略但好用的判断如果文件平均大小超过 5MB就必须走流式如果超过 50MB就必须考虑分片和断点。原因是 JVM 堆里同时存在byte[]、可能的拷贝副本、以及 GC 压力并发几个大文件就会把年轻代打满。流式写出的核心是三段式写段头 → 从InputStream到OutputStream搬运 → 写结尾 CRLF。搬运时用 8KB 的缓冲区就够别用 1 字节循环性能差十倍以上也别用太大的缓冲区比如 1MB在几百并发下会浪费内存。Files.copy(file.toPath(), out)内部用的就是合适的缓冲能直接用就用它。关于Content-Length如果对方接口要求定长有些老网关会拒绝 chunked你就得算所有文本字段段头 值 CRLF 的字节数加上每个文件段的段头字节数文件名按实际编码后的字节数算 文件长度 CRLF最后加上收尾 boundary。我一般写个方法先累加算完打印出来核对一次。如果算错了表现是请求发出后长时间无响应或者对方报unexpected end of stream。3. 四套实现的可运行代码与逐行说明3.1 零依赖方案HttpURLConnection 手写 multipart 请求体这段代码我用在很多不能引三方包的项目里逻辑最透明也最适合理解格式。核心就是一个写字符串的辅助方法和一个写文件的循环。public class MultipartUploader { private static final String CRLF \r\n; private static final int BUFFER 8192; public static String post(String url, MapString, String textFields, MapString, File files, int connectTimeoutMs, int readTimeoutMs) throws IOException { String boundary ----JavaFormBoundary UUID.randomUUID().toString().replace(-, ); HttpURLConnection conn (HttpURLConnection) new URL(url).openConnection(); conn.setRequestMethod(POST); conn.setDoOutput(true); conn.setDoInput(true); conn.setUseCaches(false); conn.setConnectTimeout(connectTimeoutMs); conn.setReadTimeout(readTimeoutMs); conn.setRequestProperty(Content-Type, multipart/form-data; boundary boundary); conn.setRequestProperty(Accept, application/json); try (OutputStream out conn.getOutputStream()) { // 1. 先写普通文本字段 for (Map.EntryString, String e : textFields.entrySet()) { writeString(out, -- boundary CRLF); writeString(out, Content-Disposition: form-data; name\ e.getKey() \ CRLF); writeString(out, Content-Type: text/plain; charsetUTF-8 CRLF CRLF); writeString(out, e.getValue() CRLF); } // 2. 再写文件字段 for (Map.EntryString, File e : files.entrySet()) { File f e.getValue(); writeString(out, -- boundary CRLF); writeString(out, Content-Disposition: form-data; name\ e.getKey() \; filename\ f.getName() \ CRLF); writeString(out, Content-Type: guessContentType(f.getName()) CRLF CRLF); Files.copy(f.toPath(), out); // 关键流式搬运内存不随文件增长 writeString(out, CRLF); } // 3. 收尾 writeString(out, -- boundary -- CRLF); out.flush(); } int code conn.getResponseCode(); InputStream resp code 200 code 300 ? conn.getInputStream() : conn.getErrorStream(); String body resp null ? : new String(resp.readAllBytes(), StandardCharsets.UTF_8); if (code 200 || code 300) { throw new IOException(upload failed, http code , body body); } return body; } private static void writeString(OutputStream out, String s) throws IOException { out.write(s.getBytes(StandardCharsets.UTF_8)); } private static String guessContentType(String name) { String lower name.toLowerCase(); if (lower.endsWith(.pdf)) return application/pdf; if (lower.endsWith(.png)) return image/png; if (lower.endsWith(.jpg) || lower.endsWith(.jpeg)) return image/jpeg; if (lower.endsWith(.xlsx)) return application/vnd.openxmlformats-officedocument.spreadsheetml.sheet; if (lower.endsWith(.zip)) return application/zip; return application/octet-stream; } }几个要点解释一下。第一Files.copy(file.toPath(), out)是完全流式的不会把整个文件读进内存这是这段代码能扛大文件的关键。第二out.flush()必须在关闭前调用否则可能有一部分数据卡在缓冲里。第三读取响应时必须区分getInputStream和getErrorStream否则 4xx/5xx 的时候拿到的是 null日志里啥也看不见白白浪费排查时间。注意文件名的中文问题在这里是原样按 UTF-8 写进去的。如果对接方按 ISO-8859-1 解析需要在写入前对文件名做一次new String(name.getBytes(UTF-8), ISO-8859-1)的反向转码这招在多个旧系统上验证有效但属于临时方案最好还是推动对方修服务端。3.2 Apache HttpClientMultipartEntityBuilder 的正确用法如果项目里有HttpClient这套写法最省事。4.x 和 5.x 的 API 有差异我把 4.5 的写法放这里5.x 只是包名从org.apache.http变成org.apache.hc.client5.http等思路完全一致。try (CloseableHttpClient client HttpClients.custom() .setConnectionManager(poolingManager) .evictExpiredConnections() .build()) { MultipartEntityBuilder builder MultipartEntityBuilder.create(); builder.setMode(HttpMultipartMode.STRICT); // 严格模式格式更规范 builder.setCharset(StandardCharsets.UTF_8); builder.setBoundary(----Boundary UUID.randomUUID().toString().replace(-, )); builder.addTextBody(bizType, archive, ContentType.TEXT_PLAIN.withCharset(StandardCharsets.UTF_8)); builder.addTextBody(fileName, 季度报表.pdf, ContentType.TEXT_PLAIN.withCharset(StandardCharsets.UTF_8)); File file new File(/data/out/report.pdf); builder.addBinaryBody(file, file, ContentType.APPLICATION_OCTET_STREAM, file.getName()); HttpPost post new HttpPost(https://example.invalid/api/upload); post.setEntity(builder.build()); post.setConfig(RequestConfig.custom() .setConnectTimeout(5000) .setSocketTimeout(120000) // 大文件必须给足 .setConnectionRequestTimeout(2000) .build()); try (CloseableHttpResponse resp client.execute(post)) { int code resp.getStatusLine().getStatusCode(); String body resp.getEntity() null ? : EntityUtils.toString(resp.getEntity(), StandardCharsets.UTF_8); System.out.println(code - body); } }setMode(HttpMultipartMode.STRICT)这行值得单独说。默认是BROWSER_COMPATIBLE它在处理文件名和字符集时会做一些兼容性妥协某些严格的服务端反而不认。我在对接一个金融类归档接口时默认模式一直 400改成 STRICT 立刻就通了。反过来也有服务端只认 BROWSER_COMPATIBLE所以这两个模式要作为一个排查开关来用。另一个细节是addBinaryBody传File时是流式的传byte[]就是全内存。有些镜像接口单文件限制 20MB用byte[]也没事但一旦放开到 100MB必须传File或者InputStream。3.3 OkHttpMultipartBody.Builder 的清爽写法OkHttp 的 API 设计最直观Android 端和轻量 Java 客户端首选。注意RequestBody.create在 4.x 之后参数顺序变了别照着老博客抄。OkHttpClient client new OkHttpClient.Builder() .connectTimeout(5, TimeUnit.SECONDS) .writeTimeout(120, TimeUnit.SECONDS) .readTimeout(120, TimeUnit.SECONDS) .build(); File file new File(/data/out/report.pdf); MediaType octet MediaType.parse(application/octet-stream); RequestBody fileBody RequestBody.create(file, octet); // 4.x 写法File 在前 MultipartBody body new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(bizType, archive) .addFormDataPart(fileName, 季度报表.pdf) .addFormDataPart(file, file.getName(), fileBody) .build(); Request request new Request.Builder() .url(https://example.invalid/api/upload) .post(body) .build(); try (Response resp client.newCall(request).execute()) { System.out.println(resp.code() - (resp.body() null ? : resp.body().string())); }OkHttp 有一个隐藏优势它对 multipart 的格式做了完整封装你不用操心 CRLF 和 boundary出问题的概率低。但要注意writeTimeout——很多人只设了readTimeout结果传大文件时在写出阶段超时报的却是 timeout 这种含糊的错。上传场景里writeTimeout必须单独给足因为它管的是把字节推给对端的耗时和读响应完全两码事。3.4 Spring 环境RestTemplate 与 WebClient 的选择Spring 体系里最省代码的是RestTemplate配合MultiValueMap和FileSystemResource十行搞定。但有两个配置必须确认一是RestTemplate的messageConverters里必须有FormHttpMessageConverter默认有二是超时要在ClientHttpRequestFactory上设。Bean public RestTemplate uploadRestTemplate() { SimpleClientHttpRequestFactory factory new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(5000); factory.setReadTimeout(120000); factory.setBufferRequestBody(false); // 关键大文件不缓冲整个请求体 return new RestTemplate(factory); } public String upload(File file) { MultiValueMapString, Object form new LinkedMultiValueMap(); form.add(bizType, archive); form.add(fileName, 季度报表.pdf); form.add(file, new FileSystemResource(file)); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); HttpEntityMultiValueMapString, Object entity new HttpEntity(form, headers); ResponseEntityString resp uploadRestTemplate.postForEntity( https://example.invalid/api/upload, entity, String.class); return resp.getBody(); }setBufferRequestBody(false)是重点。默认情况下SimpleClientHttpRequestFactory会把整个请求体缓冲起来以计算Content-Length文件一大就吃内存。设成 false 之后改走 chunked内存立刻降下来。代价是某些不接受 chunked 的服务端会报错这时候要么改成 true 并接受内存开销要么换成HttpComponentsClientHttpRequestFactory走流式定长。如果是高并发场景WebClient更合适它是非阻塞的上传大文件时不会长期占用线程。MultipartBodyBuilder builder new MultipartBodyBuilder(); builder.part(bizType, archive); builder.part(fileName, 季度报表.pdf); builder.part(file, new FileSystemResource(file)) .contentType(MediaType.APPLICATION_OCTET_STREAM); webClient.post() .uri(https://example.invalid/api/upload) .contentType(MediaType.MULTIPART_FORM_DATA) .body(BodyInserters.fromMultipartData(builder.build())) .retrieve() .bodyToMono(String.class) .block(Duration.ofSeconds(120));3.5 服务端怎么接接收侧的三处对齐写完客户端一定要顺手把服务端写一遍这样才能定位是发错了还是收错了。以 Spring Boot 为例PostMapping(value /api/upload, consumes MediaType.MULTIPART_FORM_DATA_VALUE) public MapString, Object upload(RequestPart(bizType) String bizType, RequestPart(fileName) String fileName, RequestPart(file) MultipartFile file) throws IOException { if (file.isEmpty()) { throw new IllegalArgumentException(file is empty); } Path target Paths.get(/data/in, System.currentTimeMillis() _ fileName); try (InputStream in file.getInputStream()) { Files.copy(in, target, StandardCopyOption.REPLACE_EXISTING); } MapString, Object result new HashMap(); result.put(size, Files.size(target)); result.put(originName, file.getOriginalFilename()); return result; }三处对齐要检查consumes是否声明了 multipartRequestPart的 name 是否和客户端字段名一字不差multipart的大小限制是否放开spring.servlet.multipart.max-file-size和max-request-size默认只有 1MB 和 10MB。默认限制这一条坑过太多人客户端传 5MB 的文件服务端直接返回 413 或者一个奇怪的MaxUploadSizeExceededException看着像客户端的问题其实是服务端配置没改。4. 参数与配置的计算超时、分片、连接池4.1 超时到底该给多少按带宽算一个下限超时不能靠感觉给。我用的公式是读超时 ≈ 文件大小(MB) × 8 ÷ 上行带宽(Mbps) × 安全系数。举例20MB 的文件服务端上行按 10Mbps 保守估那就是20 × 8 ÷ 10 16 秒乘 3 倍安全系数约 48 秒再叠加服务端处理时间最终给 90~120 秒比较稳。反过来如果文件只有几十 KB那瓶颈在服务端业务处理上比如它要做 OCR、转码、入库这时候读超时给 30 秒以上才合理。我见过一个接口平时 200 毫秒返回某天突然频繁超时最后查出来是对方在同步做全文索引慢的时候要 20 秒。连接超时是另一回事它管的是 TCP 握手给 3~5 秒足够。给太长只会让网络不通的情况卡得更久给太短会在对方偶尔抖动时误判。4.2 大文件什么时候该上分片我的判断线是 50MB。低于它单请求走完简单可靠高于它就要考虑分片上传客户端按固定大小切块比如 5MB 一块每块单独发一个 multipart 请求带上chunkIndex、chunkTotal、fileMd5服务端按 md5 归集最后调一个合并接口。分片带来的好处不只是避开超时更重要的是可重试。单请求失败要整个重传分片失败只重传那一块在网络质量差的环境里差别巨大。代价是服务端要维护临时状态还要处理合并顺序、并发合并、临时文件清理。所以如果对方接口不支持分片别自己造分片协议——按单请求做把超时和重试配对就行。还有一个折中方案失败重试时判断是否幂等。如果服务端支持按fileMd5做去重重试就安全如果不支持盲目重试可能造成重复归档这比上传失败更麻烦。4.3 连接池与并发别让上传把整个服务拖死上传是 IO 密集型操作但连接是有限资源。用HttpClient时PoolingHttpClientConnectionManager的maxTotal和defaultMaxPerRoute要给对。我的经验值是内部服务调用maxPerRoute给 20~50maxTotal给 200如果上传目标只有一个域名那就主要看maxPerRoute。另一个必须做的是限流。上传动作容易把出口带宽吃满进而影响同机器上其他服务的调用。我一般会用信号量或者线程池隔离给它一个独立的池子比如固定 8 个线程专门做上传队列长度限制 100超了就直接拒绝并返回稍后重试。这个设计看起来降低了吞吐但避免了一个批量导入任务把整个应用拖垮的雪崩。还有一点经常被忽略上传完成后的InputStream和连接必须及时关闭。HttpClient里没关的响应体会导致连接无法归还池子跑一段时间就出现ConnectionPoolTimeoutException。这个错误信息很有迷惑性看着像池子太小其实是漏关连接。5. 线上排查实录状态码、乱码、截断、字段丢失5.1 状态码速查表状态码最常见原因优先检查400格式不合规、字段名不匹配、boundary 错抓包看 body 原文对比 name 和 boundary401 / 403鉴权头缺失、签名过期请求头、时间戳、token 有效期404路径写错、网关路由未配置完整 URL特别是 context-path413超过服务端大小限制max-file-size、网关的 body 上限415Content-Type 不带 boundary 或不被支持请求头是否手写覆盖了正确的值500服务端解析异常、磁盘满、编码异常服务端日志重点看解析器栈信息这张表我贴在工位上用了很久。核心思路是4xx 基本都是客户端能改的5xx 基本都要看服务端日志。但有一个例外415 有时是客户端手写请求头导致的——比如用了HttpClient之后又手动setHeader(Content-Type, multipart/form-data)把自动生成的 boundary 覆盖掉了。这个错误特别隐蔽因为请求头看起来完全正确只是少了 boundary。5.2 中文文件名乱码的三种成因与验证方法成因一写入了 UTF-8服务端按 ISO-8859-1 解析出现测试这类字符。验证方法是对着字节反推如果看到æ之类的组合就是典型的编码错位。成因二写入了 GBK服务端按 UTF-8 解析出现锟斤拷或者一堆问号。这类错误在老旧系统对接中常见。成因三客户端在拼接 filename 时做了 URL 编码服务端没解码落盘名里带%E4%B8%AD。验证的通用手段是打印服务端收到的getOriginalFilename()原始字节而不是直接打印字符串。因为打印字符串时又经过一次编码转换看到的可能已经是错上加错的结果。我一般会写Arrays.toString(name.getBytes(StandardCharsets.ISO_8859_1))看一眼原始字节判断就很准。5.3 文件能上传但打不开字节截断排查这类问题最让人抓狂接口返回 200文件也确实落盘了但打开报文件损坏。八成是字节数对不上。排查步骤我固定三步走第一对比客户端源文件和落盘文件的大小如果落盘文件小了几十个字节基本是少写了结尾的 CRLF 或者 boundary第二如果落盘文件比源文件大说明把段头也写进文件里了通常是少了一个空行导致解析器把段头当成了内容第三如果大小完全一致但打不开那就是文件本身的字节没问题问题在内容里被插入了额外字符——最常见的是在写文件时用了write(String)而不是write(byte[])导致二进制被按字符集转码字节全变了。第三条特别隐蔽因为文件长度看起来差不多UTF-8 下某些单字节被转成两字节长度会有微小差异。判断方法是算源文件和落盘文件的 MD5一致才算过。我在上传组件里固定加了一步上传成功后计算本地文件 MD5 和服务端返回的 MD5 比对不一致就告警。这一条让好几个偶发问题变成了可定位的明确报错。5.4 服务端收不到文件的三道关卡客户端明明传了服务端file是 null逐层排查。第一关是字段名。RequestPart(file)要求 name 必须是file大小写敏感。这一关最简单也最容易错。第二关是拦截器与包装。有些项目里加了全局的请求体包装器用于日志打印它会先getInputStream读一遍 body导致后面的MultipartResolver拿不到数据。表现是字段全空但请求头正常。排查方法是看拦截器里有没有对multipart/form-data做跳过处理。第三关是解析顺序。如果请求里混了 query 参数和 body 字段或者表单里有重复 name某些解析器只取第一个。这类问题建议在服务端加一行日志打印所有getParameterNames()和file.getOriginalFilename()一眼就能看出收到了什么。5.5 常被忽略的几个实操细节先说Expect: 100-continue。某些客户端库默认会带这个头先问服务端我可以发了吗服务端不回就直接等表现为请求卡住几十秒。遇到偶发卡顿且跟网络环境相关时试着把这个头关掉往往立刻好转。再说重试。上传不是天然幂等的盲目重试会制造重复数据。我的做法是只对连接阶段的失败重试连接超时、握手中断对已经写出数据的请求不重试如果业务允许用requestId做幂等键让服务端去重。最后是一个小技巧调试时把请求体的前 1KB 和最后 1KB 打出来用十六进制比任何日志都直观。段头格式对不对、boundary 有没有多空格、结尾有没有--一眼就能看出来。我在本地加了一个开关只在测试环境打印上线关掉避免大文件把日志撑爆。我自己在实际操作中的体会是这个需求的技术难度并不在代码本身而在格式约定和两侧实现差异的交叉点上。写代码之前先花十分钟把报文结构画出来把字段名、文件名编码、大小限制这三件事跟对接方确认清楚后面能省掉大半天排查。真正稳的上传组件往往不是写得最花哨的那个而是把 MD5 校验、超时分级、失败可重试这三件朴素的事做扎实的那个。