基于源码分析 HikariCP 常见参数的具体含义

HikariCP 是目前风头最劲的 JDBC 连接池，号称性能最佳，SpringBoot 2.0 也将 HikariCP 作为默认的数据库连接池。

要想用好 HikariCP，理解常见参数的具体含义至关重要。但是对于某些参数，尽管官方文档给出了详细解释，很多开发、DBA 读完后还是会感到困惑。

因此，本文将从源码角度对 HikariCP 中的一些常见参数进行分析，希望能帮助大家更加清晰地理解这些参数的具体含义。

本文将分析的参数包括：

maximumPoolSize
minimumIdle
connectionTimeout
idleTimeout 及空闲连接的清理逻辑。
maxLifetime
keepaliveTime
connectionTestQuery 及连接有效性检测的实现逻辑。
leakDetectionThreshold
什么时候会检测连接的有效性？

maximumPoolSize

连接池可以创建的最大连接数，包括空闲和活动连接。默认值为 10。

java 复制代码

if (maxPoolSize < 1) {
   maxPoolSize = DEFAULT_POOL_SIZE;
}

如果未显式设置 maxPoolSize，则默认为 -1，此时连接池会使用默认的最大连接数 DEFAULT_POOL_SIZE（10）。

当连接池达到该限制且没有可用的空闲连接时，对新连接的请求（通过 getConnection()）将会阻塞，最多等待 connectionTimeout 毫秒，然后超时失败。

java 复制代码

public Connection getConnection() throws SQLException
{
   return getConnection(connectionTimeout);
}

public Connection getConnection(final long hardTimeout) throws SQLException
   {
      suspendResumeLock.acquire();
      final var startTime = currentTime();

      try {
         var timeout = hardTimeout;
         do {
            var poolEntry = connectionBag.borrow(timeout, MILLISECONDS);
         ...

   }

minimumIdle

最小空闲连接数。

java 复制代码

if (minIdle < 0 || minIdle > maxPoolSize) {
   minIdle = maxPoolSize;
}

如果未显式设置 minimumIdle，则默认为 -1，此时会取 maximumPoolSize 的值。官方建议不要设置这个参数，让 HikariCP 作为一个固定大小的连接池进行管理。

如果连接池中的空闲连接数低于 minimumIdle，且连接池中的总连接数小于 maximumPoolSize（最大连接数），HikariCP 会调用fillPool方法补充连接。

java 复制代码

private synchronized void fillPool(final boolean isAfterAdd)
{  
   // 获取当前空闲连接数
   final var idle = getIdleConnections();
   // 检查是否需要创建新连接，创建新连接的条件是总连接数小于 maximumPoolSize 且空闲连接数小于 minimumIdle。
   final var shouldAdd = getTotalConnections() < config.getMaximumPoolSize() && idle < config.getMinimumIdle();
  
   if (shouldAdd) {
      // 计算需要创建的连接数
      final var countToAdd = config.getMinimumIdle() - idle;
      for (int i = 0; i < countToAdd; i++)
         addConnectionExecutor.submit(isAfterAdd ? postFillPoolEntryCreator : poolEntryCreator);
   }
   else if (isAfterAdd) {
      logger.debug("{} - Fill pool skipped, pool has sufficient level or currently being filled.", poolName);
   }
}

fillPool会在三种场景下调用：

销毁连接时。
HouseKeeper 的周期性任务中。
恢复暂停的连接池时（这种场景不常见，可忽略）。

connectionTimeout

获取连接时的最大等待时间，单位为毫秒，默认值为 30000（30秒），最小允许值是 250。

如果 connectionTimeout 设置为 0，则它会取 Java int 类型的最大值，即 2147483647，约 24.85 天。

java 复制代码

public void setConnectionTimeout(long connectionTimeoutMs)
{
   if (connectionTimeoutMs == 0) {
      this.connectionTimeout = Integer.MAX_VALUE;
   }
   else if (connectionTimeoutMs < SOFT_TIMEOUT_FLOOR) {
      throw new IllegalArgumentException("connectionTimeout cannot be less than " + SOFT_TIMEOUT_FLOOR + "ms");
   }
   else {
      this.connectionTimeout = connectionTimeoutMs;
   }
}

idleTimeout

空闲连接的超时时长，单位为毫秒。超过指定时长的连接将被销毁掉。默认值为 600000（10分钟），最小允许值是 10000（10秒）。

注意，如果 idleTimeout 的设置不合理，连接池会基于其它参数的值来设置 idleTimeout，具体逻辑如下：

java 复制代码

// 如果 idleTimeout 与 maxLifetime 的值过于接近，且 maxLifetime 大于 0，连接池将禁用 idleTimeout，避免设置的超时时间影响连接生命周期。
if (idleTimeout + SECONDS.toMillis(1) > maxLifetime && maxLifetime > 0 && minIdle < maxPoolSize) {
   LOGGER.warn("{} - idleTimeout is close to or more than maxLifetime, disabling it.", poolName);
   idleTimeout = 0;
} // 如果 idleTimeout 小于 10 秒，且 minIdle 小于最大连接数 maxPoolSize，连接池会将 idleTimeout 设置为默认值 IDLE_TIMEOUT（10分钟），避免空闲连接存活时间过短影响池的正常使用。
else if (idleTimeout != 0 && idleTimeout < SECONDS.toMillis(10) && minIdle < maxPoolSize) {
   LOGGER.warn("{} - idleTimeout is less than 10000ms, setting to default {}ms.", poolName, IDLE_TIMEOUT);
   idleTimeout = IDLE_TIMEOUT;
} // 如果连接池已配置为固定大小（即 minIdle == maxPoolSize），并且 idleTimeout 被显式设置，连接池会发出警告，说明该设置无效。
else  if (idleTimeout != IDLE_TIMEOUT && idleTimeout != 0 && minIdle == maxPoolSize) {
   LOGGER.warn("{} - idleTimeout has been set but has no effect because the pool is operating as a fixed size pool.", poolName);
}

连接池中的空闲连接是指当前没有被使用、处于空闲状态的连接。空闲连接可以随时被借用（即从连接池中获取）来进行数据库操作。

注意，空闲连接在 MySQL 中的状态是Sleep，但不是所有Sleep状态的连接都是空闲连接。

空闲连接的清理逻辑

空闲连接由 HouseKeeper 定期清理。

HouseKeeper 是 HikariCP 中的一个定时任务，负责清理空闲连接、调整连接池大小等。

HouseKeeper 会在启动后 100 毫秒执行第一次任务，然后每隔 housekeepingPeriodMs 毫秒执行一次。

housekeepingPeriodMs 的值由com.zaxxer.hikari.housekeeping.periodMs决定，默认是 30000 毫秒（30秒）。

java 复制代码

private final long housekeepingPeriodMs = Long.getLong("com.zaxxer.hikari.housekeeping.periodMs", SECONDS.toMillis(30));
   
this.houseKeeperTask = houseKeepingExecutorService.scheduleWithFixedDelay(new HouseKeeper(), 100L, housekeepingPeriodMs, MILLISECONDS);

下面我们看看 HouseKeeper 任务具体的实现逻辑。

java 复制代码

private final class HouseKeeper implements Runnable
   {
      ...
      public void run()
      {
         try {
            ...
            if (idleTimeout > 0L && config.getMinimumIdle() < config.getMaximumPoolSize()) {
               logPoolState("Before cleanup ");
               // 获取连接池所有未使用的连接（STATE_NOT_IN_USE）
               final var notInUse = connectionBag.values(STATE_NOT_IN_USE);
               // 计算需要清理的连接数 maxToRemove，即当前未使用连接数减去最小空闲连接数。
               var maxToRemove = notInUse.size() - config.getMinimumIdle();
               for (PoolEntry entry : notInUse) {
                  // 如果连接的空闲时间超过 idleTimeout，则关闭该连接。
                  if (maxToRemove > 0 && elapsedMillis(entry.lastAccessed, now) > idleTimeout && connectionBag.reserve(entry)) {
                     closeConnection(entry, "(connection has passed idleTimeout)");
                     maxToRemove--;
                  }
               }
               logPoolState("After cleanup  ");
            }
            else
               logPoolState("Pool ");
            // 调用 fillPool(true) 以确保连接池维持最小空闲连接数。
            fillPool(true); // Try to maintain minimum connections
         }
         catch (Exception e) {
            logger.error("Unexpected exception in housekeeping task", e);
         }
      }
   }

可以看到，空闲连接能回收的前提是 idleTimeout 大于 0，且 minIdle 小于 maxPoolSize。

如果按照官方建议不显式设置 minIdle 的话，则 minIdle 会取 maxPoolSize 的值，此时空闲连接将不会被回收。

无论是否回收空闲连接，最后都会调用 fillPool 来填充连接池，以确保池中有足够的连接。

空闲连接的持续时长是通过elapsedMillis(entry.lastAccessed, now)计算的，其中 entry.lastAccessed 记录了连接最后一次被访问的时间。该时间戳会在以下两种场景下设置：

创建物理连接时：当一个新的连接被创建并加入连接池时，lastAccessed 会被设置为当前时间，表示连接的创建时间。
连接归还给连接池时：当连接被归还给连接池时，lastAccessed 会更新为归还时的时间。

因此，空闲连接的持续时长实际上等于当前系统时间减去连接最后一次归还给连接池的时间。

maxLifetime

连接池中连接的最大生命周期，单位为毫秒。默认值为 1800000（30分钟），最小允许值是 30000（30秒）。

java 复制代码

if (maxLifetime != 0 && maxLifetime < SECONDS.toMillis(30)) {
   LOGGER.warn("{} - maxLifetime is less than 30000ms, setting to default {}ms.", poolName, MAX_LIFETIME);
   maxLifetime = MAX_LIFETIME;
}

如果 maxLifetime 设置为 0，则表示不限制连接的最大生命周期。

如果 maxLifetime 不等于 0 且小于 30 秒，则会输出警告日志，提示 maxLifetime 设置过短，并将 maxLifetime 设置为默认的最大生命周期 MAX_LIFETIME（即 30 分钟）。

在创建一个新的物理连接时，会为其设置一个到期执行的任务MaxLifetimeTask，该任务将在连接的生命周期到期时执行。连接的生命周期时间等于 maxLifetime 减去一个随机偏移量。

java 复制代码

private PoolEntry createPoolEntry()
   {
      try {
         final var poolEntry = newPoolEntry(getTotalConnections() == 0);

         final var maxLifetime = config.getMaxLifetime();
         if (maxLifetime > 0) {
            // 如果 maxLifetime 大于 10000 毫秒，则生成一个最大为 maxLifetime 的 25% 的随机偏移量
            final var variance = maxLifetime > 10_000L ? ThreadLocalRandom.current().nextLong( maxLifetime / lifeTimeVarianceFactor ) : 0L;
            final var lifetime = maxLifetime - variance;
            poolEntry.setFutureEol(houseKeepingExecutorService.schedule(new MaxLifetimeTask(poolEntry), lifetime, MILLISECONDS));
         }
         ...
         return poolEntry;
      }
      ...
      return null;
   }

当连接的生命周期（lifetime）到期时，MaxLifetimeTask 会被触发，它会调用 softEvictConnection() 方法尝试驱逐该连接。如果驱逐成功，则会调用 addBagItem() 方法判断是否向连接池中添加新的连接。

java 复制代码

private final class MaxLifetimeTask implements Runnable
{
   ...
   public void run()
   {
      if (softEvictConnection(poolEntry, "(connection has passed maxLifetime)", false /* not owner */)) {
         addBagItem(connectionBag.getWaitingThreadCount());
      }
   }
}

下面我们看看softEvictConnection()的实现逻辑。

java 复制代码

private boolean softEvictConnection(final PoolEntry poolEntry, final String reason, final boolean owner)
{
   // 将连接标记为驱逐状态
   poolEntry.markEvicted();
   if (owner || connectionBag.reserve(poolEntry)) {
      closeConnection(poolEntry, reason);
      return true;
   }

   return false;
}

void markEvicted()
{
   this.evict = true;
}

public boolean reserve(final T bagEntry)
{
   return bagEntry.compareAndSet(STATE_NOT_IN_USE, STATE_RESERVED);
}

连接首先会被标记为驱逐状态。

如果调用者是连接的拥有者，或者连接的状态可以从 STATE_NOT_IN_USE（未使用）转变为 STATE_RESERVED（已预留），则会调用 closeConnection 销毁该连接。

需要注意的是，对于正在使用的连接，仅会将其标记为驱逐状态，而不会销毁，即使其生命周期已经到期。只有当连接被归还到连接池时，才会真正执行销毁操作。

下面是连接归还到连接池时的实现细节。

java 复制代码

void recycle(final PoolEntry poolEntry)
{
   metricsTracker.recordConnectionUsage(poolEntry);
   // 如果连接被标记为驱逐状态，则销毁连接
   if (poolEntry.isMarkedEvicted()) { 
      closeConnection(poolEntry, EVICTED_CONNECTION_MESSAGE);
   } else {
      if (isRequestBoundariesEnabled) {
         try {
            poolEntry.connection.endRequest();
         } catch (SQLException e) {
            logger.warn("endRequest Failed for: {},({})", poolEntry.connection, e.getMessage());
         }
      }
      // 如果连接未被标记为驱逐，将执行正常的连接归还操作
      connectionBag.requite(poolEntry);
   }
}

如果连接被标记为驱逐状态，则会销毁该连接。如果连接未被标记为驱逐，则会执行正常的连接归还操作。

keepaliveTime

对空闲连接进行定期心跳检测的时间间隔，单位为毫秒。默认值为 120000（2分钟），最小允许值是 30000（30秒）。

java 复制代码

if (keepaliveTime != 0 && keepaliveTime < SECONDS.toMillis(30)) {
   LOGGER.warn("{} - keepaliveTime is less than 30000ms, disabling it.", poolName);
   keepaliveTime = 0L;
}

如果 keepaliveTime 不等于 0 且小于 30 秒，则输出警告日志，提示 keepaliveTime 设置过短，并禁用心跳检测（将 keepaliveTime 设置为 0）。

定期检测的目的主要有两个：

检测连接是否失效。
防止连接因长时间空闲而被数据库或其他中间层关闭。

在创建新的物理连接时，会为其设置一个定期执行的任务KeepaliveTask，该任务会在 heartbeatTime 后首次执行，并随后以相同的时间间隔（heartbeatTime）重复执行。heartbeatTime 等于 keepaliveTime 减去一个随机偏移量（variance）。

variance 是最大为 keepaliveTime 的 10% 的随机偏移量。引入该随机偏移量的目的是为了避免所有连接在同一时刻发送心跳，从而减轻系统资源竞争和负载。

java 复制代码

private PoolEntry createPoolEntry()
   {
      try {
         final var poolEntry = newPoolEntry(getTotalConnections() == 0);
         ...
         final long keepaliveTime = config.getKeepaliveTime();
         if (keepaliveTime > 0) {
            // variance up to 10% of the heartbeat time
            final var variance = ThreadLocalRandom.current().nextLong(keepaliveTime / 10);
            final var heartbeatTime = keepaliveTime - variance;
            poolEntry.setKeepalive(houseKeepingExecutorService.scheduleWithFixedDelay(new KeepaliveTask(poolEntry), heartbeatTime, heartbeatTime, MILLISECONDS));
         }

         return poolEntry;
      }
      ...
      return null;
   }

以下是 KeepaliveTask 的具体实现。

java 复制代码

private final class KeepaliveTask implements Runnable
   {
      ...
      public void run()
      {
         // 尝试将连接的状态从 STATE_NOT_IN_USE（未使用）改为 STATE_RESERVED（已保留），防止它被其他线程借用
         if (connectionBag.reserve(poolEntry)) {
            // 检查连接是否失效
            if (isConnectionDead(poolEntry.connection)) {
               // 将连接从连接池中移除并关闭
               softEvictConnection(poolEntry, DEAD_CONNECTION_MESSAGE, true);
               // 检查当前等待连接的线程数，判断是否向连接池中添加新的连接
               addBagItem(connectionBag.getWaitingThreadCount());
            }
            else {
               connectionBag.unreserve(poolEntry);
               logger.debug("{} - keepalive: connection {} is alive", poolName, poolEntry.connection);
            }
         }
      }
   }

connectionTestQuery

用于设置连接检测语句，默认为 none。

对于支持 JDBC4 的驱动程序，建议不要设置该参数，因为 JDBC4 提供了Connection.isValid()方法来进行连接有效性检查。

JDBC4 是 Java Database Connectivity (JDBC) 的第 4 版，首次在 Java 6（即 Java 1.6）中引入。因此，只要程序使用的是 Java 1.6 及更高版本，就可以使用isValid()方法。

连接有效性检测的实现逻辑

如果 connectionTestQuery 为 none，则会将 isUseJdbc4Validation 设置为 true。

java 复制代码

// 如果 connectionTestQuery 为 none，则将其设置为 null
connectionTestQuery = getNullIfEmpty(connectionTestQuery);

// 如果 connectionTestQuery 为 null，则 isUseJdbc4Validation 设置为 true。
this.isUseJdbc4Validation = config.getConnectionTestQuery() == null;

isUseJdbc4Validation 会用在两个地方：

判断驱动是否支持connection.isValid方法。
检测连接是否失效。

检测连接是否失效是在isConnectionDead中实现的。

java 复制代码

boolean isConnectionDead(final Connection connection)
   {
      try {
         setNetworkTimeout(connection, validationTimeout);
         try {
            final var validationSeconds = (int) Math.max(1000L, validationTimeout) / 1000;

            if (isUseJdbc4Validation) {
               return !connection.isValid(validationSeconds);
            }

            try (var statement = connection.createStatement()) {
               if (isNetworkTimeoutSupported != TRUE) {
                  setQueryTimeout(statement, validationSeconds);
               }

               statement.execute(config.getConnectionTestQuery());
            }
         }
         ...
      }
   }

可以看到，如果 isUseJdbc4Validation 为 true，则会调用connection.isValid方法来检测连接的有效性。否则，系统将使用配置的 connectionTestQuery 来执行 SQL 查询，以检查连接是否有效。

leakDetectionThreshold

连接从池中取出后，如果未归还超过一定时间，则会记录日志，提示可能的连接泄漏。默认值为 0，表示禁用泄漏检测。

java 复制代码

if (leakDetectionThreshold > 0 && !unitTest) {
   if (leakDetectionThreshold < SECONDS.toMillis(2) || (leakDetectionThreshold > maxLifetime && maxLifetime > 0)) {
      LOGGER.warn("{} - leakDetectionThreshold is less than 2000ms or more than maxLifetime, disabling it.", poolName);
      leakDetectionThreshold = 0;
   }
}

如果 leakDetectionThreshold 小于 2 秒，或者 leakDetectionThreshold 大于连接池的 maxLifetime，则会发出警告，并将其重置为 0，禁用泄漏检测。

实现细节可参考：如何定位 Druid & HikariCP 连接池的连接泄漏问题？

什么时候会检测连接的有效性？

除了通过 KeepaliveTask 定期检查连接的有效性外，HikariCP 还会在借用连接时进行有效性检测。

这个检测逻辑在 getConnection 方法中实现。具体来说，在从连接池借用连接后，会检查连接的最后归还时间（poolEntry.lastAccessed）与当前时间的差值是否超过 aliveBypassWindowMs（默认 500 毫秒）。如果超过该时间阈值，则会调用 isConnectionDead(poolEntry.connection) 来检查连接是否失效。

java 复制代码

public Connection getConnection(final long hardTimeout) throws SQLException
   {
      suspendResumeLock.acquire();
      final var startTime = currentTime();

      try {
         var timeout = hardTimeout;
         do {
            // 从连接池中借用一个连接
            var poolEntry = connectionBag.borrow(timeout, MILLISECONDS);
            if (poolEntry == null) {
               break; // We timed out... break and throw exception
            }

            final var now = currentTime();
            if (poolEntry.isMarkedEvicted() || (elapsedMillis(poolEntry.lastAccessed, now) > aliveBypassWindowMs && isConnectionDead(poolEntry.connection))) {
               closeConnection(poolEntry, poolEntry.isMarkedEvicted() ? EVICTED_CONNECTION_MESSAGE : DEAD_CONNECTION_MESSAGE);
               timeout = hardTimeout - elapsedMillis(startTime);
            }
            else {
               ...
               return poolEntry.createProxyConnection(leakTaskFactory.schedule(poolEntry));
            }
         } while (timeout > 0L);
        ...
   }

aliveBypassWindowMs 由配置项com.zaxxer.hikari.aliveBypassWindowMs控制，默认值为 500 毫秒。

这一逻辑与其他连接池中的 testOnBorrow 参数类似，只不过 testOnBorrow 是每次都检查，而 HikariCP 只有在连接空闲超过 500 毫秒时才会检查。