Java 11+ HTTPClient如何正确设置Content-Length请求头

异常触发的核心原因 #

• Java 11及以上版本内置的java.net.http.HttpClient对部分请求头做了硬管控，Content-Length、Transfer-Encoding属于明确标记的受限请求头，不允许用户手动通过.header()、.setHeader()方法设置，否则直接抛出“受限请求头名称”异常，这是客户端的设计限制，不是代码逻辑错误。
• 原代码本身存在HTTP规范层面的冲突：同时手动设置Transfer-Encoding: chunked和Content-Length两个互斥头。分块传输（chunked）的设计初衷就是适配请求体长度未知的场景，启用该传输模式时本身就不应该携带Content-Length头，这种头组合本身就会被合规服务端拒收。
• 删除Content-Length设置后抛出缺少头的异常，本质是保留的Transfer-Encoding: chunked让客户端切换到分块传输模式，不会自动生成Content-Length头，而你的目标服务端不支持分块传输、强制要求请求必须携带Content-Length，才会触发IO错误。

正确实现方式 #

内置HttpClient的设计逻辑是，Content-Length头的计算与设置完全由对应的BodyPublisher自动完成，用户不需要也不允许手动干预。你只需要移除所有手动设置的冲突头即可：

1. 删除手动设置Content-Length的代码行
2. 删除手动设置Transfer-Encoding: chunked的代码行
3. 使用的HttpRequest.BodyPublishers.ofByteArray(file)实现，本身会自动读取传入字节数组的总长度，在发送请求时自动写入正确的Content-Length头。

修正后的可运行代码如下：

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("目标请求URL"))
        .header("Content-Type","application/pdf")
        .header("Authorization",String.format("Token token=%s",token))
        .POST(HttpRequest.BodyPublishers.ofByteArray(file))
        .build();

特殊场景的适配 #

如果后续遇到需要手动指定请求体长度的自定义流式传输场景，不要尝试通过反射等方式绕开受限头的管控（Java模块化系统会拦截这类操作），可以直接自定义实现BodyPublisher接口，重写contentLength()方法返回你计算好的固定长度，内置客户端会自动根据这个返回值写入正确的Content-Length头，全程不需要手动设置受限头。

关于你提到的第三方库表现差异：

• Apache HttpClient对请求头的管控逻辑更宽松，允许用户手动设置Content-Length，原代码迁移到该客户端后可以直接正常运行
• OkHttp的请求头管控逻辑和内置HttpClient类似，会自动校验头的合法性，遇到手动设置的冲突头组合时会拦截抛出异常，因此你之前的代码在OkHttp上无法正常运行

内容的提问来源于stack exchange，提问作者Michael S