Apache HttpClient 请求参数添加详解

1. 简介

HttpClient 是 Apache HttpComponents 项目的一部分，它提供了一组低层级的 Java 组件，专注于 HTTP 及其相关协议的处理。HttpClient 最核心的功能就是执行 HTTP 方法。

在本篇教程中，我们将重点介绍如何向 HttpClient 5 的请求中添加参数。我们会讲解使用 URIBuilder 配合字符串键值对和 NameValuePair 的方式来构造 URL 参数，并进一步演示如何通过 UrlEncodedFormEntity 在 POST 请求体中传递参数。

✅ 示例目标 URL 格式如下：

https://example.com?param1=value1&param2=value2

2. 使用 URIBuilder 添加请求参数

URIBuilder 提供了基于构建者模式的 API，可以非常方便地创建 URI 并追加查询参数。你可以选择使用字符串键值对的方式添加参数，也可以使用 NameValuePair 列表。

2.1 使用字符串键值对添加参数

HttpGet httpGet = new HttpGet("https://postman-echo.com/get");
URI uri = new URIBuilder(httpGet.getUri())
    .addParameter("param1", "value1")
    .addParameter("param2", "value2")
    .build();
httpGet.setUri(uri);

try (CloseableHttpClient client = HttpClients.createDefault();
     CloseableHttpResponse response = (CloseableHttpResponse) client
         .execute(httpGet, new CustomHttpClientResponseHandler())) {

    final int statusCode = response.getCode();
    assertThat(statusCode, equalTo(HttpStatus.SC_OK));
}

这种方式简单粗暴，适合参数较少、结构简单的场景。

2.2 使用 NameValuePair 列表添加参数

如果你更喜欢面向对象的方式来组织参数，可以使用 NameValuePair 列表：

@BeforeEach
public void setUp() {
    nameValuePairs = new ArrayList<>();
    NameValuePair param1NameValuePair = new BasicNameValuePair("param1", "value1");
    NameValuePair param2NameValuePair = new BasicNameValuePair("param2", "value2");
    nameValuePairs.add(param1NameValuePair);
    nameValuePairs.add(param2NameValuePair);
}       

HttpGet httpGet = new HttpGet("https://postman-echo.com/get");
URI uri = new URIBuilder(httpGet.getUri())
    .addParameters(nameValuePairs)
    .build();
httpGet.setUri(uri);

try (CloseableHttpClient client = HttpClients.createDefault();
     CloseableHttpResponse response = (CloseableHttpResponse) client
         .execute(httpGet, new CustomHttpClientResponseHandler())) {

    final int statusCode = response.getCode();
    assertThat(statusCode, equalTo(HttpStatus.SC_OK));
}

⚠️ 注意：以上两种方式都适用于 GET 请求，因为它们是将参数附加到 URL 查询字符串中的。

3. 使用 UrlEncodedFormEntity 添加 POST 请求参数

如果你需要发送 POST 请求并把参数放在请求体中（如常见的表单提交），可以使用 UrlEncodedFormEntity：

HttpPost httpPost = new HttpPost("https://postman-echo.com/post");
httpPost.setEntity(new UrlEncodedFormEntity(nameValuePairs, StandardCharsets.UTF_8));

try (CloseableHttpClient client = HttpClients.createDefault();
     CloseableHttpResponse response = (CloseableHttpResponse) client
         .execute(httpPost, new CustomHttpClientResponseHandler())) {

    final int statusCode = response.getCode();
    assertThat(statusCode, equalTo(HttpStatus.SC_OK));
}

❌ 但是要注意：GET 请求不能使用 UrlEncodedFormEntity，因为 GET 请求没有请求体，无法携带实体内容。

4. 总结

本文展示了三种常用的 HttpClient 参数传递方式：

使用 URIBuilder + 字符串键值对
使用 URIBuilder + NameValuePair 列表
使用 UrlEncodedFormEntity 构造 POST 表单数据

这些方法各有适用场景，合理选用可以让代码更加清晰易维护。

📌 所有示例代码均可在 GitHub 上找到。

Persistence

REST

Security