Java HttpClient BodyHandlers.ofInputStream 何时更合适

如果 Java HttpClient 的响应可能很大，而且业务不需要把完整内容一次性装进内存，BodyHandlers.ofInputStream() 通常比 ofString() 或 ofByteArray() 更合适。它把响应体交给一个可读取的 InputStream，调用方可以边读边写文件、解压或交给自己的解析器；代价是流的关闭和消费责任也转到了调用方。

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

先按响应处理方式选择 BodyHandler

这几个 handler 的区别不在于“哪个更高级”，而在于 body 最终要交给谁。小 JSON 需要立即转成文本时，ofString() 直观；小型二进制且确实要一次性处理时，ofByteArray() 简单；目标是文件时，ofFile(path) 可以直接写入；只有当业务需要自己控制读取节奏、边读边处理或在流上叠加解压/校验时，ofInputStream() 才更有价值。

ofInputStream 返回的是可继续消费的响应流

ofInputStream() 的返回类型是 BodyHandler。使用同步 send 时，先拿到响应对象和响应头，再从 body() 取得流。状态码判断应该放在读取前：非 2xx 响应也可能带有 body，不能因为直接返回错误就把这个流遗留在连接上。

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;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com/archive.zip"))
        .GET()
        .build();

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

if (response.statusCode() / 100 != 2) {
    // 非成功响应也要关闭 body，避免把未消费的交换留在连接上。
    response.body().close();
    throw new IllegalStateException("HTTP status: " + response.statusCode());
}

Path target = Path.of("archive.zip");
try (InputStream in = response.body();
     OutputStream out = Files.newOutputStream(target)) {
    // 固定大小缓冲区只负责搬运，不把整个响应读进 byte[]。
    in.transferTo(out);
}

这个写法的关键不是 transferTo 本身，而是把 response.body() 放进资源管理范围。即使复制过程中抛出 IOException，InputStream 仍会执行关闭。若业务要先读取少量头部再决定是否继续，也要在放弃时显式关闭，而不是把引用丢掉。

异步场景也要把流的生命周期接完整

换成 sendAsync 不会自动替你消费 body。使用 ofInputStream() 时，异步结果可以在响应头可用后交付 HttpResponse，后续读取仍然是你的工作。可以在异步回调中把流交给一个明确的消费函数，但不要让流逃逸到无人负责的队列。

client.sendAsync(request, HttpResponse.BodyHandlers.ofInputStream())
        .thenAccept(response -> {
            // 回调拥有 body 的关闭责任；失败分支也不能跳过 close。
            try (InputStream in = response.body()) {
                if (response.statusCode() / 100 != 2) {
                    return; // try-with-resources 仍会关闭错误响应 body。
                }
                in.transferTo(OutputStream.nullOutputStream());
            } catch (java.io.IOException e) {
                throw new java.io.UncheckedIOException(e);
            }
        });

如果只是下载到固定文件，异步版本可以直接考虑 BodyHandlers.ofFile(path)，让 handler 完成写文件；如果需要限速、校验摘要、解压或解析增量记录，才保留 InputStream 这层控制。生产代码还应保存并观察 CompletableFuture 的异常，而不是让回调中的异常无人读取。

用四个检查点验收选择

• 响应可能超过内存预算，且业务可以逐块处理：选择 ofInputStream()，不要用 ofByteArray() 伪装成流式。
• 目标只是把 body 写入一个文件：优先比较 ofFile() 与自定义流逻辑，确认是否真的需要中间处理。
• 所有成功、失败、提前返回和异常路径都能关闭 body：把关闭动作放进 try-with-resources。
• 异步读取有明确的拥有者和完成信号：记录 future 的异常，并确认消费者读完或关闭流。

相关问题

ofInputStream 会不会自动把整个响应读进内存？

它把响应体暴露为流供调用方消费，适合避免一次性聚合；但实际内存仍受客户端缓冲、你的读取缓冲和后续处理方式影响，不能把它理解成零内存。

只读取前几 KB 后返回可以吗？

可以，但返回前必须关闭流。是否能复用底层连接由实现和剩余 body 处理决定，代码不要依赖“丢掉引用就会自动清理”。

什么时候直接用 ofFile 更省心？

当响应只需要落到一个路径，不需要自定义解压、摘要校验或增量解析时，ofFile() 能减少手写复制和资源管理代码。