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

决台 · 4 天前

HikariCP 是目前风头最劲的 JDBC 连接池，号称性能最佳，SpringBoot 2.0 也将 HikariCP 作为默认的数据库连接池。
要想用好 HikariCP，理解常见参数的具体含义至关重要。但是对于某些参数，尽管官方文档给出了详细解释，很多开发、DBA 读完后还是会感到困惑。
因此，本文将从源码角度对 HikariCP 中的一些常见参数进行分析，希望能帮助大家更加清晰地理解这些参数的具体含义。
本文将分析的参数包括：

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

maximumPoolSize

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

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

复制代码

连接池中的空闲连接是指当前没有被使用、处于空闲状态的连接。空闲连接可以随时被借用（即从连接池中获取）来进行数据库操作。
注意，空闲连接在 MySQL 中的状态是Sleep，但不是所有Sleep状态的连接都是空闲连接。
空闲连接的清理逻辑

空闲连接由 HouseKeeper 定期清理。
HouseKeeper 是 HikariCP 中的一个定时任务，负责清理空闲连接、调整连接池大小等。
HouseKeeper 会在启动后 100 毫秒执行第一次任务，然后每隔 housekeepingPeriodMs 毫秒执行一次。
housekeepingPeriodMs 的值由com.zaxxer.hikari.housekeeping.periodMs决定，默认是 30000 毫秒（30秒）。

public Connection getConnection() throws SQLException { return getConnection(connectionTimeout); } public Connection getConnection(final long hardTimeout) throws SQLException { suspendResumeLock.acquire(); finalvar startTime = currentTime(); try { var timeout = hardTimeout; do { var poolEntry = connectionBag.borrow(timeout, MILLISECONDS); ... }

复制代码

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

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

复制代码

可以看到，空闲连接能回收的前提是 idleTimeout 大于 0，且 minIdle 小于 maxPoolSize。
如果按照官方建议不显式设置 minIdle 的话，则 minIdle 会取 maxPoolSize 的值，此时空闲连接将不会被回收。
无论是否回收空闲连接，最后都会调用 fillPool 来填充连接池，以确保池中有足够的连接。
空闲连接的持续时长是通过elapsedMillis(entry.lastAccessed, now)计算的，其中 entry.lastAccessed 记录了连接最后一次被访问的时间。该时间戳会在以下两种场景下设置：

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

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

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

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

复制代码

如果 maxLifetime 设置为 0，则表示不限制连接的最大生命周期。
如果 maxLifetime 不等于 0 且小于 30 秒，则会输出警告日志，提示 maxLifetime 设置过短，并将 maxLifetime 设置为默认的最大生命周期 MAX_LIFETIME（即 30 分钟）。
在创建一个新的物理连接时，会为其设置一个到期执行的任务MaxLifetimeTask，该任务将在连接的生命周期到期时执行。连接的生命周期时间等于 maxLifetime 减去一个随机偏移量。

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; } }

复制代码

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

// 如果 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); }

复制代码

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

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

复制代码

连接首先会被标记为驱逐状态。
如果调用者是连接的拥有者，或者连接的状态可以从 STATE_NOT_IN_USE（未使用）转变为 STATE_RESERVED（已预留），则会调用 closeConnection 销毁该连接。
需要注意的是，对于正在使用的连接，仅会将其标记为驱逐状态，而不会销毁，即使其生命周期已经到期。只有当连接被归还到连接池时，才会真正执行销毁操作。
下面是连接归还到连接池时的实现细节。

private finalclass HouseKeeper implements Runnable { ... public void run() { try { ... if (idleTimeout > 0L && config.getMinimumIdle() < config.getMaximumPoolSize()) { logPoolState("Before cleanup "); // 获取连接池所有未使用的连接（STATE_NOT_IN_USE） finalvar 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); } } }

复制代码

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

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

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

复制代码

如果 keepaliveTime 不等于 0 且小于 30 秒，则输出警告日志，提示 keepaliveTime 设置过短，并禁用心跳检测（将 keepaliveTime 设置为 0）。
定期检测的目的主要有两个：

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

在创建新的物理连接时，会为其设置一个定期执行的任务KeepaliveTask，该任务会在 heartbeatTime 后首次执行，并随后以相同的时间间隔（heartbeatTime）重复执行。heartbeatTime 等于 keepaliveTime 减去一个随机偏移量（variance）。
variance 是最大为 keepaliveTime 的 10% 的随机偏移量。引入该随机偏移量的目的是为了避免所有连接在同一时刻发送心跳，从而减轻系统资源竞争和负载。

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

复制代码

以下是 KeepaliveTask 的具体实现。

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

复制代码

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。

private boolean softEvictConnection(final PoolEntry poolEntry, final String reason, final boolean owner) { // 将连接标记为驱逐状态 poolEntry.markEvicted(); if (owner || connectionBag.reserve(poolEntry)) { closeConnection(poolEntry, reason); returntrue; } returnfalse; } void markEvicted() { this.evict = true; } public boolean reserve(final T bagEntry) { return bagEntry.compareAndSet(STATE_NOT_IN_USE, STATE_RESERVED); }

复制代码

isUseJdbc4Validation 会用在两个地方：

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

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

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); } }

复制代码

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

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

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

复制代码

如果 leakDetectionThreshold 小于 2 秒，或者 leakDetectionThreshold 大于连接池的 maxLifetime，则会发出警告，并将其重置为 0，禁用泄漏检测。
实现细节可参考：如何定位 Druid & HikariCP 连接池的连接泄漏问题？
什么时候会检测连接的有效性？

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

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

复制代码

aliveBypassWindowMs 由配置项com.zaxxer.hikari.aliveBypassWindowMs控制，默认值为 500 毫秒。
这一逻辑与其他连接池中的 testOnBorrow 参数类似，只不过 testOnBorrow 是每次都检查，而 HikariCP 只有在连接空闲超过 500 毫秒时才会检查。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

账号		自动登录	找回密码
密码			立即注册