Java HttpClient 上传文件时怎么构造 multipart 请求体

用 Java 11 之后的 HttpClient 上传文件时，最容易漏掉的不是 POST 方法，而是 multipart 的边界字节。JDK 没有提供一个现成的 multipart 表单构造器，需要把每个字段的头、CRLF、文件内容和结束边界拼成一个 BodyPublisher，再把完整的 boundary 放进 Content-Type。

小文件可以用已知长度的字节段加 BodyPublishers.ofFile，通过 BodyPublishers.concat 让 HttpClient 计算完整请求体长度；大文件则使用 ofInputStream，重点是 Supplier 在重试时必须重新打开文件。不要手动设置 Content-Length。

先把 multipart 请求拆成可计算的几段

一个文件上传请求至少包含四类字节：边界和字段头、字段值、文件字段头、文件内容，最后再追加关闭边界。各段之间不是靠 Java 字符串的换行随意连接，而是用 \r\n。文本头建议用 UTF-8 转成字节，文件本身保持原始字节，不要先转成字符串。

下面的辅助方法把一段表单头编码为字节。示例只处理普通文件名；如果文件名来自用户输入，还应先限制控制字符，避免把引号或换行带入字段头。

static byte[] utf8(String value) {
    // 所有 multipart 头和文本字段统一使用 UTF-8，避免平台默认编码造成长度偏差
    return value.getBytes(StandardCharsets.UTF_8);
}

static byte[] filePartHeader(String boundary, String field, String filename) {
    // 头部末尾的两个 CRLF 把字段头与真正的文件字节隔开
    String header = "--" + boundary + "\r\n"
            + "Content-Disposition: form-data; name=\"" + field
            + "\"; filename=\"" + filename + "\"\r\n"
            + "Content-Type: application/octet-stream\r\n\r\n";
    return utf8(header);
}

用 BodyPublishers.concat 保留文件流和长度信息

当文件不大、可以接受读取到内存时，ofByteArray 最简单；但上传文件更适合让 ofFile 单独发布文件段。JDK 文档说明，concat 只有在所有子发布器都报告已知长度时才报告已知总长度，所以前缀、文件和后缀都应选择长度可确定的发布器。

static HttpRequest.BodyPublisher multipart(Path file, String description)
        throws IOException {
    String boundary = "----JavaHttpClient" + UUID.randomUUID();
    String filename = file.getFileName().toString();

    // 文本字段、文件字段头和结束边界都是可计算长度的字节段
    byte[] descriptionPart = utf8("--" + boundary + "\r\n"
            + "Content-Disposition: form-data; name=\"description\"\r\n\r\n"
            + description + "\r\n");
    byte[] fileHeader = filePartHeader(boundary, "file", filename);
    byte[] closing = utf8("\r\n--" + boundary + "--\r\n");

    // ofFile 不把整份文件读入 byte[]，concat 仍能得到完整请求体的长度
    return HttpRequest.BodyPublishers.concat(
            HttpRequest.BodyPublishers.ofByteArray(descriptionPart),
            HttpRequest.BodyPublishers.ofByteArray(fileHeader),
            HttpRequest.BodyPublishers.ofFile(file),
            HttpRequest.BodyPublishers.ofByteArray(closing));
}

// 调用处必须复用同一个 boundary，不能重新生成一个
String boundary = "----JavaHttpClient" + UUID.randomUUID();

实际代码中应让方法同时返回 boundary 和 publisher，避免调用处重新生成。为了把结构写完整，可以使用一个小的记录类型：

record MultipartBody(String boundary, HttpRequest.BodyPublisher publisher) {}

static MultipartBody buildMultipart(Path file, String description) {
    // boundary 只生成一次，Content-Type 与请求体共同使用它
    String boundary = "----JavaHttpClient" + UUID.randomUUID();
    byte[] prefix = utf8("--" + boundary + "\r\n"
            + "Content-Disposition: form-data; name=\"description\"\r\n\r\n"
            + description + "\r\n"
            + "--" + boundary + "\r\n"
            + "Content-Disposition: form-data; name=\"file\"; filename=\""
            + file.getFileName() + "\"\r\n"
            + "Content-Type: application/octet-stream\r\n\r\n");
    byte[] suffix = utf8("\r\n--" + boundary + "--\r\n");
    // 三个发布器长度已知，HttpClient 可以据此处理完整请求体长度
    HttpRequest.BodyPublisher body = HttpRequest.BodyPublishers.concat(
            HttpRequest.BodyPublishers.ofByteArray(prefix),
            HttpRequest.BodyPublishers.ofFile(file),
            HttpRequest.BodyPublishers.ofByteArray(suffix));
    return new MultipartBody(boundary, body);
}

Content-Length 为什么不能手动硬塞

HttpRequest.Builder 会限制部分请求头，content-length 就属于默认不能由用户代码直接设置的名称。这里不应该用 header("Content-Length", ...) 与客户端抢控制权；要做的是让 BodyPublisher 正确报告长度。若某个子发布器长度未知，concat 的总长度也会变成未知。

请求构造可以这样写：

MultipartBody multipart = buildMultipart(Path.of("report.txt"), "月度报表");
HttpRequest request = HttpRequest.newBuilder(URI.create("https://upload.example.test/files"))
        // boundary 必须与 buildMultipart 返回的值逐字一致
        .header("Content-Type", "multipart/form-data; boundary=\""
                + multipart.boundary() + "\"")
        .POST(multipart.publisher())
        .build();

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

如果文件很大，或者不希望 concat 维护多个已知段，可以把前缀、文件和后缀包装进 ofInputStream(() -> ...)。这种发布器的长度通常未知，Supplier 也不能只返回一个已经读过的流：请求重试或重复发送时必须重新创建新的输入流。代价是客户端无法提前得到完整长度，服务端和中间代理需要接受这种传输方式。

常见问题

为什么服务端说缺少 file 字段？

先看字段名是否与接口约定一致，再检查每个边界前的 --、头部后的空行和最后的 --boundary-- 是否完整。

为什么自己计算的 Content-Length 总是不对？

长度按字节计算，不按 Java 字符数计算；中文字段、文件头和每个 CRLF 都要计入，文件本身则使用实际字节数。

能不能把 Content-Type 写成固定值？

不能省略 boundary。应使用 multipart/form-data; boundary="实际边界"，并确保它和请求体内的值完全相同。

这类上传问题的定位顺序很固定：先核对 boundary，再核对 CRLF 和文件字段头，最后判断 BodyPublisher 是否能报告准确长度。把协议分段和长度策略分开处理，HttpClient 的请求构造就不会再靠猜。