Java超大文件分片上传实战：解决OOM与连接超时

在 Java 后端开发里，“JAVA http 请求”本身不算难事，难点是当请求体变成几个 GB 的超大附件时，问题会全部冒出来。我之前负责一个数据文件交换平台，用户经常上传 3GB、6GB 的现场采集包，最初同事按普通 Multipart 方式直传，线上压测直接 OOM，后来改成流式分片上传才稳定下来。这篇文章从方案选型、参数设计到代码实现完整走一遍，适合正在写文件上传、被大文件内存和超时问题折磨的 Java 开发者参考。

1. 一次性请求为什么扛不住超大附件

1.1 文件全量进内存是 OOM 的头号原因

普通小文件上传，几 MB、几十 MB，一次性读进内存再塞给 HTTP 请求，通常没有感知。但文件到 GB 级以后，内存问题立刻变得尖锐。假设用一个byte[]去装 4GB 文件，JVM 堆默认开 2GB，一次请求就把堆打满，GC 频繁不说，严重时直接OutOfMemoryError。就算堆开 8GB，也只是把问题往后推，因为多用户并发上传时，每个请求都瓜分一块大内存，最终还是会被打挂。

这里有个很容易被忽略的点：不只是业务代码里的byte[]会占用内存，HTTP 客户端库、服务端框架在解析请求体时也可能做缓冲。有的 Multipart 框架会先把文件落地到临时目录，这还算良心；有的会把部分内容放在内存里，分片多、文件大时照样出问题。所以超大附件第一原则就是：不要试图让一个 HTTP 请求承载整个文件的内存模型。

网络层同样不稳。一个 6GB 文件走公网传输，即便带宽有 50Mbps，也需要十几分钟甚至更久。中途一旦断网、服务端重启、代理超时，整个请求就废了。客户端往往只能收到SocketException: Connection reset或Read timed out，文件又要从头传一遍。这种体验放到生产环境，用户会直接炸掉。

1.2 流式、分片、断点续传到底选哪个

既然不能一次性上传，常见的替代方案有三个：流式上传、分片上传、断点续传。很多刚接触的人容易把三者混为一谈，其实它们是不同层面的东西。

流式上传解决的是“不一次性读进内存”的问题。文件从磁盘读出后，通过流直接写入 HTTP 请求体，而不在堆里铺开。Java 11 的HttpClient有BodyPublishers.ofInputStream()，HttpURLConnection 也有setFixedLengthStreamingMode()，都能做到流式。但流式上传如果只开一个请求，网络中断就得全量重来。

分片上传解决的是“单请求不可控”的问题。把文件切成固定大小的小块，一块一个 HTTP 请求，单块失败只重传这一块。分片上传天然支持并发，也能配合进度展示。

断点续传解决的是“重传成本高”的问题。在分片基础上记录哪些分片已经上传成功，程序重启或网络恢复后，只传剩余分片，不用从头开始。三者其实可以叠加：分片 + 流式 + 已传分片记录，这才是超大附件上传最稳的形态。

2. 上手前先设计好分片参数和接口约定

2.1 选 JDK 自带的 HttpClient 还是开源客户端库

这个示例我直接用 JDK 11+ 自带的java.net.http.HttpClient，零额外依赖，代码放在任何普通 Java 项目里都能跑。如果你还在用 Java 8，思路同样适用，把发送部分换成 HttpURLConnection 的setFixedLengthStreamingMode就行。

为什么不用 HttpClient 之类的第三方库？不是不好，而是对于超大附件上传来说，核心逻辑在“分片、重试、状态记录”，不在 HTTP 客户端本身。JDK 自带的客户端足够稳定，也支持异步和自定义 BodyPublisher。少一个依赖，生产环境就少一个版本冲突和漏洞排查点。我用这个方案在项目里跑过 6GB 文件，实测很稳。

顺带提一句，HttpClient实例是线程安全的，整个进程里创建一个全局复用即可，不要每个分片都 new 一个客户端。频繁创建会耗尽连接资源，还会让 TLS 握手成为性能瓶颈。

2.2 分片大小、超时和重试次数定多少合适

这个没有官方标准，但可以根据带宽、内存和单请求耗时来定。我常用的是 8MB 或 16MB。8MB 分片在公网弱网环境下重试成本低，16MB 分片在带宽充足的内网环境可以减少请求次数。

简单算一下：一个 6GB 文件，按 8MB 分片，分片数是6 * 1024 / 8 = 768。如果按 2MB 分片，分片数会到 3072，HTTP 请求本身的开销会占很大比例，服务端要处理 3000 多个请求，日志和索引压力都大。如果按 128MB 分片，分片数少了，但单块传输时间变长，一旦网络抖动，重试代价就很高。所以 8MB 到 16MB 是多数场景下的甜点区间。

超时时间要区分连接超时和请求超时。连接超时一般设 10 秒即可，连不上的话再等也没意义。请求超时是“从发出请求到收到响应”的整个时间，强烈建议给足。8MB 分片在很差的网络下也可能会传好几分钟，我一般设 30 分钟。重试次数 3 次左右，间隔用递增退避，比如 1 秒、2 秒、4 秒。重试太频繁会把服务端打爆，不重试又会因为一次瞬断导致整个任务失败。

2.3 用请求头传递分片信息，别在 URL 里传超长参数

分片上传要让服务端知道“这是哪一块、总共几块、偏移量多少”。很多新手习惯把这些参数拼在 URL 里：

PUT /api/upload?chunkIndex=0&totalChunks=768&offset=0

URL 短还好，一旦参数多、文件名长，很容易碰上网关、代理对 URL 长度的限制，而且日志会把敏感文件名烤出来。更干净的做法是用自定义请求头传递分片元数据，请求体只放原始二进制分片。

服务端如果点击“合并”动作，约定一个独立接口，根据文件名和 chunk count 去合并分片。客户端不需要在每次上传时重复传文件名，可以在创建上传任务时用另一个接口注册文件元信息，拿到一个任务 ID，后续请求头里只带任务 ID。这样更利于扩展断点续传和分片管理。

3. JAVA http 分片上传核心代码

3.1 分片上传的主循环怎么组织

直接看代码。这里我定义一个ChunkUploader，核心方法是upload(Path filePath, String uploadUrl, Set<Integer> uploadedChunks)。uploadedChunks是已经上传成功的分片编号集合，用于断点续传。

import java.io.IOException; import java.io.RandomAccessFile; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; import java.time.Duration; import java.util.Set; public class ChunkUploader { private static final long CHUNK_SIZE = 8 * 1024 * 1024; // 8MB private static final int MAX_RETRY = 3; private final HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); public void upload(Path filePath, String uploadUrl, Set<Integer> uploadedChunks) throws Exception { long fileSize = Files.size(filePath); long totalChunks = (fileSize + CHUNK_SIZE - 1) / CHUNK_SIZE; System.out.println("fileSize=" + fileSize + ", totalChunks=" + totalChunks); try (RandomAccessFile raf = new RandomAccessFile(filePath.toFile(), "r")) { byte[] buffer = new byte[(int) CHUNK_SIZE]; for (int index = 0; index < totalChunks; index++) { if (uploadedChunks.contains(index)) { System.out.println("skip already uploaded chunk: " + index); continue; } long offset = index * CHUNK_SIZE; int len = (int) Math.min(CHUNK_SIZE, fileSize - offset); raf.seek(offset); raf.readFully(buffer, 0, len); boolean success = sendChunk(uploadUrl, index, totalChunks, offset, buffer, len); if (!success) { throw new IOException("chunk upload failed, index=" + index); } uploadedChunks.add(index); double percent = (index + 1) * 100.0 / totalChunks; System.out.printf("uploaded %d/%d, progress %.2f%%%n", index + 1, totalChunks, percent); } } } }

这里有三个细节值得注意。

第一，RandomAccessFile只打开一次，通过seek定位分片位置，避免每个分片都重新打开文件。大文件频繁打开关闭文件句柄，性能损耗很大。

第二，readFully一定会在当前分片长度len内填满 buffer。最后一个分片长度可能不足 8MB，所以BodyPublishers.ofByteArray只发送[0, len)部分，不会把后面残留数据发出去。

第三，uploadedChunks.add(index)是放在 HTTP 响应成功之后。如果失败，不会加入集合，下次重试还会继续传这一块。这个集合本身是内存里的，生产环境应该落到数据库或本地状态文件中。

3.2 单个分片如何通过 JAVA http 请求发送

sendChunk是真正的 HTTP 发送逻辑。使用HttpRequest.Builder构造 PUT 请求，请求体是分片字节数组。

private boolean sendChunk(String uploadUrl, int index, long totalChunks, long offset, byte[] buffer, int len) throws InterruptedException { for (int attempt = 1; attempt <= MAX_RETRY; attempt++) { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(uploadUrl)) .timeout(Duration.ofMinutes(30)) .header("Content-Type", "application/octet-stream") .header("X-Chunk-Index", String.valueOf(index)) .header("X-Chunk-Count", String.valueOf(totalChunks)) .header("X-Chunk-Offset", String.valueOf(offset)) .PUT(HttpRequest.BodyPublishers.ofByteArray(buffer, 0, len)) .build(); try { HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); int status = response.statusCode(); if (status >= 200 && status < 300) { return true; } // 4xx 一般是参数或权限问题，重试意义不大；5xx 和网络异常值得重试 if (status >= 400 && status < 500) { return false; } } catch (IOException e) { System.err.println("chunk " + index + " network error: " + e.getMessage()); } Thread.sleep(attempt * 1000L); } return false; }

这里特意区分了 4xx 和 5xx。4xx 代表请求本身有问题，比如服务端不认识X-Chunk-Index头、文件任务未注册、权限不足，重试一百次也一样。5xx 和 IOException 才是网络抖动、服务端暂时不可用，值得退避重试。

如果服务端用 Spring Boot 写，接口大致长这样：

@PutMapping("/api/upload/chunk") public ResponseEntity<Void> uploadChunk( @RequestHeader("X-Chunk-Index") int index, @RequestHeader("X-Chunk-Count") int total, @RequestHeader("X-Chunk-Offset") long offset, @RequestBody byte[] data) throws IOException { Path chunkFile = Path.of("/data/chunks/", "part-" + index); Files.write(chunkFile, data, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING); return ResponseEntity.ok().build(); }

提示：生产环境不建议用@RequestBody byte[]接收大分片，应该用InputStream流式读到临时文件，避免服务端在分片较大或并发高时内存告急。这里的写法只是为了演示接口协议。

3.3 上传进度、断点续传和并发上传进阶

进度输出我写在循环里，打印当前分片和总进度。真正产品化时，可以换成 WebSocket 推送或回调，前端轮询也能接受。

断点续传的关键是uploadedChunks集合。最简单的实现是用一个本地文件保存已传分片索引，每次启动时读进来。更规范的做法是在服务端提供queryUploadedChunks(taskId)接口，客户端启动先查一下，只传缺失的分片。不要依赖“服务端已经存在分片就当成功”，因为可能只传了一半进程就崩了。

并发上传能显著提速，但要注意线程安全。上面这个主循环是同步串行的，逻辑最简单，适合正确性优先的场景。要提速的话，用固定线程池控制并发数，通常 3 到 5 个并发就够，并发太多会让服务端连接数飙升，也会触发大量 TCP 重传。

ExecutorService pool = Executors.newFixedThreadPool(3); CountDownLatch latch = new CountDownLatch(pendingChunks.size()); AtomicInteger failedCount = new AtomicInteger(); for (int index : pendingChunks) { pool.submit(() -> { try { // 并发时不能复用同一个 RandomAccessFile boolean result = sendChunkWithItsOwnFile(filePath, ...); if (!result) { failedCount.incrementAndGet(); } } finally { latch.countDown(); } }); } latch.await(60, TimeUnit.MINUTES); pool.shutdown();

并发上传的坑比同步多不少。比如 RandomAccessFile 不是线程安全的，每个线程必须单独打开文件；再比如同一个分片可能被并发提交两次，服务端要用文件写锁或原子写入避免损坏。所以我建议第一次实现先跑通同步串行，确认稳定性后再优化并发。

4. 上线前必须处理的四个细节

4.1 不要忽略服务端和网关的请求体大小限制

Java 代码写得再对，如果网关先挡一道，请求还是进不来。很多微服务前面会挂 Nginx 之类的反向代理，默认的client_max_body_size只有 1MB，超过就返回 413。你辛辛苦苦写好分片上传，却因为网关配置没调，直接前功尽弃。

排查方法是看响应状态码。如果客户端发小分片成功、发大分片立刻 413，先查网关。Nginx 里可以调大：

client_max_body_size 2048m;

不要只调到一个固定大值，还要结合超时设置。超大附件上传时间很长，反向代理的proxy_read_timeout、proxy_send_timeout也要给足，否则传一半代理主动断连，客户端看到的是连接重置。

服务端容器也不是没有限制。Tomcat 的maxPostSize、maxSavePostSize在某些参数解析场景下会限制请求体，虽然可以直接用InputStream读取，但遇到 413 时顺手检查所有入口配置是必要的。

4.2 分片别乱写，合并时按索引对齐

分片上传的核心风险不在“传”，而在“合并”。并发传到服务端后，每个分片是独立的临时文件，如果文件名只按时间戳生成，不包含索引，合并时根本不知道哪块该排前面。

我习惯把临时分片命名为{taskId}-{index}.part，全部传完后按索引升序合并：

Path finalPath = Path.of("/data/files/", fileName); try (OutputStream out = Files.newOutputStream(finalPath, StandardOpenOption.CREATE, StandardOpenOption.WRITE)) { for (int i = 0; i < totalChunks; i++) { Path chunkPath = Path.of("/data/chunks/", taskId + "-" + i + ".part"); if (!Files.exists(chunkPath)) { throw new IOException("missing chunk: " + chunkPath); } Files.copy(chunkPath, out); } }

合并前必须检查分片数量是否等于X-Chunk-Count。缺少任何一片都要标记任务失败，不能侥幸合并出一个残缺文件。合并完成后可以删除临时分片，释放磁盘空间。磁盘空间也要留意：6GB 文件的分片在服务端累计占 6GB，加上合并后的最终文件又是 6GB，瞬时磁盘占用翻倍，存储余量不足时合并会失败。

4.3 HTTP 慢速传输的缓冲区与超时设置

大文件上传最难受的是“看着没断，实际已经卡死”。JDK HttpClient 的timeout()是等待响应的总超时。如果一个分片传输时间超过设定值，客户端会抛HttpTimeoutException。这时重试间隔要合理，不要无脑立刻重试，否则服务端还在处理上一个超时请求，客户端又开始重发，形成“超时—重试—再超时”恶性循环。

JVM 层面还有个 TCP 缓冲区问题。发出 8MB 分片时，如果 Socket 发送缓冲区太小，应用写数据会被阻塞，表现为上传速度提不上去。JDK HttpClient 默认会处理大部分细节，但如果你自己封装Socket或HttpURLConnection，可以把发送缓冲区和接收缓冲区调到 1MB 左右。

另外，HTTP 连接要设置Connection: keep-alive，避免每个分片都重新建连和 TLS 握手。JDK HttpClient 默认复用连接，但个别中间代理会缓存旧连接，长任务传完后连接可能已失效。遇到“连续传几个分片后突然报错，重试又成功”的情况，大概率就是连接被回收但客户端不知道，重试逻辑里要允许重新建连。

4.4 传输校验和日志记录不能省

文件的完整性校验我建议做两层。第一层是分片级校验，客户端在请求头带X-Chunk-MD5，服务端收到字节后计算 MD5 做比对，不一致直接返回 400，让客户端重传。对大文件来说，单块 8MB，MD5 计算成本很低，收益却很高。第二层是整个文件合并后的校验，可以对比原始文件与合并后文件的 MD5，也可以对比总字节数和文件名称。

日志尤其重要。每个分片成功、失败、重试、耗时都要有结构化日志。至少包含任务 ID、分片索引、偏移量、文件总大小、当前耗时。排障时如果只有“上传失败”四个字，你根本不知道是网络、服务端还是参数问题。我见过很多生产事故，排查半天后发现是某个分片在服务端 500 了，但因为客户端日志没记录索引，只能全量重传。

5. 分片上传常见问题与排查实录

5.1 明明传完了，服务端合并却失败

这个现象经常出现在并发上传场景。客户端把所有分片发完，服务端合并时却说缺文件。原因多半是客户端收到 200 响应只是在网关层返回，实际服务端还没落盘就返回了，或者并发提交的最后一个分片还在队列里，合并请求已经发过来了。

解决办法是服务端提供确认接口。客户端不要只看自己收到的 200，不要一收到 200 就调合并接口。正确做法是合并接口内部做完整性校验，发现缺分片就返回 409，客户端再查缺失列表，补传缺失分片后再合并。实现上可以做成分布式锁，对同一个 taskId 只允许一个合并任务执行。

5.2 大文件传到一半连接被重置

连接重置最常见的原因是超时。网络波动、服务端负载高、代理主动断开，都可能导致中间连接断掉。这类问题我处理的顺序是：

1. 看客户端异常是ConnectTimeout还是ReadTimeout，分别处理连接超时和请求超时。
2. 调大请求超时，确认代理层没有更短的“无响应断开”配置。
3. 把分片大小从 16MB 降到 8MB，缩短单请求的传输时间。
4. 开启重试，重试时只重传失败分片。

如果连接总是在同一个分片固定位置断开，还要怀疑文件读取问题。比如磁盘坏道、文件被并发程序改动、分片计算偏移量错误。这类问题比较隐蔽，所以日志里一定要记录当前分片的 offset 和 length。

5.3 并发上传后部分分片丢失或错位

并发丢片大多是客户端线程不安全造成的。比如多个线程同时用同一个RandomAccessFile读取文件，没有同步，导致读出来的内容和索引不匹配。另一个可能是我前面提到的服务端写分片文件时命名冲突，多个请求写到同一个临时文件，相互覆盖。

排查方法是直接看临时分片文件的字节数。正常每个分片除最后一块外都应该等于 CHUNK_SIZE，如果出现 0 字节文件或大小不对，基本就是写入冲突。服务端每个分片文件用“taskId + index”命名，并且写入时用临时文件加原子改名，可以规避大部分问题。

5.4 一个保底的运维手段：先小文件压测

不管代码写得看起来多完美，超大附件上传一定要先拿小文件验证完整链路。我自己每次接新项目，都会先用 10MB、100MB、1GB 三个量级压一遍，分别验证单分片、多分片、断点续传、服务端合并、MD5 校验。小文件能跑到 100MB 稳定，再上 6GB，排障成本会低很多。

分享一个我踩过多次坑之后的习惯：每次上传完成后，不仅在客户端打印进度，还会在服务端记录“分片上传完成列表”。排查问题时，两边一对照，缺哪块一目了然。大文件上传的稳定，不是靠某一个精巧的 HTTP 请求，而是靠分片设计、状态记录、服务端校验和充分的日志，四样缺一不可。