Async Http Client 技术文档

1. 安装指南

Maven 安装

在 Maven 项目中，可以通过在 pom.xml 文件中添加以下依赖来安装 Async Http Client：

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

Gradle 安装

在 Gradle 项目中，可以通过在 build.gradle 文件中添加以下依赖来安装 Async Http Client：

dependencies {
    implementation 'org.asynchttpclient:async-http-client:3.0.0'
}

2. 项目的使用说明

导入 Dsl 助手

为了使用方便的方法来启动组件，需要导入 Dsl 助手：

import static org.asynchttpclient.Dsl.*;

创建客户端实例

使用以下代码创建一个 AsyncHttpClient 实例：

import static org.asynchttpclient.Dsl.*;

AsyncHttpClient asyncHttpClient = asyncHttpClient();

关闭客户端实例

在使用完 AsyncHttpClient 实例后，必须调用 close 方法关闭它，以避免线程挂起和资源泄漏：

asyncHttpClient.close();

配置客户端

可以通过 AsyncHttpClientConfig 对象来配置 AsyncHttpClient 实例：

import static org.asynchttpclient.Dsl.*;

AsyncHttpClient c = asyncHttpClient(config().setProxyServer(proxyServer("127.0.0.1", 38080)));

3. 项目API使用文档

发送请求

基本用法

AHC 提供了两种定义请求的 API：绑定和非绑定。可以使用 AsyncHttpClient 和 Dsl 提供的方法来发送标准的 HTTP 方法（如 POST、PUT 等），也可以传递自定义的 HTTP 方法。

import org.asynchttpclient.*;

// 绑定
Future<Response> whenResponse = asyncHttpClient.prepareGet("http://www.example.com/").execute();

// 非绑定
Request request = get("http://www.example.com/").build();
Future<Response> whenResponse = asyncHttpClient.executeRequest(request);

设置请求体

使用 setBody 方法为请求添加请求体。请求体可以是以下类型：

• java.io.File
• byte[]
• List<byte[]>
• String
• java.nio.ByteBuffer
• java.io.InputStream
• Publisher<io.netty.buffer.ByteBuf>
• org.asynchttpclient.request.body.generator.BodyGenerator

处理响应

阻塞 Future

execute 方法返回一个 java.util.concurrent.Future，可以阻塞调用线程以获取响应：

Future<Response> whenResponse = asyncHttpClient.prepareGet("http://www.example.com/").execute();
Response response = whenResponse.get();

设置回调

execute 方法实际上返回一个 org.asynchttpclient.ListenableFuture，类似于 Guava 的 ListenableFuture。可以配置监听器以在 Future 完成时收到通知：

ListenableFuture<Response> whenResponse = ???;
Runnable callback = () -> {
    try {
        Response response = whenResponse.get();
        System.out.println(response);
    } catch (InterruptedException | ExecutionException e) {
        e.printStackTrace();
    }
};

java.util.concurrent.Executor executor = ???;
whenResponse.addListener(() -> ???, executor);

使用自定义 AsyncHandler

execute 方法可以接受一个 org.asynchttpclient.AsyncHandler，以在不同事件（如接收状态、头和正文块）时收到通知。以下示例仅捕获响应状态并跳过处理响应正文块：

import static org.asynchttpclient.Dsl.*;

import org.asynchttpclient.*;
import io.netty.handler.codec.http.HttpHeaders;

Future<Integer> whenStatusCode = asyncHttpClient.prepareGet("http://www.example.com/")
        .execute(new AsyncHandler<Integer>() {
            private Integer status;

            @Override
            public State onStatusReceived(HttpResponseStatus responseStatus) throws Exception {
                status = responseStatus.getStatusCode();
                return State.ABORT;
            }

            @Override
            public State onHeadersReceived(HttpHeaders headers) throws Exception {
                return State.ABORT;
            }

            @Override
            public State onBodyPartReceived(HttpResponseBodyPart bodyPart) throws Exception {
                return State.ABORT;
            }

            @Override
            public Integer onCompleted() throws Exception {
                return status;
            }

            @Override
            public void onThrowable(Throwable t) {
                t.printStackTrace();
            }
        });

Integer statusCode = whenStatusCode.get();

4. 项目安装方式

Async Http Client 的安装方式已经在“安装指南”部分详细说明，可以通过 Maven 或 Gradle 进行安装。