Apache HttpComponents Async Client请求体设置及多表单提交问题

一、JSON请求体的正确处理 #

• 你遇到的SimpleRequestBuilder.setBody无效问题，核心原因是异步客户端的请求体需要通过AsyncEntityProducer接口实现类传递，SimpleRequestBuilder的setBody仅设置了字符串内容，但未封装成异步客户端可识别的实体生产者，导致请求体未被正确发送。
• 正确实现步骤：
  1. 构建JSON字符串并设置Content-Type: application/json请求头；
  2. 使用BasicAsyncEntityProducer封装JSON字节数组，传入client.execute方法。
• 示例代码：

String jsonBody = "{\"key\": \"value\"}";
HttpUriRequest request = SimpleRequestBuilder.post("https://httpbin.org/post")
        .setHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.getMimeType())
        .build();

AsyncEntityProducer entityProducer = new BasicAsyncEntityProducer(
        new StringEntity(jsonBody, ContentType.APPLICATION_JSON),
        ContentType.APPLICATION_JSON.getMimeType());

client.execute(
        new BasicRequestProducer(null, request, null),
        entityProducer,
        new BasicResponseConsumer<>(new StringAsyncEntityConsumer()),
        new FutureCallback<HttpResponse<String>>() {
            @Override
            public void completed(HttpResponse<String> result) {
                // 请求成功处理逻辑
            }

            @Override
            public void failed(Exception ex) {
                // 请求失败处理逻辑
            }

            @Override
            public void cancelled() {
                // 请求取消处理逻辑
            }
        });

二、多部分表单的正确实现 #

• MultipartEntityBuilder生成的HttpEntity是同步实体类，无法直接适配异步客户端的AsyncEntityProducer接口；直接转字节数组会丢失多部分请求的关键元数据（如自动生成的boundary、正确的Content-Length计算），这就是服务器报错的根源。
• 推荐两种正确实现方式：

方法1：将同步MultipartEntity转为AsyncEntityProducer #

HttpEntity multipartEntity = MultipartEntityBuilder.create()
        .addTextBody("field1", "value1")
        .addBinaryBody("file", new File("test.txt"), ContentType.TEXT_PLAIN, "test.txt")
        .build();

// 用AsyncEntityProducers工具类将同步实体转为异步生产者
AsyncEntityProducer entityProducer = AsyncEntityProducers.create(multipartEntity);

HttpUriRequest request = SimpleRequestBuilder.post("https://httpbin.org/post")
        .setHeader(HttpHeaders.CONTENT_TYPE, multipartEntity.getContentType().getValue())
        .build();

client.execute(
        new BasicRequestProducer(null, request, null),
        entityProducer,
        new BasicResponseConsumer<>(new StringAsyncEntityConsumer()),
        new FutureCallback<HttpResponse<String>>() {
            // 回调处理逻辑
        });

方法2：直接构建异步多部分实体（HC 5.2+版本支持） #

如果使用HC Async Client 5.2及以上版本，可直接用AsyncMultipartEntityBuilder构建异步实体生产者，更贴合异步模型：

AsyncEntityProducer multipartProducer = AsyncMultipartEntityBuilder.create()
        .addTextBody("field1", "value1")
        .addBinaryBody("file", new File("test.txt"), ContentType.TEXT_PLAIN, "test.txt")
        .build();

HttpUriRequest request = SimpleRequestBuilder.post("https://httpbin.org/post")
        .setHeader(HttpHeaders.CONTENT_TYPE, multipartProducer.getContentType())
        .build();

client.execute(
        new BasicRequestProducer(null, request, null),
        multipartProducer,
        new BasicResponseConsumer<>(new StringAsyncEntityConsumer()),
        new FutureCallback<HttpResponse<String>>() {
            // 回调处理逻辑
        });

三、替代库推荐 #

如果觉得HC Async Client的实体处理过于繁琐，可考虑以下方案：

• OkHttp：异步API设计简洁，原生支持多部分表单和JSON请求，无需手动处理实体生产者；
• Spring WebClient：基于Reactor的响应式客户端，适合构建异步非阻塞请求，对多部分表单和JSON的支持友好；
• Vert.x Web Client：轻量级异步客户端，与Vert.x生态集成，适配高性能场景。

内容的提问来源于stack exchange，提问作者Lei Yang