项目标题摆出来就知道大家关心什么JDK17、HttpClient、大文件上传、下载、流式处理。这几个词放在一起对应的是实际开发里特别常见的场景——用Java做文件传输功能比如给后台管理系统写批量导入、给文件服务写客户端SDK、或者做数据同步工具。以前搞这类东西大家要么用HttpURLConnection手写一堆模板代码要么引入Apache HttpClient、OkHttp这类第三方库能选太多反而纠结。但JDK9就内置、JDK11正式转正的java.net.http.HttpClient到JDK17这代已经相当能打尤其在做流式上传和下载时标准库自己就能把活干得漂亮。今天这篇文章就围绕这个标题把大文件上传和下载的流式处理方案完整拆开讲清楚包括底层原理、完整可跑的代码示例以及我在实际项目中踩过的那些坑。适合正在做文件类功能、想在第三方库和标准库之间做个判断或者已经用了HttpClient但遇到性能、内存问题的朋友。1. 先想清楚为什么选 JDK17 的 HttpClient 做文件传输很多人的第一反应是HttpClient 我知道啊JDK里不是早就有HttpURLConnection了但真正上手做过文件传输就会发现老牌HttpURLConnection的痛点非常明显API设计老旧连请求头设置、连接复用这些基础操作写起来都别扭HTTP/2支持基本没有连接池管理也得自己搭。而JDK17里内置的java.net.http.HttpClient是Oracle重新设计的HTTP客户端支持HTTP/1.1和HTTP/2同步异步都能用核心API只有HttpClient、HttpRequest、HttpResponse三个类设计思路比旧API清晰得多。对这个标题涉及的场景来说选它至少有三重理由零第三方依赖、语义简洁、和CompletableFuture天然配合。1.1 标准库的进化从HttpURLConnection到HttpClient先聊点历史方便你理解为什么这个选型是趋势。HttpURLConnection是JDK 1.1时代就存在的老将它并不是不能做文件上传下载但每次用都要写大量样板代码设置DoOutput、拼multipart/form-data边界、手动管理Cookie、处理重定向……说实话如果只是发个GET请求还好一旦涉及大文件流式传输它的抽象层次低得让人头疼。而java.net.http.HttpClient从JDK 9作为孵化模块引入JDK 11正式发布到JDK 17的时候已经是长期支持版本里的稳定能力API设计借鉴了很多现代HTTP客户端的思想把请求构建和响应处理都抽象得很干净。更关键的是JDK17本身是LTS版本意味着企业可以放心把它作为生产环境的基线不需要每半年追一个版本。很多团队现在从JDK8往上升直接选JDK17的非常多。在这个版本上HttpClient已经经历了多次迭代HTTP/2连接复用、响应超时、连接超时、SSL握手配置这些细节都处理得比较成熟用标准库足以支撑文件服务端的开发。如果你还在JDK8上写文件上传要么自己封装一套要么引第三方库到了JDK17这个纠结可以直接放下。1.2 大文件传输的选型对比内置HttpClient vs 第三方库可能有朋友会问Apache HttpClient、OkHttp、甚至Spring的RestTemplate、WebClient不是也很成熟吗这话没错但要看场景。如果你已经在一个庞大的Spring Boot项目里用WebClient或RestTemplate是顺理成章的但如果你只是写一个独立的同步工具、运维脚本、或者一个轻量级的SDK为了一个文件上传功能拉进来一整个HTTP客户端依赖代价明显偏大。下面这个表是我平时选型时会做的对比客户端依赖体积HTTP/2流式上传流式下载异步学习成本适用场景JDK17 HttpClient无支持支持BodyPublishers支持BodyHandlers支持低标准库解决零依赖Apache HttpClient 5Maven依赖体积中等支持支持Entity实现支持支持中已有依赖体系OkHttpMaven依赖体积小支持支持RequestBody支持支持中低Android/移动端Spring WebClient很大支持支持支持强中高Spring生态内原生URLConnection无不支持勉强勉强无高样板多实在没得选curl命令行无支持支持支持无不支持Java调用脚本场景我个人的倾向很明确独立工具、SDK、微服务内部功能优先用JDK17内置的HttpClient。它不是最花哨的但稳定、内存占用可控、没有传递性依赖而且在这个标题对应的大文件上传/download场景里它的流式API已经足够好用。第三方库当然有它们的优势比如HttpClient 5在连接池细粒度配置上更强OkHttp在Android领域是事实标准但如果只是标准Java服务端或命令行工具内置客户端性价比最高。2. 流式上传/下载的底层思路要把大文件传输做好关键不是记住某个API而是理解HttpClient处理请求体和响应体的模型。这里有两个核心概念必须吃透BodyPublisher请求体发布器和BodyHandler响应体处理器。它们名字看着抽象本质上就是两条数据管道一个管我要发出去的字节怎么来一个管收到的字节怎么消费。把这两个抽象搞明白大文件流式处理的思路就顺了。2.1 BodyPublisher 与 BodyHandler数据管道的两端打个比方HTTP传输就像水管送水。BodyPublisher是水源决定水怎么流出来BodyHandler是水龙头决定水接到哪里去。在同步阻塞模式下HttpClient.send会把整个请求执行完但数据本身并不需要一次性全部装进内存。BodyPublisher控制请求体的产生方式BodyHandler控制响应体的消费方式。JDK为此提供了一组现成的实现类/方法作用大文件场景是否推荐BodyPublishers.ofByteArray(byte[])把整个字节数组作为请求体不推荐会完整载入内存BodyPublishers.ofInputStream(SupplierInputStream)从输入流读取请求体流式发送推荐按需读取BodyPublishers.ofFile(Path)直接把文件作为请求体非常推荐最简方案BodyPublishers.concat(...)拼接多个发布器特殊场景用HttpRequest.BodyPublishers.noBody()空请求体GET请求用BodyHandlers.ofByteArray()把响应体全部读进字节数组不推荐用于大文件下载BodyHandlers.ofInputStream()以流的方式消费响应体推荐可边读边写BodyHandlers.ofFile(Path)直接把响应体写入文件非常推荐最简方案BodyHandlers.ofFileDownload(Path)根据响应头里的文件名保存适合资源下载类场景BodyHandlers.ofString()把响应体作为字符串绝对不要用于大文件一眼就能看出来的规律是凡是要把整个内容载入内存的实现都不适合大文件。要么用ofInputStream配合流式写入要么直接用ofFile让JDK替你完成文件落盘。我之前见过有同事用HttpResponse.BodyHandlers.ofString()去接一个几百MB的文件接口结果堆内存直接飙满服务都快卡死了这就是典型的内存爆炸案例。2.2 为什么一次性读入内存的方案会崩这里要重复一个很多文章提过但确实最重要的结论大文件上传下载严禁一次性把整个文件读入内存。原因不在于某个API不好而在于JVM堆内存是有限且需要GC的。假设你拿到一个2GB的文件先读成byte[]再通过ofByteArray发送那么内存里至少同时存在源文件的byte[]、HTTP内部的缓冲、可能还有响应内容几个GB堆内存随便就没了。GC压力也大因为大数组大多会进老年代频繁Full GC直接拖垮服务。更糟的是Java里byte[]最大长度受int限制约2GB多一点就算你内存够超过这个长度你也创建不出来。所以流式处理的核心就是数据边读边写内存里始终只留一个固定大小的小缓冲区。比如Java标准库默认的缓冲区大小可能只有8KB你手动设成64KB或者128KB哪怕文件是5GB内存占用也就是这几百KB的小数组跟文件大小毫无关系。这个思路对上传和下载完全一致上传时从文件流中一小段一小段读出交给HttpClient发送下载时从响应流中一小段一小段读出写进目标文件。水龙头开多大取决于管道直径内存占用多少取决于缓冲区大小而不是水流总量。2.3 流式处理要满足哪些条件才算合格判断一个实现是不是真正的流式处理我一般看三个标准。第一是内存占用是否与文件大小无关如果你用固定的byte[8192]或byte[65536]循环读写就算合格如果出现了Files.readAllBytes()、IOUtils.toByteArray()这类调用基本就是内存炸弹。第二是请求/响应的传输是否支持分块或范围读取上传时可以通过Transfer-Encoding: chunked避免必须预知Content-Length下载时可以利用Range头做断点续传。第三是能否做到边生产边消费比如你从数据库或网络拉数据不必等全部拉完再发请求BodyPublishers.ofInputStream配合自定义InputStream就能实现。这三个条件满足你才真正掌握了流式二字。3. 实操用 JDK17 搞定大文件上传思路讲清楚之后代码才是重头戏。下面我分别演示大文件上传的两种写法一种是不推荐的一次性读入方案主要让你对比着理解另一种是真正适合生产的流式方案直接可以抄作业。3.1 反面示例一次性读入内存的写法以下代码非常简单在JDK17环境里完全能跑但它只适合几MB的小文件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; public class BadUploadExample { public static void main(String[] args) throws Exception { Path file Path.of(args[0]); // 危险操作一次性把整个文件读入内存 byte[] fileBytes Files.readAllBytes(file); HttpClient client HttpClient.newHttpClient(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(http://127.0.0.1:8080/upload)) .header(Content-Type, application/octet-stream) .POST(HttpRequest.BodyPublishers.ofByteArray(fileBytes)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(上传状态码: response.statusCode()); System.out.println(上传结果: response.body()); } }这段代码的问题一眼就能看出来Files.readAllBytes在大文件面前就是灾难。另外BodyHandlers.ofString()也绝对不该出现在文件上传接口里响应体应该用ofDiscarding()或ofString()只在小响应时用。作为对比你只要能意识到这两处不对后面流式写法就好接受了。3.2 正确示范流式上传大文件真正的生产级写法是使用BodyPublishers.ofInputStream它接收一个SupplierInputStream而不是一个现成的InputStream这个设计是有讲究的因为HttpClient在内部可能因为重定向或重试而需要多次读取请求体Supplier可以让每次请求都拿到一个新的流从头开始读。如果传一个用过的流第二次读就是空的。示例代码如下import java.io.IOException; import java.io.InputStream; 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; public class StreamUploadExample { public static void main(String[] args) throws Exception { Path file Path.of(args[0]); HttpClient client HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(http://127.0.0.1:8080/upload)) .timeout(Duration.ofMinutes(30)) .header(Content-Type, application/octet-stream) // 关键点ofInputStream 文件输入流 .POST(HttpRequest.BodyPublishers.ofInputStream(() - { try { return Files.newInputStream(file); } catch (IOException e) { throw new RuntimeException(无法打开文件: file, e); } })) .build(); HttpResponseVoid response client.send(request, HttpResponse.BodyHandlers.discarding()); System.out.println(上传完成状态码: response.statusCode()); } }这段代码里有两个容易被忽视的点。一个是BodyHandlers.discarding()对上传接口来说服务器返回的响应体通常很小只是一个状态提示直接丢弃最省内存。另一个是超时时间大文件上传肯定超过默认的30秒这里我显式设置了30分钟避免传输中断。还有一点Files.newInputStream默认缓冲区大小其实不大但放心BodyPublishers.ofInputStream内部读取时并不会一次性读全部它会按自身逻辑分块读取内存占用保持低位。如果你希望更激进一点直接用BodyPublishers.ofFile(file)是最省事的流式上传方案连InputStream都省了HttpRequest request HttpRequest.newBuilder() .uri(URI.create(http://127.0.0.1:8080/upload)) .header(Content-Type, application/octet-stream) .POST(HttpRequest.BodyPublishers.ofFile(file)) .build();ofFile底层实现就是把文件当成InputStream来发布效果和我手写Supplier一样但代码更简短。唯一的限制就是文件必须真实存在且可读取。我倾向于在工具类里优先用ofFile因为它语义最清晰只有在文件路径是动态拼装、或者文件来自其他非文件数据源时才用ofInputStream自定义流。3.3 上传进度如何实现很多人做完基本功能后会问上传进度呢尤其在前端页面展示进度条或者服务端打日志时总想知道传了多少字节。其实进度统计的原理非常简单包装一下InputStream在读read方法时累加字节数。下面就是一个可以嵌入项目的进度包装类import java.io.FilterInputStream; import java.io.IOException; import java.io.InputStream; import java.util.concurrent.atomic.AtomicLong; public class ProgressInputStream extends FilterInputStream { private final AtomicLong progress new AtomicLong(0); private final long totalSize; protected ProgressInputStream(InputStream in, long totalSize) { super(in); this.totalSize totalSize; } Override public int read() throws IOException { int b super.read(); if (b ! -1) { long current progress.incrementAndGet(); printProgress(current); } return b; } Override public int read(byte[] b, int off, int len) throws IOException { int n super.read(b, off, len); if (n ! -1) { long current progress.addAndGet(n); printProgress(current); } return n; } private void printProgress(long current) { if (totalSize 0) { double percent current * 100.0 / totalSize; System.out.printf(\r上传进度: %.2f%% (%d/%d bytes), percent, current, totalSize); } else { System.out.printf(\r已上传: %d bytes, current); } } public long getProgress() { return progress.get(); } }使用方式也非常直接long totalSize Files.size(file); InputStream in new ProgressInputStream(Files.newInputStream(file), totalSize); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(http://127.0.0.1:8080/upload)) .header(Content-Type, application/octet-stream) .POST(HttpRequest.BodyPublishers.ofInputStream(() - in)) .build();要注意的是SupplierInputStream这里如果返回同一个ProgressInputStream实例重试时流已经被读过一遍所以最好在Supplier内部new新的包装流。另外\r回车符用于刷新同一行进度在IDE控制台或标准终端里效果不错但若写到日志文件里会变成一行乱码正式项目建议使用日志框架记录百分比节点而不是每读一次就打一条日志。4. 实操大文件下载与断点续传下载方向同样遵循流式原则但侧重点略有不同下载时你面对的是响应体InputStream核心任务是把流里的数据逐块写进磁盘文件。JDK17 HttpClient也给了几种层级的方案我一个个讲。4.1 用 ofInputStream 手动下载到本地如果你需要对下载过程做精细控制比如记录下载量、中途暂停、合并进度可以用BodyHandlers.ofInputStream()拿到响应体的流然后手动循环读写import java.io.InputStream; import java.io.OutputStream; 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; public class StreamDownloadExample { public static void main(String[] args) throws Exception { String fileUrl args[0]; Path target Path.of(args[1]); HttpClient client HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .followRedirects(HttpClient.Redirect.NORMAL) .build(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(fileUrl)) .timeout(Duration.ofMinutes(30)) .GET() .build(); HttpResponseInputStream response client.send(request, HttpResponse.BodyHandlers.ofInputStream()); System.out.println(状态码: response.statusCode()); if (response.statusCode() 200) { try (InputStream in response.body(); OutputStream out Files.newOutputStream(target)) { byte[] buffer new byte[8192]; int bytesRead; long totalRead 0; while ((bytesRead in.read(buffer)) ! -1) { out.write(buffer, 0, bytesRead); totalRead bytesRead; } System.out.println(下载完成总字节数: totalRead); } } else { System.err.println(下载失败状态码: response.statusCode()); } } }这段代码的要点有三处一是设置了followRedirects(HttpClient.Redirect.NORMAL)很多文件下载URL会先302跳转到CDN或对象存储临时地址不自动跟随就会拿到跳转提示而非文件内容二是缓冲区用8KB这个大小在性能和内存占用之间比较平衡不用调太大三是try-with-resources确保输入输出流都正确关闭避免文件句柄泄漏。整个下载期间内存里只有一个8KB的buffer数组哪怕下载10GB文件都稳得很。4.2 更省心的方案BodyHandlers.ofFile 与 ofFileDownload如果你不需要精细控制JDK17还提供了更直接的方案BodyHandlers.ofFile(Path)会把响应体直接保存到指定路径连手动读写都省了。它返回的HttpResponsePath里body就是最终保存的文件路径HttpRequest request HttpRequest.newBuilder() .uri(URI.create(fileUrl)) .GET() .build(); HttpResponsePath response client.send(request, HttpResponse.BodyHandlers.ofFile(target)); System.out.println(文件保存在: response.body());而ofFileDownload更自动它不看你自己指定的目标文件名而是从响应头的Content-Disposition字段里提取文件名然后保存到指定目录。这个特别适合做爬虫、资源批量下载程序Path downloadDir Path.of(./downloads); HttpResponsePath response client.send(request, HttpResponse.BodyHandlers.ofFileDownload(downloadDir)); System.out.println(自动保存的文件: response.body());注意ofFileDownload要求目标目录必须已存在而且它保存的文件名完全取决于服务端给的响应头。如果服务端没有Content-Disposition或者文件名包含非法字符有可能会报错所以用之前要确认接口行为。我个人一般优先用ofFile指定明确路径因为文件保存的位置可控不至于被服务端带偏。4.3 断点续传用 Range 请求头实现大文件下载最怕什么下载到一半网络断了又要从头开始。HTTP协议本身就有断点续传的机制客户端在请求头里加Range: bytesstart-服务端如果支持会返回206 Partial Content并且响应体只传输从指定位置开始的数据。JDK17 HttpClient对这个原生支持你只需要自己维护偏移量。实现思路很简单先看本地已下载的文件有多大然后从那个字节位置继续请求。为避免每次断点都全量重来第一次下载时就创建文件并记录已下载长度。一个可用的骨架代码如下import java.io.InputStream; import java.io.OutputStream; 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.nio.file.StandardOpenOption; public class ResumeDownloadExample { public static void main(String[] args) throws Exception { String fileUrl args[0]; Path target Path.of(args[1]); HttpClient client HttpClient.newBuilder().followRedirects(HttpClient.Redirect.NORMAL).build(); long downloaded 0; if (Files.exists(target)) { downloaded Files.size(target); System.out.println(本地已有文件已下载: downloaded bytes); } HttpRequest.Builder requestBuilder HttpRequest.newBuilder() .uri(URI.create(fileUrl)) .timeout(Duration.ofMinutes(30)); // 如果已有部分下载加上 Range 头 if (downloaded 0) { requestBuilder.header(Range, bytes downloaded -); } HttpResponseInputStream response client.send(requestBuilder.GET().build(), HttpResponse.BodyHandlers.ofInputStream()); int status response.statusCode(); System.out.println(响应状态码: status); // 200: 服务器不支持断点续传全量下载206: 支持断点续传 boolean append (status 206); if (status 200) { downloaded 0; } else if (status ! 206) { System.err.println(下载失败: status); return; } try (InputStream in response.body(); OutputStream out Files.newOutputStream(target, append ? StandardOpenOption.APPEND : StandardOpenOption.CREATE, StandardOpenOption.WRITE)) { byte[] buffer new byte[8192]; int bytesRead; long total downloaded; while ((bytesRead in.read(buffer)) ! -1) { out.write(buffer, 0, bytesRead); total bytesRead; } System.out.println(断点续传完成最终总字节数: total); } } }关键点就是状态码的语义如果服务器不支持Range它会忽略客户端请求头返回200并重新发送全部内容此时你必须覆盖写不能追加否则文件就重复了如果服务器支持Range返回206就按追加模式继续写。还有一点这里我用Files.newOutputStream(target, StandardOpenOption.APPEND, StandardOpenOption.CREATE, StandardOpenOption.WRITE)来追加需要注意的是StandardOpenOption.APPEND和WRITE同时使用在Java里是允许的但如果你想断点续传时从指定位置写入可以改用new SeekableByteChannel配合position更精确对于文件下载来说追加模式已经够用。如果下载过程突然中断下次运行时它会先检查本地文件大小找到新的偏移量再请求自然就实现了接着传。当然这个方案有前提服务端必须支持Range请求头。大厂的对象存储、CDN基本都支持但一些临时生成的接口可能不支持所以代码里必须对200和206都做兼容。5. 常见问题与排查技巧实录这一部分是我最想写的因为这些坑不是看文档能发现的全是实操中踩出来的。下面这些问题几乎每个做文件传输的团队都会遇到至少其中一个。5.1 上传大文件时连接被重置症状文件传输到一半报错IOException: Connection reset或EOFError或者干脆没有任何异常但服务端收不到完整文件。排查思路一般按顺序看先看是不是超时设置太短尤其服务端处理慢或者网络带宽不够时默认的30秒超时很容易触发HttpTimeoutException如果是把timeout调大再看是不是代理服务器或负载均衡器有上传大小限制或空闲超时限制Nginx默认的client_max_body_size只有1MB不调大传几MB以上的文件就会返回413或断开最后看是不是HTTP/2连接在传输大文件时被中间设备重置可以临时改用HttpClient.Version.HTTP_1_1对比测试确认是否是协议层问题。我遇到比较典型的场景是在办公室网络环境上传2GB镜像稳定传到80%就断查了一圈发现是公司防火墙对大请求体有连接空闲限制。最后的解法是把请求超时调到足够长并且在上层加了失败重试机制配合Range断点续传才彻底解决。5.2 下载时内存持续上涨甚至OOM如果下载用的是BodyHandlers.ofByteArray()或BodyHandlers.ofString()大文件场景下内存飙高是必然的。排查时先看代码里响应体是怎么接的。正确做法是BodyHandlers.ofInputStream()然后循环读写或者直接用BodyHandlers.ofFile()。如果你已经用了流式方式但内存还是涨那问题多半出在读取循环里是不是把每次读到的数据又累计到了一个大的ByteArrayOutputStream里很多人写下载代码时为了最后做校验会把整个内容都塞进内存这就前功尽弃了。正确做法是边写边算哈希或者写完文件后重新打开文件计算不要保留全量字节。另外InputStream的每次read调用其实都涉及系统调用如果缓冲区太小比如1KBCPU占用会很高建议用64KB甚至256KB的缓冲数组。有个经验值缓冲区大小不要超过TCP窗口的合理范围常规8KB到256KB之间表现都不错太大反而因为单次分配大块连续内存造成GC压力。5.3 HttpClient 并发上传时的连接池问题JDK17 HttpClient默认复用连接使用同一个HttpClient实例发送多个并发请求正常来说连接池会复用TCP连接。但你做并发大文件上传时可能会发现明明没有超时部分请求却特别慢或者出现ConnectionPoolTimeoutException第三方库里的叫法JDK内置客户端不会有这个名字它是直接阻塞或超时。这是因为默认连接池有上限通常每个目标主机有2个连接多个并发上传会争用连接。解决方案也很简单针对文件上传这类耗时任务可以给不同的上传任务创建独立的HttpClient实例或者用HttpClient.newBuilder().executor(Executor)配合虚拟线程JDK21来提升并发度。我现在做上传工具时都会给每个任务new一个HttpClient实例用完后关闭底层资源避免大流量场景下连接互相拖累。JDK17环境里虽然没有虚拟线程但用ExecutorService CompletableFuture也能实现类似的并发效果只要别用同一个客户端死磕并发大文件就行。5.4 常见报错速查表下面是文件传输场景常见的报错和处理办法我整理成表格方便以后遇到问题直接查报错信息原因处理方案HttpTimeoutException: request timed out整体请求超时时间过短调大HttpRequest.timeoutConnectException: Connection refused目标服务未启动或端口不通检查服务健康状态或设置更长的connectTimeoutSSLHandshakeException证书不信任、TLS版本不匹配配SSLContext信任自签名证书需额外处理IOException: Connection reset中间设备断开连接、服务端崩溃检查代理/防火墙/服务端日志加断点续传重试FileSystemException: 文件被占用目标文件正在被其他进程写入换文件名或确保文件句柄已关闭OutOfMemoryError: Java heap space一次性读入内存改用流式读写见上文方案IllegalArgumentException: contentLength too big请求头长度超过int上限使用BodyPublishers.ofInputStream不要显式设置Content-Length413 Request Entity Too Large服务端或网关限制上传大小调整服务端配置或改用分片上传这张表不敢说覆盖所有情况但大文件上下传遇到的大多数问题都跑不出这几个方向。5.5 实操避坑清单汇总把前面提到的经验浓缩成一份清单给你的代码走查当checklist禁止用Files.readAllBytes、IOUtils.toByteArray等一次性读大文件。禁止用BodyHandlers.ofString()或ofByteArray()接收大文件下载响应体。务必在BodyPublishers.ofInputStream的参数里传入SupplierInputStream不要传单一的InputStream实例。务必关闭打开的文件流和响应体流try-with-resources是最省心的方式。务必区分200和206状态码断点续传时只有206才能追加写。务必处理followRedirects否则CDN跳转场景会拿到空的302响应。建议大文件上传的timeout至少30分钟起具体根据文件平均大小和带宽评估。建议并发上传时给每个任务建独立HttpClient或者用线程池调度多个客户端实例。建议在下载完成以后如果做MD5校验用MessageDigest边读边更新而不是把整个文件载入内存。注意Content-Length未知的情况下JDK17 HttpClient会退化为Transfer-Encoding: chunked服务端需要支持这一点对老服务尤其重要。最后再分享一点个人体会做文件传输功能这几年我自己最大的感受是方案本身都不复杂但细节决定生死。用JDK17内置HttpClient做流式上传/下载最大的优势是零依赖、语义清晰只要把BodyPublisher和BodyHandler这两组概念吃透大部分场景都能轻松覆盖。之前我写过一个文件同步工具需要定期把本地目录里的增量文件传到远端服务器文件大小从几KB到几GB都有。最初用第三方客户端实现后来重构改成JDK17 HttpClient配合ofFile上传和ofFileDownload下载代码量直接少了一半内存占用也没有任何波动。唯一花心思的地方就是重试和断点续传逻辑但只要有了Range请求头这个概念这块也就是几十行代码的事。如果你准备在生产环境用这套方案建议再扩展两个方向一是给下载加MD5校验让服务端返回文件的ETag或Content-MD5下载完成后用MessageDigest边写文件边算最后对比能立刻发现传输损坏二是做分片上传支持超大文件超过10GB走分段上传每段用独立的HttpClient请求服务端再合并这是从“能用”到“能扛住生产流量”的关键一步。JDK17的HttpClient虽然不是无所不能但大文件传输这块它完全够用了。