CloseableHttpClient 是 Apache HttpClient 4.3+ 版本中引入的核心类，它是 HttpClient 接口的默认实现，并实现了 java.io.Closeable 和 AutoCloseable 接口。

它的主要特点是‌支持资源自动释放‌（特别是连接池中的连接），并且通常与连接池（PoolingHttpClientConnectionManager）配合使用，以实现高性能的 HTTP 请求处理。

以下是关于 CloseableHttpClient 的核心用法、最佳实践及常见陷阱的详细指南。

1. 核心特性

• ‌资源管理‌：由于实现了 Closeable 接口，必须在使用完毕后关闭，以释放底层持有的系统资源（如 Socket 连接）。
• ‌线程安全‌：CloseableHttpClient 实例是线程安全的，可以在多线程环境中共享单个实例（单例模式）。
• ‌连接复用‌：默认内部维护一个连接池，支持 HTTP Keep-Alive，避免每次请求都进行 TCP 三次握手，显著提升高并发下的性能。

2. 基本用法示例

方式一：Try-with-resources（推荐用于简单场景）

利用 Java 7 引入的 try-with-resources 语法，确保客户端和响应对象被正确关闭。

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class SimpleHttpClientExample {
    public static void main(String[] args) {
        // createDefault() 创建一个带有默认配置和默认连接池的客户端
        try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
            HttpGet httpGet = new HttpGet("http://www.example.com");
            
            // execute 方法返回 CloseableHttpResponse，也需要关闭
            try (CloseableHttpResponse response = httpClient.execute(httpGet)) {
                System.out.println(response.getStatusLine());
                String result = EntityUtils.toString(response.getEntity());
                System.out.println(result);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

方式二：单例模式 + 自定义配置（推荐用于生产环境）

在高并发或微服务场景中，应创建全局唯一的 CloseableHttpClient Bean，并自定义超时时间和连接池参数。

import org.apache.http.client.config.RequestConfig;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
import java.util.concurrent.TimeUnit;

public class HttpClientConfig {

    public static CloseableHttpClient createCustomClient() {
        // 1. 配置连接池
        PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager();
        connectionManager.setMaxTotal(200); // 最大连接数
        connectionManager.setDefaultMaxPerRoute(50); // 每个路由最大连接数
        
        // 可选：定期清理空闲连接，防止 CLOSE_WAIT 堆积
        connectionManager.closeIdleConnections(30, TimeUnit.SECONDS);

        // 2. 配置请求参数（超时时间至关重要）
        RequestConfig requestConfig = RequestConfig.custom()
                .setConnectTimeout(5000)           // 连接建立超时
                .setSocketTimeout(10000)           // 数据读取超时
                .setConnectionRequestTimeout(2000) // 从连接池获取连接超时
                .build();

        // 3. 构建客户端
        return HttpClients.custom()
                .setConnectionManager(connectionManager)
                .setDefaultRequestConfig(requestConfig)
                .build();
    }
}

3. 关键注意事项与最佳实践

A. 必须关闭资源

CloseableHttpClient 和 CloseableHttpResponse 都持有底层网络资源。

• ‌错误做法‌：只关闭 Response，不关闭 Client；或者两者都不关闭。这会导致内存泄漏和文件句柄耗尽（Too many open files）。
• ‌正确做法‌：
  • 如果使用单例 Client，应在应用关闭时（如 Spring 的 @PreDestroy 或 Shutdown Hook）调用 httpClient.close()。
  • 每次请求得到的 CloseableHttpResponse 必须在 finally 块或 try-with-resources 中关闭。

B. 不要每次请求都创建新的 Client

• ‌误区‌：在循环或每个方法中调用 HttpClients.createDefault()。
• ‌后果‌：每次创建都会初始化新的连接池，导致频繁的 TCP 连接建立和销毁，性能极差，且容易耗尽端口资源。
• ‌建议‌：将 CloseableHttpClient 作为单例复用。

C. 合理设置超时时间

默认配置可能没有超时限制或限制不合理。务必通过 RequestConfig 设置：

1. ‌ConnectTimeout‌：防止连接不上服务器时无限等待。
2. ‌SocketTimeout‌：防止服务器处理慢或网络卡顿导致读取数据时无限等待。
3. ‌ConnectionRequestTimeout‌：防止在高并发下，从连接池获取连接时无限等待。

D. 处理响应实体（Entity）

• 如果不需要响应内容，也必须消耗掉 Entity 或关闭 Response，否则连接无法放回池中复用。
• 使用 EntityUtils.toString(entity) 会一次性加载所有内容到内存，对于大文件下载，建议使用流式处理（response.getEntity().getContent()）。

4. 常见问题排查

• ‌异常：java.net.SocketException: Too many open files‌

  • ‌原因‌：未正确关闭 HttpResponse 或 HttpClient，导致 Socket 句柄泄漏；或者连接池配置过小，导致大量连接处于 CLOSE_WAIT 状态。
  • ‌解决‌：确保所有资源都被关闭；启用连接池的空闲连接驱逐策略（evictIdleConnections）。

• ‌异常：org.apache.http.conn.ConnectionPoolTimeoutException‌

  • ‌原因‌：连接池已满，且等待获取连接的时间超过了 ConnectionRequestTimeout。
  • ‌解决‌：增加连接池大小（setMaxTotal）；检查是否有请求未释放连接；优化后端响应速度。

总结

场景	推荐做法
‌脚本/测试/低频调用‌	使用 HttpClients.createDefault() 配合 try-with-resources。
‌生产环境/高并发‌	使用 HttpClients.custom() 自定义连接池和超时时间，并将 Client 设为单例。
‌Spring Boot 项目‌	将配置好的 CloseableHttpClient 定义为 @Bean，注入到 Service 中使用。

正确使用 CloseableHttpClient 的关键在于：‌单例复用、显式关闭、合理超时、连接池调优‌。