Java BodyHandlers.ofFileDownload 怎样按响应头命名文件

如果下载接口返回的文件名由服务端决定，Java HttpClient 不需要先把响应读成字节数组再自己拼路径。HttpResponse.BodyHandlers.ofFileDownload(directory, openOptions) 会把目录交给客户端，把文件名交给响应头中的 Content-Disposition，最终通过 HttpResponse 返回保存后的路径。

官方文档：https://docs.oracle.com/en/java/javase/25/docs/api/java.net.http/java/net/http/HttpResponse.BodyHandlers.html#ofFileDownload(java.nio.file.Path,java.nio.file.OpenOption...)

最小可用结论：下载目录必须已经存在且可写；服务端的 Content-Disposition 需要包含 attachment 和 filename。响应返回时文件体已经写完，response.body() 就是最终的 Path。

先把目录、文件名和返回值分开

这个 BodyHandler 处理的是“响应体落盘”，不是完整的 HTTP 业务校验。目录由调用方传入，文件名由服务端响应头提供，返回值是组合后的路径。这样做适合报表、归档包或导出文件下载，调用代码不必猜测后缀，也不必把整个响应先放进内存。

用 ofFileDownload 保存服务端命名的文件

下面的示例只展示客户端侧的关键边界。假设服务端返回类似 Content-Disposition: attachment; filename="weekly-report.csv"，客户端只指定下载目录，不手写文件名。

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 DownloadByResponseName {
    public static void main(String[] args) throws Exception {
        // 目录由客户端控制，先创建目录，避免 BodyHandler 因目录不存在而失败。
        Path downloadDir = Path.of("downloads");
        Files.createDirectories(downloadDir);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                // 示例地址只代表一个下载接口，实际项目应替换为自己的 HTTPS 地址。
                .uri(URI.create("https://example.com/export/report"))
                .GET()
                .build();

        HttpResponse response = client.send(
                request,
                // 文件名从 Content-Disposition 读取，目录仍由本地参数指定。
                HttpResponse.BodyHandlers.ofFileDownload(
                        downloadDir,
                        StandardOpenOption.CREATE,
                        StandardOpenOption.WRITE));

        // BodyHandler 不替业务判断状态码；先判断状态，再使用已写完的最终路径。
        if (response.statusCode() / 100 != 2) {
            throw new IllegalStateException("下载接口返回 HTTP " + response.statusCode());
        }
        System.out.println("文件已保存：" + response.body());
    }
}

这里的泛型很重要：ofFileDownload 返回的是 BodyHandler，所以响应体类型不是字符串或字节数组。成功返回时，response.body() 指向下载目录下由服务端提供的最终文件名。

为什么文件名来自响应头而不是 URL

ofFileDownload 要求 Content-Disposition 指定附件类型，并同时包含 filename 参数。URL 的最后一段不会自动成为目标文件名；如果服务端只返回普通页面、缺少文件名参数，客户端就不能按这个 Handler 完成预期的命名下载。

官方实现还会把文件名中的多级路径只取最后一个组成部分，再与调用方提供的目录组合。因此调用方的责任是准备受控目录并记录最终返回路径，不要根据服务端字符串重新拼接任意本地路径。

OpenOption 和失败边界怎么处理

第二个参数可以传入文件打开选项，但必须和文件创建语义匹配。最小示例使用 CREATE 与 WRITE，让目标文件在不存在时创建并写入。传入无效组合会触发 IllegalArgumentException；目录不存在、不是目录、不可写或无法创建目标文件时，则会以文件 I/O 异常结束响应处理。

还要注意，预定义 BodyHandler 不负责检查 HTTP 状态码。服务端即使返回 404 或 500，响应体仍可能被按文件处理，所以应用层要先用 statusCode() 判断业务成功，再把返回路径交给后续流程。

• 下载前：确认目录存在、是默认文件系统中的目录并且可写。
• 下载中：让服务端提供 attachment 和 filename，不把 URL 末段当成可靠文件名。
• 下载后：先判断状态码，再记录 response.body() 返回的最终路径。

常见问题

目录不存在时会自动创建吗？

不会把不存在的下载目录当成正常目标。调用前用 Files.createDirectories 创建，并在生产代码中处理权限或磁盘异常。

能否固定保存为自定义文件名？

如果文件名由客户端固定，应改用 BodyHandlers.ofFile(file)。需要使用服务端命名时才选择 ofFileDownload。

返回 Path 时文件还在下载吗？

对这个 Handler 来说，响应返回时文件体已经写入完成；如果需要边接收边处理，应重新评估 ofInputStream 或自定义 BodySubscriber 的生命周期。

总的判断可以压缩成一句话：固定文件名选 ofFile，服务端通过响应头命名选 ofFileDownload；无论选择哪一个，都要把 HTTP 状态判断和文件落盘异常分开处理。