[!info] 关联笔记

• 所属 MOC：标准库 · Web · 学习路线
• 前置概念：HTTP 服务 · 异常
• 后续概念：CompletableFuture · 可观测
• 容易混淆：旧 HttpURLConnection

Java HttpClient

这个概念为什么出现

服务常调用下游 HTTP API。JDK 11+ java.net.http.HttpClient 提供现代客户端，减少对第三方的基础依赖。

[!abstract] 一句话理解 HttpClient + HttpRequest + HttpResponse 发送 HTTP；应设置超时、处理非 2xx，并避免在错误线程模型上阻塞。

最小可运行示例

场景：调用本机健康检查（需服务已启动时才成功）

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class HealthClient {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(2))
                .build();
        HttpRequest req = HttpRequest.newBuilder(URI.create("https://example.com"))
                .timeout(Duration.ofSeconds(3))
                .GET()
                .build();
        try {
            HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
            System.out.println(resp.statusCode());
        } catch (Exception ex) {
            System.out.println("call-failed: " + ex.getClass().getSimpleName());
        }
    }
}

javac HealthClient.java && java HealthClient

期望：打印状态码或 call-failed: ...（视网络环境）。

结合场景再看三个关注点

1. 超时必设。
2. 非 2xx 仍可能不抛，要检查 status。
3. 异步 sendAsync 返回 CF。

核心概念与准确模型

1. 不可变请求构建器

2. BodyHandlers/BodyPublishers

3. 重定向与版本 HTTP/2

边界情况与反直觉行为

1. 代理与 TLS 信任库。
2. 大下载要流式 handler。
3. 取消与中断。

常见误区

[!warning] 常见误区：忽略状态码只读 body 错误页 HTML 会被当成功解析。

工程实践

1. 统一客户端配置（超时、指标）。
2. 重试只对幂等。
3. 传播 correlation id 头。
4. 契约测试下游。

本节总结

• JDK 现代 HTTP 客户端
• 超时+状态码
• 同步/异步可选

自测题

1. connectTimeout 与 request timeout 差别直觉？
2. 何时用 sendAsync？

参考答案

1. 连接建立限制 vs 整个请求/响应等待限制（实现细节以文档为准）。
2. 需要非阻塞组合多个下游调用时。

延伸阅读与资料来源

资料	类型	支撑内容
HttpClient API	API	客户端