Java HttpClient 怎样流式保存大响应

Java HttpClient 保存大响应，通常不应该先用 BodyHandlers.ofString() 或 BodyHandlers.ofByteArray() 把全部内容装进内存。任务只是把响应原样写到文件时，直接选择 BodyHandlers.ofFile(target)；如果还要先判断响应头、限制大小、计算摘要或把内容交给自定义处理，就用 BodyHandlers.ofInputStream()，边读边写。

官方参考地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.net.http/java/net/http/HttpResponse.BodyHandlers.html

最小决策是：原样保存选 ofFile，需要掌控读取过程选 ofInputStream。无论哪种方式，都要检查状态码，并确保响应体最终读完或关闭。

先把“大响应”拆成两个保存场景

“流式保存”不等于必须手写一套复杂的网络循环。Java 11 引入的 java.net.http 已经提供了直接写文件的 BodyHandler。差别在于：ofFile 把文件写入交给 JDK，调用方在请求完成后拿到目标路径；ofInputStream 则把读取责任交给调用方，适合需要插入业务判断的场景。

这里的“大”不是固定的 MB 数字，而是“完整装入内存会让资源预算变得不可控”。响应大小、并发数和下游处理方式共同决定方案。即便服务端发送了 Content-Length，也不能把它当成唯一的业务安全边界。

原样落盘时直接使用 ofFile

如果目标就是把响应写成一个文件，先建立可复用的 HttpClient，再把目标路径交给 BodyHandlers.ofFile。下面的示例使用覆盖写入，避免旧文件尾部残留；状态码不在内置 handler 中自动判断，所以仍要在响应返回后处理。

import java.io.IOException;
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;
import java.time.Duration;

public final class DirectDownloader {
    private DirectDownloader() { // 工具类不保存可变状态
    }

    public static Path save(HttpClient client, URI uri, Path target)
            throws IOException, InterruptedException {
        Path parent = target.toAbsolutePath().getParent();
        if (parent != null) {
            Files.createDirectories(parent); // 先保证目标目录存在
        }

        HttpRequest request = HttpRequest.newBuilder(uri)
                .timeout(Duration.ofMinutes(2)) // 限制等待，不限制文件大小
                .GET()
                .build();

        HttpResponse response = client.send(
                request,
                HttpResponse.BodyHandlers.ofFile(
                        target,
                        StandardOpenOption.CREATE,
                        StandardOpenOption.TRUNCATE_EXISTING,
                        StandardOpenOption.WRITE));

        if (response.statusCode() / 100 != 2) {
            Files.deleteIfExists(target); // 失败响应不要留下可误用的部分文件
            throw new IOException("下载失败，HTTP 状态码: " + response.statusCode());
        }
        return response.body(); // 成功时返回实际写入的目标路径
    }
}

ofFile(file) 默认等价于使用 CREATE 和 WRITE 打开文件。这里显式加入 TRUNCATE_EXISTING，是为了覆盖已有目标时把旧内容截断。若业务需要断点续写，不能直接套用这段代码，应另行设计 Range、临时文件和校验策略。

还要注意：内置 BodyHandlers 不替你判断 HTTP 状态码。服务器返回 404 或 500 时，响应体也可能被写入目标文件，因此示例在非 2xx 后删除目标。生产环境可以改成先写同目录临时文件，成功后再原子替换，以减少消费者读到半成品的机会。

需要控制过程时改用 ofInputStream

当你要在保存前根据响应头做判断，或要同时计算摘要、限制读取量、写入多个目标，使用 ofInputStream 更直观。它在响应头已经收到后就能把 InputStream 交给调用方，随后由调用方完成复制。

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.nio.file.StandardCopyOption;
import java.time.Duration;

public final class StreamingDownloader {
    private StreamingDownloader() { // 工具类不创建实例
    }

    public static Path save(HttpClient client, URI uri, Path target)
            throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(uri)
                .timeout(Duration.ofMinutes(2)) // 连接和响应等待的上限
                .GET()
                .build();

        HttpResponse response = client.send(
                request,
                HttpResponse.BodyHandlers.ofInputStream());

        try (InputStream body = response.body()) { // 无论成功失败都释放响应流
            if (response.statusCode() / 100 != 2) {
                throw new IOException("下载失败，HTTP 状态码: " + response.statusCode());
            }

            Path parent = target.toAbsolutePath().getParent();
            if (parent != null) {
                Files.createDirectories(parent); // 只在接受响应后创建目录
            }
            Files.copy(body, target, StandardCopyOption.REPLACE_EXISTING);
            return target;
        }
    }
}

这个方案把“是否接受响应”和“怎样消费字节”分开了。Files.copy 会持续读取直到结束，不需要先把整个响应转换成 byte[]。如果中途抛出异常，目标文件可能已经是部分文件；需要给下游严格可见性的系统，应先写临时文件，复制成功后再移动到最终名称。

try-with-resources 不是装饰性写法。Oracle 文档明确要求：使用流式响应时，调用方最终要读到 EOF，或者主动关闭流；否则请求可能没有完成，连接也可能无法按预期复用。提前关闭会取消剩余读取，是否能复用底层连接取决于协议和实现。

三种处理器的响应时机有什么区别

BodyHandlers.ofFile 适合“交给 JDK 写完再继续”的路径。用它发送请求时，响应对象会在整个响应体处理完成后可用，body() 是目标 Path。它最省心，但不适合在写入前动态拒绝内容。

BodyHandlers.ofInputStream 返回的是流式响应体。收到状态码和响应头后，调用方就可以取得 InputStream，之后可以自己决定如何读取。它更灵活，也意味着你必须承担关闭、读取、错误清理和并发控制的责任。

BodySubscribers.ofInputStream() 是更底层的订阅器。如果你需要根据 ResponseInfo 自定义 BodyHandler，例如按响应头选择不同订阅器，才有必要直接使用它。普通文件下载不必为了“看起来更底层”而绕过现成的 BodyHandlers。

还有一个容易忽略的边界：如果通过 BodySubscribers.mapping 把 InputStream 映射成某种结果，不要在客户端执行器线程里做长时间阻塞读取。更稳妥的做法是把流交给调用方线程消费，或者明确配置执行器并限制并发。

把状态码、文件和资源责任放在同一层

保存逻辑至少应回答四个问题：哪些状态码算成功、目标文件是否覆盖、失败时部分文件怎么办、流由谁关闭。不要把这些决策隐藏在一个“下载成功”布尔值后面。

如果需要限制最大响应体，可以在复制循环中累计字节数，超过上限就关闭输入流并删除临时文件。这个限制属于业务安全策略，不应只依赖响应头，因为服务端可能不发送长度，或者长度与实际传输过程不一致。

按场景选择实现

可以用下面的规则快速落地：只保存就选 ofFile；需要在保存前决定接不接受就选 ofInputStream；需要自定义 Reactive Streams 订阅关系或按响应信息切换订阅器时，再考虑 BodySubscribers。

官方资料地址：https://docs.oracle.com/en/java/javase/24/docs/api/java.net.http/java/net/http/HttpClient.html；https://docs.oracle.com/en/java/javase/24/docs/api/java.net.http/java/net/http/HttpResponse.BodySubscribers.html。这些页面用于核对 API 语义，示例中的 URL 仍需由实际业务替换。

ofFile 会把整个文件先放进内存吗？

它的用途就是把响应体写入文件，不需要调用方先构造完整字符串或字节数组。真正的内存占用仍取决于 JDK 实现、缓冲和你的并发规模，但不应把它理解成“没有任何缓冲”。

为什么收到 404 也可能生成文件？

预定义 BodyHandler 主要负责消费响应体，不主动替你判断状态码。错误响应同样有响应体，所以必须在业务层检查状态码，并清理不应保留的目标文件。

InputStream 只读一部分后直接返回可以吗？

可以提前结束，但必须关闭流；这样可能牺牲底层连接复用。若希望请求自然完成，应持续读到 EOF。

每次下载都创建一个 HttpClient 可以吗？

可以工作，但官方建议复用客户端以共享其连接池。把客户端作为应用级或服务级依赖通常比每次调用临时创建更合适。