在 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 分片分片数会到 3072HTTP 请求本身的开销会占很大比例服务端要处理 3000 多个请求日志和索引压力都大。如果按 128MB 分片分片数少了但单块传输时间变长一旦网络抖动重试代价就很高。所以 8MB 到 16MB 是多数场景下的甜点区间。超时时间要区分连接超时和请求超时。连接超时一般设 10 秒即可连不上的话再等也没意义。请求超时是“从发出请求到收到响应”的整个时间强烈建议给足。8MB 分片在很差的网络下也可能会传好几分钟我一般设 30 分钟。重试次数 3 次左右间隔用递增退避比如 1 秒、2 秒、4 秒。重试太频繁会把服务端打爆不重试又会因为一次瞬断导致整个任务失败。2.3 用请求头传递分片信息别在 URL 里传超长参数分片上传要让服务端知道“这是哪一块、总共几块、偏移量多少”。很多新手习惯把这些参数拼在 URL 里PUT /api/upload?chunkIndex0totalChunks768offset0URL 短还好一旦参数多、文件名长很容易碰上网关、代理对 URL 长度的限制而且日志会把敏感文件名烤出来。更干净的做法是用自定义请求头传递分片元数据请求体只放原始二进制分片。请求头示例值作用X-Chunk-Index0当前分片序号从 0 开始X-Chunk-Count768总片数服务端用来判断完整性X-Chunk-Offset8388608当前分片在文件中的起始偏移Content-Typeapplication/octet-stream表示原始二进制体服务端如果点击“合并”动作约定一个独立接口根据文件名和 chunk count 去合并分片。客户端不需要在每次上传时重复传文件名可以在创建上传任务时用另一个接口注册文件元信息拿到一个任务 ID后续请求头里只带任务 ID。这样更利于扩展断点续传和分片管理。3. JAVA http 分片上传核心代码3.1 分片上传的主循环怎么组织直接看代码。这里我定义一个ChunkUploader核心方法是upload(Path filePath, String uploadUrl, SetInteger 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, SetInteger 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 { HttpResponseString 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 ResponseEntityVoid 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让客户端重传。对大文件来说单块 8MBMD5 计算成本很低收益却很高。第二层是整个文件合并后的校验可以对比原始文件与合并后文件的 MD5也可以对比总字节数和文件名称。日志尤其重要。每个分片成功、失败、重试、耗时都要有结构化日志。至少包含任务 ID、分片索引、偏移量、文件总大小、当前耗时。排障时如果只有“上传失败”四个字你根本不知道是网络、服务端还是参数问题。我见过很多生产事故排查半天后发现是某个分片在服务端 500 了但因为客户端日志没记录索引只能全量重传。5. 分片上传常见问题与排查实录5.1 明明传完了服务端合并却失败这个现象经常出现在并发上传场景。客户端把所有分片发完服务端合并时却说缺文件。原因多半是客户端收到 200 响应只是在网关层返回实际服务端还没落盘就返回了或者并发提交的最后一个分片还在队列里合并请求已经发过来了。解决办法是服务端提供确认接口。客户端不要只看自己收到的 200不要一收到 200 就调合并接口。正确做法是合并接口内部做完整性校验发现缺分片就返回 409客户端再查缺失列表补传缺失分片后再合并。实现上可以做成分布式锁对同一个 taskId 只允许一个合并任务执行。5.2 大文件传到一半连接被重置连接重置最常见的原因是超时。网络波动、服务端负载高、代理主动断开都可能导致中间连接断掉。这类问题我处理的顺序是看客户端异常是ConnectTimeout还是ReadTimeout分别处理连接超时和请求超时。调大请求超时确认代理层没有更短的“无响应断开”配置。把分片大小从 16MB 降到 8MB缩短单请求的传输时间。开启重试重试时只重传失败分片。如果连接总是在同一个分片固定位置断开还要怀疑文件读取问题。比如磁盘坏道、文件被并发程序改动、分片计算偏移量错误。这类问题比较隐蔽所以日志里一定要记录当前分片的 offset 和 length。5.3 并发上传后部分分片丢失或错位并发丢片大多是客户端线程不安全造成的。比如多个线程同时用同一个RandomAccessFile读取文件没有同步导致读出来的内容和索引不匹配。另一个可能是我前面提到的服务端写分片文件时命名冲突多个请求写到同一个临时文件相互覆盖。排查方法是直接看临时分片文件的字节数。正常每个分片除最后一块外都应该等于 CHUNK_SIZE如果出现 0 字节文件或大小不对基本就是写入冲突。服务端每个分片文件用“taskId index”命名并且写入时用临时文件加原子改名可以规避大部分问题。5.4 一个保底的运维手段先小文件压测不管代码写得看起来多完美超大附件上传一定要先拿小文件验证完整链路。我自己每次接新项目都会先用 10MB、100MB、1GB 三个量级压一遍分别验证单分片、多分片、断点续传、服务端合并、MD5 校验。小文件能跑到 100MB 稳定再上 6GB排障成本会低很多。分享一个我踩过多次坑之后的习惯每次上传完成后不仅在客户端打印进度还会在服务端记录“分片上传完成列表”。排查问题时两边一对照缺哪块一目了然。大文件上传的稳定不是靠某一个精巧的 HTTP 请求而是靠分片设计、状态记录、服务端校验和充分的日志四样缺一不可。