AsyncHttpClient使用说明书

[[toc]]

AsyncHttpClient（AHC）是一个高性能、异步的 HTTP 客户端库，广泛用于 Java 和 Scala 应用中，特别适合处理高并发、非阻塞的 HTTP 请求。它基于 Netty 或 Java 原生的异步 HTTP 客户端实现，支持 HTTP/1.1 和 HTTP/2 协议，适用于微服务、API 调用、爬虫等场景。

1. 核心特性

2. 主要版本

• AsyncHttpClient 1.x
  经典版本，广泛使用但已停止维护（包名：com.ning.http.client）。

• AsyncHttpClient 2.x
  全新版本，基于 Java 8+，支持 HTTP/2（包名：org.asynchttpclient）。

• AsyncHttpClient 3.x
  最新版本，基于 Java 11+，

3. 核心组件

(1) AsyncHttpClient 实例

• 全局单例，管理连接池和线程池。
• 建议复用实例，避免重复创建开销。

(2) Request 和 Response

• Request：定义请求方法（GET/POST）、URL、头、参数、Body 等。
• Response：封装响应状态码、头、Body 等。

(3) ListenableFuture 或 CompletableFuture

• 异步操作的结果句柄，支持回调或链式处理。

(4) AsyncHandler

1. execute 方法支持 AsyncHandler 事件监听

• 功能：通过实现 org.asynchttpclient.AsyncHandler 接口，可以在 HTTP 请求的不同阶段接收事件通知，例如：
• 接收到响应状态码（onStatusReceived）
• 接收到响应头（onHeadersReceived）
• 接收到响应体数据块（onBodyPartReceived）
• 请求完成或失败（onCompleted / onThrowable）

• 默认行为：若不指定 AsyncHandler，AHC 会使用 org.asynchttpclient.AsyncCompletionHandler（一个基础实现类）。

2. AsyncHandler 的核心能力

• 提前终止处理
在事件回调方法中返回 AsyncHandler.State.ABORT，可立即终止请求处理。
注意：返回 ABORT 会强制关闭底层 TCP 连接。

• 自定义结果返回
在 onCompleted 方法中返回一个计算结果，该结果将作为 Future 的最终结果。
（参考 AsyncCompletionHandler 的实现示例）

3. 示例：仅捕获响应状态码，跳过响应体处理

以下示例展示如何通过 AsyncHandler 捕获响应状态码，并忽略响应体数据块的处理：

import org.asynchttpclient.*;

public class SkipBodyHandler implements AsyncHandler<Response> {
    private Response.ResponseBuilder responseBuilder = new Response.ResponseBuilder();

    @Override
    public State onStatusReceived(HttpResponseStatus status) throws Exception {
        responseBuilder.accumulate(status);  // 记录状态码
        return State.CONTINUE;              // 继续处理后续事件
    }

    @Override
    public State onHeadersReceived(HttpHeaders headers) throws Exception {
        responseBuilder.accumulate(headers); // 记录响应头
        return State.CONTINUE;
    }

    @Override
    public State onBodyPartReceived(HttpResponseBodyPart bodyPart) throws Exception {
        // 跳过响应体处理，直接丢弃数据块
        return State.CONTINUE;
    }

    @Override
    public Response onCompleted() throws Exception {
        return responseBuilder.build();      // 返回最终的 Response 对象
    }

    @Override
    public void onThrowable(Throwable t) {
        t.printStackTrace();                 // 处理异常
    }
}

使用方式：

AsyncHttpClient client = Dsl.asyncHttpClient();
Request request = Dsl.get("https://api.example.com").build();

// 提交请求并绑定自定义的 AsyncHandler
client.executeRequest(request, new SkipBodyHandler())
    .toCompletableFuture()
    .thenAccept(response -> {
        System.out.println("Status Code: " + response.getStatusCode());
    });

4. 注意事项

• 连接关闭：返回 State.ABORT 会导致底层连接被强制关闭，可能影响连接池复用。
• 资源释放：即使提前终止请求，仍需确保关闭 AsyncHttpClient 实例。
• 性能影响：频繁终止请求可能增加 TCP 连接重建开销，需谨慎使用。

通过 AsyncHandler，开发者可以精细控制 HTTP 请求的生命周期，适用于流式处理、大文件下载中断等场景。

4. 快速入门

步骤 1：添加依赖

Maven（以 2.x 版本为例）：

<dependency>
    <groupId>org.asynchttpclient</groupId>
    <artifactId>async-http-client</artifactId>
    <version>2.12.3</version>
</dependency>

步骤 2：发起异步 GET 请求

import org.asynchttpclient.*;

public class AsyncExample {
    public static void main(String[] args) throws Exception {
        // 创建 AsyncHttpClient 实例
        try (AsyncHttpClient client = Dsl.asyncHttpClient()) {
            // 构建 GET 请求
            Request request = Dsl.get("https://api.example.com/data").build();
            
            // 发起异步请求，注册回调
            client.executeRequest(request)
                .toCompletableFuture()
                .thenAccept(response -> {
                    System.out.println("Status Code: " + response.getStatusCode());
                    System.out.println("Response Body: " + response.getResponseBody());
                })
                .join(); // 等待异步操作完成（仅示例，实际中避免阻塞）
        }
    }
}

步骤 3：处理 POST 请求（JSON 数据）

Request request = Dsl.post("https://api.example.com/submit")
    .addHeader("Content-Type", "application/json")
    .setBody("{\"key\": \"value\"}")
    .build();

client.executeRequest(request)
    .toCompletableFuture()
    .thenAccept(response -> {
        // 处理响应
    });

5. 高级配置

(1) 客户端全局配置

DefaultAsyncHttpClientConfig config = Dsl.config()
    .setConnectTimeout(5000)          // 连接超时（毫秒）
    .setRequestTimeout(10000)         // 请求超时
    .setMaxConnections(200)           // 最大连接数
    .setMaxConnectionsPerHost(50)     // 每主机最大连接数
    .setProxyServer(proxy)            // 代理设置
    .setUseInsecureTrustManager(true) // 忽略 SSL 证书验证（仅测试环境！）
    .build();

AsyncHttpClient client = Dsl.asyncHttpClient(config);

(2) 重试策略

// 自定义重试条件（如状态码 500 时重试）
client.executeRequest(request)
    .toCompletableFuture()
    .exceptionally(ex -> {
        if (ex instanceof TimeoutException) {
            // 超时重试逻辑
        }
        return null;
    });

(3) WebSocket 支持

WebSocket websocket = client.prepareGet("ws://echo.websocket.org")
    .execute(new WebSocketUpgradeHandler.Builder()
        .addWebSocketListener(new WebSocketListener() {
            @Override
            public void onOpen(WebSocket websocket) {
                websocket.sendTextFrame("Hello!");
            }
            
            @Override
            public void onTextFrame(String payload) {
                System.out.println("Received: " + payload);
            }
        }).build())
    .get();

6. 性能优化建议

1. 复用 AsyncHttpClient 实例
   避免频繁创建和销毁客户端，减少资源开销。

2. 合理配置连接池
   根据业务负载调整 maxConnections 和 maxConnectionsPerHost。

3. 使用响应式编程模型
   结合 CompletableFuture 或响应式框架（如 Reactor、RxJava）处理异步流程。

4. 监控与日志
   启用日志（org.asynchttpclient 包）监控请求细节，排查超时或错误。

7. 与其他 HTTP 客户端对比

8. 常见问题

(1) 如何处理 SSL 证书验证？

// 忽略 SSL 证书验证（仅测试环境）
Dsl.config().setUseInsecureTrustManager(true);

(2) 如何设置请求超时？

Dsl.config().setRequestTimeout(10000); // 单位：毫秒

(3) 如何上传文件？

Request request = Dsl.post("https://api.example.com/upload")
    .addBodyPart(new FilePart("file", new File("data.txt")))
    .build();

9.注意事项

1. 必须显式关闭 AsyncHttpClient 实例
   • 使用完 AsyncHttpClient 后，必须调用 close() 方法关闭实例，通常在应用关闭时执行。
   • 若未关闭，会导致 线程挂起（Hanging Threads） 和 资源泄漏（Resource Leaks）。

2. 全局资源管理
   • AsyncHttpClient 实例应作为 全局资源，与应用程序的生命周期一致。
   • 避免为每个请求创建新实例，否则每次都会新建线程和连接池，导致性能下降。

3. 共享资源的高级配置
   • 可以预先创建共享资源（如 EventLoop 和 Timer），并通过配置传递给多个客户端实例。
   • 需自行管理这些共享资源的关闭（若手动创建共享资源，需在应用退出时手动释放）。

示例：正确使用 AsyncHttpClient

// 应用启动时创建全局实例
private static final AsyncHttpClient client = Dsl.asyncHttpClient();

// 在应用关闭时调用 close()
public void shutdown() {
    client.close();
}

关键总结

遵循上述规则，可确保 AsyncHttpClient 高效稳定运行。

10. 官方资源

• GitHub 仓库
https://github.com/AsyncHttpClient/async-http-client

• 文档
https://asynchttpclient.github.io/async-http-client/

AsyncHttpClient 是处理高并发 HTTP 请求的理想选择，结合其异步特性和灵活的配置，能够显著提升应用的吞吐量和响应速度。