4. HikariCP 核心参数详解（上）：maximumPoolSize、minimumIdle、connectionTimeout、idleTimeout

HikariCP 作为 Spring Boot 2.x+ 的默认连接池，其性能优势很大程度上源于精简且合理的参数设计。本章聚焦四个最核心的运行时参数，理解它们的含义、默认值及交互关系，是后续调优的基础。

4.1 参数总览与默认值速查

下表列出了四个核心参数的名称、默认值及简要作用域。所有参数均在 spring.datasource.hikari.* 命名空间下配置。

4.2 maximumPoolSize：池的绝对上限

maximumPoolSize 定义了连接池能容纳的最大连接总数，包括正在被使用的连接和空闲连接。这是连接池最重要的容量约束。

• 作用： 控制后端数据库的连接并发上限，防止应用过度消耗数据库连接资源。
• 默认值： 10。对于大多数中小型 BFF 应用，10 个连接通常足够；但高并发场景需要根据压测结果上调。
• 设置原则： 并非越大越好。过大的连接数会导致数据库端上下文切换开销增加，反而降低吞吐量。推荐公式：maximumPoolSize = (core_count * 2) + effective_spindle_count（经验值，需结合实际压测）。

4.3 minimumIdle：空闲连接保底策略

minimumIdle 控制连接池试图保持的最少空闲连接数。当空闲连接数低于此值时，HikariCP 会尝试创建新连接（受 maximumPoolSize 约束）。

• 默认值： 等于 maximumPoolSize（即 10）。此时池中始终维持所有连接存活，没有空闲回收。
• 调优场景：
  • 节省资源： 对于流量波动大的 BFF 服务，可降低 minimumIdle（如 2~5），让低峰期释放空闲连接，减少数据库端资源占用。
  • 快速响应： 如果业务对连接获取延迟极其敏感，保持较高的 minimumIdle 可以减少新建连接的开销。
• 与 maximumPoolSize 的关系： minimumIdle 必须 ≤ maximumPoolSize。当两者相等时，池为“固定大小”模式；当 minimumIdle 小于 maximumPoolSize 时，池为“弹性伸缩”模式。

4.4 connectionTimeout：获取连接的等待极限

connectionTimeout 定义了客户端线程从连接池请求连接时，愿意等待的最大毫秒数。如果超时仍未获取到连接，HikariCP 会抛出 SQLTransientConnectionException。

• 默认值： 30000 ms（30 秒）。对于 BFF 层，这个值通常偏长。
• 调优建议：
  • BFF 场景： 建议设置为 5000~10000 ms（5~10 秒）。过长的超时会让用户请求长时间挂起，占用 Tomcat 线程。
  • 配合重试： 如果业务允许重试，可以设置更短的超时（如 3000 ms），快速失败并触发重试逻辑。
• 超时后的行为： 抛出异常，不会自动重试。应用层需要捕获异常并决定是否重试或降级。

4.5 idleTimeout：空闲连接的生存周期

idleTimeout 控制一个连接在池中保持空闲状态的最大时间。超过此时间，连接会被逐出池（evict）。此参数仅在 minimumIdle 小于 maximumPoolSize 时生效。

• 默认值： 600000 ms（10 分钟）。
• 生效条件： 当前空闲连接数 > minimumIdle。只有当池中有“多余”的空闲连接时，才会触发回收。
• 调优场景：
  • 短连接场景： 如果数据库侧有连接空闲超时回收策略（如 MySQL 的 wait_timeout 默认 8 小时），建议将 idleTimeout 设置为小于数据库侧的超时时间，避免连接被数据库端意外关闭。
  • 节省资源： 对于低流量 BFF，可以降低 idleTimeout（如 300000 ms / 5 分钟），更快释放空闲连接。

4.6 参数交互关系图解

下图展示了四个核心参数在连接池生命周期中的交互位置：

4.7 参数配置示例

以下是一个典型的 BFF 服务配置，适用于中等流量、弹性伸缩的场景：

# application.yml
spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 8000
      idle-timeout: 300000

• maximum-pool-size: 20 — 允许高峰时最多 20 个并发连接。
• minimum-idle: 5 — 低峰期保持 5 个常驻连接，减少新建开销。
• connection-timeout: 8000 — 8 秒获取超时，避免长时间阻塞 Tomcat 线程。
• idle-timeout: 300000 — 空闲 5 分钟后回收多余连接，释放数据库资源。