Apache HttpAsyncClient 使用教程

1. 概述

在本教程中，我们将介绍 Apache HttpAsyncClient 的一些最常见使用场景。内容涵盖从基本的请求发送，到设置 代理（Proxy）、使用 SSL 证书，以及 身份认证 的完整流程。

适合已经熟悉 Java 网络编程、HttpClient 基础的开发者快速上手异步请求处理。

---

2. 简单示例

我们从一个最基础的例子开始：使用 HttpAsyncClient 发起一个 GET 请求。

@Test
void whenUseHttpAsyncClient_thenCorrect() throws InterruptedException, ExecutionException, IOException {
    final SimpleHttpRequest request = SimpleRequestBuilder.get(HOST_WITH_COOKIE)
        .build();
    final CloseableHttpAsyncClient client = HttpAsyncClients.custom()
        .build();
    client.start();

    final Future<SimpleHttpResponse> future = client.execute(request, null);
    final HttpResponse response = future.get();

    assertThat(response.getCode(), equalTo(200));
    client.close();
}

📌 注意：

• **必须在调用 execute 前调用 client.start()**，否则会抛出如下异常：

java.lang.IllegalStateException: Request cannot be executed; I/O reactor status: INACTIVE

• 使用完毕后记得调用 client.close() 关闭资源。

---

3. 多线程请求处理

HttpAsyncClient 支持异步非阻塞请求，非常适合并发处理多个 HTTP 请求。

3.1. HttpAsyncClient 5.x 示例

@Test
void whenUseMultipleHttpAsyncClient_thenCorrect() throws Exception {
    final IOReactorConfig ioReactorConfig = IOReactorConfig
        .custom()
        .build();

    final CloseableHttpAsyncClient client = HttpAsyncClients.custom()
        .setIOReactorConfig(ioReactorConfig)
        .build();

    client.start();
    final String[] toGet = { "http://www.google.com/", "http://www.apache.org/", "http://www.bing.com/" };

    final GetThread[] threads = new GetThread[toGet.length];
    for (int i = 0; i < threads.length; i++) {
        final HttpGet request = new HttpGet(toGet[i]);
        threads[i] = new GetThread(client, request);
    }

    for (final GetThread thread : threads) {
        thread.start();
    }

    for (final GetThread thread : threads) {
        thread.join();
    }
}

线程类实现如下：

static class GetThread extends Thread {

    private final CloseableHttpAsyncClient client;
    private final HttpContext context;
    private final HttpGet request;

    GetThread(final CloseableHttpAsyncClient client, final HttpGet request) {
        this.client = client;
        context = HttpClientContext.create();
        this.request = request;
    }

    @Override
    public void run() {
        try {
            final Future<HttpResponse> future = client.execute(request, context, null);
            final HttpResponse response = future.get();
            assertThat(response.getStatusLine().getStatusCode(), equalTo(200));
        } catch (final Exception ex) {
            System.out.println(ex.getLocalizedMessage());
        }
    }

}

3.2. HttpAsyncClient 4.5 示例

@Test
void whenUseMultipleHttpAsyncClient_thenCorrect() throws Exception {
    final ConnectingIOReactor ioReactor = new DefaultConnectingIOReactor();
    final PoolingNHttpClientConnectionManager cm = new PoolingNHttpClientConnectionManager(ioReactor);
    final CloseableHttpAsyncClient client = HttpAsyncClients.custom().setConnectionManager(cm).build();
    client.start();
    final String[] toGet = { "http://www.google.com/", "http://www.apache.org/", "http://www.bing.com/" };

    final GetThread[] threads = new GetThread[toGet.length];
    for (int i = 0; i < threads.length; i++) {
        final HttpGet request = new HttpGet(toGet[i]);
        threads[i] = new GetThread(client, request);
    }

    for (final GetThread thread : threads) {
        thread.start();
    }

    for (final GetThread thread : threads) {
        thread.join();
    }

}

💡 小贴士：

• 5.x 版本配置更简洁，推荐使用新版
• 4.5 需要手动配置连接池 PoolingNHttpClientConnectionManager

---

4. 使用代理（Proxy）

在一些场景下，我们需要通过代理服务器发起请求，比如爬虫、测试环境等。

4.1. HttpAsyncClient 5.x 示例

@Test
void whenUseProxyWithHttpClient_thenCorrect() throws Exception {
    final HttpHost proxy = new HttpHost("127.0.0.1", GetRequestMockServer.serverPort);
    DefaultProxyRoutePlanner routePlanner = new DefaultProxyRoutePlanner(proxy);
    final CloseableHttpAsyncClient client = HttpAsyncClients.custom()
        .setRoutePlanner(routePlanner)
        .build();
    client.start();

    final SimpleHttpRequest request = new SimpleHttpRequest("GET" ,HOST_WITH_PROXY);
    final Future<SimpleHttpResponse> future = client.execute(request, null);
    final HttpResponse  response = future.get();
    assertThat(response.getCode(), equalTo(200));
    client.close();
}

4.2. HttpAsyncClient 4.5 示例

@Test
void whenUseProxyWithHttpClient_thenCorrect() throws Exception {
    final CloseableHttpAsyncClient client = HttpAsyncClients.createDefault();
    client.start();
    final HttpHost proxy = new HttpHost("127.0.0.1", GetRequestMockServer.serverPort);
    final RequestConfig config = RequestConfig.custom().setProxy(proxy).build();
    final HttpGet request = new HttpGet(HOST_WITH_PROXY);
    request.setConfig(config);
    final Future<HttpResponse> future = client.execute(request, null);
    final HttpResponse response = future.get();
    assertThat(response.getStatusLine().getStatusCode(), equalTo(200));
    client.close();
}

✅ 推荐做法：

• 使用 setRoutePlanner() 或 setProxy() 设置代理
• 测试时可以用本地代理服务模拟

---

5. 使用 SSL 证书

在 HTTPS 请求中，SSL 证书是必须的。有时我们希望跳过证书验证（比如测试环境），也可以通过自定义 SSLContext 实现。

5.1. HttpAsyncClient 5.x 示例

@Test
void whenUseSSLWithHttpAsyncClient_thenCorrect() throws Exception {
    final TrustStrategy acceptingTrustStrategy = (certificate, authType) -> true;

    final SSLContext sslContext = SSLContexts.custom()
        .loadTrustMaterial(null, acceptingTrustStrategy)
        .build();

    final TlsStrategy tlsStrategy = ClientTlsStrategyBuilder.create()
        .setHostnameVerifier(NoopHostnameVerifier.INSTANCE)
        .setSslContext(sslContext)
        .build();

    final PoolingAsyncClientConnectionManager cm = PoolingAsyncClientConnectionManagerBuilder.create()
        .setTlsStrategy(tlsStrategy)
        .build();

    final CloseableHttpAsyncClient client = HttpAsyncClients.custom()
        .setConnectionManager(cm)
        .build();

    client.start();

    final SimpleHttpRequest request = new SimpleHttpRequest("GET",HOST_WITH_SSL);
    final Future<SimpleHttpResponse> future = client.execute(request, null);

    final HttpResponse response = future.get();
    assertThat(response.getCode(), equalTo(200));
    client.close();
}

5.2. HttpAsyncClient 4.5 示例

@Test
void whenUseSSLWithHttpAsyncClient_thenCorrect() throws Exception {
    final TrustStrategy acceptingTrustStrategy = (certificate, authType) -> true;
    final SSLContext sslContext = SSLContexts.custom()
        .loadTrustMaterial(null, acceptingTrustStrategy)
        .build();

    final CloseableHttpAsyncClient client = HttpAsyncClients.custom()
        .setSSLHostnameVerifier(NoopHostnameVerifier.INSTANCE)
        .setSSLContext(sslContext).build();

    client.start();
    final HttpGet request = new HttpGet(HOST_WITH_SSL);
    final Future<HttpResponse> future = client.execute(request, null);
    final HttpResponse response = future.get();
    assertThat(response.getStatusLine().getStatusCode(), equalTo(200));
    client.close();
}

⚠️ 注意事项：

• 不建议在生产环境使用 acceptingTrustStrategy
• 建议导入真实证书，避免安全风险

---

6. 使用 Cookie

有些接口需要携带 Cookie 信息进行身份验证或状态保持。

6.1. HttpAsyncClient 5.x 示例

@Test
void whenUseCookiesWithHttpAsyncClient_thenCorrect() throws Exception {
    final BasicCookieStore cookieStore = new BasicCookieStore();
    final BasicClientCookie cookie = new BasicClientCookie(COOKIE_NAME, "1234");
    cookie.setDomain(COOKIE_DOMAIN);
    cookie.setPath("/");
    cookieStore.addCookie(cookie);
    final CloseableHttpAsyncClient client = HttpAsyncClients.custom().build();
    client.start();
    final SimpleHttpRequest request = new SimpleHttpRequest("GET" ,HOST_WITH_COOKIE);

    final HttpContext localContext = new BasicHttpContext();
    localContext.setAttribute(HttpClientContext.COOKIE_STORE, cookieStore);

    final Future<SimpleHttpResponse> future = client.execute(request, localContext, null);

    final HttpResponse response = future.get();
    assertThat(response.getCode(), equalTo(200));
    client.close();
}

6.2. HttpAsyncClient 4.5 示例

@Test
void whenUseCookiesWithHttpAsyncClient_thenCorrect() throws Exception {
    final BasicCookieStore cookieStore = new BasicCookieStore();
    final BasicClientCookie cookie = new BasicClientCookie(COOKIE_NAME, "1234");
    cookie.setDomain(COOKIE_DOMAIN);
    cookie.setPath("/");
    cookieStore.addCookie(cookie);
    final CloseableHttpAsyncClient client = HttpAsyncClients.custom().build();
    client.start();
    final HttpGet request = new HttpGet(HOST_WITH_COOKIE);

    final HttpContext localContext = new BasicHttpContext();
    localContext.setAttribute(HttpClientContext.COOKIE_STORE, cookieStore);

    final Future<HttpResponse> future = client.execute(request, localContext, null);
    final HttpResponse response = future.get();
    assertThat(response.getStatusLine().getStatusCode(), equalTo(200));
    client.close();
}

📌 使用要点：

• 使用 BasicCookieStore 存储 Cookie
• 通过 HttpContext 设置 CookieStore
• 可以添加多个 Cookie

---

7. 身份认证（Basic Auth）

有些服务接口需要 Basic Auth 认证，我们可以通过 CredentialsProvider 来实现。

7.1. HttpAsyncClient 5.x 示例

@Test
void whenUseAuthenticationWithHttpAsyncClient_thenCorrect() throws Exception {
    final BasicCredentialsProvider credsProvider = new BasicCredentialsProvider();
    final UsernamePasswordCredentials credentials =
        new UsernamePasswordCredentials(DEFAULT_USER, DEFAULT_PASS.toCharArray());
    credsProvider.setCredentials(new AuthScope(URL_SECURED_BY_BASIC_AUTHENTICATION, 80) ,credentials);
    final CloseableHttpAsyncClient client = HttpAsyncClients
        .custom()
        .setDefaultCredentialsProvider(credsProvider).build();

    final SimpleHttpRequest request = new SimpleHttpRequest("GET" ,URL_SECURED_BY_BASIC_AUTHENTICATION);

    client.start();

    final Future<SimpleHttpResponse> future = client.execute(request, null);

    final HttpResponse response = future.get();
    assertThat(response.getCode(), equalTo(200));
    client.close();
}

7.2. HttpAsyncClient 4.5 示例

@Test
public void whenUseAuthenticationWithHttpAsyncClient_thenCorrect() throws Exception {
    CredentialsProvider provider = new BasicCredentialsProvider();
    UsernamePasswordCredentials creds = new UsernamePasswordCredentials("user", "pass");
    provider.setCredentials(AuthScope.ANY, creds);
    
    CloseableHttpAsyncClient client = 
      HttpAsyncClients.custom().setDefaultCredentialsProvider(provider).build();
    client.start();
    
    HttpGet request = new HttpGet("http://localhost:8080");
    Future<HttpResponse> future = client.execute(request, null);
    HttpResponse response = future.get();
    
    assertThat(response.getStatusLine().getStatusCode(), equalTo(200));
    client.close();
}

💡 使用技巧：

• 推荐使用 AuthScope.ANY 或具体域名+端口来限制认证作用域
• 可以复用 CredentialsProvider 避免重复设置

---

8. 总结

通过本文，我们学习了 Apache HttpAsyncClient 的主要使用方式，包括：

✅ 异步请求发送
✅ 多线程并发请求
✅ 代理配置
✅ 自定义 SSL 证书
✅ Cookie 管理
✅ Basic Auth 认证

完整代码示例可参考 GitHub 项目。

如需兼容旧版本（4.5），也提供了对应的代码片段。

📌 小建议：

• 生产环境避免使用 acceptingTrustStrategy 和 NoopHostnameVerifier
• 推荐使用 5.x 版本，配置更简洁，功能更强大

---