Java HttpRequest 怎样用 BodyPublishers.ofInputStream 延迟产生请求体

如果请求体来自文件、管道或临时生成的数据，BodyPublishers.ofInputStream 的关键不是“把一个流传进去”，而是“把能够打开流的 Supplier 传进去”。这样请求真正需要发送正文时才取得输入流；如果一次请求需要重新提供正文，Supplier 还必须能再次返回一个新的流。

官方文档地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.net.http/java/net/http/HttpRequest.BodyPublishers.html

最小可靠写法是把 Files.newInputStream(path) 放进 Supplier，而不是在构造 HttpRequest 前打开一个只允许消费一次的 InputStream。Supplier 返回 null 或重复复用旧流，都可能让重发请求失败。

问题现场：请求还没发送，文件流已经被打开

常见的错误写法是先打开文件，再把这个流包装到自定义发布器里。它把“准备请求”和“真正读取请求体”混成了一个时机：请求可能稍后才发送，文件句柄却从构造阶段开始占用；一旦底层需要重新尝试，已经到达 EOF 或已经关闭的流也不能代表完整正文。

Oracle 的 API 将 ofInputStream 定义为从 InputStream 读取请求体，并明确使用 Supplier 是因为请求内容没有缓存，重复请求时需要再次取得流。因此修复点应落在流的提供方式，而不是给同一个流多包一层。

最小修复：把打开流的动作放进 Supplier

下面的例子用文件作为请求体。Supplier 每次被调用时才尝试打开文件；打开失败时抛出明确的 UncheckedIOException，让调用方能够从异常链中看到真实原因。

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

Path payload = Path.of("payload.json");

HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.example.test/import"))
        .header("Content-Type", "application/json")
        // Supplier 只描述如何取得新流，不在构造请求时提前占用文件句柄。
        .POST(HttpRequest.BodyPublishers.ofInputStream(() -> {
            try {
                // 每次调用都从文件起点打开一个新的 InputStream。
                return Files.newInputStream(payload);
            } catch (IOException e) {
                // 保留原始 IOException，避免把文件错误伪装成网络错误。
                throw new UncheckedIOException("无法打开请求体文件: " + payload, e);
            }
        }))
        .build();

HttpResponse response = HttpClient.newHttpClient()
        // BodyHandlers.ofString 只负责响应体，不负责请求体的 InputStream。
        .send(request, HttpResponse.BodyHandlers.ofString());

这里的核心关系是：HttpRequest 持有一个 BodyPublisher，而 BodyPublishers.ofInputStream 用 Supplier 描述如何取得流。它不是把已经打开的流存进请求对象，而是保留“需要时如何打开”的规则。

触发条件：Supplier 为什么必须能够再次返回新流

InputStream 通常是一次性消费对象。第一次读取后，游标已经移动；关闭之后，它更不能被当成第二次请求的正文。ofInputStream 的 API 说明也指出，内容不缓存时，如果请求需要重复，Supplier 会被再次使用；后续返回 null 会使请求失败。

因此 Supplier 应该是可重复调用的工厂，而不是保存一个共享流的容器：

Path payload = Path.of("payload.json");

HttpRequest.BodyPublisher publisher = HttpRequest.BodyPublishers.ofInputStream(() -> {
    try {
        // 这个 lambda 不捕获已经打开的流，而是每次创建独立流。
        return Files.newInputStream(payload);
    } catch (IOException e) {
        // Supplier 没有 throws IOException，使用 unchecked 异常传递打开失败。
        throw new UncheckedIOException(e);
    }
});

HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.example.test/import"))
        // BodyPublisher 可以被放入 POST 或 PUT 请求，但正文来源仍由 Supplier 管理。
        .PUT(publisher)
        .build();

不要把下面这种写法当成可重试方案：

InputStream shared = Files.newInputStream(payload);

// 错误示例：所有尝试都拿同一个共享流，第一次消费后无法代表完整正文。
HttpRequest.BodyPublisher broken = HttpRequest.BodyPublishers.ofInputStream(() -> shared);

如果业务明确只发送一次，且你能控制关闭责任，短生命周期代码也许不会立刻暴露问题；但只要存在重定向、重发策略、异步延后发送或多个调用方共享请求对象，就不应依赖这种偶然性。

根因拆解：延迟打开不等于自动替你兜底

把打开动作放进 Supplier 解决了时机问题，但它不会自动解决所有资源问题。Supplier 返回的流由发布过程消费；代码应确保异常路径不会把文件描述符长期留在外面。不要在 Supplier 外部保存每次返回的流，也不要用一个可变字段在调用之间偷偷复用。

如果正文来自临时文件，建议让文件生命周期覆盖所有可能的发送尝试，再在请求完成或失败后清理临时文件。若正文来自网络管道或压缩流，还要明确上游是否允许重新打开；不能重新获取的来源不适合直接承诺可重复发送。

HttpClient 本身也应尽量复用。Oracle 文档说明客户端通常管理自己的连接池，反复创建客户端会妨碍连接复用；这和请求体 Supplier 是两层生命周期：前者管理客户端连接资源，后者管理单个请求的字节来源。

选型对照：ofInputStream、ofFile 和 ofByteArray 怎么选

如果只需要从固定路径发送文件，ofFile 往往更直接；如果需要在发送时选择文件、生成流或控制打开失败处理，ofInputStream 更灵活。不要因为“流式”三个字就默认它会降低内存或自动支持重试，实际边界取决于 Supplier 返回的来源。

修复后的落地清单

• 请求构造阶段没有提前打开并长期持有一个共享 InputStream。
• Supplier 每次调用都能从稳定来源取得新的流，或者明确声明请求不可重复。
• 打开失败保留原始异常；不要把文件读取错误包装成模糊的 HTTP 状态错误。
• 临时文件、文件句柄、压缩流和上游管道的生命周期都覆盖实际发送过程。
• 固定文件优先比较 ofFile，小型内存正文再考虑 ofByteArray。
• HttpClient 在应用范围内复用，避免每个请求创建一个新客户端。

相关问题

Supplier 返回 null 会怎样？

官方 API 说明后续尝试中返回 null 可能导致请求失败。应让 Supplier 在无法打开时抛出带原始原因的异常，而不是用 null 隐藏失败。

ofInputStream 会把整个文件读进内存吗？

它描述的是从 InputStream 读取请求体，并不等于调用方已经把整个文件放入字节数组。内存、缓冲和重复发送能力仍取决于底层流和客户端实现边界。

只发送一次还需要 Supplier 吗？

如果使用该 API，就仍应传入 Supplier；即使业务当前只发一次，也应保持“调用时打开、用完释放”的结构，避免未来增加异步或重发逻辑时埋下共享流问题。