Java HttpClient 收到 404 时为什么 future 仍然正常完成

调用 Java HttpClient.sendAsync() 请求一个不存在的资源，日志里常会看到 HTTP 404，但后面的 future 仍然进入 thenApply，甚至最终显示“完成”。这不是 HttpClient 忽略了错误，而是 404 已经是服务器返回的合法 HTTP 响应；异步请求是否异常完成，判断的是请求传输、超时、取消或响应体处理有没有失败。

因此，404 要从 HttpResponse.statusCode() 读取并交给业务分支。只有当调用方的业务契约明确要求“找不到就当失败”时，才在后续阶段主动转成异常。

404 是响应结果，不是传输异常

sendAsync(request, bodyHandler) 的结果类型是 CompletableFuture>。服务器完成 HTTP 交互并返回状态行和响应头后，客户端拿到的是一个 HttpResponse；404 只是其中的状态码。官方 API 对预置 BodyHandler 的说明也明确指出，它们默认不检查状态码，响应体会继续交给对应的 BodySubscriber。

这两个概念可以这样分开：服务器明确说“资源不存在”，属于业务可判断结果；DNS 失败、连接被拒绝、请求超时或读取正文失败，才是 future 可能以异常完成的调用失败。把 404 当作网络异常，会让重试器反复请求一个本来就不存在的地址。

先保留状态码，再决定业务含义

读取文本响应时，最小可用写法是让异步链先返回一个包含状态码和正文的结果。不要在 thenApply(HttpResponse::body) 这一步过早丢掉状态码，否则后面只能看到正文，无法区分“404 页面”和“200 业务数据”。

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

record PageResult(int status, String body) {}

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com/missing"))
        .timeout(Duration.ofSeconds(5)) // 单次请求的超时边界
        .GET()
        .build();

CompletableFuture page = client
        .sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(response -> {
            // 404 仍然有响应对象，先保留状态码和正文
            return new PageResult(response.statusCode(), response.body());
        });

PageResult result = page.join();
if (result.status() == 404) {
    System.out.println("资源不存在，交给业务决定是否创建或跳过");
} else if (result.status() >= 200 && result.status() 

这里的 join() 只是等待示例结果，不代表 404 会抛异常；只要请求正常拿到响应，PageResult 就能被返回。生产代码还应记录请求 URI、状态码和必要的响应头，但不要把完整响应体无条件写进日志。

超时和连接失败要在异常分支处理

状态码判断解决不了“根本没有拿到响应”的情况。可以用 orTimeout 给整个 future 加上等待上限，再用 handle 同时接住正常结果和异常结果。这样 404 仍是正常的 PageResult，超时则会在错误对象中出现，排查时不会混淆。

import java.util.concurrent.CompletionException;
import java.util.concurrent.TimeUnit;

CompletableFuture message = client
        .sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(response -> {
            // 只有业务明确要求时，才把404主动转换成异常
            if (response.statusCode() == 404) {
                return "NOT_FOUND";
            }
            if (response.statusCode() >= 200 && response.statusCode()  {
            // value 和 error 二选一：分别代表正常完成与异常完成
            if (error != null) {
                return "REQUEST_FAILED: " + error.getClass().getSimpleName();
            }
            return value;
        });

System.out.println(message.join());

handle 会在两种完成路径上都执行，适合把结果转换成统一的上层返回值。如果希望异常继续向上传播，可改用 whenComplete 做记录，或保留未处理的异常链；不要为了“让日志好看”把所有异常都改成 404。

用一张检查清单固定调用契约

真正需要统一的是调用方契约：如果上层方法返回“查找结果”，404 往往应是一个明确的 NOT_FOUND 状态；如果上层只接受有效资源，则可以在状态码分支中抛出自定义异常。两种设计都可以，但应在同一个边界完成转换，避免一部分调用者把 404 当成功、另一部分调用者又盲目重试。

相关问题

为什么 thenApply 没有进入异常处理器？

因为 404 让上一个阶段正常返回了 HttpResponse。要让它进入异常链，需要在状态码分支中主动抛出异常。

BodyHandlers.ofString() 会自动判断 404 吗？

不会。它负责把响应体转换为字符串，状态码仍要由调用代码读取和解释。

超时和 404 能用同一个重试策略吗？

通常不能。404 多数表示资源定位结果，超时才可能是临时故障；是否重试还要结合请求是否幂等。