Java HttpClient 怎样用 sendAsync 读取异步响应

我第一次把 Java HttpClient 从同步调用改成异步调用时，最容易混淆的是：sendAsync 不会直接返回 HttpResponse，它返回的是一个代表“未来响应”的 CompletableFuture。真正的响应体类型由 BodyHandler 决定，成功、HTTP 状态异常和网络异常也应该在不同位置处理。

最小写法可以概括为：构造 HttpRequest，调用 client.sendAsync(request, BodyHandlers.ofString())，再通过 thenApply、thenAccept 或 exceptionally 连接后续动作。这样既能读取正文，也不会为了拿结果立刻阻塞当前线程。

先把 sendAsync 的返回值看成一条结果管道

sendAsync 的返回类型通常写成 CompletableFuture>。外层 future 表示请求何时完成，内层 response 才包含状态码、响应头和正文。BodyHandlers.ofString() 则决定正文以字符串形式交给后续阶段。

用 BodyHandlers.ofString 读取文本响应

下面的例子把异步结果继续映射成一段业务文本。代码中的中文注释说明了请求、响应体类型和异常入口，方便直接改成自己的接口调用。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.concurrent.CompletableFuture;

public class AsyncHttpExample {
    public static void main(String[] args) {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://example.com/data"))
                .GET()
                .build();

        // BodyHandlers.ofString 决定响应体以 String 形式交给 future。
        CompletableFuture> future =
                client.sendAsync(request, HttpResponse.BodyHandlers.ofString());

        future.thenAccept(response -> {
            // HTTP 4xx/5xx 不会自动变成异常，必须主动检查状态码。
            int status = response.statusCode();
            if (status >= 200 && status  {
            // 连接失败、解析失败或回调抛错会从这里进入异常分支。
            System.err.println("异步请求失败：" + error.getMessage());
            return null;
        });
    }
}

这里的关键不是把代码写成一行，而是保留类型边界：BodyHandler 处理响应体，HttpResponse 提供 HTTP 元数据，CompletableFuture 负责把完成事件传递给下一段逻辑。

不要把 HTTP 非 2xx 当成网络异常

Java HttpClient 能顺利完成一次 HTTP 交换，并不代表业务请求成功。服务器返回 404 或 503 时，future 仍可能正常完成，只是 response.statusCode() 不是 2xx。因此状态码判断应放在成功分支里；只有连接中断、DNS 失败、响应体处理失败等情况，才会进入异常完成分支。

如果业务层希望把非 2xx 也转换为异常，可以在 thenApply 中显式抛出自定义异常，再由后面的 exceptionally 或 handle 统一收口：

CompletableFuture bodyFuture = client
        .sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(response -> {
            // 业务层主动把 HTTP 错误转换成异常，避免下游误用错误正文。
            if (response.statusCode() = 300) {
                throw new IllegalStateException("HTTP 状态码：" + response.statusCode());
            }
            return response.body();
        })
        .exceptionally(error -> {
            // 统一提供降级文本；生产代码也可以记录结构化错误后继续抛出。
            return "请求未得到可用正文";
        });

thenApply、thenAccept 和 handle 各自放什么

我的经验是把 future 链按“是否产生新值”来分：需要把响应变成 DTO、字符串或业务对象时用 thenApply；只记录日志、更新指标或发送事件时用 thenAccept；同时关心成功值和失败原因时用 handle。不要在每一层都调用 join，否则异步调用很快又变成了隐藏的同步等待。

什么时候可以 join，什么时候应该继续异步

在 Web 请求、消息消费或批量并发任务中，通常应继续返回 CompletableFuture，让上层决定如何组合多个请求。只有在明确的同步边界，例如命令行程序即将退出、测试方法需要拿到最终值、或旧接口只能返回普通对象时，才考虑 join 或 get。如果必须等待，至少要把等待放在边界层，而不是放进每个回调。

另一个容易忽略的点是生命周期：sendAsync 已经把请求交给 HttpClient 的异步执行机制，回调中不要重复发起无条件递归请求，也不要把完整响应和大对象长期挂在全局集合里。需要并发控制、超时或重试时，应在 future 链外部明确建模，而不是假设 API 会自动帮你完成。

一张表记住排查顺序

最后的判断

Java HttpClient 的 sendAsync 适合把“发请求”和“处理结果”拆开：先用 BodyHandler 确定响应体形态，再用 CompletableFuture 表达成功值、HTTP 状态和异常路径。只要不把 join 到处散落，并在业务层主动检查非 2xx，异步响应处理就会保持清晰。

相关问题：

• 为什么 Java HttpClient 返回 500 时没有自动抛异常？
• sendAsync 的响应正文应该选择字符串还是字节数组？
• 多个 Java HttpClient 异步请求怎样组合后再处理？

官方 API 参考：https://docs.oracle.com/en/java/javase/24/docs/api/java.net.http/java/net/http/HttpClient.html