1. 概述
本手册通过丰富的实战案例展示如何使用 Apache HttpClient，涵盖 5.x 和 4.5 两个主流版本。
手册采用问题导向的写作风格：只聚焦核心场景和解决方案，剔除冗余理论说明。如果你需要深入探索 HttpClient 的高级特性，可以参考 **主教程**。
2. 实战手册
2.1 HttpClient 5.x 版本示例
创建客户端
CloseableHttpClient httpClient = HttpClientBuilder.create().build();
发送基础 GET 请求
httpClient.execute(new HttpGet("http://www.google.com"),
response -> {
// 处理响应
}
);
获取 HTTP 状态码
httpClient.execute(new HttpGet("http://www.google.com"),
response -> {
assertThat(response.getCode()).isEqualTo(200);
return response;
}
);
获取响应媒体类型
httpClient.execute(new HttpGet("http://www.google.com"),
response -> {
final String contentMimeType = ContentType.parse(response.getEntity().getContentType()).getMimeType();
assertThat(contentMimeType).isEqualTo(ContentType.TEXT_HTML.getMimeType());
return response;
}
);
获取响应体
httpClient.execute(new HttpGet("http://www.google.com"),
response -> {
String bodyAsString = EntityUtils.toString(response.getEntity());
assertThat(bodyAsString, notNullValue());
return response;
}
);
配置请求超时
RequestConfig requestConfig = RequestConfig.custom()
.setConnectionRequestTimeout(Timeout.ofMilliseconds(2000L))
.build();
request.setConfig(requestConfig);
httpClient.execute(request, response -> { // 处理响应 }
配置全局超时
ConnectionConfig connConfig = ConnectionConfig.custom()
.setConnectTimeout(timeout, TimeUnit.MILLISECONDS)
.setSocketTimeout(timeout, TimeUnit.MILLISECONDS)
.build();
RequestConfig requestConfig = RequestConfig.custom()
.setConnectionRequestTimeout(Timeout.ofMilliseconds(2000L))
.build();
BasicHttpClientConnectionManager cm = new BasicHttpClientConnectionManager();
cm.setConnectionConfig(connConfig);
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultRequestConfig(requestConfig)
.setConnectionManager(cm)
.build();
发送 POST 请求
httpClient.execute(new HttpPost(SAMPLE_URL),
response -> {
// 处理响应
}
);
添加请求参数
HttpPost httpPost = new HttpPost(SAMPLE_POST_URL);
List<NameValuePair> params = new ArrayList<NameValuePair>();
params.add(new BasicNameValuePair("key1", "value1"));
params.add(new BasicNameValuePair("key2", "value2"));
httpPost.setEntity(new UrlEncodedFormEntity(params));
配置重定向策略
CloseableHttpClient httpClient = HttpClientBuilder.create()
.disableRedirectHandling()
.build();
httpClient.execute(new HttpGet("http://t.co/I5YYd9tddw"),
response -> {
assertThat(response.getCode(), equalTo(301));
return response;
}
);
设置请求头
HttpGet request = new HttpGet(SAMPLE_URL);
request.addHeader(HttpHeaders.ACCEPT, "application/xml");
httpClient.execute(request,
response -> {
// 处理响应
}
);
获取响应头
httpClient.execute(new HttpGet(SAMPLE_URL),
response -> {
Header[] headers = response.getHeaders(HttpHeaders.CONTENT_TYPE);
assertThat(headers, not(emptyArray()));
}
);
资源释放
HttpGet httpGet = new HttpGet(SAMPLE_GET_URL);
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
httpClient.execute(httpGet, resp -> {
assertThat(resp.getCode()).isEqualTo(200);
return resp;
});
}
2.2 HttpClient 4.5 版本示例
创建客户端
CloseableHttpClient client = HttpClientBuilder.create().build();
发送基础 GET 请求
client.execute(new HttpGet("http://www.google.com"));
获取 HTTP 状态码
CloseableHttpResponse response = client.execute(new HttpGet("http://www.google.com"));
assertThat(response.getStatusLine().getStatusCode(), equalTo(200));
获取响应媒体类型
CloseableHttpResponse response = client.execute(new HttpGet("http://www.google.com"));
String contentMimeType = ContentType.getOrDefault(response.getEntity()).getMimeType();
assertThat(contentMimeType, equalTo(ContentType.TEXT_HTML.getMimeType()));
获取响应体
CloseableHttpResponse response = client.execute(new HttpGet("http://www.google.com"));
String bodyAsString = EntityUtils.toString(response.getEntity());
assertThat(bodyAsString, notNullValue());
配置请求超时
RequestConfig requestConfig = RequestConfig.custom()
.setConnectionRequestTimeout(1000)
.setConnectTimeout(1000)
.setSocketTimeout(1000)
.build();
HttpGet request = new HttpGet(SAMPLE_URL);
request.setConfig(requestConfig);
client.execute(request);
配置全局超时
RequestConfig requestConfig = RequestConfig.custom()
.setConnectionRequestTimeout(1000)
.setConnectTimeout(1000)
.setSocketTimeout(1000)
.build();
HttpClientBuilder builder = HttpClientBuilder.create().setDefaultRequestConfig(requestConfig);
client = builder.build();
发送 POST 请求
client.execute(new HttpPost(SAMPLE_URL));
添加请求参数
HttpPost httpPost = new HttpPost(SAMPLE_POST_URL);
List<NameValuePair> params = new ArrayList<NameValuePair>();
params.add(new BasicNameValuePair("key1", "value1"));
params.add(new BasicNameValuePair("key2", "value2"));
httpPost.setEntity(new UrlEncodedFormEntity(params));
配置重定向策略
CloseableHttpClient client = HttpClientBuilder.create()
.disableRedirectHandling()
.build();
CloseableHttpResponse response = client.execute(new HttpGet("http://t.co/I5YYd9tddw"));
assertThat(response.getStatusLine().getStatusCode(), equalTo(301));
设置请求头
HttpGet request = new HttpGet(SAMPLE_URL);
request.addHeader(HttpHeaders.ACCEPT, "application/xml");
response = client.execute(request);
获取响应头
CloseableHttpResponse response = client.execute(new HttpGet(SAMPLE_URL));
Header[] headers = response.getHeaders(HttpHeaders.CONTENT_TYPE);
assertThat(headers, not(emptyArray()));
资源释放
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
HttpGet httpGet = new HttpGet(SAMPLE_URL);
try (CloseableHttpResponse response = httpClient.execute(httpGet)) {
// 处理响应
HttpEntity entity = response.getEntity();
if (entity != null) {
try (InputStream instream = entity.getContent()) {
// 处理输入流
}
}
}
}
3. 深入探索 HttpClient
正确使用时，HttpClient 是个强大的工具库。如果想进一步探索其能力，推荐以下教程：
还可以通过完整系列教程进行深度学习。
4. 总结
本文采用了不同于常规文章的手册式结构——这是我的内部开发笔记系列之一（已发布 Google Guava、[Hamcrest](/hamcrest-collections-arrays "Hamcrest 集合手册) 和 [Mockito](/mockito-verify "Mockito 验证手册)），现在增加了 HttpClient。目标是让这些实用技巧随时可查，并在遇到新案例时持续更新。
完整源代码请访问 **GitHub 仓库**。HttpClient 4.x 代码片段请参考 4.x 模块。
项目基于 Maven 构建，可直接导入运行。