Java HttpClient 怎样为单个请求设置超时

Java 11 的 java.net.http.HttpClient 可以把超时写在具体的 HttpRequest 上。需要给某一个请求设置独立时限时，使用 HttpRequest.newBuilder().timeout(Duration)；不要为了一个慢接口重新创建客户端。客户端的 connectTimeout 只约束建立新连接的阶段，请求级 timeout 才是当前请求等待响应的总边界。

请求级 timeout 的最小写法

把时限放在构造请求的链上即可。下面的示例让这个请求最多等待 3 秒；同一个 HttpClient 发送其他请求时，不会自动继承这 3 秒。

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

public class RequestTimeoutDemo {
    public static void main(String[] args) throws Exception {
        // 客户端负责复用连接；不要为每个超时值创建一个新客户端。
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://example.com/health"))
                // 只给当前请求设置 3 秒总时限。
                .timeout(Duration.ofSeconds(3))
                .GET()
                .build();

        try {
            HttpResponse response = client.send(
                    request, HttpResponse.BodyHandlers.ofString());
            // 先判断 HTTP 状态，再把业务成功与网络成功区分开。
            System.out.println(response.statusCode());
        } catch (java.net.http.HttpTimeoutException ex) {
            // 超时属于可观测的网络失败，重试前应结合请求是否幂等判断。
            System.err.println("request timeout: " + ex.getMessage());
        }
    }
}

connectTimeout 和 timeout 不要混用

connectTimeout 写在 HttpClient.Builder 上，表示需要建立新连接时允许等待多久；timeout 写在 HttpRequest.Builder 上，约束请求本身。连接池复用已有连接时，前者可能根本不参与当前请求的等待；只设置它，不能替代请求级超时。

生产配置可以同时设置两层边界：客户端连接时限略短于请求时限，并让不同接口通过各自的 Duration 表达真实的业务等待预算。

同步与异步调用的异常处理

同步 send 会直接抛出 HttpTimeoutException；异步 sendAsync 返回的 Future 会异常完成，通常要在 exceptionally 或 whenComplete 中解包原因。超时后不要无条件重试：GET 等幂等请求可以结合退避重试，支付、写入和带副作用的 POST 应先确认服务端是否已经处理。

HttpRequest request = HttpRequest.newBuilder(uri)
        // 异步请求也必须显式设置当前请求的预算。
        .timeout(Duration.ofSeconds(2))
        .GET()
        .build();

client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .whenComplete((response, error) -> {
            if (error != null) {
                // CompletionException 可能包住 HttpTimeoutException，沿 cause 链判断。
                Throwable cause = error;
                while (cause.getCause() != null
                        && !(cause instanceof java.net.http.HttpTimeoutException)) {
                    cause = cause.getCause();
                }
                System.err.println("async request failed: " + cause.getClass().getSimpleName());
                return;
            }
            // 有响应就按状态码处理，不把 500 误记成客户端超时。
            System.out.println("status=" + response.statusCode());
        });

异常类型只是网络层结果，日志还应带上接口名、请求预算和是否重试等字段。不要把完整请求体、认证头或用户隐私写进日志。

上线前的参数与边界清单

• 先给请求设置明确的 Duration，再决定是否需要客户端级 connectTimeout。
• 把 DNS、建连、响应等待和业务处理分开观察；一个请求时限不能说明每个阶段的耗时。
• 只对幂等操作设计自动重试，重试次数和退避上限要小于上游调用链的总预算。
• 用 request.timeout() 和 client.connectTimeout() 检查配置是否按预期落在正确对象上。

相关问题

只设置 connectTimeout 为什么仍然会一直等？

它只覆盖建立新连接的阶段；连接已复用或服务端响应迟缓时，需要在当前 HttpRequest 上设置 timeout。

超时后能不能直接重试？

先判断请求是否幂等，并确认服务端可能已经收到请求；写操作应使用业务幂等键或交给业务层确认。

HTTP 500 算不算 HttpTimeoutException？

不算。500 是已经收到的 HTTP 响应，应按状态码和业务策略处理；只有等待过程超过边界才进入超时异常路径。