jdk-httpClient-demo/doc.md

JDK HTTP Client 使用教程

本文档基于 JDK 自带模块 java.net.http（Java 11+，本项目使用 Java 17）编写， 围绕本机运行的 User Management API（http://localhost:8080）进行实战演示。 每个知识点均包含：示例代码、JUnit 测试、文字说明。

运行示例/测试前，请确保 API 服务已在本机 8080 端口启动。

---

一、快速入门：请求的构造 与 响应处理

1.1 文字说明

HTTP Client 的基本使用流程只有一步：构造请求并发送。核心 API 有三个：

类	职责
java.net.http.HttpClient	HTTP 客户端，负责发送请求、管理连接
java.net.http.HttpRequest	请求对象，描述 URI、方法、请求头、请求体
java.net.http.HttpResponse<T>	响应对象，携带状态码、响应头和响应体

最小化流程分四步：

1. 创建客户端：HttpClient.newHttpClient() 用 JDK 默认配置创建实例；
2. 构造请求：HttpRequest.newBuilder().uri(...).GET().build() 链式构建；
3. 发送请求：client.send(request, BodyHandlers.ofString()) 同步阻塞发送；
4. 处理响应：通过 HttpResponse 获取 statusCode()、body() 等。

注意：send() 会抛出 IOException（IO 失败）和 InterruptedException（线程被中断）， 需要显式处理或向上抛出。

1.2 示例代码

见 QuickStart.java，核心代码如下：

// 1. 创建 HttpClient：newHttpClient() 使用 JDK 默认的配置创建一个客户端
HttpClient httpClient = HttpClient.newHttpClient();

// 2. 构造请求：HttpRequest.newBuilder() 返回一个 Builder，链式配置请求
HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(BASE_URL + "/api/users"))  // 设置请求的目标地址
        .GET()                                     // 指定请求方法为 GET
        .build();                                  // 结束构建，返回不可变对象

// 3. 发送请求：send() 同步阻塞，BodyHandlers.ofString() 将响应体转为字符串
HttpResponse<String> response =
        httpClient.send(request, HttpResponse.BodyHandlers.ofString());

// 4. 处理响应
System.out.println("HTTP 状态码: " + response.statusCode());
System.out.println("响应体: " + response.body());

1.3 测试代码

见 QuickStartTest.java。测试会真实调用本地 API，运行后控制台打印响应结果。 （测试目标：GET http://localhost:8080/api/users，正常情况下返回 {"code":200,"message":"OK","data":[...]}）