本地用命令行工具模拟上传一调就通，报文、参数、返回全部正常，结果同一份文件换成 Java 代码发出去，服务端直接回 400，日志里一句 "Required request part 'file' is not present" 让人对着屏幕发愣——这是我带过的项目里出现频率最高的一类联调事故。问题几乎从不在服务端，八成出在客户端拼装请求体时的那几个字节上：boundary 前后不一致、CRLF 少了一个、文件段的头部少了 Content-Type、Content-Length 没算对。multipart/form-data 这个格式看起来简单，本质是手工拼装一段带分隔符的字节流，规范宽松、容错极差，任何一个字符出错，服务端解析器就会静默丢弃整个 part，你在客户端看到的往往只是一个语焉不详的 400。
这篇内容就是围绕"Java 发送 POST 请求、以 multipart/form-data 格式把文件数据送到接口"这件事，从报文结构、选型取舍、手写实现、第三方库的隐藏开关，一直到我在联调现场真实排过的坑，完整走一遍。无论你用 JDK 原生 HttpURLConnection，还是用 HttpClient、OkHttp，或者在 Spring 体系里用 RestTemplate、WebClient，底层的字节流是同一套规则，把这些规则吃透，换任何库都不会翻车。适合已经写过上传代码但被服务端退回来的人，也适合准备从零实现一个文件上传客户端的人。
1. 把 multipart/form-data 的报文掰开看：它到底长什么样
1.1 一条能通过的请求体，字节级拆解
先说清楚这个格式是什么。multipart/form-data 是 HTTP 表单提交用于携带二进制内容的一种编码方式，它把整个请求体切成若干"段"（part），每段用一行分隔符隔开，段内先写头部描述这段叫什么名字、是文本还是文件、文件名是什么，空一行后紧跟真正的数据。分隔符由 boundary 参数决定，客户端随机生成，通过请求头的Content-Type: multipart/form-data; boundary=xxx告诉服务端。
一条带一个文本字段和一个文件字段的请求体，展开后大致是这样（\r\n是我标出来的换行，实际报文里就是两个字节 0x0D 0x0A）：
--X9k2LmBoundary\r\n Content-Disposition: form-data; name="bizType"\r\n \r\n invoice\r\n --X9k2LmBoundary\r\n Content-Disposition: form-data; name="file"; filename="report.pdf"\r\n Content-Type: application/pdf\r\n \r\n <这里是文件的原始二进制字节>\r\n --X9k2LmBoundary--\r\n这里有三个细节必须记住，它们决定了你的请求能不能被解析：
第一，分隔行是两个减号加 boundary，中间不能有空格；第二，最后一段结束后是两个减号加 boundary 再加两个减号，表示结束，后面还要跟一个 CRLF；第三，每一行的行尾必须是 CRLF，不能只写\n。很多解析器（尤其是严格的实现）遇到只有 LF 的行会直接把这一段当成畸形数据丢掉，而你从 Java 侧看到的只是"服务端说没收到文件"。
至于文件段的Content-Type，它不是必需的（RFC 允许省略，服务端会当作 application/octet-stream 处理），但强烈建议写上。原因很实际：某些服务端框架会拿它去做类型校验，缺了会被判成不支持的类型；另一些会给文件打上错误的 MIME，落库后前端下载时浏览器行为异常。
1.2 boundary 的三条红线：一致、不冲突、不加引号
boundary 是整个格式的"锚点"，服务端解析器的工作方式就是全文扫描这个字符串，扫到就切一刀。围绕它有三条红线，我在实际项目里三条都踩过。
红线一：请求头里的 boundary 必须和请求体里用的完全一致。包括长度、大小写、中间的连字符数量。我见过最隐蔽的一次事故，是有人在请求头里写了boundary=----WebKitFormBoundaryABC，请求体里却用了--加--WebKitFormBoundaryABC（多复制了两个减号），肉眼完全看不出差异，抓包对比才定位到。
红线二：boundary 不能出现在文件内容里。理论上要求客户端选一个不与数据冲突的字符串，实践中靠随机性保证。这就是为什么几乎所有库都把 boundary 生成成"时间戳 + 随机数 + 固定前缀"的形式。如果你手写实现时图省事写死一个----boundary，然后上传的文件恰好是个文本文件、里面又有这串字符，解析就会从中间断掉，服务端拿到的文件是残缺的。这种问题只在特定文件上复现，排查成本极高。
红线三：boundary 值不要加双引号。RFC 允许boundary="xxx"这种带引号的写法，但相当一部分服务端解析器不认，会连着引号一起当成分隔符去匹配，结果一段都匹配不上。稳妥做法是生成一个只含字母、数字和连字符的 boundary，直接裸写。
生成逻辑我一般这么写：
private static String newBoundary() { return "----JavaFormBoundary" + Long.toHexString(System.nanoTime()) + Long.toHexString(Thread.currentThread().getId()); }nanoTime保证同一毫秒内多次调用也不重复，线程 ID 进一步降低并发下的碰撞概率。
1.3 文本字段和文件字段，差别其实只有一行头
很多人以为文本字段和文件字段是两种处理方式，实际上在报文层面，它们的区别只有Content-Disposition里有没有filename参数，以及要不要额外的Content-Type。文本字段的写法是Content-Disposition: form-data; name="bizType"，文件字段多了; filename="report.pdf"。
这带来两个容易掉进去的坑。一个是文本字段的值不要自己做 URL 编码。有些人习惯了 application/x-www-form-urlencoded，顺手把中文参数 encode 一遍，结果服务端收到的就是一堆%E4%B8%AD。multipart 里文本字段就是原样字节，编码由Content-Type头部的 charset 或者双方约定决定，不需要额外转义。另一个是文本字段的值为空时，也要保留那个空行，即头部后面必须有两个连续的 CRLF，然后是零字节内容，再是 CRLF。少了这个空行，解析器会把下一段的头部当成这一段的内容吃掉，后续全部错位。
还有一点值得单独说：如果文本字段的值里含有换行，不需要做任何处理，解析器是靠 boundary 定位段边界的，不靠换行。这也是 multipart 比 URL 编码更适合传长文本的原因。
2. 选型：JDK 原生、第三方客户端、框架封装，各自适合谁
2.1 HttpURLConnection：零依赖，但所有细节都得自己扛
JDK 自带的 HttpURLConnection 最大的优势是不引入任何第三方依赖，在一些依赖管控严格、jar 包体积敏感的场景里是唯一选择。它的缺点也很明确：没有现成的 multipart 支持，请求体要自己往输出流里写，boundary 自己生成，长度自己算。
用它的正确姿势是setDoOutput(true)之后拿到getOutputStream()，把整个请求体当成字节流一段段写进去。这里有一个几乎所有人第一次都会忽略的开关：HttpURLConnection 默认会把整个请求体缓存在内存里，因为它要先算出 Content-Length 才能发。你上传一个 200MB 的文件，堆里就真的会多出一个 200MB 的字节数组，GC 压力直接爆表。
解决办法是二选一：文件大小已知就调setFixedLengthStreamingMode(long)，大小未知就调setChunkedStreamingMode(8192)走分块传输。注意走 chunked 之后请求头里不会再有 Content-Length，如果服务端或者中间的网关对 chunked 支持不好，可能出现上传卡住或者被拒的情况，这时候只能老老实实先算长度。所以我的建议是：文件来自本地磁盘（能拿到 length）就用固定长度模式，来自网络流（长度未知）才用 chunked，并且上线前确认链路上的网关支持。
2.2 第三方 HTTP 客户端：API 友好，但要盯紧实体构建器的默认行为
主流第三方客户端的共同点是提供了MultipartEntityBuilder/MultipartBody.Builder这类构建器，你只需要 add 文本、add 文件，剩下的分隔符、长度计算它全包了。代码量能压缩到十行以内，可读性也好。
但要警惕构建器的"聪明"。比如某些版本的实体构建器默认使用HttpMultipartMode.STRICT，某些默认用BROWSER_COMPATIBLE，两种模式在换行符的处理上不一样——BROWSER_COMPATIBLE 会把行尾写成 CRLF，STRICT 在某些实现里写 LF。如果你的服务端解析器对 LF 敏感，换个库版本就可能从通变成不通。稳妥做法是显式指定模式和字符集，不要依赖默认值。
另一个需要盯的是字符集。构建器通常允许设置setCharset(StandardCharsets.UTF_8)，这个设置影响的是头部字段（尤其是 filename）的编码，不影响文件内容本身。不设置的话可能落到平台默认编码，在容器里跑出来的结果和你本地 IDEA 里跑出来的不一样——这类"本地好好的、上线就乱码"的事故，一半以上源于此。
2.3 Spring 体系：写起来最短，但资源包装类有个必踩的坑
在 Spring 环境里，用 RestTemplate 发 multipart 请求只需要构造一个MultiValueMap，把文件作为Resource塞进去，再设Content-Type为multipart/form-data，框架会自动选中FormHttpMessageConverter完成序列化。
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>(); body.add("bizType", "invoice"); body.add("file", new FileSystemResource(file)); HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); HttpEntity<MultiValueMap<String, Object>> entity = new HttpEntity<>(body, headers); ResponseEntity<String> resp = restTemplate.postForEntity(url, entity, String.class);看着很干净，坑在Resource的选型上。用FileSystemResource没问题，它的getFilename()返回真实文件名。但如果你的文件在内存里（比如刚解密出来的字节数组），用了ByteArrayResource，getFilename()默认返回 null，序列化出来的 part 就没有filename参数，服务端按"文件"去取就会取不到，直接 400。正确做法是匿名子类重写getFilename()：
body.add("file", new ByteArrayResource(bytes) { @Override public String getFilename() { return "report.pdf"; } });这个坑我至少见过五次，每次都是同一句报错，每次都要重新查一遍。如果你用 WebClient，MultipartBodyBuilder的逻辑类似，part("file", resource)同样依赖 Resource 的 filename。
| 方案 | 依赖成本 | 上手速度 | 大文件友好度 | 适合场景 |
|---|---|---|---|---|
| HttpURLConnection | 零 | 慢，需手写报文 | 需手动开启流式模式，否则占内存 | 依赖受限、上传逻辑需极致可控 |
| 第三方 HttpClient | 一个 jar | 快 | 构建器内部通常已流式 | 通用业务系统、需要连接池与重试 |
| RestTemplate | 框架自带 | 最快 | 取决于 Resource 实现 | 已有 Spring 工程、内部服务互调 |
| WebClient | 框架自带 | 快 | 支持流式，需注意背压 | 响应式栈、高并发上传 |
3. 从零手写一份能跑通的 JDK 原生 multipart 请求
3.1 组装请求体的核心：先写头，再写文件字节，最后封口
手写实现的价值不只是"不用依赖"，更在于写完之后你对这个格式的理解会彻底通透，后面用任何库出问题，你都知道去哪一层找。整个流程分成四步：生成 boundary、设置请求头、逐段写入请求体、写入结束标记。
先看整体骨架：
public static String upload(String url, File file, String bizType) throws IOException { String boundary = newBoundary(); HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection(); conn.setRequestMethod("POST"); conn.setDoOutput(true); conn.setDoInput(true); conn.setConnectTimeout(5000); conn.setReadTimeout(60000); conn.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary); conn.setFixedLengthStreamingMode(calcLength(boundary, file, bizType)); try (OutputStream out = conn.getOutputStream()) { writeTextPart(out, boundary, "bizType", bizType); writeFilePart(out, boundary, "file", file); out.write(("--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8)); } int code = conn.getResponseCode(); InputStream in = code >= 200 && code < 300 ? conn.getInputStream() : conn.getErrorStream(); return readAll(in); }注意setFixedLengthStreamingMode必须在getOutputStream()之前调用，否则抛异常。而这个长度必须是完整请求体的字节数，包括所有分隔符、头部、CRLF 和文件内容，少算一个字节服务端就会读不满，连接挂在那里等到超时。
3.2 文本段与文件段的写入方法
文本段的写入最直接，拼字符串转字节即可：
private static void writeTextPart(OutputStream out, String boundary, String name, String value) throws IOException { String head = "--" + boundary + "\r\n" + "Content-Disposition: form-data; name=\"" + name + "\"\r\n" + "Content-Type: text/plain; charset=UTF-8\r\n" + "\r\n"; out.write(head.getBytes(StandardCharsets.UTF_8)); out.write(value.getBytes(StandardCharsets.UTF_8)); out.write("\r\n".getBytes(StandardCharsets.UTF_8)); }文件段稍微复杂一点，因为要在头部声明类型、写完之后不能忘了那个 CRLF：
private static void writeFilePart(OutputStream out, String boundary, String name, File file) throws IOException { String head = "--" + boundary + "\r\n" + "Content-Disposition: form-data; name=\"" + name + "\"; filename=\"" + file.getName() + "\"\r\n" + "Content-Type: " + guessContentType(file) + "\r\n" + "\r\n"; out.write(head.getBytes(StandardCharsets.UTF_8)); try (InputStream in = new FileInputStream(file)) { byte[] buf = new byte[8192]; int n; while ((n = in.read(buf)) != -1) { out.write(buf, 0, n); } } out.write("\r\n".getBytes(StandardCharsets.UTF_8)); }文件内容用 8KB 缓冲区边读边写，全程堆里只有一个 8KB 数组，和文件大小无关。这就是流式的意义。反例是把Files.readAllBytes(path)直接塞进输出流，代码只有两行，看起来更优雅，但一次 500MB 的上传就能把服务拖垮。我在一个批处理任务里见过这个写法，跑单条数据没问题，跑批量的时候频繁 Full GC，最后定位到这几行。
guessContentType可以不实现，默认返回application/octet-stream，多数服务端能接受。要实现的话用URLConnection.guessContentTypeFromName(fileName)，内置一张小映射表，覆盖常见的 pdf、png、zip 等，够用且不引依赖。
3.3 长度计算：漏算最容易出在结束符上
手写模式下必须自己算长度，公式是把三部分加起来：所有段的头部字符串字节数、所有数据字节数、所有段之间的 CRLF 与结束标记字节数。
private static long calcLength(String boundary, File file, String bizType) { long len = 0; String textHead = "--" + boundary + "\r\n" + "Content-Disposition: form-data; name=\"bizType\"\r\n" + "Content-Type: text/plain; charset=UTF-8\r\n\r\n"; len += textHead.getBytes(StandardCharsets.UTF_8).length; len += bizType.getBytes(StandardCharsets.UTF_8).length; len += 2; // 文本段后的 CRLF String fileHead = "--" + boundary + "\r\n" + "Content-Disposition: form-data; name=\"file\"; filename=\"" + file.getName() + "\"\r\n" + "Content-Type: application/octet-stream\r\n\r\n"; len += fileHead.getBytes(StandardCharsets.UTF_8).length; len += file.length(); len += 2; // 文件段后的 CRLF len += ("--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8).length; return len; }这段代码麻烦且容易和写入逻辑不同步——改了写入格式忘了改长度计算，就会出现"内容多发一个字节，服务端截断"或者"少发一个字节，连接卡住"。所以我在手写实现里更推荐另一种思路：如果服务端和网关都支持 chunked，直接用setChunkedStreamingMode(8192)，跳过长度计算。只有在必须提供 Content-Length 的场景下才老老实实维护这个公式，并且把它和写入方法写在同一个类里、加注释说明两边必须同步改。
3.4 响应处理：错误流才是信息宝库
getResponseCode()返回 4xx/5xx 时，getInputStream()会抛FileNotFoundException或者IOException，真正的错误信息在getErrorStream()里。很多人只写了成功分支，结果服务端返回的 400 包体（通常带着具体的字段校验失败原因）被完全丢掉，日志里只有一行状态码，排查全靠猜。
int code = conn.getResponseCode(); InputStream in = (code >= 200 && code < 300) ? conn.getInputStream() : conn.getErrorStream(); String body = in == null ? "" : new String(readAllBytes(in), StandardCharsets.UTF_8); if (code < 200 || code >= 300) { throw new IllegalStateException("upload failed, code=" + code + ", body=" + body); }这几行代码在联调阶段能省下大量时间。我自己排过一次服务端 400，就是因为没打错误流，绕了一大圈去抓包，最后加上这行日志，报错信息"Missing part 'file'"直接摆在眼前。
4. 第三方库写法与几个必须显式打开的开关
4.1 实体构建器：模式、字符集、类型三件事要说清楚
用第三方 HttpClient 的MultipartEntityBuilder，核心就四行：
HttpEntity entity = MultipartEntityBuilder.create() .setMode(HttpMultipartMode.BROWSER_COMPATIBLE) .setCharset(StandardCharsets.UTF_8) .addTextBody("bizType", "invoice", ContentType.TEXT_PLAIN.withCharset(StandardCharsets.UTF_8)) .addBinaryBody("file", file, ContentType.APPLICATION_OCTET_STREAM, file.getName()) .build();三点建议。第一，setMode显式指定，别让版本决定行为，BROWSER_COMPATIBLE 生成的报文和浏览器表单提交一致，兼容性最好。第二，setCharset显式指定 UTF-8，它管的是头部文本的编码，不是文件内容。第三，addBinaryBody的第三个参数传 MIME 类型，第四个参数传文件名，这两个都传了才不会踩到"服务端收不到 file"或者"文件名为 null"。
还有一件事很多人不知道：addBinaryBody有多个重载，其中接受File的那个是流式的，接受byte[]的会整块进内存。上传大文件时务必用 File 或 InputStream 的重载。
4.2 OkHttp：MultipartBody 的粒度控制与文件名编码
OkHttp 的写法更简洁：
RequestBody fileBody = RequestBody.create(file, MediaType.parse("application/octet-stream")); MultipartBody body = new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart("bizType", "invoice") .addFormDataPart("file", file.getName(), fileBody) .build();addFormDataPart的三参数版本（name、filename、body）是把 filename 单独拿出来的，这个设计很实用：你可以让磁盘上的文件名和传给服务端的文件名不一致，比如磁盘上是随机 UUID 存的临时文件，但对外要传用户原始文件名。这一招在做"文件暂存 + 异步上传"的架构时非常方便。
它在写入时默认就是流式的，大文件不会整块进内存。要注意的是连接池和超时，OkHttp 的默认读超时是 10 秒，上传大文件必然超时，必须自己调：
OkHttpClient client = new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .writeTimeout(5, TimeUnit.MINUTES) .readTimeout(5, TimeUnit.MINUTES) .build();写超时（writeTimeout）尤其容易被忽略。它管的是"两次写操作之间的最大间隔"，文件传输慢的时候，连接没断，但写不动，写超时就会触发中断。上传几十兆以上的文件，把 writeTimeout 设成分钟级是必须的。
4.3 超时、重试与幂等：上传接口不是所有都能重试
超时设置有个反直觉的点：读超时不是总耗时上限，它只管"等待下一个字节"的时间。所以上传一个 1GB 的文件，即使读了十分钟，只要中间数据一直在流动，读超时就不会触发。真正需要关注总耗时的地方，得自己在业务层加计时和熔断。
重试更危险。上传接口天然不幂等，第一次请求其实已经到服务端并落库了，只是响应在返回路上超时，你重试一次就打进去两条记录。所以我的原则是：HTTP 客户端层面不配置自动重试，重试逻辑放到业务层，配合服务端的幂等键（比如客户端生成的 requestId）一起用。服务端收到相同 requestId 的重复请求直接返回上次结果，这样重试才安全。如果服务端没做幂等，宁可不重试，让用户手动再点一次。
5. 六个真实现场踩过的坑，以及我的排查链路
5.1 415 与 400 之争：boundary 到底丢没丢
服务端返回 415（不支持的媒体类型）或 400，第一件事不是改代码，是打印出你实际发出去的Content-Type头。我见过三种情况：一是手动setRequestProperty("Content-Type", "multipart/form-data")但忘了拼 boundary，有些框架会自动补上，有些不补，不补的就是 415；二是在 RestTemplate 里既设了MediaType.MULTIPART_FORM_DATA，又手动往 headers 里加了一个 Content-Type，两个值互相覆盖，最后生效的那个没有 boundary；三是经过了一层网关，网关把 Content-Type 重写成了application/json（因为它在做内容路由），请求体还是 multipart 格式，服务端解析器直接懵。
排查链路我固定这么走：先在客户端把最终请求头打全，日志里同时打出 boundary 的值；再用同一个 boundary 去和服务端解析时的日志比对。多数框架在解析失败时会打 "the request was rejected because no multipart boundary was found" 这类日志，一看就知道。
5.2 文件收到了，文件名却是乱码或者 "null"
这个问题的根因有两层。表层是 filename 的编码：Content-Disposition: form-data; name="file"; filename="测试文档.pdf"，这串中文按 UTF-8 编成字节发出去，服务端如果按 ISO-8859-1 解码，就会变成一堆测试。深层原因是这个参数在规范里没有规定编码方式，各家实现自己决定。
我的处理顺序是：第一步，先确认客户端确实按 UTF-8 写了头部（构建器设了 charset）；第二步，看服务端有没有提供文件名编码的配置项，很多框架有这个开关，改成 UTF-8 后立刻正常；第三步，如果服务端改不了，客户端就别传中文文件名了，改成"时间戳 + 扩展名"这种纯 ASCII 名字，把原始文件名作为另一个独立的文本字段传过去，服务端用这个字段落库。第三种方案最土，但在跨团队、改不动对方的场景下成功率最高，我用过不止一次。
至于文件名为 null，基本可以断定是ByteArrayResource没重写getFilename()，或者手写实现时忘了在Content-Disposition里拼 filename 参数。
5.3 文件内容末尾多了几个字节，或者被截断
上传的 PDF 打开提示损坏，或者图片底部出现灰色条，通常是多写或少写了 CRLF。multipart 里每个 part 的数据后面必须跟一个 CRLF，这个 CRLF 不算文件内容，但解析器要靠它定位下一段的起始。如果你在写文件字节之后没补 CRLF，解析器会把下一行的--boundary当作文件结尾的一部分吞掉或者截断；如果补了两个，文件末尾就多出两个字节。
还有一种更隐蔽的：用 PrintWriter 写头部。PrintWriter 在某些平台上会把\n转成平台换行符，Windows 上变成 CRLF，Linux 上还是 LF，跨平台测试结果不一致。所有涉及 multipart 头部的写入，一律用OutputStream加显式的"\r\n"字符串，不要用任何会做换行转换的 Writer。
5.4 大文件上传 OOM：问题往往不在文件本身
前面提过 HttpURLConnection 默认缓存请求体，这是最常见的 OOM 来源。除此之外还有两个：一是用MultipartEntityBuilder.addBinaryBody(name, byte[])，整个文件进堆；二是自己先Files.readAllBytes再包装成ByteArrayResource，同样整块进内存。
排查方法很直接：上传一个 100MB 的文件，在 JVM 上加-Xmx256m跑，如果 OOM 了就是没走流式。修复方式按库不同分别处理：HttpURLConnection 开流式模式；HttpClient 换成接受 File/InputStream 的 addBinaryBody 重载；Spring 换成 FileSystemResource 或 InputStreamResource（注意 InputStreamResource 的contentLength()返回 -1，某些场景会导致走 chunked）。
还有一个和内存无关但很常见的问题：上传大文件时网关的请求体大小限制。服务端日志什么都看不到，请求根本没到应用层，全被网关拦了，返回一个 413。这个必须在联调初期就和运维确认清楚限额。
5.5 中文参数乱码：编码声明要写在段头上
文本字段传中文，服务端收到乱码，原因通常是段头缺少 charset 声明。虽然规范上默认是 US-ASCII，但实际各方都按 UTF-8 处理，前提是你在段的Content-Type里写清楚charset=UTF-8，或者整个请求的编码被服务端统一按 UTF-8 配置。
.addTextBody("remark", "测试备注", ContentType.TEXT_PLAIN.withCharset(StandardCharsets.UTF_8))这行里的withCharset就是给这一段的头部加上charset=UTF-8。如果不加，某些服务端会按默认字符集解码，中文直接变问号。另外注意不要在发送前自己做 URL 编码，multipart 里不需要。
5.6 请求体被读了两遍，第二次是空的
这个坑出在拦截器和重试机制上。有些框架的日志拦截器会把请求体读出来打印，读完没重置流的位置，真正发送时流已经在末尾，服务端收到的是空文件。表现是：日志里明明有内容，服务端说文件是 0 字节。
判断方法：把日志拦截器关掉再测一次，如果正常了，就是这个问题。修复方式是用支持重复读的请求体包装（把内容缓存成字节数组，或者支持 reset 的流），但缓存成字节数组又会回到内存问题，所以更好的做法是——日志拦截器只打印请求头，不打印请求体，或者只打印前 N 个字节的摘要。
6. 想让它更稳：几个我在生产环境补上的细节
6.1 服务端字段名对不上，是最冤的一种失败
Content-Disposition: form-data; name="file"里的这个 name，必须和服务端@RequestParam("file")或者MultipartFile参数名完全一致，大小写敏感。我遇到过前端传fileName、服务端收file的情况，两边各自测都正常，联调就 400。约定阶段就把字段名、是否必填、单文件还是多文件（多文件的话 name 要重复出现多次，不是用逗号分隔）写进接口文档，能省掉一轮往返。
多文件上传的报文形态值得单独提一句：同一个 name 出现多次，每次带一个 filename，服务端收到的是数组。有些人在客户端把多个文件打包成 zip 传，那是另一个字段名，语义完全不同。
6.2 用一份最小可复现的 curl 作为黄金参照
联调阶段我习惯先让对方给我一条能通的 curl 命令：
curl -v -F "bizType=invoice" -F "file=@/tmp/report.pdf;type=application/pdf" \ http://host/api/upload-v会把请求头打出来，-F会自动构造 multipart 报文。拿到它之后，做两件事：一是用--trace-ascii把完整请求体 dump 出来，作为字节级对照；二是用 Java 代码发一次，把两边报文逐行比对。差异通常在 boundary 数量、CRLF、头部顺序、有没有 Content-Length 这几个地方。这个方法比读服务端源码快得多，我在跨团队联调里基本都靠它破局。
6.3 上传进度和断点：别等到用户投诉才想起来
multipart 上传本身没有进度回调，要自己做就得在写输出流的时候计数。手写实现里加个CountingOutputStream包装一下，每写一批就更新已发送字节数，配合文件总大小算出百分比。第三方库大多提供了请求体包装的扩展点，思路一样。
断点续传是另一个量级的事情，multipart 格式本身不支持分片续传，得靠额外的协议设计：客户端按固定大小切片，每片单独上报序号，服务端合并校验。如果业务里确实有大文件场景（几百兆以上），建议一开始就规划分片上传 + 秒传（先按文件哈希查重），而不是等用户上传失败几次之后再补。
6.4 别忽略连接复用对上传性能的影响
每次上传都新建连接，在文件小、频率高的场景下，TCP 握手和 TLS 握手的开销会占掉相当比例的时间。用连接池的客户端（第三方 HttpClient、OkHttp）默认就复用了，但要注意池大小和空闲回收时间。我见过一个批量上传任务，因为连接池最大连接数设成 1，20 个线程排队抢一个连接，整体耗时是预期值的十几倍，日志里看起来每条请求都正常，就是慢，最后调大池子才解决。
还有一个细节：上传完成后一定要关掉响应体和输入流。连接池要靠这个动作把连接还回去，不关的话连接泄漏，跑一段时间就开始报"连接超时"，而这个报错和上传逻辑毫无关系，排查方向很容易跑偏。
6.5 关于临时文件的取舍
大文件上传时，如果需要在发送前做校验（比如算哈希、检查文件头），那就绕不开"先落地再上传"。我的做法是用一个带 TTL 的临时目录，落地时用 UUID 命名，上传成功或失败都在 finally 里删掉。不要在内存里做中转，也不要把临时文件放在系统默认临时目录里（容器环境下那个目录可能挂的是 tmpfs，占内存），显式指定一个有足够空间、有清理策略的路径，能避开很多莫名其妙的磁盘告警。
真正让我改掉"图省事"习惯的是一次线上事故：上传的文件在服务端永远是 0 字节，查了两小时，最后发现是某个中间环节提前把临时文件删了，上传线程读到的是一个已经被删除的文件句柄。从那以后，我所有涉及文件的操作都遵守一条：谁创建谁负责删，删除动作放在最外层，且必须在所有读写完成之后。
这个东西写到这里，基本上从报文原理到落地细节都覆盖到了。如果你现在正卡在某个 400 上，我的建议是先别改代码，把实际发出去的原始字节 dump 出来，和你手上那份能通的 curl 报文摆在一起逐行看，差异会自己跳出来。
