HttpClient headers 怎样读取响应头

Java 11 及以上的 HttpClient，读取响应头的入口不是响应体，而是 HttpResponse.headers()。它返回一个只读的 HttpHeaders，再按“只要一个值”“保留所有值”或“遍历完整集合”选择对应方法。

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

最小写法是 response.headers().firstValue("Content-Type")；如果一个头可能出现多次，用 allValues，不要把多值头强行当成一个字符串。

先确认读取入口：response.headers()

发送请求后，响应对象同时承载状态码、响应头和响应体。响应头的类型是 HttpHeaders，因此不需要把原始 HTTP 文本重新切行解析。

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create("https://example.com/api"))
        // 只设置请求端需要的媒体类型，响应头要从 HttpResponse 读取
        .header("Accept", "application/json")
        .GET()
        .build();

HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
HttpHeaders headers = response.headers();

// 状态码、响应头和响应体分别读取，避免把响应体当成头部来源
System.out.println(response.statusCode());
System.out.println(headers.firstValue("Content-Type").orElse("未返回 Content-Type"));

这里的 headers 是只读视图，适合查询，不适合通过 put 或 remove 修改服务器已经返回的内容。若需求是发送请求头，应在 HttpRequest.Builder 上设置，而不是修改响应头。

单值用 firstValue，多值用 allValues

很多响应头通常只有一个值，例如 Content-Type。这时 firstValue 返回 Optional，缺失时不会直接抛空指针。

// 单值读取：缺失响应头时给出明确的业务默认值
String contentType = headers.firstValue("Content-Type")
        .orElse("application/octet-stream");

// 可能重复出现的头保留所有值，不在客户端擅自拼接
List cookies = headers.allValues("Set-Cookie");
for (String cookie : cookies) {
    // Cookie 可能携带敏感信息，日志中只记录是否存在，不直接打印完整值
    System.out.println("收到一个 Set-Cookie 响应头");
}

allValues 返回不可修改的列表。HttpHeaders 不会替你把逗号分隔的字段值拆开，也不会把多次出现的字段自动合并；协议语义需要由具体头字段决定。

需要完整遍历时使用 map()

调试接口或记录诊断摘要时，可以读取 headers.map()。它是 Map> 的不可修改视图，每个名称对应一个值列表。

// 遍历完整头集合：保留一个名称对应多个值的形态
for (Map.Entry> entry : headers.map().entrySet()) {
    // 生产日志应按字段白名单脱敏，示例只输出名称和值数量
    System.out.printf("%s: %d 个值%n", entry.getKey(), entry.getValue().size());
}

按名称查询时，firstValue、allValues 以及 map 的读取都不区分头名称大小写，所以 Content-Type 和 content-type 查询结果一致。map 的条目顺序不应被当成协议顺序。

响应头为空时怎样排查

如果读取不到值，先按下面的顺序定位：确认请求确实拿到了 HttpResponse；确认查询的是响应头而不是请求头；确认头名称拼写正确；最后确认服务端是否真的返回了该字段。

• 缺失头：firstValue 得到空的 Optional，按业务决定默认值或返回错误。
• 重定向：若客户端跟随重定向，response 是最终响应；需要检查中间响应时，再查看 previousResponse()。
• 敏感字段：Set-Cookie、授权相关字段不要原样写入日志，只保留存在性、数量或脱敏摘要。
• 异步请求：sendAsync 完成后仍然从得到的 HttpResponse 调用同一组方法，读取规则不变。

一张表记住三个方法

记忆方式很简单：一个值看 firstValue，多个值看 allValues，全部字段看 map。不要为了“方便”把多值头拼成单字符串，也不要把只读响应头视图当成请求构造器使用。

相关问题

HttpHeaders 的名称区分大小写吗？

通过名称查询时不区分大小写，但不要依赖 map 条目的排列顺序。

为什么 firstValue 返回 Optional？

因为服务器可能没有返回该字段，使用 Optional 可以把缺失情况显式交给调用方处理。

能不能修改 response.headers()？

不能把它当成可变集合修改。要改变发出的请求头，请回到 HttpRequest.Builder 构造请求。