Skip to content

JDBC-连接池 ​

[TOC]

概述 ​

传统直连弊端 ​

在标准的原生 JDBC 编程中,每次执行数据库操作都需要经历“建立物理连接 -> 执行 SQL -> 销毁物理连接”的完整生命周期。这种“用完即弃”的直连模式在并发场景下存在严重的性能瓶颈与资源隐患:

  1. 网络与认证开销大:每次调用 DriverManager.getConnection() 时,底层都需要经过 TCP 三次握手、MySQL 协议握手、账户密码权限校验以及服务端线程与内存分配;调用 Connection.close() 时又要经历 TCP 四次挥手与服务端资源释放。对于简单的查询语句,建立和销毁连接的耗时往往远超 SQL 本身的执行时间。

  2. 连接数失控引发崩溃:原生 DriverManager 不具备连接数量上限控制能力。当业务遭遇突发高并发请求时,应用程序会瞬间向数据库发起大量物理连接请求,极易耗尽数据库的连接数上限(如抛出 Too many connections 异常)或耗尽服务器内存与 CPU 资源,导致数据库宕机。

  3. 连接泄漏难以排查:若开发人员在业务代码中遗漏了 close() 调用,或者在异常分支中未能正确释放连接,物理连接将长期被无效占用,最终拖垮整个应用。

下面通过一段循环获取与释放连接的测试代码,直观展示传统 DriverManager 直连在高频操作下的性能表现:

java
package com.example.pool;

import java.sql.Connection;
import java.sql.DriverManager;

// 1. 演示传统 DriverManager 直连模式的高频连接开销
public class TraditionalJdbcDemo {

  // 2. 循环获取并销毁物理连接,测试整体耗时
  public static void main(String[] args) throws Exception {
    String url = "jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC";
    // 3. 记录测试起始时间戳
    long startTime = System.currentTimeMillis();

    for (int i = 0; i < 5000; i++) {
      Connection connection = DriverManager.getConnection(url, "root", "root");

      // 4. 销毁底层 TCP 物理连接,触发四次挥手与服务端内存回收
      connection.close();
    }

    long endTime = System.currentTimeMillis();

    // 5. 输出五千次物理连接创建与销毁的总耗时
    System.out.println("传统直连耗时: " + (endTime - startTime) + " ms");
  }
}

连接池化机制 ​

数据库连接池(Connection Pool) 基于池化思想(Pooling) 设计,本质是一个负责统一分配、管理和释放数据库连接的缓冲容器。它通过预先创建、循环复用、上限管控三大手段,彻底解决了传统直连的性能缺陷。

数据库连接池的完整运行生命周期分为以下四个阶段:

  1. 初始化预热:系统启动或首次访问连接池时,连接池根据配置的初始连接数(initialSize),预先与数据库建立指定数量的物理连接,并将其保存在内存空闲队列中待命。

  2. 连接借出:当业务线程需要访问数据库时,不再新建物理连接,而是向连接池申请。连接池从空闲队列中取出一个可用连接返回给调用方,并将其标记为“活跃(Active)”状态。

  3. 阻塞与扩容:若当前空闲队列为空,且已创建的连接总数未达到最大上限(maxPoolSize / maxActive),连接池会动态新建物理连接并分配给线程;若连接总数已达上限,后续请求线程将进入阻塞等待队列,直至有其他线程归还连接或等待超时抛出异常。

  4. 连接归还:当业务线程执行完 SQL 并调用 connection.close() 时,连接池通过动态代理或装饰器模式拦截了该方法——不再真正断开底层 TCP 物理连接,而是清理连接上的状态(如重置自动提交标志、清理未关闭的 Statement),随后将该连接重新放回空闲队列,供后续请求复用。

image-20261104111604726

核心控制参数 ​

尽管不同厂商的连接池实现各异,但它们在容量管控、超时控制与保活检测上共享一套核心配置参数:

参数类别通用参数概念作用说明
容量控制初始连接数(initialSize)连接池启动时预先创建的物理连接数量。
容量控制最小空闲连接数(minIdle)空闲队列中常驻保留的最少连接数,低于该值时连接池会自动补充。
容量控制最大连接数(maxActive / maximumPoolSize)连接池允许同时存在的最大物理连接上限,防止压垮数据库。
超时控制最大等待时间(maxWait / connectionTimeout)池中无可用连接时,调用方线程阻塞等待的最大毫秒数,超时则抛出异常。
生命周期最大空闲时间(maxIdleTime / idleTimeout)空闲连接在池中存活的最长时间,超出后将被销毁以释放多余资源。
保活检测有效性检测(validationQuery / connectionTestQuery)借出或空闲巡检时探活连接是否有效的机制,避免应用拿到已被数据库服务端主动断开的“死连接”。

主流技术演进 ​

Java 生态中的数据库连接池经历了从早期开源方案向高性能、云原生与可观测性方向的演进:

DBCP ​

Apache 基金会早期推出的连接池(Commons DBCP),曾是 Tomcat 与早期 Spring 项目的常见选型。早期的 DBCP 1.x 采用单线程锁机制,在高并发下性能较差且容易出现死锁;后续基于 Commons Pool 2 重构的 DBCP2 虽有所改善,但整体性能与功能已被后起之秀超越。

C3P0 ​

老牌开源连接池,曾与 Hibernate 框架深度绑定。C3P0 支持自动回收空闲连接与 PreparedStatement 缓存,稳定性较好;但由于其底层架构陈旧、内部锁竞争激烈,在现代高并发场景下吞吐量偏低,目前仅在维护遗留系统时遇到。

Druid ​

阿里巴巴开源的企业级数据库连接池。Druid 不仅具备优异的并发性能,还内置了强大的监控统计(StatFilter)、SQL 防注入防火墙(WallFilter)、慢 SQL 日志记录以及密码加密等扩展能力,在对可观测性与安全性要求较高的国内企业级项目中应用广泛。

HikariCP ​

目前性能最强的轻量级数据库连接池,自 Spring Boot 2.x 起成为官方默认连接池。HikariCP 通过字节码级精简、自定义的 FastList(消除 ArrayList 的越界检查与从头扫描)以及无锁集合 ConcurrentBag(基于 ThreadLocal 本地缓存与窃取机制),将连接借出与归还的开销压榨到了极致。

DataSource ​

统一数据源标准 ​

在早期 JDBC 1.0 规范中,应用程序只能通过 java.sql.DriverManager 类获取数据库连接。随着企业级应用对连接池化和分布式事务的需求日益迫切,Java 自 JDBC 2.0 扩展包起引入了 javax.sql.DataSource 接口,将其确立为获取数据库连接的官方标准工厂接口。

如果各个连接池厂商(如 C3P0、Druid、HikariCP)各自设计一套获取连接的专有方法(例如 getC3p0Conn()、fetchDruidConn()),业务层与持久层框架(如 MyBatis、Spring JDBC)的代码就会与特定第三方库深度耦合。一旦项目需要更换连接池,所有获取连接的代码都必须推倒重写。

javax.sql.DataSource 的核心价值在于面向接口编程与依赖解耦:

  1. 标准调用契约:Java 官方只定义 DataSource 接口规范而不提供具体实现,由各大数据库厂商和开源连接池组件负责编写实现类。

  2. 无缝切换实现:业务代码只需面向 javax.sql.DataSource 接口调用 getConnection() 方法。当底层从 C3P0 替换为 Druid 或 HikariCP 时,仅需修改数据源初始化配置,核心业务代码无需任何改动。

对比 DriverManager ​

相较于传统的 DriverManager,官方强烈推荐使用 DataSource 获取数据库连接,二者在架构定位与功能特性上存在本质差异:

对比维度java.sql.DriverManagerjavax.sql.DataSource
定位与角色早期的静态工具管理类现代标准数据源工厂接口
连接池支持不支持,每次调用均创建新的 TCP 物理连接天然支持,主流实现类均内置连接池复用机制
分布式事务不支持扩展子接口 XADataSource 支持跨库分布式事务
属性配置方式硬编码 URL 字符串或传递 Properties符合 JavaBean 规范,支持通过 Setter 或外部配置注入
JNDI 容器集成无法绑定至应用服务器命名目录支持注册到 JNDI 命名服务,由容器集中托管
并发扩展性底层方法使用 synchronized 同步锁,高并发易阻塞由各连接池实现类通过细粒度锁或无锁结构优化

接口继承体系 ​

在 JDK 源码中,javax.sql.DataSource 继承自 CommonDataSource 与 Wrapper 两个父接口,各层级的职责划分十分明确:

image-20261104111733547

java
package javax.sql;

import java.sql.Connection;
// 1. 继承公共数据源配置接口与代理包装器接口
import java.sql.SQLException;
import java.sql.Wrapper;
// 2. 定义获取数据库连接的统一工厂标准
public interface DataSource extends CommonDataSource, Wrapper {

  Connection getConnection() throws SQLException;

  Connection getConnection(String username, String password) throws SQLException;
}

CommonDataSource ​

自 JDK 1.6 引入的顶层父接口,提取了普通数据源(DataSource)、连接池底层数据源(ConnectionPoolDataSource)以及分布式事务数据源(XADataSource)的公共管理能力,主要负责管理日志输出流(LogWriter)、登录超时时间(LoginTimeout)以及父级日志记录器(ParentLogger)。

Wrapper ​

自 JDK 1.6 引入的包装器模式接口。由于连接池普遍采用代理或装饰器模式对原生 DataSource 和 Connection 进行多层包装,当开发者需要绕过标准接口、直接调用底层特定厂商实现类的专有扩展方法时,可通过 Wrapper 提供的 unwrap(Class<T> iface) 方法将代理对象安全拆包为目标实现类。

Connection.close 动态代理拦截 ​

使用连接池时,开发者最常产生的一个疑问是:为什么从 DataSource 获取的 Connection 对象,在调用 connection.close() 后并没有断开物理连接,而是归还到了池中?

这背后的核心机制是装饰器模式(Decorator) 或 JDK 动态代理(Dynamic Proxy)。连接池在初始化时,会通过底层的 DriverManager 创建真正的物理连接(如 MySQL 驱动的 ConnectionImpl),但绝对不会将这个物理连接直接暴露给调用方:

  1. 包装物理连接:连接池在内部创建一个实现了 java.sql.Connection 接口的代理包装对象(例如 Druid 中的 DruidPooledConnection、HikariCP 中的 HikariProxyConnection),并将真正的物理连接封装在该包装对象内部。

  2. 转发常规操作:当业务代码调用 createStatement()、prepareStatement() 或 commit() 等常规方法时,包装对象直接将请求委托给内部的真实物理连接执行。

  3. 拦截关闭操作:当业务代码调用 close() 方法时,包装对象会拦截该调用——不触发真实物理连接的 close() 方法,而是清理当前连接上的临时状态,并将包装对象关联的池化条目重新放回连接池的空闲队列中。

image-20261104111809880

下面通过手写一个极简的自定义连接池 SimpleDataSource 与动态代理连接,完整还原 DataSource 拦截 close() 归还连接的底层原理:

java
package com.example.pool;

import javax.sql.DataSource;
import java.io.PrintWriter;
import java.lang.reflect.Proxy;
import java.sql.*;
import java.util.LinkedList;
import java.util.logging.Logger;

// 1. 自定义极简数据源,实现官方 javax.sql.DataSource 标准接口
public class SimpleDataSource implements DataSource {

  // 2. 定义空闲连接队列,用于存储预先创建的物理连接
  private final LinkedList<Connection> idlePool = new LinkedList<>();

  // 3. 构造器预热:预先创建 3 个真实物理连接放入空闲队列
  public SimpleDataSource(String url, String user, String password) throws SQLException {
    for (int i = 0; i < 3; i++) {
      Connection realConn = DriverManager.getConnection(url, user, password);
      idlePool.addLast(realConn);
    }
  }

  // 4. 实现标准获取连接方法,返回包装后的动态代理连接
  @Override
  public Connection getConnection() throws SQLException {
    if (idlePool.isEmpty()) {
      throw new SQLException("连接池已耗尽,暂无可用空闲连接");
    }

    final Connection realConn = idlePool.removeFirst();

    // 5. 使用 JDK 动态代理包装真实连接,拦截 close 方法调用
    return (Connection) Proxy.newProxyInstance(
        realConn.getClass().getClassLoader(),
        new Class[]{Connection.class},
        (proxy, method, args) -> {
          // 6. 若调用的是 close 方法,不关闭物理连接,而是将其归还至空闲队列
          if ("close".equals(method.getName())) {
            idlePool.addLast(realConn);
            System.out.println("拦截 close():连接已归还至连接池,当前空闲数 = " + idlePool.size());
            return null;
          }
          // 7. 其他方法(如 prepareStatement)直接转发给底层真实物理连接执行
          return method.invoke(realConn, args);
        }
    );
  }

  // 8. 省略其余未使用的接口默认实现方法
  @Override
  public Connection getConnection(String username, String password) throws SQLException { return null; }
  @Override
  public PrintWriter getLogWriter() throws SQLException { return null; }
  @Override
  public void setLogWriter(PrintWriter out) throws SQLException {}
  @Override
  public void setLoginTimeout(int seconds) throws SQLException {}
  @Override
  public int getLoginTimeout() throws SQLException { return 0; }
  @Override
  public Logger getParentLogger() { return null; }
  @Override
  public <T> T unwrap(Class<T> iface) throws SQLException { return null; }
  @Override
  public boolean isWrapperFor(Class<?> iface) throws SQLException { return false; }

  // 9. 测试面向 DataSource 接口获取与归还连接
  public static void main(String[] args) throws Exception {
    String url = "jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC";
    DataSource dataSource = new SimpleDataSource(url, "root", "root");

    // 10. 配合 try-with-resources 语法,代码块结束时自动触发代理对象的 close() 归还连接
    try (Connection conn = dataSource.getConnection()) {
      System.out.println("成功借出代理连接: " + conn.getClass().getName());
    }
  }
}

API: DataSource ​

连接获取 ​

  • getConnection():数据源连接获取。从当前 DataSource 数据源(或底层数据库连接池)中获取一条可用的 Connection 数据库连接会话。

    • Connection:(),预设凭证获取连接。使用数据源初始化时已预先配置好的默认用户名与密码尝试建立或从连接池借出一条数据库连接。
    • Connection:(String username, String password),指定账密获取连接。使用显式传入的 username 和 password 覆盖默认凭证,向数据源申请建立一条数据库连接。
  • ConnectionBuilder createConnectionBuilder():(),连接构建器创建。自 JDK 9 引入的 default 默认方法,创建并返回一个支持链式设置用户名、密码及分片键(ShardingKey)的 ConnectionBuilder 实例;若底层驱动或连接池未实现该方法,则默认抛出 SQLFeatureNotSupportedException。

注意事项:

  1. DataSource 是取代 DriverManager 获取数据库连接的首选标准接口,其常见实现分为三类:基础直连实现(每次调用 getConnection() 均新建物理连接,如 MysqlDataSource)、连接池实现(由 Druid、HikariCP 等管理连接复用,调用 Connection.close() 时将连接归还池中而非物理断开)以及分布式事务实现(配合 XADataSource 生成参与两阶段提交的连接)。
  2. 在主流第三方连接池(如 HikariCP 的 HikariDataSource)中,由于池内连接在初始化时已按统一账号建立,调用带参重载 getConnection(String username, String password) 通常会直接抛出 SQLFeatureNotSupportedException,生产环境中应统一调用无参 getConnection()。
java
import com.mysql.cj.jdbc.MysqlDataSource;
import java.sql.Connection;
import java.sql.ConnectionBuilder;
import java.sql.SQLException;
import javax.sql.DataSource;

public class DataSourceConnectDemo {

  // 1. 初始化数据源实现类并配置基础连接地址
  public static void main(String[] args) throws SQLException {
    MysqlDataSource mysqlDs = new MysqlDataSource();
    mysqlDs.setURL("jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC");
    mysqlDs.setUser("root");
    mysqlDs.setPassword("123456");
    DataSource dataSource = mysqlDs;

    // 2. 调用无参 getConnection 使用数据源预设凭证获取连接
    try (Connection conn = dataSource.getConnection()) {
      System.out.println("无参获取连接成功: " + conn);
    }

    // 3. 调用带参 getConnection 临时覆盖用户名与密码获取连接
    try (Connection customConn = dataSource.getConnection("root", "123456")) {
      System.out.println("指定账密获取连接成功: " + customConn);
    }

    // 4. 演示使用 JDK 9 引入的 ConnectionBuilder 构建器模式获取连接
    try {
      ConnectionBuilder builder = dataSource.createConnectionBuilder();
      try (Connection builtConn = builder.user("root").password("123456").build()) {
        System.out.println("Builder 获取连接成功: " + builtConn);
      }
    } catch (SQLException e) {
      System.out.println("当前驱动对 ConnectionBuilder 的支持状态: " + e.getMessage());
    }
  }
}

诊断配置 ​

  • void setLoginTimeout():(int seconds),连接超时时间设置。设置当前 DataSource 在尝试连接底层数据库时允许等待的最大秒数;设为 0 表示采用系统默认超时时间或无超时限制。

  • int getLoginTimeout():(),连接超时时间获取。返回当前 DataSource 等待建立数据库连接的最大允许秒数。

  • void setLogWriter():(PrintWriter out),日志字符流设置。为当前 DataSource 实例绑定专用的日志追踪与错误诊断字符输出流 PrintWriter;传入 null 表示禁用该数据源的日志记录。

  • PrintWriter getLogWriter():(),日志字符流获取。获取当前 DataSource 实例绑定的专用日志追踪字符输出流;若尚未配置则返回 null。

注意事项:

  1. DataSource 中定义的 setLoginTimeout() 和 setLogWriter() 仅对当前 DataSource 实例生效(实例级隔离),不会像 DriverManager.setLoginTimeout() 那样污染整个 JVM 进程的全局配置。
  2. 这四个方法虽继承自父接口 CommonDataSource,但在 DataSource 接口定义中被显式重新声明以保持向后兼容。
java
import com.mysql.cj.jdbc.MysqlDataSource;
import java.io.PrintWriter;
import java.sql.SQLException;
import javax.sql.DataSource;

public class DataSourceConfigDemo {

  // 1. 创建数据源实例并向上转型为标准 DataSource 接口
  public static void main(String[] args) throws SQLException {
    MysqlDataSource mysqlDs = new MysqlDataSource();
    mysqlDs.setURL("jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC");
    DataSource dataSource = mysqlDs;

    // 2. 配置并读取数据源建立物理连接的最大超时秒数
    dataSource.setLoginTimeout(15);
    int timeout = dataSource.getLoginTimeout();
    System.out.println("数据源连接超时时间(秒): " + timeout);

    // 3. 绑定数据源专用的字符日志输出流并验证配置结果
    PrintWriter logWriter = new PrintWriter(System.out, true);
    dataSource.setLogWriter(logWriter);
    if (dataSource.getLogWriter() != null) {
      dataSource.getLogWriter().println("DataSource 诊断日志输出流已启用");
    }
  }
}

继承: CommonDataSource ​

createShardingKeyBuilder, getLoginTimeout, getLogWriter, getParentLogger, setLoginTimeout, setLogWriter

继承: Wrapper ​

isWrapperFor, unwrap

C3P0 连接池 ​

组件架构 ​

C3P0 是一个历史悠久的开源 JDBC 连接池组件,实现了 javax.sql.DataSource 标准接口,并支持 JDBC3 规范与 JDBC2 标准扩展。C3P0 早期曾作为 Hibernate 等 ORM 框架的默认内置连接池,具备自动回收空闲连接、缓存 PreparedStatement 以及支持多命名配置源等特性。

在 C3P0 的架构中,com.mchange.v2.c3p0.ComboPooledDataSource 是最核心的数据源实现类。它在内部组合了连接池管理组件与底层物理驱动数据源,对外提供统一的连接获取与配置入口。

依赖引入 ​

手动引入依赖 ​

在未使用构建工具的普通 Java 项目中,需手动下载并挂载 C3P0(含底层公共基础库)与数据库驱动 Jar 包:

  1. 拷贝依赖包:在项目根目录下新建 lib(或 libs)目录,将下载的 c3p0-0.9.5.5.jar、mchange-commons-java-0.2.19.jar(底层必需依赖,缺失会抛出 NoClassDefFoundError)与 MySQL 驱动包复制到该目录下。

  2. 添加至类路径:在 IDE(如 IntelliJ IDEA)中右键点击该 lib 目录或对应 Jar 包,选择 Add as Library... 将其加入到当前模块的编译与运行类路径中。

Maven 坐标引入 ​

使用 C3P0 连接池时,需在项目的 pom.xml 中引入 c3p0 核心依赖(其底层会自动传递引入 mchange-commons-java 基础工具库)以及对应的数据库驱动:

xml
<dependencies>
    <!-- 1. 引入 C3P0 连接池核心依赖 -->
    <dependency>
        <groupId>com.mchange</groupId>
        <artifactId>c3p0</artifactId>
        <version>0.9.5.5</version>
    </dependency>

    <!-- 2. 引入 MySQL 数据库驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.0.33</version>
    </dependency>
</dependencies>

核心配置参数 ​

C3P0 的配置项主要分为基础连接四要素、池容量控制与超时回收参数:

参数名称默认值参数说明
driverClassnull数据库驱动全限定类名(如 com.mysql.cj.jdbc.Driver)。
jdbcUrlnull数据库连接 URL 地址。
usernull数据库登录用户名。
passwordnull数据库登录密码。
initialPoolSize3连接池初始化时预先创建的物理连接数。
minPoolSize3连接池常驻保留的最小连接数。
maxPoolSize15连接池允许同时存在的最大连接数上限。
acquireIncrement3当池中空闲连接耗尽时,C3P0 一次性向数据库批量新建的连接数量。
checkoutTimeout0池中无可用连接时,调用方线程阻塞等待的最大毫秒数(0 表示无限期等待)。
maxIdleTime0空闲连接的最大存活秒数,超出该时间未被使用的连接将被销毁(0 表示永不销毁)。
maxStatements0连接池全局缓存的 PreparedStatement 总数(0 表示不开启缓存)。

方式: 编程式显式配置 ​

在不依赖外部配置文件的情况下,可以直接实例化 ComboPooledDataSource 对象,并通过调用其 Setter 方法手动注入数据库连接信息与池化参数。这种方式直观清晰,但在修改数据库参数时需要重新编译代码,通常仅用于快速测试或动态构建数据源的场景:

java
package com.example.pool;

import com.mchange.v2.c3p0.ComboPooledDataSource;
import java.sql.Connection;

// 1. 演示通过 Setter 方法编程式配置 C3P0 连接池
public class C3p0ProgrammaticDemo {

  // 2. 构建数据源实例并手动注入连接与容量参数
  public static void main(String[] args) throws Exception {
    ComboPooledDataSource dataSource = new ComboPooledDataSource();

    // 3. 设置数据库连接四要素
    dataSource.setDriverClass("com.mysql.cj.jdbc.Driver");
    dataSource.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    dataSource.setUser("root");
    dataSource.setPassword("root");

    // 4. 设置连接池初始容量与最大容量上限
    dataSource.setInitialPoolSize(5);
    dataSource.setMaxPoolSize(20);
    dataSource.setCheckoutTimeout(3000);

    // 5. 从连接池借出代理连接
    Connection connection = dataSource.getConnection();
    System.out.println("成功获取 C3P0 连接: " + connection);

    // 6. 将连接归还至 C3P0 空闲队列
    connection.close();
  }
}

方式: c3p0-config.xml ​

在实际企业级开发中,通常将连接参数剥离到外部配置文件中。C3P0 内置了约定优于配置的自动加载机制:只要在类路径(resources 根目录)下放置名为 c3p0-config.xml(或 c3p0.properties)的文件,ComboPooledDataSource 在实例化时就会自动扫描并解析该文件,无需编写任何文件读取代码。

c3p0-config.xml 支持定义两个层级的配置节点:

  1. <default-config>:全局默认配置节点。当调用无参构造器 new ComboPooledDataSource() 时,自动读取该节点下的参数。

  2. <named-config name="...">:具名配置节点。用于多数据源场景(例如主从库分离),当调用有参构造器 new ComboPooledDataSource("mysql_master") 时,精准加载对应名称节点下的参数。

image-20261104112147676

以下为放置在 src/main/resources/c3p0-config.xml 中的标准配置文件示例:

xml
<?xml version="1.0" encoding="UTF-8"?>
<c3p0-config>
    <!-- 1. 默认配置:调用无参构造器时自动加载 -->
    <default-config>
        <!-- 2. 数据库连接基础四要素 -->
        <property name="driverClass">com.mysql.cj.jdbc.Driver</property>
        <property name="jdbcUrl">jdbc:mysql://localhost:3306/test_db?useSSL=false&amp;serverTimezone=UTC</property>
        <property name="user">root</property>
        <property name="password">root</property>

        <!-- 3. 连接池容量与超时控制参数 -->
        <property name="initialPoolSize">5</property>
        <property name="minPoolSize">5</property>
        <property name="maxPoolSize">20</property>
        <property name="acquireIncrement">5</property>
        <property name="checkoutTimeout">3000</property>
        <property name="maxIdleTime">60</property>
    </default-config>

    <!-- 4. 具名配置:调用有参构造器传入对应名称时加载 -->
    <named-config name="slave_db">
        <property name="driverClass">com.mysql.cj.jdbc.Driver</property>
        <property name="jdbcUrl">jdbc:mysql://192.168.1.102:3306/slave_db?useSSL=false&amp;serverTimezone=UTC</property>
        <property name="user">readonly</property>
        <property name="password">123456</property>
        <property name="initialPoolSize">10</property>
        <property name="maxPoolSize">50</property>
    </named-config>
</c3p0-config>

配置完成后,Java 代码只需一行构造器调用即可完成数据源初始化:

java
package com.example.pool;

import com.mchange.v2.c3p0.ComboPooledDataSource;
import javax.sql.DataSource;
import java.sql.Connection;

// 1. 演示基于 c3p0-config.xml 自动装配数据源
public class C3p0XmlConfigDemo {

  // 2. 分别加载默认配置与具名配置获取连接
  public static void main(String[] args) throws Exception {
    DataSource defaultDs = new ComboPooledDataSource();
    try (Connection conn = defaultDs.getConnection()) {
      System.out.println("默认数据源连接: " + conn);
    }

    // 3. 传入 named-config 名称,加载从库专属配置
    DataSource slaveDs = new ComboPooledDataSource("slave_db");
    try (Connection slaveConn = slaveDs.getConnection()) {
      System.out.println("具名从库数据源连接: " + slaveConn);
    }
    // 4. try-with-resources 块结束时自动拦截 close() 并归还连接
  }
}

API: ComboPooledDataSource ​

构造方法 ​

  • ComboPooledDataSource():数据源实例构造。创建 C3P0 组合连接池数据源实例,支持加载全局默认配置、指定具名配置节点或控制底层 Bean 属性自动注册行为。
    • ComboPooledDataSource:(),默认配置构造。创建数据源实例并自动扫描类路径下的 c3p0-config.xml 或 c3p0.properties,加载 <default-config> 节点下的全局默认参数。
    • ComboPooledDataSource:(String configName),具名配置构造。根据传入的 configName 匹配并加载 c3p0-config.xml 中对应的 <named-config name="..."> 具名数据源配置节点,常用于多数据源环境。
    • ComboPooledDataSource:(boolean autoregister),注册控制构造。创建默认数据源实例,并通过 autoregister 参数指定是否将该实例自动注册到 C3P0Registry 全局注册中心。

注意事项:

  1. ComboPooledDataSource 重量级程度与数据库连接池相当,一个数据库实例在应用生命周期内仅需创建一个对应的 ComboPooledDataSource 单例,严禁在每次数据库请求时重复 new 构造。
  2. 若调用 (String configName) 构造器时传入的名称在 c3p0-config.xml 中不存在,C3P0 会记录警告日志并退化为加载 <default-config> 默认配置。
java
package com.example.pool;

import com.mchange.v2.c3p0.ComboPooledDataSource;

// 1. 演示 ComboPooledDataSource 重载构造方法的使用
public class ComboConstructorDemo {

  // 2. 分别使用无参默认构造与具名配置构造初始化数据源
  public static void main(String[] args) {
    ComboPooledDataSource defaultDs = new ComboPooledDataSource();
    System.out.println("默认数据源标识: " + defaultDs.getDataSourceName());

    // 3. 传入具名配置名称,加载对应 <named-config> 节点参数
    ComboPooledDataSource namedDs = new ComboPooledDataSource("slave_db");
    System.out.println("具名数据源标识: " + namedDs.getDataSourceName());

    // 4. 释放并销毁底层连接池资源
    defaultDs.close();
    namedDs.close();
  }
}

连接参数配置 ​

  • void setDriverClass():(String driverClass) throws PropertyVetoException,驱动类名设置。显式指定底层 JDBC 数据库驱动的全限定类名(如 com.mysql.cj.jdbc.Driver),当类名受约束验证拒绝时抛出 PropertyVetoException。

  • String getDriverClass():(),驱动类名获取。返回当前数据源已配置的 JDBC 驱动全限定类名。

  • void setJdbcUrl():(String jdbcUrl),连接地址设置。设置底层物理数据库的 JDBC 连接 URL 地址。

  • String getJdbcUrl():(),连接地址获取。返回当前数据源配置的 JDBC 连接 URL 字符串。

  • void setUser():(String user),登录账号设置。设置用于数据库身份认证的登录用户名。

  • String getUser():(),登录账号获取。返回当前数据源配置的数据库登录用户名。

  • void setPassword():(String password),登录密码设置。设置用于数据库身份认证的登录密码。

  • String getPassword():(),登录密码获取。返回当前数据源配置的数据库登录密码。

注意事项:

  1. setDriverClass() 声明了受检异常 java.beans.PropertyVetoException,在编程式配置时必须显式捕获或向上抛出,而 setJdbcUrl()、setUser()、setPassword() 则不抛出受检异常。
java
package com.example.pool;

import com.mchange.v2.c3p0.ComboPooledDataSource;
import java.beans.PropertyVetoException;

// 1. 演示数据库连接基础四要素的读取与写入
public class ComboConnectionConfigDemo {

  // 2. 通过编程式方法注入驱动类、URL 及认证凭据
  public static void main(String[] args) throws PropertyVetoException {
    ComboPooledDataSource dataSource = new ComboPooledDataSource();

    // 3. 配置 JDBC 驱动与数据库连接四要素
    dataSource.setDriverClass("com.mysql.cj.jdbc.Driver");
    dataSource.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    dataSource.setUser("root");
    dataSource.setPassword("root");

    // 4. 验证并读取已生效的连接配置属性
    System.out.println("生效驱动类: " + dataSource.getDriverClass());
    System.out.println("生效连接串: " + dataSource.getJdbcUrl());
    System.out.println("生效用户名: " + dataSource.getUser());

    dataSource.close();
  }
}

容量策略配置 ​

  • void setInitialPoolSize():(int initialPoolSize),初始连接数设置。设置连接池初始化预热阶段预先创建的物理连接数量,默认值为 3,取值应介于 minPoolSize 与 maxPoolSize 之间。

  • int getInitialPoolSize():(),初始连接数获取。返回连接池配置的初始物理连接数。

  • void setMinPoolSize():(int minPoolSize),最小连接数设置。设置连接池常驻维持的最少物理连接数量,默认值为 3。

  • int getMinPoolSize():(),最小连接数获取。返回连接池常驻维持的最少物理连接数量。

  • void setMaxPoolSize():(int maxPoolSize),最大连接数设置。设置连接池允许同时存在的最大物理连接总数上限,默认值为 15。

  • int getMaxPoolSize():(),最大连接数获取。返回连接池允许的最大物理连接总数上限。

  • void setAcquireIncrement():(int acquireIncrement),扩容步长设置。设置当空闲连接耗尽且未达 maxPoolSize 时,C3P0 单次向数据库批量新建的物理连接个数,默认值为 3。

  • void setCheckoutTimeout():(int checkoutTimeout),借出超时设置。设置池中无可用连接时调用线程阻塞等待的最大毫秒数,默认值为 0(表示无限期阻塞等待),超时将抛出 SQLException。

  • void setMaxIdleTime():(int maxIdleTime),最大空闲时间设置。设置空闲连接在池中允许存活的最大秒数,默认值为 0(表示永不回收空闲连接),超过该时长未使用的空闲连接将被异步销毁。

  • void setMaxStatements():(int maxStatements),全局预编译缓存设置。设置连接池管控的全局 PreparedStatement 缓存总容量上限,默认值为 0(表示关闭预编译缓存)。

java
package com.example.pool;

import com.mchange.v2.c3p0.ComboPooledDataSource;

// 1. 演示 C3P0 连接池容量边界与超时回收策略配置
public class ComboPoolSizingDemo {

  // 2. 定制连接池初始容量、扩容步长及超时阈值
  public static void main(String[] args) {
    ComboPooledDataSource dataSource = new ComboPooledDataSource();

    // 3. 设置容量上下限与动态扩容步长
    dataSource.setInitialPoolSize(5);
    dataSource.setMinPoolSize(5);
    dataSource.setMaxPoolSize(30);
    dataSource.setAcquireIncrement(5);

    // 4. 设置借出等待超时毫秒数(3秒)与空闲存活秒数(60秒)
    dataSource.setCheckoutTimeout(3000);
    dataSource.setMaxIdleTime(60);

    System.out.println("初始连接数: " + dataSource.getInitialPoolSize());
    System.out.println("最大连接数: " + dataSource.getMaxPoolSize());

    dataSource.close();
  }
}

连接管理与监控 ​

  • getConnection():池化连接借出。实现自 javax.sql.DataSource 接口,从 C3P0 空闲连接队列中借出一个包装后的代理数据库连接 NewProxyConnection。

    • Connection:() throws SQLException,默认凭据借出连接。使用数据源预设的 user 和 password 从连接池中借出一个可用连接。
    • Connection:(String username, String password) throws SQLException,指定凭据借出连接。使用临时传入的用户名与密码匹配对应的认证池并借出可用连接。
  • int getNumConnectionsDefaultUser():() throws SQLException,总连接数查询。返回当前默认用户池中已建立的物理连接总数(包含活跃连接与空闲连接)。

  • int getNumBusyConnectionsDefaultUser():() throws SQLException,活跃连接数查询。返回当前已被业务线程借出、正在使用中的活跃连接数量。

  • int getNumIdleConnectionsDefaultUser():() throws SQLException,空闲连接数查询。返回当前存放在池中待命、可供立即借出的空闲连接数量。

  • void softResetDefaultUser():() throws SQLException,池连接软重置。异步销毁默认用户池中的所有现有空闲连接,并在正在使用的活跃连接归还后同样将其销毁重建,不中断当前正在执行的业务 SQL。

  • void hardReset():(),数据源硬重置。立即强制关闭池中所有空闲与活跃连接,彻底重置内部 PoolBackedDataSource 状态(会导致正在使用连接的业务线程抛出异常)。

  • void close():(),数据源彻底销毁。关闭当前 C3P0 数据源,断开所有底层 TCP 物理连接并停止后台维护线程,关闭后不可再次使用。

java
package com.example.pool;

import com.mchange.v2.c3p0.ComboPooledDataSource;
import java.sql.Connection;

// 1. 演示 C3P0 连接借出、运行态指标监控与资源销毁
public class ComboPoolMonitorDemo {

  // 2. 借出连接并实时打印池内总连接数、活跃数与空闲数
  public static void main(String[] args) throws Exception {
    ComboPooledDataSource dataSource = new ComboPooledDataSource();
    dataSource.setDriverClass("com.mysql.cj.jdbc.Driver");
    dataSource.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    dataSource.setUser("root");
    dataSource.setPassword("root");
    dataSource.setInitialPoolSize(5);

    // 3. 借出一个代理连接,触发连接池延迟初始化
    try (Connection conn = dataSource.getConnection()) {
      // 4. 查询连接借出期间的运行态监控指标
      System.out.println("当前总连接数: " + dataSource.getNumConnectionsDefaultUser());
      System.out.println("当前活跃连接数: " + dataSource.getNumBusyConnectionsDefaultUser());
      System.out.println("当前空闲连接数: " + dataSource.getNumIdleConnectionsDefaultUser());
    }

    // 5. 连接自动归还后,执行软重置平滑刷新池中物理连接
    dataSource.softResetDefaultUser();
    System.out.println("归还后空闲连接数: " + dataSource.getNumIdleConnectionsDefaultUser());

    // 6. 应用退出前销毁数据源,释放全部后台线程与 TCP 连接
    dataSource.close();
  }
}

继承: Object ​

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

继承: AbstractPoolBackedDataSource ​

assertCpds, close, getConnection, getConnection, getConnectionPoolDataSource, getDataSourceName, getIdentityToken, getLoginTimeout, getLogWriter, getNumBusyConnections, getNumBusyConnectionsAllUsers, getNumBusyConnectionsDefaultUser, getNumConnections, getNumConnectionsAllUsers, getNumConnectionsDefaultUser, getNumFailedCheckinsDefaultUser, getNumFailedCheckoutsDefaultUser, getNumFailedIdleTestsDefaultUser, getNumHelperThreads, getNumIdleConnections, getNumIdleConnectionsAllUsers, getNumIdleConnectionsDefaultUser, getNumThreadsAwaitingCheckoutDefaultUser, getNumUnclosedOrphanedConnections, getNumUnclosedOrphanedConnectionsAllUsers, getNumUnclosedOrphanedConnectionsDefaultUser, getNumUserPools, getReference, getStartTimeMillisDefaultUser, getStatementCacheNumCheckedOutDefaultUser, getStatementCacheNumCheckedOutStatementsAllUsers, getStatementCacheNumConnectionsWithCachedStatementsAllUsers, getStatementCacheNumConnectionsWithCachedStatementsDefaultUser, getStatementCacheNumStatementsAllUsers, getStatementCacheNumStatementsDefaultUser, getThreadPoolNumActiveThreads, getThreadPoolNumIdleThreads, getThreadPoolNumTasksPending, getThreadPoolSize, getThreadPoolStackTraces, getThreadPoolStatus, getUpTimeMillisDefaultUser, hardReset, isWrapperFor, resetPoolManager, resetPoolManager, sampleLastAcquisitionFailureStackTrace, sampleLastAcquisitionFailureStackTraceDefaultUser, sampleLastCheckinFailureStackTrace, sampleLastCheckinFailureStackTraceDefaultUser, sampleLastCheckoutFailureStackTrace, sampleLastCheckoutFailureStackTraceDefaultUser, sampleLastIdleTestFailureStackTrace, sampleLastIdleTestFailureStackTraceDefaultUser, sampleStatementCacheStatus, sampleStatementCacheStatusDefaultUser, sampleThreadPoolStackTraces, sampleThreadPoolStatus, setConnectionPoolDataSource, setDataSourceName, setIdentityToken, setLoginTimeout, setLogWriter, setNumHelperThreads, softReset, softResetAllUsers, softResetDefaultUser, toString, unwrap

继承: AbstractComboPooledDataSource ​

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, getAcquireIncrement, getAcquireRetryAttempts, getAcquireRetryDelay, getAutomaticTestTable, getCheckoutTimeout, getConnectionCustomizerClassName, getConnectionTesterClassName, getContextClassLoaderSource, getDataSourceName, getDebugUnreturnedConnectionStackTraces, getDescription, getDriverClass, getExtensions, getFactoryClassLocation, getForceIgnoreUnresolvedTransactions, getForceSynchronousCheckins, getForceUseNamedDriverClass, getIdleConnectionTestPeriod, getInitialPoolSize, getJdbcUrl, getMaxAdministrativeTaskTime, getMaxConnectionAge, getMaxIdleTime, getMaxIdleTimeExcessConnections, getMaxPoolSize, getMaxStatements, getMaxStatementsPerConnection, getMinPoolSize, getOverrideDefaultPassword, getOverrideDefaultUser, getParentLogger, getPassword, getPreferredTestQuery, getPrivilegeSpawnedThreads, getProperties, getPropertyCycle, getStatementCacheNumDeferredCloseThreads, getTestConnectionOnCheckin, getTestConnectionOnCheckout, getUnreturnedConnectionTimeout, getUser, getUserOverridesAsString, isAutoCommitOnClose, isBreakAfterAcquireFailure, isForceIgnoreUnresolvedTransactions, isForceSynchronousCheckins, isForceUseNamedDriverClass, isPrivilegeSpawnedThreads, isTestConnectionOnCheckin, isTestConnectionOnCheckout, isUsesTraditionalReflectiveProxies, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, setAcquireIncrement, setAcquireRetryAttempts, setAcquireRetryDelay, setAutoCommitOnClose, setAutomaticTestTable, setBreakAfterAcquireFailure, setCheckoutTimeout, setConnectionCustomizerClassName, setConnectionTesterClassName, setContextClassLoaderSource, setDataSourceName, setDebugUnreturnedConnectionStackTraces, setDescription, setDriverClass, setExtensions, setFactoryClassLocation, setForceIgnoreUnresolvedTransactions, setForceSynchronousCheckins, setForceUseNamedDriverClass, setIdleConnectionTestPeriod, setInitialPoolSize, setJdbcUrl, setMaxAdministrativeTaskTime, setMaxConnectionAge, setMaxIdleTime, setMaxIdleTimeExcessConnections, setMaxPoolSize, setMaxStatements, setMaxStatementsPerConnection, setMinPoolSize, setOverrideDefaultPassword, setOverrideDefaultUser, setPassword, setPreferredTestQuery, setPrivilegeSpawnedThreads, setProperties, setPropertyCycle, setStatementCacheNumDeferredCloseThreads, setTestConnectionOnCheckin, setTestConnectionOnCheckout, setUnreturnedConnectionTimeout, setUser, setUserOverridesAsString, setUsesTraditionalReflectiveProxies

HikariCP 连接池 ​

组件架构与依赖引入 ​

HikariCP(名字源自日语“光”,寓意极致的速度)是由 Brett Wooldridge 开发的轻量级、高性能 JDBC 连接池组件。自 Spring Boot 2.0 起,官方正式将默认数据库连接池从 Tomcat JDBC Pool 切换为 HikariCP。它摒弃了繁杂的监控与拦截器包装,专注于将连接借出与归还的吞吐量压榨到极致。

在 HikariCP 的核心类设计中,职责被清晰地拆分为配置类与数据源类:

  1. com.zaxxer.hikari.HikariConfig:负责承载所有的连接参数、池容量策略以及底层驱动属性配置,支持直接通过编程式 Setter 注入或读取外部 .properties 配置文件。

  2. com.zaxxer.hikari.HikariDataSource:实现了 javax.sql.DataSource 标准接口,内部持有 HikariPool 核心池实例,负责对外提供连接借出与数据源销毁能力。

image-20261104112313943

在 Maven 项目中使用 HikariCP 时,需在 pom.xml 中引入 HikariCP 依赖(其底层仅依赖 slf4j-api 日志门面,极为轻量)及对应的数据库驱动:

xml
<dependencies>
    <!-- 1. 引入 HikariCP 高性能连接池核心依赖 -->
    <dependency>
        <groupId>com.zaxxer</groupId>
        <artifactId>HikariCP</artifactId>
        <version>5.1.0</version>
    </dependency>

    <!-- 2. 引入 MySQL 数据库驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.0.33</version>
    </dependency>
</dependencies>

极致性能原理 ​

HikariCP 能够在各类基准测试中远超 C3P0、DBCP2 与 Druid,主要归功于其底层的三项核心架构优化:

image-20261104112252703

ConcurrentBag 无锁并发集合 ​

传统的连接池通常使用阻塞队列(如 LinkedBlockingQueue)或加锁容器来管理空闲连接,高并发借出与归还时不可避免地会产生激烈的锁竞争。HikariCP 专门设计了无锁集合 ConcurrentBag,融合了三种机制来实现近乎零竞争的连接存取:

  1. ThreadLocal 线程本地缓存:每个工作线程优先从自己的 ThreadLocal 列表中倒序获取最近刚归还过的连接,完全无需加锁,大幅提升 CPU 缓存命中率。

  2. CopyOnWriteArrayList 共享池窃取:若当前线程的 ThreadLocal 中没有可用空闲连接,则扫描全局共享的 CopyOnWriteArrayList,通过 CAS(Compare-And-Swap)原子操作将状态为 STATE_NOT_IN_USE 的连接修改为 STATE_IN_USE(即“线程窃取”机制)。

  3. SynchronousQueue 交接等待:若全局共享池中也无空闲连接,调用线程将阻塞在 SynchronousQueue 上,等待后台扩容线程或其他线程归还连接时直接进行一对一交接(Handoff)。

FastList 自定义列表 ​

在 JDBC 规范中,一个 Connection 可以创建多个 Statement,当 Connection 关闭时必须顺带关闭其名下所有未关闭的 Statement。其他连接池普遍使用 java.util.ArrayList 记录当前连接打开的 Statement,但 ArrayList 存在两个性能痛点:

  1. 每次调用 get(int index) 都会执行数组下标越界检查(Range Check)。

  2. 调用 remove(Object o) 移除已关闭的 Statement 时,默认从数组头部(索引 0)开始向后线性扫描;而在实际开发中,Statement 的创建与关闭遵循“后进先出”顺序(最后创建的往往最先关闭)。

HikariCP 自定义了 FastList 替代 ArrayList:彻底移除了越界检查,并将 remove(Object) 改为从数组尾部向前逆序扫描,将移除操作的平均比较次数降至最低。

Javassist 字节码级精简 ​

HikariCP 在编译期利用 Javassist 框架生成动态代理类(如 HikariProxyConnection、HikariProxyStatement),而非在运行期使用反射开销较大的 JDK 动态代理。同时,作者针对编译后的字节码进行了深度瘦身,精简方法调用层级与字节码指令数量,使热点方法字节码严格控制在 JVM 内联阈值(默认 35 字节)以内,从而触发 JIT 编译器的方法内联优化。

核心配置参数 ​

HikariCP 奉行极简配置哲学,参数命名直观且默认值经过高度调优:

参数名称默认值参数说明
jdbcUrlnull数据库连接 URL 地址。
usernamenull数据库登录用户名。
passwordnull数据库登录密码。
driverClassName自动识别数据库驱动全限定类名(通常无需显式配置,HikariCP 会根据 jdbcUrl 自动推导)。
minimumIdle同 maximumPoolSize池中维护的最小空闲连接数(官方建议保持与 maximumPoolSize 一致,作为固定大小连接池运行以规避动态扩容抖动)。
maximumPoolSize10连接池允许同时存在的最大连接总数(含空闲与活跃连接)。
connectionTimeout30000 (30 秒)客户端等待从池中借出连接的最大毫秒数,超时抛出 SQLException(最小允许值为 250ms)。
idleTimeout600000 (10 分钟)空闲连接在池中允许存活的最大毫秒数(仅在 minimumIdle < maximumPoolSize 时生效)。
maxLifetime1800000 (30 分钟)物理连接在池中的最大生命周期毫秒数。强烈建议设置为比数据库服务端的 wait_timeout 小数分钟,防止拿到被服务端强行断开的死连接。
autoCommittrue从池中借出连接时的默认自动提交行为。

连接探活机制说明:只要底层驱动支持 JDBC4 规范(现代主流驱动均支持),HikariCP 在借出连接时会自动调用高效的 Connection.isValid() 协议包进行探活,**严禁手动配置 connectionTestQuery**(如 SELECT 1),否则反而会降低探活性能。

编程式配置与优化 ​

使用编程方式初始化 HikariCP 时,推荐先实例化 HikariConfig 配置对象,设置连接属性与 MySQL 驱动层的预编译缓存优化参数(通过 addDataSourceProperty 透传给底层 MySQL 驱动),最后将其传入 HikariDataSource 构造器:

java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;

// 1. 演示使用 HikariConfig 编程式构建 HikariDataSource
public class HikariProgrammaticDemo {

  // 2. 配置连接池参数与 MySQL 预编译性能优化项
  public static void main(String[] args) throws Exception {
    HikariConfig config = new HikariConfig();

    // 3. 设置数据库连接基础信息
    config.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    config.setUsername("root");
    config.setPassword("root");

    // 4. 设置连接池容量与超时控制参数
    config.setMinimumIdle(10);
    config.setMaximumPoolSize(10);
    config.setConnectionTimeout(30000);
    config.setMaxLifetime(1800000);

    // 5. 透传官方推荐的 MySQL 驱动级 PreparedStatement 缓存优化参数
    config.addDataSourceProperty("cachePrepStmts", "true");
    config.addDataSourceProperty("prepStmtCacheSize", "250");
    config.addDataSourceProperty("prepStmtCacheSqlLimit", "2048");
    config.addDataSourceProperty("useServerPrepStmts", "true");

    // 6. 基于配置对象初始化数据源,并利用 try-with-resources 自动归还连接与关闭数据源
    try (HikariDataSource dataSource = new HikariDataSource(config);
       Connection conn = dataSource.getConnection();
       PreparedStatement pstmt = conn.prepareStatement("SELECT 1");
       ResultSet rs = pstmt.executeQuery()) {

      if (rs.next()) {
        System.out.println("成功获取 HikariCP 连接并执行查询,结果 = " + rs.getInt(1));
      }
    }
  }
}

外部配置文件加载 ​

在实际项目中,通常将 HikariCP 配置解耦至类路径下的 hikari.properties 文件中。HikariConfig 提供了专门的有参构造器,支持直接传入配置文件路径或 Properties 对象完成自动解析与装配。

首先在 src/main/resources/hikari.properties 中编写如下配置(支持通过 dataSource. 前缀直接配置底层驱动属性):

ini
# 1. 数据库连接基础信息
jdbcUrl=jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC
username=root
password=root

# 2. 连接池容量与生命周期参数
minimumIdle=10
maximumPoolSize=10
connectionTimeout=30000
idleTimeout=600000
maxLifetime=1800000

# 3. 透传给底层 MySQL 驱动的预编译缓存优化参数
dataSource.cachePrepStmts=true
dataSource.prepStmtCacheSize=250
dataSource.prepStmtCacheSqlLimit=2048
dataSource.useServerPrepStmts=true

随后在 Java 代码中通过加载类路径下的 hikari.properties 构建 HikariDataSource:

java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import java.io.InputStream;
import java.sql.Connection;
import java.util.Properties;

// 1. 演示基于外部 hikari.properties 配置文件初始化连接池
public class HikariPropertiesDemo {

  // 2. 读取类路径配置文件并装配数据源
  public static void main(String[] args) throws Exception {
    Properties props = new Properties();

    // 3. 通过类加载器读取 resources 目录下的 hikari.properties
    try (InputStream in = HikariPropertiesDemo.class.getClassLoader().getResourceAsStream("hikari.properties")) {
      props.load(in);
    }

    // 4. 将 Properties 传入 HikariConfig,构建数据源并借出连接
    HikariConfig config = new HikariConfig(props);
    try (HikariDataSource dataSource = new HikariDataSource(config);
       Connection conn = dataSource.getConnection()) {
      System.out.println("成功通过配置文件获取 HikariCP 连接: " + conn);
    }
  }
}

API: HikariConfig ​

构造方法 ​

  • HikariConfig():配置对象构造。创建 HikariCP 连接池的核心参数配置实例,支持空实例编程式构建、传入 Properties 属性集对象或指定外部 .properties 配置文件路径自动解析。
    • HikariConfig:(),默认空参构造。创建一个默认初始化的空配置实例,供后续通过编程式调用 Setter 方法逐项注入连接与容量参数。
    • HikariConfig:(Properties properties),属性集对象构造。根据传入的 java.util.Properties 键值对集合自动反射映射并注入对应的连接池属性及 dataSource. 前缀的驱动底层属性。
    • HikariConfig:(String propertyFileName),配置文件路径构造。根据传入的文件系统路径或类路径(Classpath)下的 .properties 文件名,自动读取并解析全部配置参数。

注意事项:

  1. 调用 (String propertyFileName) 构造器时,HikariCP 会优先尝试将其作为本地磁盘文件系统路径(File)加载;若文件不存在,则退化为通过当前类加载器(ClassLoader)从类路径根目录读取。
  2. 在将 HikariConfig 实例传递给 new HikariDataSource(config) 完成数据源初始化后,再修改原 HikariConfig 对象的属性不会对已运行的连接池产生直接影响。
java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;
import java.util.Properties;

// 1. 演示 HikariConfig 重载构造方法的使用
public class HikariConfigConstructorDemo {

  // 2. 分别使用无参构造与 Properties 属性集构造配置实例
  public static void main(String[] args) {
    HikariConfig emptyConfig = new HikariConfig();
    System.out.println("无参构造默认最大连接数: " + emptyConfig.getMaximumPoolSize());

    // 3. 封装 Properties 键值对并传入有参构造器自动映射属性
    Properties props = new Properties();
    props.setProperty("jdbcUrl", "jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    props.setProperty("username", "root");
    props.setProperty("password", "root");
    props.setProperty("maximumPoolSize", "20");

    // 4. 基于 Properties 构建配置对象并验证解析结果
    HikariConfig propConfig = new HikariConfig(props);
    System.out.println("解析后的 JDBC URL: " + propConfig.getJdbcUrl());
    System.out.println("解析后的最大连接数: " + propConfig.getMaximumPoolSize());
  }
}

连接参数配置 ​

  • void setJdbcUrl():(String jdbcUrl),连接地址设置。设置底层物理数据库的 JDBC 连接 URL 地址。

  • String getJdbcUrl():(),连接地址获取。返回当前已配置的 JDBC 连接 URL 字符串。

  • void setUsername():(String username),登录账号设置。设置用于数据库身份认证的默认登录用户名。

  • String getUsername():(),登录账号获取。返回当前已配置的数据库登录用户名。

  • void setPassword():(String password),登录密码设置。设置用于数据库身份认证的默认登录密码。

  • String getPassword():(),登录密码获取。返回当前已配置的数据库登录密码。

  • void setDriverClassName():(String driverClassName),驱动类名设置。显式指定底层 JDBC 驱动的全限定类名(如 com.mysql.cj.jdbc.Driver),若类名无法加载则立即抛出 RuntimeException。

  • String getDriverClassName():(),驱动类名获取。返回当前显式配置的 JDBC 驱动全限定类名。

  • void addDataSourceProperty():(String propertyName, Object value),底层驱动属性追加。向底层具体数据库驱动(如 MySQL Connector/J)透传专有优化参数(如 cachePrepStmts、prepStmtCacheSize)。

  • Properties getDataSourceProperties():(),底层驱动属性集获取。返回已通过 addDataSourceProperty() 注入的所有底层驱动专有属性集合。

注意事项:

  1. 现代 JDBC 4.0 驱动均支持 SPI 自动注册,HikariCP 能够直接根据 jdbcUrl 自动推导驱动类型,通常无需显式调用 setDriverClassName()。
java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;

// 1. 演示 HikariConfig 数据库连接参数与底层驱动优化属性的配置
public class HikariConnectionPropDemo {

  // 2. 设置基础连接三要素并透传 MySQL 预编译缓存参数
  public static void main(String[] args) {
    HikariConfig config = new HikariConfig();

    // 3. 设置 JDBC URL 与认证凭据(驱动类由 URL 自动识别)
    config.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    config.setUsername("root");
    config.setPassword("root");

    // 4. 向底层 MySQL 驱动追加服务端预编译与缓存优化属性
    config.addDataSourceProperty("cachePrepStmts", "true");
    config.addDataSourceProperty("prepStmtCacheSize", "250");
    config.addDataSourceProperty("prepStmtCacheSqlLimit", "2048");

    // 5. 打印确认已生效的 URL 与驱动级属性集合
    System.out.println("连接地址: " + config.getJdbcUrl());
    System.out.println("透传驱动属性: " + config.getDataSourceProperties());
  }
}

容量与超时配置 ​

  • void setMinimumIdle():(int minIdle),最小空闲连接数设置。设置连接池努力维持的最少空闲连接数;官方建议将其保持默认(与 maximumPoolSize 相等)以构建固定容量连接池。

  • int getMinimumIdle():(),最小空闲连接数获取。返回当前配置的最小空闲连接数。

  • void setMaximumPoolSize():(int maxPoolSize),最大连接总数设置。设置连接池允许同时存在的最大物理连接总数(包含空闲与使用中连接),默认值为 10。

  • int getMaximumPoolSize():(),最大连接总数获取。返回当前配置的最大连接总数上限。

  • void setConnectionTimeout():(long connectionTimeoutMs),借出等待超时设置。设置调用方线程等待从池中借出连接的最大毫秒数,默认值为 30000(30 秒),允许设置的最小非零值为 250 毫秒。

  • long getConnectionTimeout():(),借出等待超时获取。返回客户端等待借出连接的最大超时毫秒数。

  • void setIdleTimeout():(long idleTimeoutMs),空闲存活超时设置。设置连接在池中允许保持空闲状态的最大毫秒数,默认值为 600000(10 分钟),仅在 minimumIdle < maximumPoolSize 时生效。

  • long getIdleTimeout():(),空闲存活超时获取。返回空闲连接在池中允许存活的最大毫秒数。

  • void setMaxLifetime():(long maxLifetimeMs),最大生命周期设置。设置池中单个物理连接的最大存活毫秒数,默认值为 1800000(30 分钟),到期且未在使用中的连接将被平滑淘汰重建。

  • long getMaxLifetime():(),最大生命周期获取。返回物理连接的最大生命周期毫秒数。

  • void setValidationTimeout():(long validationTimeoutMs),有效性检测超时设置。设置借出连接前执行存活检测(Connection.isValid())的最大超时毫秒数,默认值为 5000(5 秒),必须小于 connectionTimeout。

注意事项:

  1. maxLifetime 必须设置为比数据库服务端的空闲断开时间(如 MySQL 的 wait_timeout)小数分钟,防止数据库服务端单方面断开连接导致应用借出失效连接。
java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;

// 1. 演示 HikariConfig 连接池容量边界与超时生命周期配置
public class HikariSizingTimeoutDemo {

  // 2. 配置固定容量池与各项超时毫秒阈值
  public static void main(String[] args) {
    HikariConfig config = new HikariConfig();

    // 3. 将最小空闲数与最大连接数均设为 15,构建固定大小连接池
    config.setMinimumIdle(15);
    config.setMaximumPoolSize(15);

    // 4. 设置借出超时(10秒)、空闲超时(5分钟)与最大生命周期(25分钟)
    config.setConnectionTimeout(10000);
    config.setIdleTimeout(300000);
    config.setMaxLifetime(1500000);

    // 5. 读取并验证已配置的超时与生命周期阈值
    System.out.println("最大连接容量: " + config.getMaximumPoolSize());
    System.out.println("借出超时(ms): " + config.getConnectionTimeout());
    System.out.println("最大寿命(ms): " + config.getMaxLifetime());
  }
}

会话状态与诊断配置 ​

  • void setPoolName():(String poolName),连接池名称设置。设置连接池的可读标识名称,该名称会直接体现在日志输出与 JMX 监控面板中(默认自动生成如 HikariPool-1)。

  • String getPoolName():(),连接池名称获取。返回当前连接池配置的标识名称。

  • void setAutoCommit():(boolean isAutoCommit),默认自动提交设置。设置连接从池中借出或归还重置时的默认事务自动提交状态,默认值为 true。

  • boolean isAutoCommit():(),默认自动提交判断。返回连接池是否开启了默认的事务自动提交。

  • void setReadOnly():(boolean readOnly),只读模式设置。设置从池中借出的连接是否默认标记为只读模式(Connection.setReadOnly(boolean)),默认值为 false,常用于读写分离从库数据源。

  • boolean isReadOnly():(),只读模式判断。返回当前连接池是否默认将借出连接设为只读模式。

  • void setTransactionIsolation():(String isolationLevel),默认事务隔离级别设置。设置池中连接的默认事务隔离级别名称(如 "TRANSACTION_READ_COMMITTED"、"TRANSACTION_REPEATABLE_READ")。

  • void setLeakDetectionThreshold():(long leakDetectionThresholdMs),连接泄漏检测阈值设置。设置连接被借出后未归还的最大容忍毫秒数,默认值为 0(不开启,开启时最小值为 2000 毫秒),超出未归还时将打印借出位置的调用栈警告日志以定位连接泄漏。

  • void validate():(),配置合法性校验。显式触发对当前 HikariConfig 所有属性数值范围、冲突关系及必填项的完整性校验,并提供默认值回填。

  • void copyStateTo():(HikariConfig other),配置状态深拷贝。将当前 HikariConfig 实例中的所有配置字段与属性完整复制到另一个目标 HikariConfig 实例中。

java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;

// 1. 演示 HikariConfig 会话状态控制、连接泄漏诊断与合法性校验
public class HikariDiagnosticConfigDemo {

  // 2. 配置从库只读池参数、开启连接泄漏检测并执行配置校验与克隆
  public static void main(String[] args) {
    HikariConfig config = new HikariConfig();
    config.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    config.setUsername("root");
    config.setPassword("root");

    // 3. 设置池名称、事务隔离级别与会话只读状态
    config.setPoolName("OrderReadSlavePool");
    config.setAutoCommit(true);
    config.setReadOnly(true);
    config.setTransactionIsolation("TRANSACTION_READ_COMMITTED");

    // 4. 开启 5 秒连接泄漏追踪警告,并触发配置完整性校验
    config.setLeakDetectionThreshold(5000);
    config.validate();

    // 5. 将校验通过的配置状态完整复制到备份配置实例中
    HikariConfig backupConfig = new HikariConfig();
    config.copyStateTo(backupConfig);
    System.out.println("克隆后的连接池名称: " + backupConfig.getPoolName());
    System.out.println("克隆后的只读模式状态: " + backupConfig.isReadOnly());
  }
}

API: HikariDataSource ​

构造方法 ​

  • HikariDataSource():数据源实例构造。创建 HikariCP 高性能连接池数据源实例,支持根据初始化时机选择延迟启动(Fast-path 以外的懒加载)或基于配置对象立即预热启动连接池。
    • HikariDataSource:(),无参延迟启动构造。创建一个尚未初始化底层连接池的空数据源实例,允许后续直接在该实例上调用继承自 HikariConfig 的 Setter 方法注入配置,并在首次调用 getConnection() 时触发底层 HikariPool 的双重检查锁懒加载创建,同时锁定配置禁止再次修改。
    • HikariDataSource:(HikariConfig configuration),有参立即启动构造。根据传入的 HikariConfig 配置对象立即执行参数校验(validate()),将配置状态深拷贝至当前数据源内部,并当场启动底层 HikariPool 连接池完成物理连接预热(官方推荐的高性能构造方式)。

注意事项:

  1. 使用有参构造 new HikariDataSource(config) 时,底层会直接将 pool 引用赋值给 final 修饰的快路径字段 fastPathPool,后续每次调用 getConnection() 均可跳过双重检查锁判断;而无参构造只能走 volatile 修饰的慢路径字段 pool,因此在生产环境中推荐优先使用有参构造。
  2. 一旦数据源启动了底层连接池(即有参构造执行完毕,或无参构造首次调用了 getConnection()),当前数据源的配置状态即被密封(Sealed),此时再调用 setJdbcUrl() 等配置修改方法将直接抛出 IllegalStateException。
java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

// 1. 演示 HikariDataSource 两种重载构造方法的初始化时机差异
public class HikariDataSourceConstructorDemo {

  // 2. 对比有参立即启动构造与无参延迟启动构造的运行状态
  public static void main(String[] args) {
    HikariConfig config = new HikariConfig();
    config.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    config.setUsername("root");
    config.setPassword("root");

    // 3. 有参构造:构造完成时底层 HikariPool 已立即创建并处于运行状态
    HikariDataSource eagerDs = new HikariDataSource(config);
    System.out.println("有参构造后连接池是否运行: " + eagerDs.isRunning());

    // 4. 无参构造:构造完成时底层连接池尚未创建,需等到首次 getConnection() 才启动
    HikariDataSource lazyDs = new HikariDataSource();
    lazyDs.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    lazyDs.setUsername("root");
    lazyDs.setPassword("root");
    System.out.println("无参构造未借出连接前是否运行: " + lazyDs.isRunning());

    // 5. 关闭数据源,释放底层连接池资源
    eagerDs.close();
    lazyDs.close();
  }
}

连接借出与驱逐 ​

  • getConnection():池化连接借出。实现自 javax.sql.DataSource 标准接口,从底层 HikariPool 的 ConcurrentBag 无锁集合中借出一个经 Javassist 字节码增强的代理连接 HikariProxyConnection。

  • Connection:() throws SQLException,默认凭据借出连接。使用数据源预设的认证信息从连接池借出一个可用连接;若数据源已关闭则抛出 SQLException。

  • Connection:(String username, String password) throws SQLException,指定凭据借出(不支持)。HikariCP 不支持在运行期按不同账号密码动态切分连接池,调用该重载方法将直接抛出 SQLFeatureNotSupportedException。

  • void evictConnection():(Connection connection),指定连接驱逐。将传入的 HikariProxyConnection 代理连接及其底层物理连接立即从连接池中软驱逐并标记关闭,用于主动剔除业务层感知到的异常或污染连接。

注意事项:

  1. 切勿在 HikariCP 上调用双参重载 getConnection(String username, String password),该方法在源码中固定抛出 new SQLFeatureNotSupportedException()。
java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import java.sql.Connection;

// 1. 演示从 HikariDataSource 借出连接与主动驱逐指定物理连接
public class HikariConnectionEvictDemo {

  // 2. 初始化数据源,借出连接并演示 evictConnection 主动淘汰机制
  public static void main(String[] args) throws Exception {
    HikariConfig config = new HikariConfig();
    config.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    config.setUsername("root");
    config.setPassword("root");

    // 3. 结合 try-with-resources 自动管理数据源与连接的生命周期
    try (HikariDataSource dataSource = new HikariDataSource(config);
       Connection conn = dataSource.getConnection()) {

      System.out.println("成功借出代理连接: " + conn.getClass().getName());

      // 4. 主动将该连接从池中驱逐,底层物理连接将被销毁而不再放回空闲队列复用
      dataSource.evictConnection(conn);
      System.out.println("已主动驱逐当前连接");
    }
    // 5. 代码块结束时自动触发代理连接与数据源的 close()
  }
}

生命周期与监控 ​

  • HikariPoolMXBean getHikariPoolMXBean():(),连接池运行监控句柄获取。返回用于实时查询连接池内部运行态指标(如空闲连接数 getIdleConnections()、活跃连接数 getActiveConnections()、等待线程数 getThreadsAwaitingConnection())及执行软驱逐的 MXBean 实例。

  • HikariConfigMXBean getHikariConfigMXBean():(),连接池动态配置句柄获取。返回支持在运行期通过 JMX 或代码动态调整部分容量与超时参数(如动态修改 maximumPoolSize、connectionTimeout)的 MXBean 实例。

  • boolean isRunning():(),运行状态判断。判断底层 HikariPool 连接池当前是否已完成初始化且处于正常服务运行状态(POOL_NORMAL)。

  • boolean isClosed():(),关闭状态判断。判断当前 HikariDataSource 数据源是否已被调用 close() 关闭销毁。

  • void close():(),数据源销毁关闭。实现自 java.io.Closeable 接口,幂等地关闭当前数据源,停止后台保活与扩容线程池,并断开池中所有底层 TCP 物理连接。

java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import com.zaxxer.hikari.HikariPoolMXBean;
import java.sql.Connection;

// 1. 演示通过 HikariPoolMXBean 监控运行指标及管理数据源生命周期
public class HikariLifecycleMonitorDemo {

  // 2. 启动数据源,采集借出连接期间的实时监控指标并执行关闭检查
  public static void main(String[] args) throws Exception {
    HikariConfig config = new HikariConfig();
    config.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    config.setUsername("root");
    config.setPassword("root");
    config.setMaximumPoolSize(5);

    // 3. 创建数据源并获取运行态监控句柄 HikariPoolMXBean
    HikariDataSource dataSource = new HikariDataSource(config);
    HikariPoolMXBean poolMXBean = dataSource.getHikariPoolMXBean();

    // 4. 借出一个连接,实时打印池内总连接数、活跃数与空闲数
    try (Connection conn = dataSource.getConnection()) {
      System.out.println("数据源运行状态: " + dataSource.isRunning());
      System.out.println("当前总连接数: " + poolMXBean.getTotalConnections());
      System.out.println("当前活跃连接数: " + poolMXBean.getActiveConnections());
      System.out.println("当前空闲连接数: " + poolMXBean.getIdleConnections());
    }

    // 5. 连接归还后再次查看空闲连接数
    System.out.println("归还后空闲连接数: " + poolMXBean.getIdleConnections());

    // 6. 关闭数据源并验证关闭状态标志
    dataSource.close();
    System.out.println("数据源是否已关闭: " + dataSource.isClosed());
  }
}

包装器与驱动管理 ​

  • <T> T unwrap():(Class<T> iface) throws SQLException,数据源安全拆包。实现自 java.sql.Wrapper 接口,将当前代理或抽象的 DataSource 拆包还原为指定目标接口或实现类(如拆包为 HikariDataSource.class 或底层包装的真实 DataSource)。

  • boolean isWrapperFor():(Class<?> iface) throws SQLException,包装兼容性判断。判断当前数据源是否为指定类型 iface 的实例或其包装器,供调用 unwrap() 前做安全类型探测。

  • void setLoginTimeout():(int seconds) throws SQLException,驱动登录超时设置。实现自 javax.sql.CommonDataSource 接口,设置底层驱动建立连接的登录超时秒数。

  • int getLoginTimeout():() throws SQLException,驱动登录超时获取。返回底层驱动配置的登录超时秒数。

  • Logger getParentLogger():() throws SQLFeatureNotSupportedException,父级 JUL 日志器获取(不支持)。由于 HikariCP 统一使用 SLF4J 日志门面而非 java.util.logging,调用该方法将固定抛出 SQLFeatureNotSupportedException。

java
package com.example.pool;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

// 1. 演示面向标准 DataSource 接口使用 Wrapper 安全拆包为 HikariDataSource
public class HikariWrapperDemo {

  // 2. 将上层 DataSource 引用安全还原为底层 HikariDataSource 实现类
  public static void main(String[] args) throws Exception {
    HikariConfig config = new HikariConfig();
    config.setPoolName("PaymentCorePool");
    config.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    config.setUsername("root");
    config.setPassword("root");

    // 3. 向上转型为标准 javax.sql.DataSource 接口引用
    DataSource standardDs = new HikariDataSource(config);

    // 4. 先探测类型兼容性,再调用 unwrap 拆包调用 HikariDataSource 专有方法
    if (standardDs.isWrapperFor(HikariDataSource.class)) {
      HikariDataSource hikariDs = standardDs.unwrap(HikariDataSource.class);
      System.out.println("拆包成功,连接池名称: " + hikariDs.getPoolName());

      // 5. 调用拆包后实现类的 close 方法销毁连接池
      hikariDs.close();
    }
  }
}

继承: HikariConfig ​

addDataSourceProperty, addHealthCheckProperty, copyStateTo, getCatalog, getConnectionInitSql, getConnectionTestQuery, getConnectionTimeout, getCredentials, getDataSource, getDataSourceClassName, getDataSourceJNDI, getDataSourceProperties, getDriverClassName, getExceptionOverride, getExceptionOverrideClassName, getHealthCheckProperties, getHealthCheckRegistry, getIdleTimeout, getInitializationFailTimeout, getIsolateInternalQueries, getJdbcUrl, getKeepaliveTime, getLeakDetectionThreshold, getMaximumPoolSize, getMaxLifetime, getMetricRegistry, getMetricsTrackerFactory, getMinimumIdle, getPassword, getPoolName, getScheduledExecutor, getSchema, getThreadFactory, getTransactionIsolation, getUsername, getValidationTimeout, isAllowPoolSuspension, isAutoCommit, isReadOnly, isRegisterMbeans, setAllowPoolSuspension, setAutoCommit, setCatalog, setConnectionInitSql, setConnectionTestQuery, setConnectionTimeout, setCredentials, setDataSource, setDataSourceClassName, setDataSourceJNDI, setDataSourceProperties, setDriverClassName, setExceptionOverride, setExceptionOverrideClassName, setHealthCheckProperties, setHealthCheckRegistry, setIdleTimeout, setInitializationFailTimeout, setIsolateInternalQueries, setJdbcUrl, setKeepaliveTime, setLeakDetectionThreshold, setMaximumPoolSize, setMaxLifetime, setMetricRegistry, setMetricsTrackerFactory, setMinimumIdle, setPassword, setPoolName, setReadOnly, setRegisterMbeans, setScheduledExecutor, setSchema, setThreadFactory, setTransactionIsolation, setUsername, setValidationTimeout, validate

Druid 连接池 ​

组件架构 ​

Druid 是阿里巴巴开源的企业级数据库连接池组件,号称“为监控而生”。它不仅在高并发场景下具备优异的连接池吞吐性能,还内置了责任链模式的 Filter 拦截器体系,原生支持 SQL 执行耗时监控(StatFilter)、SQL 防注入防火墙(WallFilter)、慢 SQL 日志记录以及数据库密码非对称加密等企业级特性。

在 Druid 的核心架构中,主要由以下两个类对外提供服务:

  1. com.alibaba.druid.pool.DruidDataSource:Druid 的核心数据源实现类,实现了 javax.sql.DataSource 标准接口,内部采用双数组结构(connections 空闲连接数组与 activeConnections 活跃连接追踪)配合可重入锁 ReentrantLock 管理连接的借出、归还与后台异步保活销毁。

  2. com.alibaba.druid.pool.DruidDataSourceFactory:符合 JNDI 与工厂设计模式的静态工厂类,支持直接传入 java.util.Properties 或 Map 配置集合,一键完成 DruidDataSource 的属性解析与实例化。

image-20261104112453603

依赖引入 ​

手动引入依赖 ​

在未使用构建工具的普通 Java 项目中,需手动下载并挂载 Druid 与数据库驱动 Jar 包:

  1. 拷贝依赖包:在项目根目录下新建 lib(或 libs)目录,将下载的 druid-1.2.20.jar 与 MySQL 驱动包复制到该目录下。

  2. 添加至类路径:在 IDE(如 IntelliJ IDEA)中右键点击该 lib 目录或对应 Jar 包,选择 Add as Library... 将其加入到当前模块的编译与运行类路径中。

Maven 坐标引入 ​

在 Maven 项目中使用 Druid 时,需在 pom.xml 中引入 druid 核心依赖以及对应的数据库驱动:

xml
<dependencies>
    <!-- 1. 引入阿里巴巴 Druid 连接池核心依赖 -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid</artifactId>
        <version>1.2.20</version>
    </dependency>

    <!-- 2. 引入 MySQL 数据库驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.0.33</version>
    </dependency>
</dependencies>

核心配置参数 ​

Druid 的配置参数吸收了 DBCP 的命名风格,涵盖连接四要素、容量边界、后台保活检测与扩展插件配置:

参数名称默认值参数说明
driverClassName自动识别数据库驱动全限定类名(可根据 url 自动识别)。
urlnull数据库连接 URL 地址。
usernamenull数据库登录用户名。
passwordnull数据库登录密码。
initialSize0连接池启动时预先创建的初始物理连接数。
minIdle0连接池常驻保留的最小空闲连接数。
maxActive8连接池允许同时存在的最大活跃连接数上限。
maxWait-1池中无可用连接时,调用方线程阻塞等待的最大毫秒数(-1 表示无限期等待,生产环境务必配置具体超时时间)。
timeBetweenEvictionRunsMillis60000 (60 秒)后台 DestroyThread 线程定期扫描并检测空闲连接的间隔毫秒数。
minEvictableIdleTimeMillis1800000 (30 分钟)连接在池中保持空闲而不被空闲回收器销毁的最小毫秒数。
validationQuerySELECT 1用于检测物理连接是否有效的 SQL 查询语句。
testWhileIdletrue建议开启。申请连接时,若空闲时间超过 timeBetweenEvictionRunsMillis,则执行 validationQuery 探活,保证性能的同时避免拿到死连接。
testOnBorrowfalse建议关闭。每次借出连接时均强制执行探活查询,开启后会严重损耗高并发吞吐性能。
filtersnull配置扩展拦截器别名列表,如 stat(监控统计)、wall(防注入防火墙)、slf4j(日志输出),多个值用逗号分隔。

方式: 编程式显式配置 ​

在不借助外部配置文件时,可直接实例化 DruidDataSource 对象,并通过 Setter 方法设置连接属性、容量上限及扩展过滤器:

java
package com.example.pool;

import com.alibaba.druid.pool.DruidDataSource;
import java.sql.Connection;

// 1. 演示通过 DruidDataSource 编程式配置连接池
public class DruidProgrammaticDemo {

  // 2. 手动实例化数据源并注入容量与监控过滤参数
  public static void main(String[] args) throws Exception {
    try (DruidDataSource dataSource = new DruidDataSource()) {

      // 3. 配置数据库连接基础信息
      dataSource.setDriverClassName("com.mysql.cj.jdbc.Driver");
      dataSource.setUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
      dataSource.setUsername("root");
      dataSource.setPassword("root");

      // 4. 配置连接池容量与超时等待上限
      dataSource.setInitialSize(5);
      dataSource.setMinIdle(5);
      dataSource.setMaxActive(20);
      dataSource.setMaxWait(3000);

      // 5. 开启 SQL 监控统计(stat)与防注入防火墙(wall)扩展插件
      dataSource.setFilters("stat,wall");

      // 6. 借出连接并在 try-with-resources 结束时自动拦截 close() 归还连接
      try (Connection conn = dataSource.getConnection()) {
        System.out.println("成功获取 Druid 连接: " + conn);
      }
    }
  }
}

方式: DruidDataSourceFactory ​

在企业级项目开发中,通常将 Druid 的配置项统一存放在 resources/druid.properties 文件中,并调用 DruidDataSourceFactory.createDataSource(Properties) 静态工厂方法自动完成数据源装配。

在实际生产项目中,为了避免频繁创建与销毁物理连接,会使用基于 Druid 连接池的 JDBCUtilsByDruid 替代直连版 JDBCUtils。两者的对外方法签名保持完全一致,使得业务代码可以零成本无缝切换。

druid.properties ​

在类路径下创建 druid.properties 配置文件,注意键名必须严格遵循 Druid 工厂规定的标准属性名称(如 driverClassName、username):

properties
# 1. 数据库基础连接四要素(键名需遵循 Druid 标准属性名)
driverClassName=com.mysql.cj.jdbc.Driver
url=jdbc:mysql://localhost:3306/test_db?rewriteBatchedStatements=true&serverTimezone=UTC
username=root
password=123456

# 2. 连接池初始化容量、最小空闲数、最大活跃数与最长等待毫秒数
initialSize=10
minIdle=5
maxActive=50
maxWait=5000

JDBCUtilsByDruid~ ​

JDBCUtilsByDruid 内部维护全局唯一的 javax.sql.DataSource 静态实例。需要特别区分的是,在 JDBCUtilsByDruid.close 方法中调用的 connection.close(),其运行期实际类型是 DruidPooledConnection 代理引用,该方法不会断开底层 TCP 物理连接,而是将连接引用归还回 Druid 空闲连接池中:

java
package com.hspedu.jdbc.utils;

import com.alibaba.druid.pool.DruidDataSourceFactory;
import java.io.InputStream;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Properties;
import javax.sql.DataSource;

// 1. 封装基于 Druid 数据库连接池的连接获取与归还工具类
public class JDBCUtilsByDruid {

  // 2. 维护全局唯一的 DataSource 数据源静态引用
  private static DataSource ds;

  // 3. 类加载时读取 druid.properties 并初始化 Druid 连接池实例
  static {
    Properties properties = new Properties();
    try (InputStream is = JDBCUtilsByDruid.class.getClassLoader().getResourceAsStream("druid.properties")) {
      properties.load(is);
      ds = DruidDataSourceFactory.createDataSource(properties);
    } catch (Exception e) {
      throw new RuntimeException(e);
    }
  }

  // 4. 从 Druid 连接池借出经代理包装的可用 Connection
  public static Connection getConnection() throws SQLException {
    return ds.getConnection();
  }

  // 5. 释放 ResultSet 与 Statement,并将代理 Connection 归还回 Druid 连接池
  public static void close(ResultSet resultSet, Statement statement, Connection connection) {
    try {
      if (resultSet != null) {
        resultSet.close();
      }
      if (statement != null) {
        statement.close();
      }
      if (connection != null) {
        connection.close();
      }
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
  }
}

API: DruidDataSource ​

构造方法 ​

  • DruidDataSource():数据源实例构造。创建阿里巴巴 Druid 企业级连接池数据源实例,支持标准无参初始化或开启读写锁并发模式。
    • DruidDataSource:(),默认独占锁构造。创建数据源实例,底层默认使用非公平的可重入独占锁 ReentrantLock(false) 控制池内连接的并发借出与归还,适合绝大多数高并发业务场景。
    • DruidDataSource:(boolean fairLock),锁公平性控制构造。创建数据源实例,并根据传入的 fairLock 布尔值指定内部 ReentrantLock 是否采用公平锁策略(当设为 true 时按照线程等待先后顺序分配连接,但会略微降低吞吐量)。

注意事项:

  1. 构造 DruidDataSource 实例后,底层物理连接池并不会立即创建,而是等到显式调用 init() 方法或首次调用 getConnection() 时才触发双重检查锁初始化。
  2. 一旦 DruidDataSource 完成初始化(inited == true),大部分核心连接与容量配置属性的 Setter 方法将禁止修改(调用会抛出 UnsupportedOperationException)。
java
package com.example.pool;

import com.alibaba.druid.pool.DruidDataSource;

// 1. 演示 DruidDataSource 重载构造方法的使用
public class DruidDataSourceConstructorDemo {

  // 2. 分别使用默认非公平锁构造与公平锁构造初始化数据源
  public static void main(String[] args) {
    DruidDataSource defaultDs = new DruidDataSource();
    System.out.println("默认构造是否启用公平锁: " + defaultDs.isFairLock());

    // 3. 传入 true 启用公平锁排队借出机制
    DruidDataSource fairDs = new DruidDataSource(true);
    System.out.println("有参构造是否启用公平锁: " + fairDs.isFairLock());

    // 4. 关闭并释放数据源资源
    defaultDs.close();
    fairDs.close();
  }
}

连接与插件配置 ​

  • void configFromPropety():(Properties properties),属性集批量注入。从传入的 Properties 对象中自动识别并加载以 druid. 开头的配置项(如 druid.url、druid.username、druid.maxActive),支持通过外部配置文件或系统环境变量覆盖数据源配置。

  • void setFilters():(String filters) throws SQLException,扩展拦截器链配置。根据逗号分隔的别名字符串(如 "stat,wall,slf4j")加载并挂载对应的 Filter 拦截器实例,用于开启 SQL 监控统计、防注入防火墙及日志记录功能。

  • void setConnectionProperties():(String connectionProperties),底层驱动属性串设置。以分号分隔的键值对字符串形式(如 "config.decrypt=true;config.decrypt.key=..." 或 "rewriteBatchedStatements=true")向底层驱动与 Filter 传递扩展参数。

  • void setResetStatEnable():(boolean resetStatEnable),监控指标重置开关。设置是否允许在运行期通过管理后台或 API 重置清零 SQL 监控统计指标,默认值为 true。

注意事项:

  1. 方法名 configFromPropety 在 Druid 官方源码中确实拼写为 Propety(少了一个字母 r),调用时需注意保持与源码签名一致。
  2. setFilters() 声明了受检异常 SQLException(当无法在 META-INF/druid-filter.properties 中找到对应别名或实例化失败时抛出),而其他常规属性 Setter 方法则不抛出受检异常。
java
package com.example.pool;

import com.alibaba.druid.pool.DruidDataSource;
import java.sql.SQLException;

// 1. 演示 DruidDataSource 扩展拦截器链与底层驱动属性的配置
public class DruidPluginConfigDemo {

  // 2. 挂载 stat 监控与 wall 防火墙插件,并注入驱动扩展参数
  public static void main(String[] args) throws SQLException {
    try (DruidDataSource dataSource = new DruidDataSource()) {

      // 3. 通过别名挂载 SQL 统计监控与防注入防火墙 Filter
      dataSource.setFilters("stat,wall");

      // 4. 以分号分隔字符串形式向底层 MySQL 驱动注入批处理重写与慢 SQL 记录参数
      dataSource.setConnectionProperties("rewriteBatchedStatements=true;druid.stat.slowSqlMillis=2000");

      // 5. 查看已成功挂载的 Filter 类名列表与解析后的连接属性集
      System.out.println("已挂载拦截器列表: " + dataSource.getFilterClassNames());
      System.out.println("已生效驱动属性集: " + dataSource.getConnectProperties());
    }
  }
}

容量与保活配置 ​

  • void setInitialSize():(int initialSize),初始连接数设置。设置连接池启动初始化时预先创建的物理连接数量,默认值为 0。

  • void setMinIdle():(int value),最小空闲连接数设置。设置连接池常驻维持的最少空闲连接数量,默认值为 0。

  • void setMaxActive():(int maxActive),最大活跃连接数设置。设置连接池允许同时存在的最大连接总数上限,默认值为 8。

  • void setMaxWait():(long maxWaitMillis),借出等待超时设置。设置池中无可用连接时调用线程阻塞等待的最大毫秒数,默认值为 -1(表示无限期等待,生产环境强烈建议设置为 3000 等明确超时值)。

  • void setKeepAlive():(boolean keepAlive),空闲长连接保活设置。设置是否开启后台定期对空闲超过 keepAliveBetweenTimeMillis 的连接执行探活检测,默认值为 false(开启后可有效防止防火墙或数据库服务端主动断开空闲长连接)。

  • void setRemoveAbandoned():(boolean removeAbandoned),连接泄漏强制回收设置。设置是否自动强制回收被业务线程借出后超出 removeAbandonedTimeout 秒仍未归还的疑似泄漏连接,默认值为 false(仅建议在排查连接泄漏问题时开启)。

  • void setRemoveAbandonedTimeout():(int removeAbandonedTimeout),连接泄漏超时秒数设置。设置判定连接发生泄漏的最大借出占用秒数,默认值为 300(5 分钟)。

java
package com.example.pool;

import com.alibaba.druid.pool.DruidDataSource;

// 1. 演示 DruidDataSource 容量边界、长连接保活与防泄漏回收配置
public class DruidSizingKeepAliveDemo {

  // 2. 配置容量上下限、开启 KeepAlive 保活及连接泄漏超时检测
  public static void main(String[] args) {
    try (DruidDataSource dataSource = new DruidDataSource()) {

      // 3. 设置初始连接数、最小空闲数、最大活跃数及借出等待超时(3秒)
      dataSource.setInitialSize(5);
      dataSource.setMinIdle(5);
      dataSource.setMaxActive(20);
      dataSource.setMaxWait(3000);

      // 4. 开启空闲连接主动保活与 180 秒连接泄漏检测回收
      dataSource.setKeepAlive(true);
      dataSource.setRemoveAbandoned(true);
      dataSource.setRemoveAbandonedTimeout(180);

      // 5. 验证已配置的容量与保活状态
      System.out.println("最大活跃连接上限: " + dataSource.getMaxActive());
      System.out.println("是否开启长连接保活: " + dataSource.isKeepAlive());
    }
  }
}

连接管理与监控 ​

  • void init():() throws SQLException,连接池显式初始化。显式触发数据源初始化流程:校验配置参数、实例化 Filter 链、按 initialSize 预先创建物理连接,并启动后台创建线程(CreateConnectionThread)与销毁线程(DestroyConnectionThread)。

  • getConnection():池化连接借出。从 Druid 连接池中借出一个包装后的代理连接 DruidPooledConnection(若连接池尚未初始化,内部会自动先触发 init())。

    • DruidPooledConnection:() throws SQLException,默认超时借出连接。使用数据源全局配置的 maxWait 毫秒数阻塞等待并借出一个可用连接。
    • DruidPooledConnection:(long maxWaitMillis) throws SQLException,指定超时借出连接。覆盖全局配置,使用本次传入的 maxWaitMillis 最大等待毫秒数借出一个可用连接。
    • Connection:(String username, String password) throws SQLException,指定凭据借出连接。校验传入的用户名与密码必须与数据源预设凭据一致(不一致将抛出 UnsupportedOperationException),随后借出默认池连接。
  • int getPoolingCount():(),当前空闲连接数查询。返回当前存放在池内 connections 数组中可供立即借出的空闲连接数量。

  • int getActiveCount():(),当前活跃连接数查询。返回当前已被业务线程借出、尚未调用 close() 归还的活跃连接数量。

  • long getConnectCount():(),累计借出次数统计。返回自连接池启动以来,调用方成功借出连接的累计总次数。

  • void shrink():(boolean checkTime),空闲连接主动收缩。立即扫描池中空闲连接,若 checkTime 为 true 则仅清理超出最小空闲存活时间的连接,若为 false 则强制将空闲连接收缩至 minIdle 数量。

  • void close():(),数据源销毁关闭。实现自 java.io.Closeable 接口,安全停止后台创建与销毁守护线程,断开池中所有底层物理连接,并注销 JMX 监控 MBean。

java
package com.example.pool;

import com.alibaba.druid.pool.DruidDataSource;
import com.alibaba.druid.pool.DruidPooledConnection;

// 1. 演示 DruidDataSource 显式初始化、连接借出、运行指标监控与空闲收缩
public class DruidLifecycleMonitorDemo {

  // 2. 初始化连接池,实时打印借出前后的空闲数、活跃数与累计借出次数
  public static void main(String[] args) throws Exception {
    DruidDataSource dataSource = new DruidDataSource();
    dataSource.setUrl("jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    dataSource.setUsername("root");
    dataSource.setPassword("root");
    dataSource.setInitialSize(5);
    dataSource.setMinIdle(2);
    dataSource.setMaxActive(10);

    // 3. 显式调用 init() 预热创建 5 个初始物理连接
    dataSource.init();
    System.out.println("初始化完成后空闲连接数: " + dataSource.getPoolingCount());

    // 4. 借出一个 DruidPooledConnection 代理连接(指定 2000ms 超时)
    try (DruidPooledConnection conn = dataSource.getConnection(2000)) {
      System.out.println("借出期间活跃连接数: " + dataSource.getActiveCount());
      System.out.println("借出期间空闲连接数: " + dataSource.getPoolingCount());
      System.out.println("累计借出连接总次数: " + dataSource.getConnectCount());
    }

    // 5. 强制将多余空闲连接收缩至 minIdle (2个)
    dataSource.shrink(false);
    System.out.println("执行 shrink(false) 后空闲连接数: " + dataSource.getPoolingCount());

    // 6. 关闭数据源并释放所有物理连接
    dataSource.close();
    System.out.println("数据源是否已关闭: " + dataSource.isClosed());
  }
}

继承: Object ​

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

继承: WrapperAdapter ​

isWrapperFor, unwrap

继承: DruidAbstractDataSource ​

addConnectionProperty, addFilters, clearFilters, createPhysicalConnection, createPhysicalConnection, discardConnection, getAccessToUnderlyingConnectionAllowed, getAcquireIncrement, getAsyncCloseConnectionEnable, getClearFiltersEnable, getConnectProperties, getConnectionErrorRetryAttempts, getConnectionInitSqls, getConnectionProperties, getCreateError, getCreateScheduler, getCreateTimespanMillis, getCreateTimespanNano, getCreatedTime, getDbType, getDefaultAutoCommit, getDefaultCatalog, getDefaultReadOnly, getDefaultTransactionIsolation, getDestroyScheduler, getDriver, getDriverClassLoader, getDriverClassName, getDriverMajorVersion, getDriverMinorVersion, getDupCloseLogEnable, getErrorCount, getExceptionSorter, getExceptionSorterClassName, getFailFast, getFilterClassNames, getFilters, getHistogramRanges, getID, getInitialSize, getKeepAliveBetweenTimeMillis, getLastCreateError, getLastCreateErrorTime, getLastCreateErrorTimeMillis, getLastError, getLastErrorTime, getLastErrorTimeMillis, getLockQueueLength, getLoginTimeout, getLogAbandoned, getLogDifferentThread, getLogWriter, getMaxActive, getMaxCreateTaskCount, getMaxEvictableIdleTimeMillis, getMaxIdle, getMaxOpenPreparedStatements, getMaxPoolPreparedStatementPerConnectionSize, getMaxWait, getMaxWaitThreadCount, getMinEvictableIdleTimeMillis, getMinIdle, getName, getNotFullTimeoutRetryCount, getObjectName, getOnFatalErrorMaxActive, getParentLogger, getPassword, getPasswordCallback, getPasswordCallbackClassName, getPhyMaxUseCount, getPhyTimeoutMillis, getPoolPreparedStatements, getProperties, getProxyFilters, getQueryTimeout, getRawDriver, getRawDriverMajorVersion, getRawDriverMinorVersion, getRawJdbcUrl, getRemoveAbandoned, getRemoveAbandonedTimeout, getRemoveAbandonedTimeoutMillis, getSafeUrl, getSharePreparedStatements, getStatLogger, getStatLoggerClassName, getTestOnBorrow, getTestOnReturn, getTestWhileIdle, getTimeBetweenConnectErrorMillis, getTimeBetweenEvictionRunsMillis, getTimeBetweenLogStatsMillis, getTransactionQueryTimeout, getTransactionThresholdMillis, getUrl, getUseGlobalDataSourceStat, getUseLocalSessionState, getUseOracleImplicitCache, getUseUnfairLock, getUserCallback, getUsername, getValidConnectionChecker, getValidConnectionCheckerClassName, getValidationQuery, getValidationQueryTimeout, getWaitThreadCount, isAccessToUnderlyingConnectionAllowed, isAsyncCloseConnectionEnable, isBreakAfterAcquireFailure, isClearFiltersEnable, isDefaultAutoCommit, isDupCloseLogEnable, isEnable, isFailFast, isFairLock, isFull, isInitExceptionThrow, isInitialized, isKeepAlive, isKillWhenSocketReadTimeout, isLogAbandoned, isLogDifferentThread, isOnFatalError, isOracle, isPoolPreparedStatements, isRemoveAbandoned, isResetStatEnable, isSharePreparedStatements, isTestOnBorrow, isTestOnReturn, isTestWhileIdle, isUseGlobalDataSourceStat, isUseLocalSessionState, isUseOracleImplicitCache, isUseUnfairLock, setAccessToUnderlyingConnectionAllowed, setAsyncCloseConnectionEnable, setBreakAfterAcquireFailure, setClearFiltersEnable, setConnectProperties, setConnectionErrorRetryAttempts, setConnectionInitSqls, setConnectionProperties, setCreateScheduler, setDbType, setDefaultAutoCommit, setDefaultCatalog, setDefaultReadOnly, setDefaultTransactionIsolation, setDestroyScheduler, setDriver, setDriverClassLoader, setDriverClassName, setDupCloseLogEnable, setEnable, setExceptionSorter, setExceptionSorter, setExceptionSorterClassName, setFailFast, setFilters, setInitExceptionThrow, setInitialSize, setKeepAliveBetweenTimeMillis, setKillWhenSocketReadTimeout, setLoginTimeout, setLogAbandoned, setLogDifferentThread, setLogWriter, setMaxActive, setMaxCreateTaskCount, setMaxEvictableIdleTimeMillis, setMaxIdle, setMaxOpenPreparedStatements, setMaxPoolPreparedStatementPerConnectionSize, setMaxWait, setMaxWaitThreadCount, setMinEvictableIdleTimeMillis, setMinIdle, setName, setNotFullTimeoutRetryCount, setObjectName, setOnFatalErrorMaxActive, setOracle, setPassword, setPasswordCallback, setPasswordCallbackClassName, setPhyMaxUseCount, setPhyTimeoutMillis, setPoolPreparedStatements, setProxyFilters, setQueryTimeout, setRemoveAbandoned, setRemoveAbandonedTimeout, setRemoveAbandonedTimeoutMillis, setSharePreparedStatements, setStatLogger, setStatLoggerClassName, setTestOnBorrow, setTestOnReturn, setTestWhileIdle, setTimeBetweenConnectErrorMillis, setTimeBetweenEvictionRunsMillis, setTimeBetweenLogStatsMillis, setTransactionQueryTimeout, setTransactionThresholdMillis, setUrl, setUseGlobalDataSourceStat, setUseLocalSessionState, setUseOracleImplicitCache, setUseUnfairLock, setUserCallback, setUsername, setValidConnectionChecker, setValidConnectionCheckerClassName, setValidationQuery, setValidationQueryTimeout, validateConnection

继承: DruidDataSourceC3P0Adapter ​

getAcquireRetryAttempts, getAcquireRetryDelay, getAutoCommitOnClose, getAutomaticTestTable, getCheckoutTimeout, getConnectionCustomizerClassName, getConnectionTesterClassName, getDebugUnreturnedConnectionStackTraces, getDescription, getDriverClass, getFactoryClassLocation, getForceIgnoreUnresolvedTransactions, getIdleConnectionTestPeriod, getInitialPoolSize, getJdbcUrl, getMaxAdministrativeTaskTime, getMaxConnectionAge, getMaxIdleTime, getMaxIdleTimeExcessConnections, getMaxPoolSize, getMaxStatements, getMaxStatementsPerConnection, getMinPoolSize, getNumBusyConnections, getNumConnections, getNumIdleConnections, getNumThreadsAwaitingCheckoutDefaultUser, getOverrideDefaultPassword, getOverrideDefaultUser, getPreferredTestQuery, getPropertyCycle, getTestConnectionOnCheckin, getTestConnectionOnCheckout, getUnreturnedConnectionTimeout, getUser, getUsesTraditionalReflectiveProxies, hardReset, isAutoCommitOnClose, isForceIgnoreUnresolvedTransactions, isTestConnectionOnCheckin, isTestConnectionOnCheckout, isUsesTraditionalReflectiveProxies, setAcquireRetryAttempts, setAcquireRetryDelay, setAutoCommitOnClose, setAutomaticTestTable, setCheckoutTimeout, setConnectionCustomizerClassName, setConnectionTesterClassName, setDebugUnreturnedConnectionStackTraces, setDescription, setDriverClass, setFactoryClassLocation, setForceIgnoreUnresolvedTransactions, setIdleConnectionTestPeriod, setInitialPoolSize, setJdbcUrl, setMaxAdministrativeTaskTime, setMaxConnectionAge, setMaxIdleTime, setMaxIdleTimeExcessConnections, setMaxPoolSize, setMaxStatements, setMaxStatementsPerConnection, setMinPoolSize, setOverrideDefaultPassword, setOverrideDefaultUser, setPreferredTestQuery, setPropertyCycle, setTestConnectionOnCheckin, setTestConnectionOnCheckout, setUnreturnedConnectionTimeout, setUser, setUsesTraditionalReflectiveProxies, softReset

API: DruidDataSourceFactory ​

构造方法 ​

  • DruidDataSourceFactory DruidDataSourceFactory():(),工厂实例构造。创建 DruidDataSourceFactory 对象实例,主要供 JNDI 命名目录容器(如 Tomcat Resource 工厂机制)通过反射实例化并调用 getObjectInstance() 使用;常规业务代码直接调用静态工厂方法即可,无需显式构造实例。
java
package com.example.pool;

import com.alibaba.druid.pool.DruidDataSourceFactory;

// 1. 演示 DruidDataSourceFactory 默认无参构造器的实例化
public class DruidFactoryConstructorDemo {

  // 2. 构造工厂对象实例(通常由 JNDI 容器在底层反射调用)
  public static void main(String[] args) {
    DruidDataSourceFactory factory = new DruidDataSourceFactory();

    // 3. 打印创建的工厂实例类型信息
    System.out.println("成功实例化数据源工厂: " + factory.getClass().getName());
  }
}

属性键名常量 ​

  • final String DruidDataSourceFactory.PROP_DRIVERCLASSNAME:驱动类名配置键常量。常量值为 "driverClassName",用于在 Properties 或 Map 配置集合中指定 JDBC 驱动全限定类名。

  • final String DruidDataSourceFactory.PROP_URL:连接地址配置键常量。常量值为 "url",用于在配置集合中指定数据库的 JDBC 连接 URL 地址。

  • final String DruidDataSourceFactory.PROP_USERNAME:登录账号配置键常量。常量值为 "username",用于在配置集合中指定数据库登录用户名。

  • final String DruidDataSourceFactory.PROP_PASSWORD:登录密码配置键常量。常量值为 "password",用于在配置集合中指定数据库登录密码。

  • final String DruidDataSourceFactory.PROP_INITIALSIZE:初始连接数配置键常量。常量值为 "initialSize",用于在配置集合中指定连接池启动时预先创建的物理连接数。

  • final String DruidDataSourceFactory.PROP_MINIDLE:最小空闲数配置键常量。常量值为 "minIdle",用于在配置集合中指定连接池常驻维持的最少空闲连接数。

  • final String DruidDataSourceFactory.PROP_MAXACTIVE:最大连接数配置键常量。常量值为 "maxActive",用于在配置集合中指定连接池允许同时存在的最大活跃连接总数上限。

  • final String DruidDataSourceFactory.PROP_MAXWAIT:最大等待时间配置键常量。常量值为 "maxWait",用于在配置集合中指定借出连接时阻塞等待的最大毫秒数。

  • final String DruidDataSourceFactory.PROP_VALIDATIONQUERY:探活查询语句配置键常量。常量值为 "validationQuery",用于在配置集合中指定检测连接有效性的 SQL 查询语句(如 "SELECT 1")。

  • final String DruidDataSourceFactory.PROP_TESTWHILEIDLE:空闲探活开关配置键常量。常量值为 "testWhileIdle",用于在配置集合中指定是否在申请连接且空闲时间超期时执行有效性探活检测。

  • final String DruidDataSourceFactory.PROP_FILTERS:扩展过滤器配置键常量。常量值为 "filters",用于在配置集合中指定需要挂载的 Filter 插件别名列表(如 "stat,wall")。

  • final String DruidDataSourceFactory.PROP_CONNECTIONPROPERTIES:驱动扩展属性配置键常量。常量值为 "connectionProperties",用于在配置集合中指定传递给底层 JDBC 驱动或 Filter 的分号分隔键值对字符串。

注意事项:

  1. 在编写 druid.properties 或通过代码组装 Map 配置时,直接引用 DruidDataSourceFactory.PROP_* 常量作为 Key 可以有效避免手写字符串拼写错误导致配置静默失效。
java
package com.example.pool;

import com.alibaba.druid.pool.DruidDataSourceFactory;
import java.util.Properties;

// 1. 演示使用 DruidDataSourceFactory 标准属性键名常量组装配置
public class DruidFactoryConstantsDemo {

  // 2. 引用工厂类静态常量构建类型安全的 Properties 配置集合
  public static void main(String[] args) {
    Properties props = new Properties();

    // 3. 使用标准常量键名设置连接地址、用户名、最大连接数与监控插件
    props.setProperty(DruidDataSourceFactory.PROP_URL, "jdbc:mysql://localhost:3306/test_db");
    props.setProperty(DruidDataSourceFactory.PROP_USERNAME, "root");
    props.setProperty(DruidDataSourceFactory.PROP_MAXACTIVE, "20");
    props.setProperty(DruidDataSourceFactory.PROP_FILTERS, "stat,wall");

    // 4. 打印验证组装完成的标准化属性集合
    System.out.println("组装完成的配置项: " + props);
  }
}

数据源构建与装配 ​

  • DruidDataSourceFactory.createDataSource():静态工厂构建数据源。接收外部传入的 Properties 或 Map 键值对集合,在内部自动实例化 DruidDataSource 并完成全部属性的解析与注入,返回标准 javax.sql.DataSource 接口引用。

    • DataSource:(Properties properties) throws Exception,属性集构建数据源。读取 java.util.Properties 对象中的配置项并创建对应的 DruidDataSource 实例,常用于加载类路径下的 druid.properties 文件。
    • DataSource:(Map properties) throws Exception,映射表构建数据源。读取任意 java.util.Map 集合(如 YAML 解析后的 Map 或动态构建的 HashMap)中的配置项并创建对应的 DruidDataSource 实例。
  • void DruidDataSourceFactory.config():(DruidDataSource dataSource, Map<?, ?> properties) throws SQLException,已有数据源属性装配。将传入的 Map 配置集合中的各项参数解析并批量注入到一个已经存在的 DruidDataSource 实例中(createDataSource 底层即委托该方法完成属性绑定)。

  • Object getObjectInstance():(Object obj, Name name, Context nameCtx, Hashtable<?, ?> environment) throws Exception,JNDI 容器对象工厂方法。实现自 javax.naming.spi.ObjectFactory 接口,解析 JNDI Reference 引用地址属性并构建返回 DruidDataSource 实例。

注意事项:

  1. DruidDataSourceFactory.createDataSource() 返回的编译期类型是标准接口 javax.sql.DataSource(运行期实际类型为 DruidDataSource)。如果在程序退出时需要关闭连接池,可将其向下转型为 DruidDataSource 或 java.io.Closeable 后调用 close(),也可通过 unwrap(DruidDataSource.class) 拆包。
  2. 若配置集合中包含 "init"="true" 键值对,config() 方法会在属性注入完毕后立即触发 dataSource.init() 完成物理连接池预热;否则默认采用延迟初始化策略,在首次调用 getConnection() 时才建立物理连接。
java
package com.example.pool;

import com.alibaba.druid.pool.DruidDataSource;
import com.alibaba.druid.pool.DruidDataSourceFactory;
import javax.sql.DataSource;
import java.sql.Connection;
import java.util.HashMap;
import java.util.Map;

// 1. 演示使用 DruidDataSourceFactory 静态工厂方法创建与装配数据源
public class DruidFactoryCreateDemo {

  // 2. 通过 Map 配置集合构建数据源并借出连接
  public static void main(String[] args) throws Exception {
    Map<String, String> configMap = new HashMap<>();

    // 3. 填入连接四要素与容量配置参数
    configMap.put(DruidDataSourceFactory.PROP_DRIVERCLASSNAME, "com.mysql.cj.jdbc.Driver");
    configMap.put(DruidDataSourceFactory.PROP_URL, "jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=UTC");
    configMap.put(DruidDataSourceFactory.PROP_USERNAME, "root");
    configMap.put(DruidDataSourceFactory.PROP_PASSWORD, "root");
    configMap.put(DruidDataSourceFactory.PROP_INITIALSIZE, "3");
    configMap.put(DruidDataSourceFactory.PROP_MAXACTIVE, "10");

    // 4. 调用 createDataSource 静态工厂方法一键构建标准 DataSource
    DataSource dataSource = DruidDataSourceFactory.createDataSource(configMap);
    try (Connection conn = dataSource.getConnection()) {
      System.out.println("通过 createDataSource 成功借出连接: " + conn);
    }

    // 5. 演示使用 config 静态方法向已有 DruidDataSource 实例注入 Map 配置
    try (DruidDataSource existingDs = new DruidDataSource()) {
      DruidDataSourceFactory.config(existingDs, configMap);
      System.out.println("通过 config 装配后的最大连接数: " + existingDs.getMaxActive());
    }

    // 6. 将标准接口拆包为 DruidDataSource 并安全关闭
    dataSource.unwrap(DruidDataSource.class).close();
  }
}

Apache DBUtils 封装 ​

原生 ResultSet 痛点 ​

在使用连接池(如 Druid、HikariCP)管理数据库连接后,获取与归还连接的开销已得到大幅优化,但原生 JDBC 的结果集处理(java.sql.ResultSet)依然存在三个显著的开发痛点:

  1. 连接关闭导致结果集失效:ResultSet 的数据读取强依赖于底层的 Connection 连接。一旦调用 connection.close() 将连接归还至连接池,关联的 ResultSet 会被立即关闭,业务层无法在关闭连接后继续遍历结果集。

  2. 结果集不利于跨层传递:ResultSet 属于持久层游标资源,既不支持序列化,也不具备直观的业务语义,无法直接作为方法返回值传递给 Service 层或前端视图层。

  3. 手动映射代码高度冗余:若在关闭连接前手动将 ResultSet 中的记录逐条读取并封装到 ArrayList<Entity> 集合中,每个数据表的查询都需要重复编写大量的 while (rs.next()) 与 rs.getXxx("column") 样板代码。

为解决上述问题,Apache 基金会推出了轻量级 JDBC 工具库 Commons DBUtils。它在不引入重量级 ORM 框架的前提下,通过反射与策略模式自动将 ResultSet 转换为 JavaBean 实体或集合,并在结果集转换完毕后安全释放底层资源。在此基础上结合 Druid 连接池进一步封装通用的泛型基类 BasicDAO<T>,即可实现全项目零样板代码的数据库增删改查。

模拟 ResultSet 封装 ​

在引入 DBUtils 之前,可以先手动完成一次结果集到集合的转换,以理解其底层原理。核心思路是在连接归还之前,将 ResultSet 中的每一行记录逐条读取并转存到与连接无关的 ArrayList<Actor> 集合中,此后即使关闭连接,集合中的数据依然可以被反复使用与跨层传递。

image-20261112175531221

该映射过程遵循表 → 类、行 → 对象、列 → 属性的对应关系:

数据库概念Java 概念映射说明
actor 表Actor 类定义与表结构对应的 Java 类,该类通常被称为 JavaBean、POJO 或 Domain 实体类。
表中的一行记录一个 Actor 对象每遍历一次 resultSet.next(),就创建一个新的 Actor 对象承载该行数据。
记录中的列值Actor 对象的属性通过 resultSet.getXxx("列名") 读取列值,再调用对应的 Setter 方法为属性赋值。
整个查询结果集ArrayList<Actor> 集合将封装好的 Actor 对象依次放入集合,最终以集合作为方法返回值交给上层使用。

具体实现可拆分为以下步骤:

  1. 定义实体类:创建属性与 actor 表字段(id、name、sex、borndate、phone)一一对应的 Actor 类(完整定义参见下文「实体类定义」)。

  2. 获取连接并执行查询:从连接池借出 Connection,通过 PreparedStatement 发送 SELECT 语句得到 ResultSet。

  3. 逐行映射为对象:循环调用 resultSet.next(),每读取一行便创建一个 Actor 对象并为其属性赋值。

  4. 对象加入集合:将每个 Actor 对象添加到 ArrayList<Actor> 中。

  5. 释放资源并返回集合:在 finally 中关闭 ResultSet、PreparedStatement 并归还连接,最后返回已脱离连接依赖的集合。

java
package com.example.dao;

import com.example.entity.Actor;
import com.example.pool.JDBCUtilsByDruid;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;

// 1. 手动将 ResultSet 结果集逐行映射为 Actor 实体并封装至 ArrayList 集合
public class ActorManualMapper {

  public List<Actor> listActors(int minId) {
    // 2. 创建承载查询结果的 ArrayList 集合,其生命周期独立于 Connection
    List<Actor> actors = new ArrayList<>();
    Connection connection = null;
    PreparedStatement preparedStatement = null;
    ResultSet resultSet = null;
    try {
      // 3. 从 Druid 连接池借出连接,发送 SELECT 语句获取原生结果集
      connection = JDBCUtilsByDruid.getConnection();
      preparedStatement = connection.prepareStatement("SELECT id, name, sex, borndate, phone FROM actor WHERE id >= ?");
      preparedStatement.setInt(1, minId);
      resultSet = preparedStatement.executeQuery();
      // 4. 遍历结果集,每一行记录对应创建一个 Actor 对象,并将列值赋给对应属性
      while (resultSet.next()) {
        Actor actor = new Actor();
        actor.setId(resultSet.getInt("id"));
        actor.setName(resultSet.getString("name"));
        actor.setSex(resultSet.getString("sex"));
        actor.setBorndate(resultSet.getTimestamp("borndate"));
        actor.setPhone(resultSet.getString("phone"));
        // 5. 将封装完成的 Actor 对象放入 ArrayList 集合
        actors.add(actor);
      }
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      // 6. 关闭 ResultSet 与 PreparedStatement,并将连接归还回连接池
      JDBCUtilsByDruid.close(resultSet, preparedStatement, connection);
    }
    // 7. 连接归还后集合数据依然有效,可安全返回给 Service 层反复使用
    return actors;
  }
}

手动封装的局限性:上述代码虽然解决了结果集依赖连接、不便传递的问题,但 while 循环内的字段映射逻辑与具体实体类强绑定。每新增一张数据表,都需要重复编写一套几乎相同的 getXxx / setXxx 样板代码。DBUtils 正是通过反射读取 ResultSetMetaData 列名并自动调用实体类 Setter 方法,将这段重复逻辑抽象为通用的 BeanListHandler<T>。

依赖引入 ​

Maven 依赖引入 ​

在 Maven 项目中使用 Apache DBUtils 配合 Druid 连接池时,需在 pom.xml 中引入 commons-dbutils、druid 以及 MySQL 数据库驱动依赖:

xml
<dependencies>
    <!-- 1. 引入 Apache Commons DBUtils 核心依赖 -->
    <dependency>
        <groupId>commons-dbutils</groupId>
        <artifactId>commons-dbutils</artifactId>
        <version>1.7</version>
    </dependency>

    <!-- 2. 引入阿里巴巴 Druid 连接池依赖 -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid</artifactId>
        <version>1.2.20</version>
    </dependency>

    <!-- 3. 引入 MySQL 数据库驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.0.33</version>
    </dependency>
</dependencies>

手动引入依赖 ​

在未使用 Maven 的传统 Java 项目中手动导入 JAR 包时,需将以下 3 个核心 JAR 包复制到项目根目录下的 lib 文件夹,并在 IDE 中右键选择 Add as Library... 添加至构建类路径(Classpath):

  1. commons-dbutils-1.7.jar:Apache DBUtils 核心工具包(零第三方外部依赖)。

  2. druid-1.2.20.jar:阿里巴巴 Druid 连接池核心包。

  3. mysql-connector-j-8.0.33.jar:MySQL 数据库 JDBC 驱动包。

核心组件 ​

Apache DBUtils 的设计极为精简,核心职责由 QueryRunner 与 ResultSetHandler 两个组件协同完成:

QueryRunner ​

QueryRunner 是 SQL 语句的核心执行引擎。它封装了 PreparedStatement 的创建、占位符参数(?)的批量绑定、SQL 语句执行以及 ResultSet 和 PreparedStatement 的自动关闭逻辑,对外主要提供 query()(执行查询)与 update()(执行增删改)两类方法。

ResultSetHandler ​

ResultSetHandler 是结果集转换的策略接口。QueryRunner 在执行完 SELECT 查询拿到原生 ResultSet 后,会将其回调给传入的 ResultSetHandler 实现类进行解析转换。DBUtils 内置了多种开箱即用的实现类以应对不同的查询场景:

实现类名称返回值类型适用查询场景说明
BeanListHandler<T>List<T>多行记录查询。通过反射将结果集中的每一行记录转换为一个 T 类型的 JavaBean 对象,并汇总封装为 List<T> 集合返回。
BeanHandler<T>T单行记录查询。将结果集中的第一行记录通过反射转换为单个 T 类型的 JavaBean 对象返回(若无记录则返回 null)。
ScalarHandler<T>T / Object单行单列标量查询。提取结果集中第一行第一列的单个数据值返回,常用于 COUNT(*)、MAX()、SUM() 等聚合统计或查询单个字段。
MapListHandlerList>无实体类多行查询。将每一行记录转换为以列名为 Key、列值为 Value 的 Map,并汇总为 List 集合返回,常用于多表联查动态字段场景。

JavaBean 反射映射约束:使用 BeanHandler 或 BeanListHandler 时,目标实体类必须提供一个公共无参构造器,且类的属性名(Setter 方法名)需与 SQL 查询返回的列名或列别名(AS)保持一致,否则对应属性将无法通过反射赋值(保持默认值 null)。

实例: actor 表 CRUD ​

将 JDBCUtilsByDruid(负责借出与归还连接)与 QueryRunner(负责执行 SQL 并转换结果集)组合使用,即可在不编写任何 while (rs.next()) 样板代码的前提下完成对 actor 表的增删改查。实体类 Actor 的完整定义参见下文「实体类定义」。

每一次数据库操作都遵循相同的固定流程:

  1. 借出连接:调用 JDBCUtilsByDruid.getConnection() 从 Druid 连接池获取代理连接。
  2. 执行 SQL:
    • DML 语句:调用 queryRunner.update(connection, sql, params...),返回受影响行数;
    • 查询语句:调用 queryRunner.query(connection, sql, handler, params...),并按场景传入 BeanListHandler、BeanHandler 或 ScalarHandler。
  3. 归还连接:在 finally 中调用 JDBCUtilsByDruid.close(null, null, connection)。ResultSet 与 PreparedStatement 已由 QueryRunner 内部自动关闭,因此前两个参数直接传入 null。
java
package com.example.dao;

import com.example.entity.Actor;
import com.example.pool.JDBCUtilsByDruid;
import org.apache.commons.dbutils.QueryRunner;
import org.apache.commons.dbutils.handlers.BeanHandler;
import org.apache.commons.dbutils.handlers.BeanListHandler;
import org.apache.commons.dbutils.handlers.ScalarHandler;
import java.sql.Connection;
import java.sql.SQLException;
import java.util.List;

// 1. 使用 DBUtils + JDBCUtilsByDruid 完成对 actor 表的 CRUD 操作
public class DBUtilsCrudDemo {

  // 2. 创建无参 QueryRunner(不绑定 DataSource),连接由调用方手动传入并负责归还
  private static final QueryRunner queryRunner = new QueryRunner();

  public static void main(String[] args) {
    testDML();
    testQueryMulti();
    testQuerySingle();
    testQueryScalar();
  }

  // 3. DML 增删改:INSERT、UPDATE、DELETE 统一调用 update(),返回受影响的行数
  public static void testDML() {
    Connection connection = null;
    try {
      connection = JDBCUtilsByDruid.getConnection();
      // 3.1 添加记录
      int insertRows = queryRunner.update(connection, "INSERT INTO actor VALUES (NULL, ?, ?, ?, ?)", "张三丰", "男", "1990-11-11", "116");
      // 3.2 修改记录
      int updateRows = queryRunner.update(connection, "UPDATE actor SET name = ? WHERE id = ?", "张无忌", 1);
      // 3.3 删除记录
      int deleteRows = queryRunner.update(connection, "DELETE FROM actor WHERE id = ?", 2);
      System.out.println("添加: " + insertRows + ",修改: " + updateRows + ",删除: " + deleteRows);
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      // 4. ResultSet 与 PreparedStatement 已由 QueryRunner 内部关闭,此处只需归还连接
      JDBCUtilsByDruid.close(null, null, connection);
    }
  }

  // 5. 多行查询:BeanListHandler 通过反射将每行记录封装为 Actor,并汇总为 List<Actor>
  public static void testQueryMulti() {
    Connection connection = null;
    try {
      connection = JDBCUtilsByDruid.getConnection();
      String sql = "SELECT id, name, sex, borndate, phone FROM actor WHERE id >= ?";
      List<Actor> actors = queryRunner.query(connection, sql, new BeanListHandler<>(Actor.class), 1);
      actors.forEach(System.out::println);
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      JDBCUtilsByDruid.close(null, null, connection);
    }
  }

  // 6. 单行查询:BeanHandler 返回单个 Actor 对象,无匹配记录时返回 null
  public static void testQuerySingle() {
    Connection connection = null;
    try {
      connection = JDBCUtilsByDruid.getConnection();
      String sql = "SELECT id, name, sex, borndate, phone FROM actor WHERE id = ?";
      Actor actor = queryRunner.query(connection, sql, new BeanHandler<>(Actor.class), 1);
      System.out.println("单行查询结果: " + actor);
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      JDBCUtilsByDruid.close(null, null, connection);
    }
  }

  // 7. 单行单列查询:ScalarHandler 提取结果集首行首列的标量值
  public static void testQueryScalar() {
    Connection connection = null;
    try {
      connection = JDBCUtilsByDruid.getConnection();
      String sql = "SELECT name FROM actor WHERE id = ?";
      Object name = queryRunner.query(connection, sql, new ScalarHandler<>(), 1);
      System.out.println("单值查询结果: " + name);
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      JDBCUtilsByDruid.close(null, null, connection);
    }
  }
}

连接的关闭责任:QueryRunner 的 query(Connection, ...) 与 update(Connection, ...) 重载只会关闭其内部创建的 PreparedStatement 与 ResultSet,不会关闭外部传入的 Connection。因此必须在 finally 中手动调用 JDBCUtilsByDruid.close 将连接归还连接池,否则连接会持续被占用,最终导致连接池耗尽、后续请求阻塞至 maxWait 超时。

连接的作用域与线程安全:Connection 必须作为方法内的局部变量(或在跨方法事务场景下绑定到 ThreadLocal),保证每个方法/线程拿到的是自己独立的连接,切勿将其提升为类的成员属性或静态变量全局共用。一方面,DruidPooledConnection 在调用 close() 归还入池后,原代理引用即被标记为失效,后续方法继续复用该引用会直接抛出异常;另一方面,Connection 本身非线程安全,多线程共享同一连接会导致连接被提前关闭或事务状态相互串扰。

重复代码的进一步抽取:观察上述四个方法可以发现,「借出连接 → 执行 SQL → 归还连接」的骨架完全一致,变化的只有 SQL、参数与 ResultSetHandler。下文的 BasicDAO<T> 正是将这段骨架抽取为通用的泛型模板方法。

源码: queryRunner.query ​

追踪上文 queryRunner.query(connection, sql, new BeanListHandler<>(Actor.class), 1) 的底层调用栈,深入 org.apache.commons.dbutils.QueryRunner(及其父类 AbstractQueryRunner)源码,可以清晰看到 DBUtils 是如何串联参数自动绑定、策略回调转换与资源分级释放的:

java
package org.apache.commons.dbutils;

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Types;

// 1. QueryRunner 查询与参数填充核心源码提炼(基于 Commons DBUtils 1.7)
public class QueryRunner extends AbstractQueryRunner {

  // 2. 外部显式传入 Connection 的查询入口:将 closeConn 标志固定设为 false
  public <T> T query(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params)
      throws SQLException {
    return this.<T>query(conn, false, sql, rsh, params);
  }

  // 3. 核心私有查询方法:串联校验、预编译、参数绑定、结果集转换与资源释放
  private <T> T query(Connection conn, boolean closeConn, String sql, ResultSetHandler<T> rsh, Object... params)
      throws SQLException {
    PreparedStatement stmt = null;
    ResultSet rs = null;
    T result = null;

    try {
      // 4. 创建 PreparedStatement 并调用 fillStatement 批量填充可变参数
      stmt = this.prepareStatement(conn, sql);
      this.fillStatement(stmt, params);
      // 5. 执行查询获取 ResultSet,并回调 ResultSetHandler 完成反射封装
      rs = this.wrap(stmt.executeQuery());
      result = rsh.handle(rs);

    } catch (SQLException e) {
      this.rethrow(e, sql, params);

    } finally {
      // 6. 嵌套 finally 确保 rs 与 stmt 必定被关闭;closeConn 为 false 时不关闭外部 conn
      try {
        close(rs);
      } finally {
        close(stmt);
        if (closeConn) {
          close(conn);
        }
      }
    }

    return result;
  }

  // 7. 继承自 AbstractQueryRunner:遍历 params 数组为 PreparedStatement 占位符赋值
  @Override
  public void fillStatement(PreparedStatement stmt, Object... params) throws SQLException {
    if (params == null) {
      return;
    }
    for (int i = 0; i < params.length; i++) {
      if (params[i] != null) {
        stmt.setObject(i + 1, params[i]);
      } else {
        stmt.setNull(i + 1, Types.VARCHAR);
      }
    }
  }
}

从上述核心源码可以提炼出 queryRunner.query() 的四个关键执行阶段:

  1. 入口转发与 closeConn 标记:当调用显式传入 Connection 的 query(conn, sql, rsh, params) 重载时,内部将布尔参数 closeConn 硬编码为 false 并转发给私有核心 query 方法(反之,若调用不传 Connection 的重载,则会从 QueryRunner 绑定的 DataSource 中借出连接,并将 closeConn 设为 true)。

  2. 预编译与可变参数自动填充:调用 this.prepareStatement(conn, sql) 获取 PreparedStatement,随后调用父类 AbstractQueryRunner 的 fillStatement(stmt, params) 方法。该方法遍历可变参数数组 Object... params,通过 stmt.setObject(i + 1, params[i]) 自动将参数按顺序绑定到 SQL 的 ? 占位符上(注意 JDBC 占位符索引从 1 开始,数组下标从 0 开始)。

  3. 结果集策略回调(rsh.handle):调用 stmt.executeQuery() 得到原生 ResultSet 并经 wrap() 包装后,将其传递给 rsh.handle(rs)。此时控制权交由具体的策略实现类(如 BeanListHandler),在 handle 方法内部通过反射创建 Actor 实例、读取 ResultSetMetaData 列名并调用 Setter 方法完成集合组装,最终将转换后的 List<Actor> 赋给 result。

  4. 资源分级安全释放:在 finally 代码块中,源码采用了嵌套 try...finally 结构——将 close(stmt) 放在 close(rs) 的内层 finally 中,确保即便关闭 ResultSet 时抛出异常,PreparedStatement 也一定会被关闭。随后检查 if (closeConn),由于外部传入连接时 closeConn 为 false,原生 Connection 不会被关闭,因此调用方在外部 finally 中只需执行 JDBCUtilsByDruid.close(null, null, connection) 归还连接即可。

API: QueryRunner ​

构造方法 ​

  • QueryRunner():SQL 执行器构造。创建 QueryRunner 实例,支持无数据源的手动连接传入模式或绑定 DataSource 的自动连接管理模式,并可配置预编译参数元数据探测的容错行为。
    • QueryRunner:(),无参构造。创建未绑定 DataSource 的 QueryRunner 实例,后续调用查询、更新或批处理方法时必须显式传入 Connection 对象。
    • QueryRunner:(DataSource ds),数据源绑定构造。创建与指定 DataSource 连接池关联的实例,支持直接调用不含 Connection 参数的执行方法,内部自动从数据源获取并在执行后归还连接。
    • QueryRunner:(boolean pmdKnownBroken),元数据容错构造。创建未绑定数据源的实例并指定 pmdKnownBroken 标志;当设为 true 时,填充 null 参数时不再调用 PreparedStatement.getParameterMetaData() 探测参数类型,用于兼容不支持参数元数据的数据库驱动。
    • QueryRunner:(DataSource ds, boolean pmdKnownBroken),数据源加元数据容错构造。同时绑定 DataSource 数据源并设置是否跳过 ParameterMetaData 类型探测。

注意事项:

  1. QueryRunner 是完全无状态的线程安全类,在实际工程中可作为单例或成员变量(如 BasicDAO 中的属性)跨线程共享复用。
  2. 在 MySQL 驱动默认未开启 useServerPrepStmts=true 且向 SQL 传入 null 参数值时,若驱动抛出参数元数据不可用异常,可将 pmdKnownBroken 设为 true 进行规避。
java
package com.hspedu.jdbc.dbutils;

import com.alibaba.druid.pool.DruidDataSourceFactory;
import java.io.InputStream;
import java.util.Properties;
import javax.sql.DataSource;
import org.apache.commons.dbutils.QueryRunner;

public class QueryRunnerConstructDemo {

  public static void main(String[] args) throws Exception {
    // 1. 使用无参构造器创建实例,适用于手动传入 Connection 控制事务的场景
    QueryRunner manualRunner = new QueryRunner();
    System.out.println("无参构造实例: " + manualRunner);

    Properties props = new Properties();
    try (InputStream is = QueryRunnerConstructDemo.class.getClassLoader().getResourceAsStream("druid.properties")) {
      props.load(is);
    }
    DataSource dataSource = DruidDataSourceFactory.createDataSource(props);

    // 2. 传入 DataSource 构造实例,执行 SQL 时自动从连接池借出并归还连接
    QueryRunner dsRunner = new QueryRunner(dataSource);
    System.out.println("绑定数据源实例: " + dsRunner.getDataSource());

    // 3. 开启 pmdKnownBroken 容错标志,避免驱动不支持参数元数据时抛出异常
    QueryRunner safeRunner = new QueryRunner(dataSource, true);
    System.out.println("是否跳过参数元数据探测: " + safeRunner.isPmdKnownBroken());
  }
}

数据查询 ​

  • query():DQL 查询执行。执行预编译 SELECT 查询语句,将底层返回的 ResultSet 委托给指定的 ResultSetHandler 策略实现类转换为目标类型对象。
    • <T> T:(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params),指定连接带参查询。在给定的 Connection 上绑定可变参数数组并执行查询,方法内部自动关闭 PreparedStatement 和 ResultSet,但不关闭传入的 Connection。
    • <T> T:(Connection conn, String sql, ResultSetHandler<T> rsh),指定连接无参查询。在给定的 Connection 上执行不含 ? 占位符的静态查询语句并转换结果集,不关闭传入的 Connection。
    • <T> T:(String sql, ResultSetHandler<T> rsh, Object... params),数据源带参查询。从构造器绑定的 DataSource 中自动获取连接,绑定可变参数执行查询后,自动关闭 PreparedStatement、ResultSet 并将 Connection 归还连接池。
    • <T> T:(String sql, ResultSetHandler<T> rsh),数据源无参查询。从绑定的 DataSource 中自动获取连接执行无参查询,执行完毕后自动关闭全部数据库资源。

注意事项:

  1. 凡是显式接收 Connection 参数的重载方法,QueryRunner 仅负责关闭内部创建的 PreparedStatement 和 ResultSet,调用方必须在外部(或事务提交后)自行关闭或归还该 Connection。
  2. 凡是不接收 Connection 参数的重载方法,必须确保 QueryRunner 在构造时已传入非空的 DataSource,否则调用时会直接抛出 SQLException: Null DataSource。
java
package com.hspedu.jdbc.dbutils;

import com.hspedu.jdbc.domain.User;
import com.hspedu.jdbc.utils.JDBCUtilsByDruid;
import java.sql.Connection;
import java.util.List;
import org.apache.commons.dbutils.QueryRunner;
import org.apache.commons.dbutils.handlers.BeanHandler;
import org.apache.commons.dbutils.handlers.BeanListHandler;
import org.apache.commons.dbutils.handlers.ScalarHandler;

public class QueryRunnerQueryDemo {

  public static void main(String[] args) throws Exception {
    QueryRunner qr = new QueryRunner();

    try (Connection conn = JDBCUtilsByDruid.getConnection()) {
      // 1. 传入 Connection、带参 SQL 与 BeanHandler 查询单行记录并封装为实体对象
      String singleSql = "SELECT id, username, balance FROM t_user WHERE id = ?";
      User user = qr.query(conn, singleSql, new BeanHandler<>(User.class), 1);
      System.out.println("单行查询结果: " + user);

      // 2. 传入 Connection、带参 SQL 与 BeanListHandler 查询多行记录并封装为集合
      String listSql = "SELECT id, username, balance FROM t_user WHERE balance >= ?";
      List<User> userList = qr.query(conn, listSql, new BeanListHandler<>(User.class), 500.00);
      System.out.println("多行查询数量: " + userList.size());

      // 3. 执行不含占位符参数的静态聚合查询,通过 ScalarHandler 提取单值结果
      String countSql = "SELECT COUNT(*) FROM t_user";
      Long totalCount = qr.query(conn, countSql, new ScalarHandler<>());
      System.out.println("总记录数: " + totalCount);
    }
  }
}

数据变更 ​

  • update():DML 变更执行。执行预编译 INSERT、UPDATE 或 DELETE 语句,返回受当前语句影响的数据库记录行数。

    • int:(Connection conn, String sql, Object... params),指定连接多参变更。在给定的 Connection 上绑定多个占位符参数并执行 DML 更新,不关闭传入的 Connection。
    • int:(Connection conn, String sql, Object param),指定连接单参变更。在给定的 Connection 上绑定单个占位符参数并执行 DML 更新,不关闭传入的 Connection。
    • int:(Connection conn, String sql),指定连接无参变更。在给定的 Connection 上执行不含占位符的静态 DML 语句,不关闭传入的 Connection。
    • int:(String sql, Object... params),数据源多参变更。从绑定的 DataSource 获取连接,绑定可变参数执行 DML 语句后自动归还连接。
    • int:(String sql, Object param),数据源单参变更。从绑定的 DataSource 获取连接,绑定单个参数执行 DML 语句后自动归还连接。
    • int:(String sql),数据源无参变更。从绑定的 DataSource 获取连接,执行无参 DML 语句后自动归还连接。
  • insert():新增主键回填。专门用于执行 INSERT 语句,并在底层开启 Statement.RETURN_GENERATED_KEYS 将数据库生成的自增主键结果集交由 ResultSetHandler 提取返回。

    • <T> T:(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params),指定连接带参新增回填。在给定连接上执行带参插入并解析生成的自增主键,不关闭传入的 Connection。
    • <T> T:(Connection conn, String sql, ResultSetHandler<T> rsh),指定连接无参新增回填。在给定连接上执行无参插入并解析生成的自增主键,不关闭传入的 Connection。
    • <T> T:(String sql, ResultSetHandler<T> rsh, Object... params),数据源带参新增回填。从绑定的 DataSource 获取连接执行带参插入,解析返回自增主键后自动归还连接。
    • <T> T:(String sql, ResultSetHandler<T> rsh),数据源无参新增回填。从绑定的 DataSource 获取连接执行无参插入,解析返回自增主键后自动归还连接。
java
package com.hspedu.jdbc.dbutils;

import com.hspedu.jdbc.utils.JDBCUtilsByDruid;
import java.math.BigInteger;
import java.sql.Connection;
import org.apache.commons.dbutils.QueryRunner;
import org.apache.commons.dbutils.handlers.ScalarHandler;

public class QueryRunnerUpdateDemo {

  public static void main(String[] args) throws Exception {
    QueryRunner qr = new QueryRunner();

    try (Connection conn = JDBCUtilsByDruid.getConnection()) {
      // 1. 调用 insert 执行新增语句,并通过 ScalarHandler 直接提取生成的自增主键
      String insertSql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
      BigInteger generatedId = qr.insert(conn, insertSql, new ScalarHandler<>(), "Grace", 1500.00);
      System.out.println("新增记录自增主键 ID: " + generatedId);

      // 2. 调用 update 传入可变参数数组执行条件更新,返回受影响的行数
      String updateSql = "UPDATE t_user SET balance = balance + ? WHERE id = ?";
      int updatedRows = qr.update(conn, updateSql, 300.00, generatedId);
      System.out.println("更新受影响行数: " + updatedRows);

      // 3. 调用单参数重载的 update 执行删除操作
      String deleteSql = "DELETE FROM t_user WHERE id = ?";
      int deletedRows = qr.update(conn, deleteSql, generatedId);
      System.out.println("删除受影响行数: " + deletedRows);
    }
  }
}

批量处理 ​

  • batch():批量 DML 执行。针对同一条预编译 DML 语句绑定二维参数数组 Object[][],底层循环调用 addBatch() 后一次性触发 executeBatch() 批量提交。

    • int[]:(Connection conn, String sql, Object[][] params),指定连接批量执行。在给定的 Connection 上批量执行预编译语句,返回每组参数受影响行数组成的 int[] 数组,不关闭传入的 Connection。
    • int[]:(String sql, Object[][] params),数据源批量执行。从绑定的 DataSource 获取连接完成批量提交,执行完毕后自动归还连接并返回每行受影响计数数组。
  • insertBatch():批量新增主键回填。针对 INSERT 语句执行二维参数数组批量写入,并将批量生成的所有自增主键封装为结果集交由 ResultSetHandler 转换返回。

    • <T> T:(Connection conn, String sql, ResultSetHandler<T> rsh, Object[][] params),指定连接批量新增回填。在给定的 Connection 上批量插入数据并提取生成的自增主键,不关闭传入的 Connection。
    • <T> T:(String sql, ResultSetHandler<T> rsh, Object[][] params),数据源批量新增回填。从绑定的 DataSource 获取连接执行批量插入,提取生成的自增主键后自动归还连接。

注意事项:

  1. 二维数组 Object[][] params 的第一维长度代表批处理执行的次数(行数),第二维长度必须与 SQL 模板中 ? 占位符的个数严格一致。
  2. 在 MySQL 环境下使用 batch() 或 insertBatch() 时,建议在 JDBC URL 中配置 rewriteBatchedStatements=true 以激活底层多值合并重写优化。
java
package com.hspedu.jdbc.dbutils;

import com.hspedu.jdbc.utils.JDBCUtilsByDruid;
import java.sql.Connection;
import java.util.Arrays;
import java.util.List;
import org.apache.commons.dbutils.QueryRunner;
import org.apache.commons.dbutils.handlers.ColumnListHandler;

public class QueryRunnerBatchDemo {

  public static void main(String[] args) throws Exception {
    QueryRunner qr = new QueryRunner();

    // 1. 构建二维参数数组,第一维代表批次行数,第二维代表每行的占位符参数值
    Object[][] batchParams = new Object[][]{
      {"Henry", 800.00},
      {"Ivy", 950.00},
      {"Jack", 1200.00}
    };

    try (Connection conn = JDBCUtilsByDruid.getConnection()) {
      // 2. 调用 batch 批量执行 DML 语句,返回每行受影响行数组成的整型数组
      String sql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
      int[] affectedCounts = qr.batch(conn, sql, batchParams);
      System.out.println("批量插入受影响行数: " + Arrays.toString(affectedCounts));

      // 3. 调用 insertBatch 批量插入并通过 ColumnListHandler 提取所有生成的自增主键集合
      List<Object> generatedIds = qr.insertBatch(conn, sql, new ColumnListHandler<>(1), batchParams);
      System.out.println("批量生成的自增主键列表: " + generatedIds);
    }
  }
}

继承: AbstractQueryRunner ​

close, close, closeQuietly, closeQuietly, closeQuietly, closeQuietly, fillStatement, fillStatementWithBean, fillStatementWithBean, getDataSource, isPmdKnownBroken, prepareCall, prepareConnection, prepareStatement, prepareStatement, rethrow, wrap

API: ResultSetHandler ​

结果集转换 ​

  • T handle():(ResultSet rs),结果集对象转换。将传入的 ResultSet 结果集游标数据解析并转换为目标泛型类型 T 的对象实例返回;若结果集无匹配记录,通常返回 null 或空集合。

注意事项:

  1. handle 方法接收到的 ResultSet 游标初始位于第一行数据之前(Before First),在自定义实现中读取列数据前必须先调用 rs.next() 推进游标。
  2. 实现 handle 方法时无需在方法内部手动关闭传入的 ResultSet,QueryRunner 会在 handle 执行完毕后的 finally 代码块中自动关闭该结果集。
  3. ResultSetHandler<T> 仅包含一个抽象方法,在 JDK 8 及以上环境中除使用内置实现类(如 BeanHandler、BeanListHandler、ScalarHandler)外,还可直接通过 Lambda 表达式定制轻量级转换逻辑。
java
package com.hspedu.jdbc.dbutils;

import com.hspedu.jdbc.domain.User;
import com.hspedu.jdbc.utils.JDBCUtilsByDruid;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLException;
import org.apache.commons.dbutils.QueryRunner;
import org.apache.commons.dbutils.ResultSetHandler;

public class ResultSetHandlerDemo {

  public static void main(String[] args) throws Exception {
    QueryRunner qr = new QueryRunner();
    String sql = "SELECT id, username, balance FROM t_user WHERE id = ?";

    // 1. 匿名内部类实现 ResultSetHandler 接口,重写 handle 方法自定义结果集封装逻辑
    ResultSetHandler<User> customHandler = new ResultSetHandler<User>() {
      @Override
      public User handle(ResultSet rs) throws SQLException {
        // 2. 推进游标至首行有效记录,提取列数据并组装为 User 实例返回
        if (rs.next()) {
          return new User(
              rs.getInt("id"),
              rs.getString("username"),
              rs.getDouble("balance")
          );
        }
        return null;
      }
    };

    try (Connection conn = JDBCUtilsByDruid.getConnection()) {
      // 3. 将自定义 ResultSetHandler 传入 QueryRunner,底层自动回调 handle 方法完成转换
      User user = qr.query(conn, sql, customHandler, 1);
      System.out.println("自定义处理器转换结果: " + user);

      // 4. 直接调用处理器实例的 handle 方法可对任意原生 ResultSet 执行独立转换
      try (ResultSet rawRs = conn.prepareStatement("SELECT id, username, balance FROM t_user LIMIT 1").executeQuery()) {
        User directUser = customHandler.handle(rawRs);
        System.out.println("直接调用 handle 转换结果: " + directUser);
      }
    }
  }
}

BasicDAO 封装 ​

实现 BasicDAO 封装 ​

为了避免在每个业务模块中重复创建 QueryRunner、重复从 JDBCUtilsByDruid 获取和归还连接,可以将 Apache DBUtils 与 Druid 工具类融合封装为一个通用的泛型基类 BasicDAO<T>。

BasicDAO<T> 针对增删改查封装了四个标准模板方法:

  1. update:接收任意 DML 语句(INSERT、UPDATE、DELETE)与可变参数列表,返回受影响的行数。

  2. queryMulti:接收查询语句与目标实体类 Class<T>,内部绑定 BeanListHandler<T>,返回多行实体列表 List<T>。

  3. querySingle:接收查询语句与目标实体类 Class<T>,内部绑定 BeanHandler<T>,返回单行实体对象 T。

  4. queryScalar:接收查询语句,内部绑定 ScalarHandler,返回单行单列标量结果 Object。

image-20261109182142433

image-20261113141139769

以下为结合 JDBCUtilsByDruid 实现的 BasicDAO<T> 完整代码:

java
package com.example.dao;

import com.example.pool.JDBCUtilsByDruid;
import org.apache.commons.dbutils.QueryRunner;
import org.apache.commons.dbutils.handlers.BeanHandler;
import org.apache.commons.dbutils.handlers.BeanListHandler;
import org.apache.commons.dbutils.handlers.ScalarHandler;
import java.sql.Connection;
import java.sql.SQLException;
import java.util.List;

// 1. 定义泛型通用数据访问基类,封装基于 DBUtils 与 Druid 的 CRUD 操作
public class BasicDAO<T> {

  // 2. 维护 Apache DBUtils 的核心 SQL 执行器实例
  private final QueryRunner queryRunner = new QueryRunner();

  // 3. 通用 DML 更新方法,支持所有数据表的 INSERT、UPDATE、DELETE 操作
  public int update(String sql, Object... parameters) {
    Connection connection = null;
    try {
      connection = JDBCUtilsByDruid.getConnection();
      return queryRunner.update(connection, sql, parameters);
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      JDBCUtilsByDruid.close(null, null, connection);
    }
  }

  // 4. 通用多行查询方法,使用 BeanListHandler 将结果集封装为实体对象集合
  public List<T> queryMulti(String sql, Class<T> clazz, Object... parameters) {
    Connection connection = null;
    try {
      connection = JDBCUtilsByDruid.getConnection();
      return queryRunner.query(connection, sql, new BeanListHandler<>(clazz), parameters);
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      JDBCUtilsByDruid.close(null, null, connection);
    }
  }

  // 5. 通用单行查询方法,使用 BeanHandler 将单条记录封装为单个实体对象
  public T querySingle(String sql, Class<T> clazz, Object... parameters) {
    Connection connection = null;
    try {
      connection = JDBCUtilsByDruid.getConnection();
      return queryRunner.query(connection, sql, new BeanHandler<>(clazz), parameters);
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      JDBCUtilsByDruid.close(null, null, connection);
    }
  }

  // 6. 通用单值查询方法,使用 ScalarHandler 提取首行首列的标量数据(如聚合统计)
  public Object queryScalar(String sql, Object... parameters) {
    Connection connection = null;
    try {
      connection = JDBCUtilsByDruid.getConnection();
      return queryRunner.query(connection, sql, new ScalarHandler<>(), parameters);
    } catch (SQLException e) {
      throw new RuntimeException(e);
    } finally {
      JDBCUtilsByDruid.close(null, null, connection);
    }
  }
}

业务 DAO 继承与调用 ​

完成 BasicDAO<T> 封装后,任何具体数据表的 DAO 类只需继承 BasicDAO<实体类>,即可直接复用全部通用增删改查方法,仅在存在复杂特有业务时才需额外编写专属方法。

实体类定义 ​

首先定义与数据库 actor 表字段一一对应的 Actor 实体类(务必保留公共无参构造器):

java
package com.example.entity;

import java.util.Date;

// 1. 定义与数据库 actor 表结构对应的 JavaBean 实体类
public class Actor {

  private Integer id;
  private String name;
  private String sex;
  private Date borndate;
  private String phone;

  // 2. 必须提供公共无参构造器,供 DBUtils 底层通过反射实例化对象
  public Actor() {
  }

  // 3. 提供 Getter 与 Setter 方法,属性名需与数据库列名(或别名)保持一致
  public Integer getId() { return id; }
  public void setId(Integer id) { this.id = id; }
  public String getName() { return name; }
  public void setName(String name) { this.name = name; }
  public String getSex() { return sex; }
  public void setSex(String sex) { this.sex = sex; }
  public Date getBorndate() { return borndate; }
  public void setBorndate(Date borndate) { this.borndate = borndate; }
  public String getPhone() { return phone; }
  public void setPhone(String phone) { this.phone = phone; }

  @Override
  public String toString() {
    return "Actor{id=" + id + ", name='" + name + "', sex='" + sex + "', phone='" + phone + "'}";
  }
}

子类继承与测试 ​

随后创建 ActorDAO 继承 BasicDAO<Actor>,直接调用父类封装的四个模板方法完成全套数据访问操作:

java
package com.example.dao;

import com.example.entity.Actor;
import java.util.List;

// 1. 继承通用 BasicDAO 并指定泛型为 Actor,自动获得全部基础 CRUD 能力
public class ActorDAO extends BasicDAO<Actor> {

  // 2. 演示调用继承自 BasicDAO 的多行查询、单行查询、单值查询与 DML 更新
  public static void main(String[] args) {
    ActorDAO actorDAO = new ActorDAO();

    // 3. 查询多行记录并自动映射为 List<Actor> 集合
    String multiSql = "SELECT id, name, sex, borndate, phone FROM actor WHERE id >= ?";
    List<Actor> actors = actorDAO.queryMulti(multiSql, Actor.class, 1);
    actors.forEach(System.out::println);

    // 4. 查询单行记录并自动映射为单个 Actor 实体
    String singleSql = "SELECT id, name, sex, borndate, phone FROM actor WHERE id = ?";
    Actor actor = actorDAO.querySingle(singleSql, Actor.class, 1);
    System.out.println("单行查询结果: " + actor);

    // 5. 查询单行单列标量值(统计总记录数)
    String scalarSql = "SELECT COUNT(*) FROM actor";
    Object count = actorDAO.queryScalar(scalarSql);
    System.out.println("总记录数: " + count);

    // 6. 执行 DML 更新操作并返回受影响行数
    String updateSql = "UPDATE actor SET phone = ? WHERE id = ?";
    int affectedRows = actorDAO.update(updateSql, "13800138000", 1);
    System.out.println("更新受影响行数: " + affectedRows);
  }
}