HttpRequest BodyPublishers.ofFile 怎样发送本地文件

我在给 Java 服务做文件上传时，通常不会先把整个文件读进字节数组。Java HttpClient 已经提供了 HttpRequest.BodyPublishers.ofFile(Path)，可以把本地文件路径交给请求体发布器，再由 HttpRequest.Builder 组装 POST 或 PUT 请求。关键是分清：ofFile 负责请求体输入，响应文件保存则属于 BodyHandler 的另一条链路。

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

发送本地文件时，先用 Path 表示输入文件，再用 BodyPublishers.ofFile(path) 生成 BodyPublisher；文件不存在、不可读或媒体类型不匹配时，应在发送前或请求处理阶段明确处理，而不是把它当成响应下载 API。

先把文件上传的职责拆开

HttpRequest.BodyPublisher 是把高层对象转换成待发送字节流的接口。BodyPublishers.ofFile 是它的一个工厂方法，输入是 Path，输出是可以交给请求构造器的发布器。它不负责 multipart 字段名，也不负责保存服务器返回的文件；如果服务端要求 multipart/form-data，需要另外构造 multipart 请求体。

最小关系可以记成：Path → ofFile(Path) → BodyPublisher → POST/PUT。请求头中的 Content-Type 仍然由调用方根据接口约定设置，不能因为文件扩展名存在就默认推断成正确的媒体类型。

用 BodyPublishers.ofFile 把 Path 接到请求体

下面的代码展示一个普通二进制上传请求。示例只负责构造请求，不假设服务端一定返回成功；真实项目应根据接口认证、幂等性和响应码补充自己的策略。

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;

Path file = Path.of("payload.bin");

// 先检查输入文件，避免把确定性的路径错误拖到发送阶段
if (!Files.isRegularFile(file) || !Files.isReadable(file)) {
    throw new IOException("上传文件不存在或不可读: " + file);
}

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://upload.example.com/files"))
        // 媒体类型必须遵循服务端契约，不能只看文件后缀猜测
        .header("Content-Type", "application/octet-stream")
        // ofFile 把本地 Path 作为请求体来源
        .POST(HttpRequest.BodyPublishers.ofFile(file))
        .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse response = client.send(
        request,
        HttpResponse.BodyHandlers.ofString());

// 只根据状态码决定业务分支，响应体是否成功要看接口协议
if (response.statusCode() / 100 != 2) {
    throw new IOException("文件上传失败，HTTP 状态码=" + response.statusCode());
}

这里的 Files.isRegularFile 和 Files.isReadable 是发送前的快速判断，不能替代真正的异常处理：检查之后文件仍可能被删除、权限可能改变，ofFile 或发送过程仍可能出现 IOException。因此调用方要保留异常传播或转换逻辑。

请求方法、媒体类型和文件异常怎么放置

ofFile 只产生请求体，方法由 POST、PUT 或 method 决定。上传接口一般会明确要求 application/octet-stream、具体文档类型或 multipart。若把文件直接作为二进制请求体，就不要同时把它误写成 JSON 字符串；如果要上传元数据和文件，需按服务端协议组织 multipart，而不是把 ofFile 当成 multipart 自动封装器。

文件路径来自用户输入时，还应先把允许目录、文件大小和符号链接策略纳入业务约束。本文只讨论 Java API 的请求体连接，不把本地路径校验扩展成安全上传方案；但至少要记录文件读取失败，并避免把完整本地路径、令牌或响应体写进普通日志。

不要把 ofFile 和响应文件下载混为一谈

发送请求时，BodyPublisher 向 HTTP Client 提供出站字节；接收响应时，HttpResponse.BodyHandler 决定入站数据如何被处理。比如响应要写入目标文件，可以在响应侧选择相应的文件处理器。两者都出现“文件”，但方向相反：一个读取本地文件作为请求体，另一个把响应体写到本地目标。

这一区分也影响异常归属：本地输入失败属于请求准备或请求体发布问题；远端返回 4xx/5xx 属于服务器响应；响应文件写入失败则属于响应处理路径。把三类错误混成一个“上传失败”，后续排障会很困难。

按任务选择合适的 BodyPublisher

1. 已有完整本地文件：使用 BodyPublishers.ofFile(path)，让文件路径成为请求体来源。
2. 内容本来就在内存中：使用 ofString 或 ofByteArray，避免为了调用 ofFile 临时落盘。
3. 数据由流或响应式生产：评估 ofInputStream 或 fromPublisher，并额外处理可重试发送、长度和资源生命周期。
4. 服务端要求 multipart：按协议拼装 multipart 请求体，并明确边界、字段名和文件部分的媒体类型。

实践中最稳妥的顺序是：先确认服务端需要的请求体格式，再选择发布器；随后用 Path 检查输入可用性，最后根据 HTTP 状态码和接口错误体做业务判断。这样既保留了 ofFile 的简洁，也不会把一个工厂方法误认为完整上传框架。

相关问题

BodyPublishers.ofFile 会自动设置 Content-Type 吗？

不会。它只提供文件请求体；媒体类型要由请求头和服务端协议决定。

ofFile 能直接上传 multipart/form-data 吗？

不能把它当作 multipart 封装器。multipart 需要字段、边界和各部分头信息，必须按接口协议构造请求体。

怎么保存服务器返回的文件？

那是响应侧的 BodyHandler 选择，和请求侧的 BodyPublishers.ofFile 是两条不同的数据路径。