JdbcTemplate 设计与模板方法模式

敖正炀
3 阅读29分钟

概述

前文《Spring 数据访问异常体系》深入剖析了 Spring 如何通过 DataAccessException 体系，将异构持久化技术（JDBC、Hibernate、MyBatis 等）产生的受检异常统一翻译为语义丰富、层次分明的非受检异常。在这套异常体系的消费者中，JdbcTemplate 无疑是最直接且最经典的实现。当你调用 jdbcTemplate.query(...) 时，框架内部已经悄然捕获了 JDBC 层抛出的 SQLException，并通过 SQLExceptionTranslator 精准地翻译为 DataAccessException 的某个子类（如 DataIntegrityViolationException、CannotGetJdbcConnectionException）。与此同时，数据库连接的获取、语句的创建、资源的释放这些繁琐且容易出错的操作，也被 JdbcTemplate 尽数封装，开发者的视线里只剩下与业务逻辑最相关的 SQL、参数与结果映射。

这一切复杂的简化，其架构核心正是模板方法模式（Template Method Pattern）的完美演绎：JdbcTemplate 在其 execute、query、update 等核心方法中，定义了一套牢不可破的 JDBC 操作骨架——获取连接、创建声明、执行回调、翻译异常、释放资源，而将“SQL 语句的定义”、“参数的设定”、“结果集的映射”这些变化多端的步骤，延迟到用户自定义的回调接口中实现。本文将带您深入 JdbcTemplate 的源码腹地，剖析这段骨架中的每一个关节，并结合 DataSourceUtils、JdbcUtils 等 Spring 内部工具类，揭示这套设计背后关于资源管理、异常翻译、线程安全与事务协同的深层次工程智慧。

核心要点：

  • 模板方法骨架：execute 方法定义的 JDBC 标准流程——获取连接、创建语句、执行、释放资源。
  • 回调接口体系：ConnectionCallback、PreparedStatementCallback、RowMapper、ResultSetExtractor 各司其职。
  • 资源管理的封装：DataSourceUtils 对事务上下文连接的感知，JdbcUtils 的安全关闭。
  • 异常自动翻译：SQLException 在骨架内部被统一转换为 DataAccessException。
  • 设计模式：模板方法、回调（策略）、不可变对象、适配器的完美协作。

文章组织架构图如下：

flowchart TB
    subgraph S1 ["1. JdbcTemplate 总览"]
        A["从 JDBC 原生代码到模板方法"]
    end
    subgraph S2 ["2. 核心骨架：execute 与模板方法模式"]
        B["execute 方法完整拆解"]
    end
    subgraph S3 ["3. 回调接口体系与结果映射"]
        C["ConnectionCallback/RowMapper/ResultSetExtractor"]
    end
    subgraph S4 ["4. 资源管理的精髓"]
        D["DataSourceUtils 与 JdbcUtils 源码剖析"]
    end
    subgraph S5 ["5. 异常翻译与线程安全设计"]
        E["SQLExceptionTranslator 集成与不可变状态"]
    end
    subgraph S6 ["6. 批处理、分页与命名参数"]
        F["batchUpdate/NamedParameterJdbcTemplate"]
    end
    subgraph S7 ["7. 与 Spring 事务管理器的协同"]
        G["事务上下文连接共享"]
    end
    subgraph S8 ["8. 设计模式总结与工程实践"]
        H["模板方法/回调/策略/适配器"]
    end
    subgraph S9 ["9. 生产事故排查专题"]
        I["连接泄漏与回调异常处理"]
    end
    subgraph S10 ["10. 面试高频专题"]
        J["12 道深度面试题"]
    end

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10

    classDef topic fill:#f8f9fa,stroke:#333,stroke-width:2px,rx:5,color:#333;
    class S1,S2,S3,S4,S5,S6,S7,S8,S9,S10 topic;

架构图说明：

  • 总览说明：全文 10 个模块严格遵循认知递进路径。从原生 JDBC 的痛点切入，引出 JdbcTemplate 作为解决方案。随后深入到核心骨架 execute 方法，展示模板方法模式的代码体现。接着展开回调接口体系与资源管理的具体实现，再探讨其异常翻译机制与线程安全设计。在夯实基础后，扩展到批处理、命名参数等高级特性，并与 Spring 事务管理器进行协作演示。最后通过设计模式总结、生产事故排查与高频面试题，完成从理论到实践的闭环。
  • 逐模块说明：模块 1-3 构建 JdbcTemplate 的核心运行模型，让读者理解模板方法与回调如何协作；模块 4-5 揭示了 JdbcTemplate 在背后所做的资源管理和异常处理，这是其健壮性的根基；模块 6-7 展示了其功能扩展与和企业级事务机制的整合；模块 8 从设计模式高度进行抽象总结；模块 9-10 则关照现实开发中的雷区与面试场景，确保知识落地。
  • 关键结论：JdbcTemplate 的精髓在于“将不变的部分（资源管理、异常处理）封装在模板方法中，将变化的部分（SQL、参数、结果映射）暴露为回调接口”，这是 Spring JDBC 封装中最经典且最具教学意义的模板方法模式应用。

1. JdbcTemplate 总览：从 JDBC 原生代码到模板方法

1.1 原生 JDBC 编程的灾难

在直接使用 JDBC API 进行数据访问时，开发者会立即陷入一种僵硬的固定模式。即使是执行一条最简单的查询，也需要编写大量模版化的代码：

// 原生 JDBC 查询示例
public User getUserByIdNative(Connection con, Long id) {
    PreparedStatement ps = null;
    ResultSet rs = null;
    try {
        ps = con.prepareStatement("SELECT id, name, email FROM users WHERE id = ?");
        ps.setLong(1, id);
        rs = ps.executeQuery();
        if (rs.next()) {
            User user = new User();
            user.setId(rs.getLong("id"));
            user.setName(rs.getString("name"));
            user.setEmail(rs.getString("email"));
            return user;
        }
        return null;
    } catch (SQLException e) {
        // 必须处理或包装异常
        throw new RuntimeException(e);
    } finally {
        // 必须按顺序关闭资源，否则会导致连接泄漏
        try { if (rs != null) rs.close(); } catch (SQLException e) { /* 忽略 */ }
        try { if (ps != null) ps.close(); } catch (SQLException e) { /* 忽略 */ }
        // 注意：连接通常由外部传入，此处不能关闭
    }
}

这段代码暴露了原生 JDBC 的四大核心痛点：

  1. 资源管理复杂且易错：Connection、Statement、ResultSet 都需要在 finally 块中依次显式关闭，且每个 close() 都会抛出 SQLException，导致关闭代码层层嵌套。
  2. 受检异常处理繁琐：SQLException 是受检异常，必须捕获或抛出，这侵蚀了业务逻辑的清晰度。
  3. 重复的样板代码：任何数据库操作几乎都需要重复上述流程，违反了 DRY 原则。
  4. 连接生命周期难以控制：连接从何处获取、如何归还、在事务中如何保证使用同一连接，这些问题的正确处理需要对 JDBC 和事务有深入理解。

1.2 模板方法模式的救赎

JdbcTemplate 正是为了消除这些痛点而生。它运用模板方法模式，将上述代码中的通用流程固化为一个算法骨架，而把变化的步骤——如 SQL 语句、参数设定、结果映射——抽象为回调接口，交由用户实现。核心思想如下：

  • 不变的骨架：获取连接、准备语句、执行、异常捕获与翻译、资源释放。这部分永远由 JdbcTemplate 控制。
  • 变化的回调：具体的 SQL 字符串、PreparedStatement 的参数设置、ResultSet 的行映射逻辑。这些由开发者在回调对象中提供。
// 使用 JdbcTemplate 的等效代码
jdbcTemplate.queryForObject(
    "SELECT id, name, email FROM users WHERE id = ?",
    (rs, rowNum) -> new User(rs.getLong("id"), rs.getString("name"), rs.getString("email")),
    userId
);

代码量急剧减少，且无需关心任何资源释放。这正是模板方法模式“好莱坞原则”——“Don't call us, we'll call you”的生动体现。框架决定何时调用你的映射代码，并保证在前后完成所有资源管理工作。

1.3 JdbcTemplate 的核心定位与类关系

在 Spring JDBC 模块中，JdbcTemplate 是接口 JdbcOperations 的核心实现。JdbcOperations 定义了丰富的数据库操作方法，包括 execute、query、queryForObject、update 等。而 JdbcTemplate 通过组合一个 DataSource，并利用一系列内部回调接口和工具类，完成了对所有操作的实现。其核心类关系如下图所示：

classDiagram
    class JdbcOperations {
        <<interface>>
        +execute(ConnectionCallback~T~) T
        +query(String, RowMapper~T~) List~T~
        +update(String) int
    }
    
    class JdbcAccessor {
        #DataSource dataSource
        #SQLExceptionTranslator exceptionTranslator
        +setDataSource(DataSource)
        +getExceptionTranslator() SQLExceptionTranslator
    }
    
    class JdbcTemplate {
        -boolean lazyInit
        +execute(ConnectionCallback~T~) T
        +query(PreparedStatementCreator, PreparedStatementSetter, ResultSetExtractor~T~) T
    }
    
    class DataSource {
        <<interface>>
        +getConnection() Connection
    }
    
    class SQLExceptionTranslator {
        <<interface>>
        +translate(String, String, SQLException) DataAccessException
    }
    
    class SQLErrorCodeSQLExceptionTranslator {
        +customizeTranslations()
    }
    
    class DataSourceUtils {
        +getConnection(DataSource) Connection
        +releaseConnection(Connection, DataSource)
    }
    
    class JdbcUtils {
        +closeStatement(Statement)
        +closeResultSet(ResultSet)
    }
    
    JdbcOperations <|.. JdbcTemplate : 实现
    JdbcAccessor <|-- JdbcTemplate : 继承
    JdbcTemplate o-- DataSource : 依赖
    JdbcTemplate o-- SQLExceptionTranslator : 使用
    DataSourceUtils ..> DataSource : 获取连接
    JdbcTemplate ..> DataSourceUtils : 静态调用
    JdbcTemplate ..> JdbcUtils : 静态调用
    SQLExceptionTranslator <|.. SQLErrorCodeSQLExceptionTranslator : 默认实现

图 1 说明：

  • 继承体系：JdbcTemplate 继承自 JdbcAccessor，后者提供了对 DataSource 和 SQLExceptionTranslator 的统一配置与管理。同时实现了 JdbcOperations 接口，面向接口编程。
  • 核心依赖：JdbcTemplate 组合了 DataSource，但不直接管理物理连接的获取/释放，而是委托给 DataSourceUtils 这一辅助类，以感知当前线程的事务上下文。
  • 资源管理：JdbcUtils 提供了一组静态方法，专门用于安全地关闭 Statement、ResultSet、Connection，屏蔽了关闭时的检查异常。
  • 异常翻译：持有 SQLExceptionTranslator 接口的引用，默认使用从 sql-error-codes.xml 中读取映射规则的 SQLErrorCodeSQLExceptionTranslator，将 SQLException 转换为前文所讲的 DataAccessException 层次结构。

2. 核心骨架：execute 方法与模板方法模式

2.1 模板方法骨架入口：execute(ConnectionCallback)

所有 JdbcTemplate 的数据库操作，无论是 query、update 还是 batchUpdate，最终都会调用到以下核心私有方法（实际是 execute 的各个重载版本）。我们以最通用、最能体现模板方法思想的 public <T> T execute(ConnectionCallback<T> action) 为例，深度拆解其源码。

源码片段 1：org.springframework.jdbc.core.JdbcTemplate.execute(ConnectionCallback<T> action)

// org.springframework.jdbc.core.JdbcTemplate
@Override
public <T> T execute(ConnectionCallback<T> action) throws DataAccessException {
    Assert.notNull(action, "Callback object must not be null");

    // 1. 获取连接：通过 DataSourceUtils 以获得事务感知能力
    Connection con = DataSourceUtils.getConnection(obtainDataSource());
    
    try {
        // 2. 创建连接的代理（如果需要），以便控制 close 行为
        Connection conToUse = createConnectionProxy(con);
        // 3. 执行用户定义的回调逻辑，将连接传递给用户
        return action.doInConnection(conToUse);
    }
    catch (SQLException ex) {
        // 4. 异常翻译：将 SQLException 转换为 DataAccessException 并抛出
        throw translateException("ConnectionCallback", getSql(action), ex);
    }
    finally {
        // 5. 释放连接：借由 DataSourceUtils 以处理事务环境下的连接
        DataSourceUtils.releaseConnection(con, getDataSource());
    }
}

这段代码完美诠释了模板方法模式的骨架定式：

  • 步骤 1 (连接获取)：DataSourceUtils.getConnection(obtainDataSource())。这里没有直接调用 dataSource.getConnection()，而是通过 DataSourceUtils 从当前线程的事务同步管理器中获取可能已绑定的连接（详见模块 4）。
  • 步骤 2 (连接代理)：createConnectionProxy(con)。当连接需要被代理（例如，通过 LazyConnectionDataSourceProxy 或需要对 close 调用进行拦截时），此步骤返回一个代理连接，确保即使回调内部关闭了连接，物理连接也不会被实际关闭。
  • 步骤 3 (回调执行)：action.doInConnection(conToUse)。这是模板方法中唯一留给用户实现的部分，即“变化的步骤”。用户在一个已经正确获取并可用的连接上下文里执行业务操作。
  • 步骤 4 (异常翻译)：catch (SQLException ex) 块调用 translateException，利用 SQLExceptionTranslator 将受检异常转换为 Spring 的 DataAccessException 层次结构（详见模块 5 及前文异常体系篇）。
  • 步骤 5 (资源释放)：finally 块确保无论如何，连接都会被释放。DataSourceUtils.releaseConnection 会判断当前是否处于事务中，如果是则不清真关闭，而是减少引用计数或留待事务完成时处理；否则关闭物理连接（详见模块 4）。

这是典型的模板方法模式：算法骨架由 JdbcTemplate 定义，不能被覆写；具体步骤中的“连接使用”通过回调接口 ConnectionCallback 延迟给用户。骨架确保了资源一定会被安全释放、异常一定会被正确翻译，完全弥合了原生 JDBC 编程中的陷阱。

2.2 query 方法的骨架扩展

query 方法展现了模板方法模式的进一步细化。它不仅使用了 ConnectionCallback，在内部还嵌套使用了 StatementCallback 或 PreparedStatementCallback，将“创建语句”、“设置参数”、“执行并提取结果”也作为骨架流程。

源码片段 2：org.springframework.jdbc.core.JdbcTemplate.query 的核心执行逻辑

// org.springframework.jdbc.core.JdbcTemplate (简化)
@Override
public <T> T query(
        PreparedStatementCreator psc, final PreparedStatementSetter pss,
        final ResultSetExtractor<T> rse) throws DataAccessException {

    Assert.notNull(rse, "ResultSetExtractor must not be null");

    return execute(psc, new PreparedStatementCallback<T>() {
        @Override
        public T doInPreparedStatement(PreparedStatement ps) throws SQLException {
            ResultSet rs = null;
            try {
                if (pss != null) {
                    pss.setValues(ps);
                }
                rs = ps.executeQuery();
                return rse.extractData(rs);
            }
            finally {
                JdbcUtils.closeResultSet(rs);
            }
        }
    });
}

这里的 execute(psc, action) 是另一个重载，内部骨架流程为：通过 psc 创建 PreparedStatement，执行 action.doInPreparedStatement(ps)，最后在 finally 中关闭 Statement。可以看到，在 doInPreparedStatement 回调内部，又进一步固化了“设置参数 → 执行查询 → 关闭 ResultSet”的子骨架，而将结果集的提取逻辑交给 ResultSetExtractor 回调。层层嵌套的模板方法与回调组合，使得每一层的关注点彻底分离。

execute 方法模板方法模式骨架序列图如下：

sequenceDiagram
    participant Client as 客户端代码
    participant JdbcT as JdbcTemplate
    participant DSU as DataSourceUtils
    participant DS as DataSource
    participant Conn as Connection
    participant Action as ConnectionCallback
    participant Trans as SQLExceptionTranslator

    Client->>JdbcT: execute(ConnectionCallback)
    JdbcT->>DSU: getConnection(obtainDataSource())
    DSU->>DS: 检查事务同步/创建新连接
    DS-->>DSU: Connection
    DSU-->>JdbcT: 返回 Connection (可能为代理)
    JdbcT->>JdbcT: createConnectionProxy(con) (可选)
    JdbcT->>Action: doInConnection(conToUse)
    Action-->>Action: 用户自定义逻辑 (如创建 Statement)
    Action-->>JdbcT: 返回结果 T 或抛出 SQLException
    alt 发生 SQLException
        JdbcT->>Trans: translateException(task, sql, ex)
        Trans-->>JdbcT: DataAccessException 子类
        JdbcT-->>Client: 抛出 DataAccessException
    else 正常返回
        JdbcT->>DSU: releaseConnection(con, ds)
        DSU->>Conn: 判断事务状态，关闭或归还
        JdbcT-->>Client: 返回 T
    end

图 2 说明：

  • 启动：客户端调用 execute，并传入一个 ConnectionCallback 实现。
  • 获取连接：JdbcTemplate 委托 DataSourceUtils 获取连接，DataSourceUtils 会检查当前线程是否有事务绑定的连接。
  • 代理与调用：可能对连接进行代理包装，然后回调用户逻辑。
  • 异常路径：任何在 doInConnection 内部抛出的 SQLException 都会被捕获，并通过 SQLExceptionTranslator 翻译为 DataAccessException 再抛出。
  • 资源清理：finally 块中通过 DataSourceUtils.releaseConnection 保证连接最终被合理处理（实际关闭或归还事务管理器）。整个流程确保用户无需关心任何清理细节。

3. 回调接口体系与结果映射

JdbcTemplate 的强大之处在于提供了一套完备的回调接口，将各种变化维度独立抽象，使得用户可以按需选择最适合的回调粒度。这些接口构成了一个层次分明、职责清晰的回调体系。

3.1 核心回调接口的层次与职责

  • ConnectionCallback<T>：粒度最粗的回调。用户拿到一个 Connection，可以在其上做任何 JDBC 操作（创建多个 Statement，控制事务等）。适用于需要在单个连接上执行复杂多步操作的场景，但同时用户需自行负责 Statement 和 ResultSet 的关闭（虽然连接最终会被 JdbcTemplate 释放）。
  • StatementCallback<T>：用户收到一个已经创建好的 Statement，只需执行 SQL 并处理结果。Statement 的生命周期由框架管理。
  • PreparedStatementCallback<T>：与 StatementCallback 类似，但收到的是 PreparedStatement，适合需要设置参数的预编译 SQL。它是使用最频繁的回调。
  • CallableStatementCallback<T>：专门用于处理存储过程的回调。
  • RowMapper<T>：行映射接口。它是结果映射中最常用的策略，负责将 ResultSet 的当前行映射为一个领域对象，JdbcTemplate 会迭代所有行并调用此接口。
  • ResultSetExtractor<T>：结果集提取器。它将整个 ResultSet 交给用户处理，用户可以自由地遍历、聚合数据，返回一个复合结果。适用于需要将整个结果集处理为单一对象（如求和、统计）或复杂嵌套结构的场景。
  • RowCallbackHandler：纯流式行处理器。无返回值，处理每一行，常用于将大批量数据分段写入文件或消息队列，避免 OOM。

3.2 RowMapper vs ResultSetExtractor：策略的分野

这两个接口体现了策略模式：它们都是“映射结果集”这一变化维度的不同算法策略。

RowMapper 内部实现的是无状态的映射函数：T mapRow(ResultSet rs, int rowNum) throws SQLException。它的职责仅限于当前行，不关心整体的 ResultSet 遍历。JdbcTemplate 的 query 方法会封装对 ResultSet.next() 的循环调用，并将每一行交给 RowMapper 处理，最终收集为 List<T> 返回。这是面向“记录列表”的场景。

ResultSetExtractor 则要求用户完全控制遍历过程：T extractData(ResultSet rs) throws SQLException。用户在一个回调中收到整个 ResultSet，可以执行复杂的逻辑，比如将多张表的数据处理为一棵树、或者边遍历边聚合而无需在中途保存所有对象。这是面向“自定义聚合”的场景。

RowMapper 与 ResultSetExtractor 协作序列图如下：

sequenceDiagram
    participant JdbcT as JdbcTemplate
    participant PSC as PreparedStatementCreator
    participant PSS as PreparedStatementSetter
    participant RM as RowMapper
    participant RSE as ResultSetExtractor
    participant RS as ResultSet

    Note over JdbcT: query(String sql, RowMapper, args) 内部转换为
    JdbcT->>JdbcT: 构造 PreparedStatementCreator 和 PreparedStatementSetter
    JdbcT->>JdbcT: execute(psc, new PreparedStatementCallback() { ... })
    JdbcT->>PSC: createPreparedStatement(con)
    PSC-->>JdbcT: PreparedStatement
    JdbcT->>PSS: setValues(ps)
    PSS-->>JdbcT: 
    JdbcT->>RS: ps.executeQuery()
    RS-->>JdbcT: ResultSet
    JdbcT->>RSE: "extractData(rs) (如果直接使用 ResultSetExtractor)"
    RSE->>RS: "while(rs.next())"
    RS-->>RSE: true/false
    RSE->>RM: "mapRow(rs, rowNum)"
    RM-->>RSE: User
    RSE-->>JdbcT: "返回 List 结果"
    JdbcT->>JdbcUtils: closeResultSet(rs)
    JdbcT->>JdbcUtils: closeStatement(ps)

图 3 说明：

  • 当用户调用 query(sql, rowMapper, args) 时，JdbcTemplate 内部会创建 PreparedStatementCreator 和 PreparedStatementSetter，将 SQL 和参数封装起来。
  • 在 PreparedStatementCallback 的骨架中，先通过设置器绑定参数，然后执行查询返回 ResultSet。
  • 如果用户传入的是 RowMapper，JdbcTemplate 会匿名创建一个 ResultSetExtractor 实现，该实现内部循环遍历 ResultSet，并为每一行调用 RowMapper.mapRow()。这一策略模式的协作使得用户只需关注单行映射。
  • 最终，ResultSet 和 Statement 由 JdbcUtils 在 finally 块中安全关闭，整个过程对用户透明。

3.3 回调组合实战示例

下面的代码对比了不同回调接口的使用场景：

// 示例1: RowMapper 用于典型的列表查询
List<User> users = jdbcTemplate.query(
    "SELECT id, name FROM users WHERE status = ?",
    (rs, rowNum) -> new User(rs.getLong("id"), rs.getString("name")),
    "ACTIVE"
);

// 示例2: ResultSetExtractor 用于自定义聚合（如计算总和与最大值）
Integer totalAge = jdbcTemplate.query(
    "SELECT age FROM users",
    (ResultSetExtractor<Integer>) rs -> {
        int sum = 0;
        while (rs.next()) {
            sum += rs.getInt("age");
        }
        return sum;
    }
);

// 示例3: RowCallbackHandler 用于流式写入文件（避免大集合占用内存）
jdbcTemplate.query(
    "SELECT id, data FROM large_table",
    (RowCallbackHandler) rs -> {
        // 将 rs 的当前行内容写入文件输出流
        writeToFile(rs.getLong("id"), rs.getString("data"));
    }
);

这三种方式清晰地展示了如何根据不同的业务需求选择最合适的回调策略。

4. 资源管理的精髓：DataSourceUtils 与 JdbcUtils

资源的安全管理是 JdbcTemplate 健壮性的基石。Spring 将连接获取/释放的复杂性抽离到 DataSourceUtils，将关闭操作的冗余消除在 JdbcUtils 中。

4.1 DataSourceUtils：事务感知的连接管理

DataSourceUtils.getConnection(DataSource dataSource) 是连接获取的唯一入口。它不仅仅是简单的 ds.getConnection()，还会检查当前线程是否已经处于 Spring 管理的事务中。

源码片段 3：org.springframework.jdbc.datasource.DataSourceUtils.getConnection 核心逻辑

// org.springframework.jdbc.datasource.DataSourceUtils
public static Connection getConnection(DataSource dataSource) throws CannotGetJdbcConnectionException {
    // 1. 从事务同步管理器中获取当前线程绑定的连接资源
    ConnectionHolder conHolder = (ConnectionHolder) TransactionSynchronizationManager.getResource(dataSource);
    if (conHolder != null && conHolder.hasConnection()) {
        // 2. 如果已存在绑定的连接，直接返回该连接
        return conHolder.getConnection();
    }
    // 3. 否则，从数据源获取新的物理连接
    Connection con = fetchConnection(dataSource);
    // 4. 如果当前线程有活动事务同步，则将新连接绑定到当前线程
    if (TransactionSynchronizationManager.isSynchronizationActive()) {
        ConnectionHolder holderToUse = conHolder;
        if (holderToUse == null) {
            holderToUse = new ConnectionHolder(con);
        }
        // 增加引用计数
        holderToUse.requested();
        TransactionSynchronizationManager.bindResource(dataSource, holderToUse);
        // ... 注册事务同步回调，以便在事务完成时释放连接
    }
    return con;
}

这段逻辑揭示了 JdbcTemplate 与 Spring 事务管理器协同的核心机制：

  • 事务场景：当 @Transactional 开启事务后，TransactionSynchronizationManager 会激活事务同步，并将一个 ConnectionHolder 绑定到当前线程。此后对同一 DataSource 的 getConnection 调用将返回完全相同的物理连接，保证了同一事务内的所有数据库操作共享连接。连接的实际关闭将推迟到事务完成时进行（提交或回滚后）。
  • 非事务场景：若无活动事务，则每次调用都会获取新的连接，并在 JdbcTemplate 回调完成后，通过 releaseConnection 立即关闭，归还给连接池。

这种设计使得 JdbcTemplate 无需关心是否处于事务中，它永远只问 DataSourceUtils 要连接，并用完后调用其 releaseConnection 方法即可。

DataSourceUtils 获取事务感知连接序列图：

sequenceDiagram
    participant JdbcT as JdbcTemplate
    participant DSU as DataSourceUtils
    participant TSM as TransactionSynchronizationManager
    participant DS as DataSource
    participant Conn as Connection

    JdbcT->>DSU: getConnection(dataSource)
    DSU->>TSM: getResource(dataSource)
    alt 当前线程已存在事务绑定连接
        TSM-->>DSU: ConnectionHolder (含 Connection)
        DSU->>DSU: conHolder.getConnection()
        DSU-->>JdbcT: 返回绑定连接 (共享连接)
    else 无事务绑定
        DSU->>DS: getConnection()
        DS-->>DSU: 物理 Connection
        DSU->>TSM: 若有活动事务同步，bindResource
        DSU-->>JdbcT: 返回新连接
    end
    Note over JdbcT, Conn: 执行业务逻辑...
    JdbcT->>DSU: releaseConnection(con, dataSource)
    DSU->>TSM: 检查连接绑定及引用计数
    alt 非事务或引用计数归零
        DSU->>Conn: close() 归还连接池
    else 处在事务中
        DSU->>DSU: 解绑或计数减一，不关闭物理连接
    end

图 4 说明：

  • 分支处理：getConnection 首先检查 TransactionSynchronizationManager，无绑定时走创建逻辑，有绑定时直接复用。
  • 释放行为：releaseConnection 同样依赖事务同步状态决定是真实关闭连接还是单纯解绑/减计数。这使得连接的生命周期与事务边界完全对齐。

4.2 JdbcUtils：静默关闭的优雅实现

关闭 ResultSet、Statement、Connection 时若抛出 SQLException，会遮蔽可能发生的业务异常。JdbcUtils 提供了静默关闭方法，捕获所有 SQLException 并忽略，避免影响主流程。

源码片段 4：org.springframework.jdbc.support.JdbcUtils.closeResultSet

// org.springframework.jdbc.support.JdbcUtils
public static void closeResultSet(@Nullable ResultSet rs) {
    if (rs != null) {
        try {
            rs.close();
        }
        catch (SQLException ex) {
            logger.trace("Could not close JDBC ResultSet", ex);
        }
        catch (Throwable ex) {
            // 不信任 JDBC 驱动程序，可能抛出 RuntimeException 或 Error
            logger.trace("Unexpected exception on closing JDBC ResultSet", ex);
        }
    }
}

类似的，closeStatement 和 closeConnection 都遵循相同模式。这保证了在 finally 块中执行清理时，任何关闭异常都不会被抛出，从而不会异常终止正常的异常处理流程。JdbcTemplate 的内部骨架大量使用这些方法，例如在 PreparedStatementCallback 执行后，无论成功与否，都会调用 JdbcUtils.closeResultSet(rs) 和 JdbcUtils.closeStatement(ps)。

5. 异常翻译与线程安全设计

5.1 SQLExceptionTranslator 的集成与应用

前文《Spring 数据访问异常体系》详细论述了 DataAccessException 层次结构及翻译器。在 JdbcTemplate 中，异常翻译通过私有方法 translateException 完成，并被植入模板方法骨架的 catch 块。

源码片段 5：org.springframework.jdbc.core.JdbcTemplate.translateException

// org.springframework.jdbc.core.JdbcTemplate
protected DataAccessException translateException(String task, @Nullable String sql, SQLException ex) {
    DataAccessException dae = getExceptionTranslator().translate(task, sql, ex);
    return (dae != null ? dae : new UncategorizedSQLException(task, sql, ex));
}

public SQLExceptionTranslator getExceptionTranslator() {
    SQLExceptionTranslator exceptionTranslator = getExceptionTranslatorFromProperty();
    if (exceptionTranslator != null) {
        return exceptionTranslator;
    }
    // 使用基于 SQL 错误码的翻译器
    return new SQLErrorCodeSQLExceptionTranslator(getDataSource());
}

JdbcTemplate 默认构造基于数据源的 SQLErrorCodeSQLExceptionTranslator，它会加载 sql-error-codes.xml 配置，根据数据库厂商错误码和 SQL 状态将 SQLException 映射为具体的 DataAccessException 子类，例如唯一约束违反映射为 DuplicateKeyException，连接失败映射为 CannotGetJdbcConnectionException。这一翻译过程对用户完全透明，开发者只需在代码中捕获 DataAccessException（如果需要）或依赖 Spring 的声明式异常处理即可。

5.2 线程安全设计：无状态的不可变配置

JdbcTemplate 的实例可以在多个线程间安全共享。其线程安全性源于其不可变状态设计：

  • 它在初始化后，其持有的核心依赖如 DataSource、SQLExceptionTranslator、maxRows、fetchSize 等，都是“配置项”。这些字段在对象构造后基本不会改变（除非通过 setter 重新配置，但这并非典型使用模式）。
  • 它的方法执行不依赖于任何实例级的可变状态。每个 execute 调用都从 DataSource 获取连接，并通过局部变量流转，不存在实例级别的累加器或上下文。
  • execute 方法内部的所有状态（如 Connection、Statement、ResultSet）都是方法级的局部变量，天然线程安全。

因此，Spring 推荐对于同一个数据源定义一个 JdbcTemplate Bean，并在所有 DAO 中注入复用，完全不必担心多线程并发访问的问题。

6. 批处理、分页与命名参数

6.1 批处理：batchUpdate 的原理

JdbcTemplate 对 JDBC 批处理提供了良好封装，通过 batchUpdate 方法支持两种模式。

模式一：BatchPreparedStatementSetter 适用于对同一条 SQL 执行多组参数值的批量操作。框架内部循环调用 setValues(ps, i) 设置第 i 组参数，然后调用 ps.addBatch()，最后统一执行 ps.executeBatch()，并返回每条 SQL 影响的行数数组。其骨架同样遵循模板方法：创建 Statement、循环设置参数并添加批处理、执行批处理、关闭 Statement。用户仅需提供批大小和参数设置逻辑。

示例：

int[] updateCounts = jdbcTemplate.batchUpdate(
    "INSERT INTO users (name, email) VALUES (?, ?)",
    new BatchPreparedStatementSetter() {
        public void setValues(PreparedStatement ps, int i) throws SQLException {
            User user = userList.get(i);
            ps.setString(1, user.getName());
            ps.setString(2, user.getEmail());
        }
        public int getBatchSize() {
            return userList.size();
        }
    });

模式二：PreparedStatementCreator + ParameterizedPreparedStatementSetter 可以配合 PreparedStatementCreator 直接拿到创建好的 PreparedStatement，并由 ParameterizedPreparedStatementSetter 对多组参数进行设置。这种模式不必持有全部参数值，可以由一个流式数据源驱动。

6.2 命名参数支持

NamedParameterJdbcTemplate 是对 JdbcTemplate 的包装，通过解析带命名参数的 SQL（如 SELECT * FROM users WHERE name = :name），使用 NamedParameterUtils 将其转换为带占位符的标准 JDBC SQL，并构建参数数组。内部仍然是委托给 JdbcTemplate 执行，本质上是 SQL 解析和参数映射的适配层。

6.3 分页支持

JdbcTemplate 本身不具备分页语义，但可以极方便地与数据库方言结合实现分页查询。通常配合 RowMapper 和带有 LIMIT/OFFSET 或 ROWNUM 的 SQL 片段来实现。这并非框架强制，而是留待用户组装。通过 PreparedStatementSetter 设置分页参数，即可达成。

7. 与 Spring 事务管理器的协同

JdbcTemplate 本身不控制事务边界的启停。它是事务的一个“参与者”，其与 Spring 事务管理器的协同完全通过 DataSourceUtils 和 TransactionSynchronizationManager 进行松耦合协作。

  • 非事务执行：没有 @Transactional 加持时，JdbcTemplate 的每个方法独立获取连接，执行完毕立即释放（归还池）。每次调用都是一个自动提交的独立事务（取决于连接的 autoCommit 设置）。
  • 事务执行：当 Spring 事务管理器（如 DataSourceTransactionManager）开启事务后，会通过 TransactionSynchronizationManager.bindResource 将连接绑定到当前线程。JdbcTemplate 内部通过 DataSourceUtils.getConnection 获取的正是这个绑定的连接。无论在一个事务性方法中调用多少次 JdbcTemplate 的查询或更新，都共享同一个物理连接，从而保证事务的原子性。连接的实际提交或回滚由事务管理器在切面中完成，JdbcTemplate 完全无感知。

此处的详细机制将在后续事务深度篇章中，结合 TransactionSynchronizationManager 和 AbstractPlatformTransactionManager 的源码进行展开，此处仅点到为止，明确 JdbcTemplate 的无侵入协同角色。

8. 设计模式总结与工程实践

8.1 设计模式的全景图

JdbcTemplate 是 Spring 框架中多种设计模式糅合的典范：

  1. 模板方法模式：

    • 应用：execute、query、update 方法体系。固化了“获取连接→准备→执行→翻译异常→释放资源”的骨架，将具体变化延迟到回调。
    • 效果：消除了重复代码，强制资源安全处理，将错误倾向降至最低。

  2. 回调模式（好莱坞原则）：

    • 应用：ConnectionCallback、PreparedStatementCallback 等接口。框架掌握控制权，适时调用用户代码。
    • 效果：实现控制反转，用户无需管理流程，只需实现片段逻辑。

  3. 策略模式：

    • 应用：RowMapper 与 ResultSetExtractor 是可互换的映射策略，SQLExceptionTranslator 是可替换的异常翻译策略。
    • 效果：可以在运行时根据场景选择不同的结果处理算法，或切换不同的异常映射逻辑。

  4. 适配器模式：

    • 应用：DataSourceUtils 对 DataSource 的适配。它将标准 DataSource 接口适配为能够感知 Spring 事务上下文的连接提供者。
    • 效果：使得 JdbcTemplate 可以透明地工作在事务/非事务环境。

  5. 单一职责：

    • JdbcTemplate 负责执行流程编排；DataSourceUtils 负责连接获取/释放策略；JdbcUtils 负责关闭操作；SQLExceptionTranslator 负责异常翻译。职责清晰，极易维护扩展。

8.2 工程实践：何时选择 JdbcTemplate

  • 适用场景：当需要执行简洁的 SQL 查询、ORM 框架过于重量级、需要精确控制 SQL 和映射时，JdbcTemplate 是最佳轻量级工具。它与 Spring 事务、连接池无缝集成，是编写 Repository/Dao 的直接选择。
  • 不适用场景：当对象与关系存在复杂继承、关联映射，或需要缓存、延迟加载等高级特性时，转向 Spring Data JPA 等 ORM 方案更合适。JdbcTemplate 可作为 ORM 的底层补充，执行原生 SQL 和批量操作。

9. 生产事故排查专题

9.1 连接泄漏：当自定义 ConnectionCallback 误关连接

事故描述：在自定义的 ConnectionCallback 内部，开发者调用了 connection.close()，原本期望释放连接。但 JdbcTemplate 在 finally 块中再次调用 DataSourceUtils.releaseConnection，导致连接池中同一个连接被两次“归还”（取决于连接池的实现，可能会标记为关闭的连接再次被复用时出错，或在 releaseConnection 时发现连接已关闭而抛出异常）。更严重的是，如果事务环境下在回调中关闭了连接，事务管理器后续无法操作，导致事务一致性破坏。

排查过程：

  • 监控到大量 CannotGetJdbcConnectionException 或池耗尽告警。
  • 通过添加 log4jdbc 或连接池的监控日志，发现某些连接的关闭调用栈与 JdbcTemplate 骨架不一致。
  • 追踪代码发现某个 DAO 使用了 execute(ConnectionCallback) 并错误调用了 Connection.close()。

修复：JdbcTemplate 的回调中绝对不应手动关闭连接。应将连接视为由框架传入的“借用资源”，仅在其上创建 Statement 并执行。若需控制物理资源，留给框架的 finally 处理。

事故排查序列图（连接泄漏模拟）如下：

sequenceDiagram
    participant User as 自定义 ConnectionCallback
    participant JdbcT as JdbcTemplate
    participant Conn as 物理连接
    participant Pool as 连接池

    User->>Conn: con.close() (错误操作!)
    Conn->>Pool: 连接被归还/标记关闭
    JdbcT->>JdbcT: 回调结束，进入 finally
    JdbcT->>Conn: releaseConnection → 再次 close/归还
    Conn-->>Pool: 可能出现“连接已关闭”异常或双重空闲计数
    Pool-->>JdbcT: 记录异常，连接代理状态混乱
    Note over Pool: 后续获取连接时可能分配到一个已关闭连接

图 5 说明：一旦用户在回调中手动关闭连接，就破坏了 JdbcTemplate 设计的单一资源出口。正确的做法是完全依赖框架的资源管理，回调只负责业务操作。

9.2 RowMapper 中抛出未捕获异常导致 ResultSet 未关闭

事故描述：在自定义 RowMapper 的 mapRow 方法中，由于业务逻辑出错抛出了 RuntimeException（如 NullPointerException），该异常并非 SQLException，因此没有被 JdbcTemplate 的异常翻译 catch 块捕获。开发者担心这是否会导致 ResultSet 和 Statement 无法关闭，从而引发连接泄漏。

验证：查看 JdbcTemplate.query 源码（见模块 2.2 源码片段 2）的 PreparedStatementCallback 实现中，有 finally { JdbcUtils.closeResultSet(rs); }。这意味着无论 rse.extractData(rs) 内部是正常返回还是抛出任何异常（包括 RuntimeException），ResultSet 都会被关闭。而外层的 execute 骨架有 finally 确保 Statement 被关闭，连接被释放。Spring JDBC 框架的这一冗余安全网保证了即便用户回调抛出非受检异常，资源链也不会断裂。这是一次深刻的源码确认，证明其资源管理的闭环设计。

10. 面试高频专题

（本专题与正文逻辑分离，供读者自测）

1. JdbcTemplate 是怎么使用模板方法模式的？

  • 回答：JdbcTemplate 在 execute(ConnectionCallback) 等方法中定义了固定算法骨架：通过 DataSourceUtils.getConnection 获取连接（可能事务感知），创建连接代理，调用用户回调 doInConnection，catch 到 SQLException 后翻译为 DataAccessException，并在 finally 中释放连接。这个骨架不可变，而将具体数据库操作通过回调接口开放给用户。
  • 追问：为什么不直接把连接传给用户？答：为了控制资源生命周期，防止泄漏，并确保异常翻译。
  • 加分：可以提及 query 方法使用嵌套模板方法，在外层管理 Connection/Statement，内层管理 ResultSet，形成分级骨架。

2. RowMapper 和 ResultSetExtractor 的区别？

  • 回答：RowMapper 处理单行映射，框架遍历结果集为每一行调用它，最终返回 List；ResultSetExtractor 处理整个 ResultSet，用户控制遍历，可返回任意对象，适合聚合或流式处理。
  • 追问：什么场景下必须用 ResultSetExtractor？答：需要将多行数据聚合成一个对象（如统计总数），或需要处理多个 ResultSet 的情况（存储过程）。
  • 加分：提及 RowCallbackHandler 用于无返回的流式处理，避免内存压力。

3. JdbcTemplate 是如何处理异常的？

  • 回答：模板方法骨架中的 catch (SQLException ex) 块调用 translateException 方法，利用 SQLExceptionTranslator（默认 SQLErrorCodeSQLExceptionTranslator）将 SQLException 翻译为 DataAccessException 层次中的具体异常。
  • 追问：如果翻译器不认识那个错误码怎么办？答：返回 null，此时默认包装为 UncategorizedSQLException。
  • 加分：可以自定义 SQLExceptionTranslator 并设置到 JdbcTemplate，以支持特定数据库的错误。

4. JdbcTemplate 是线程安全的吗？为什么？

  • 回答：是线程安全的。因为其实例持有的是无状态的配置项（DataSource、fetchSize 等），不存储可变执行状态。每次操作都是通过局部变量完成。
  • 追问：如果我在运行时通过 setter 修改了 DataSource 呢？答：如果多个线程同时修改并读取，会产生竞态，所以通常只在初始化时配置，运行时视为不可变。
  • 加分：Spring 单例 Bean 注入 JdbcTemplate 正是利用其线程安全性。

5. JdbcTemplate 怎么配合 Spring 事务？

  • 回答：JdbcTemplate 通过 DataSourceUtils.getConnection 从 TransactionSynchronizationManager 获取当前线程绑定的连接。事务环境下，这个连接是同一事务共享的。它不提交或回滚，仅执行 SQL，事务边界由事务管理器控制。
  • 追问：非事务环境呢？答：每次获取新连接，执行后立即释放。
  • 加分：解释 ConnectionHolder 的引用计数和 TransactionSynchronization。

6. DataSourceUtils 的作用是什么？

  • 回答：它是连接管理的辅助类，核心功能包括：从 TransactionSynchronizationManager 查找或创建绑定连接；提供 releaseConnection 方法以根据事务状态决定关闭或解绑；将 Connection 包装为 ConnectionHolder 并绑定资源。
  • 追问：为什么不能直接用 dataSource.getConnection()？答：那样就无法感知事务，会导致同一事务使用不同的连接。
  • 加分：提及 DataSourceUtils 还提供 doGetConnection 的内部获取物理连接逻辑。

7. 如果自定义一个 JdbcTemplate 的回调接口，需要注意什么？

  • 回答：不要手动关闭传入的 Connection、Statement、ResultSet，这些资源的生命周期由框架管理；只能抛出 SQLException 型的受检异常（如果接口声明），非受检异常也可抛出但会被外层 finally 安全处理；注意状态无遗留。
  • 追问：如果回调中真的关闭了 Connection 会怎样？答：可能导致连接被重复关闭或事务连接被断，引发连接池混乱。
  • 加分：可自定义 PreparedStatementCreator 等来包装特定创建的 Statement。

8. batchUpdate 的内部实现是怎样的？

  • 回答：在模板方法骨架内，循环调用 setValues 设置参数，然后 ps.addBatch()，最后执行 ps.executeBatch()。对于大集合，可能会分批执行并调用 ps.clearBatch() 清除。
  • 追问：如何获得每条记录影响的行数？答：返回 int[] 数组。失败时也会部分执行。
  • 加分：结合 @Transactional 实现批量操作的原子性。

9. 如何在 JdbcTemplate 中获取自增主键？

  • 回答：使用 PreparedStatementCreator 并调用 connection.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS)，随后在回调中从 ps.getGeneratedKeys() 获取。Spring 提供 GeneratedKeyHolder 简化这一过程，可以使用 update(PreparedStatementCreator, KeyHolder)。
  • 追问：GeneratedKeyHolder 的原理？答：它提取 PreparedStatement 生成的自增键并存储到 Map。
  • 加分：提到批量插入时如何使用 BatchPreparedStatementSetter 配合生成键（较复杂）。

10. 简述 JdbcTemplate 中使用了哪些设计模式。

  • 回答：模板方法模式（execute骨架）、回调模式（Callback接口）、策略模式（RowMapper vs ResultSetExtractor， SQLExceptionTranslator）、适配器模式（DataSourceUtils适配DataSource）等。
  • 追问：这些模式如何协作？答：模板方法定义流程，回调实现变化，策略替换算法，适配器统一接口。
  • 加分：结合单一职责和开闭原则分析其架构稳定性。

11. 如何通过 JdbcTemplate 执行存储过程？

  • 回答：使用 execute(CallableStatementCreator, CallableStatementCallback)。可以注册输出参数，执行后提取结果。
  • 追问：如何处理 OUT 参数？答：在回调中调用 cs.registerOutParameter，执行后通过 cs.getObject(index) 获取。
  • 加分：使用 SimpleJdbcCall 进一步简化存储过程调用。

12. （系统设计题）设计一个轻量级的数据库访问层，要求能够支持事务、自动封装资源管理、并允许使用者灵活地映射结果集。请参考 JdbcTemplate 的设计模式，给出核心接口和模板方法骨架的伪代码。

  • 回答：
    • 定义一个 Operations 接口包含 execute(ConnectionCallback)。
    • 实现类持有数据源，模板方法骨架：getCon() -> try { callback.doInCon(con) } catch(SQLEx) { translate } finally { releaseCon }。
    • 提供 RowMapper 接口：T mapRow(ResultSet rs, int rowNum)，以及内置的 queryForList 方法遍历结果集调用 RowMapper。
    • 配合事务：ConnectionFactory 从线程局部变量中获取绑定连接，保证事务内共享。
  • 追问：如何保证连接关闭？答：都在 finally 块中释放，事务由外部事务管理器完成。
  • 加分：讨论 ResultSetExtractor 和批处理支持的设计。

附录：JdbcTemplate 核心回调接口速查表

回调接口方法签名职责生命周期关注
ConnectionCallback<T>T doInConnection(Connection con)使用原生 Connection 执行任意操作连接由框架管理，勿手动关
StatementCallback<T>T doInStatement(Statement stmt)在已创建的 Statement 上执行Statement 由框架关闭
PreparedStatementCallback<T>T doInPreparedStatement(PreparedStatement ps)在预编译的 PreparedStatement 上执行ps 由框架关闭
CallableStatementCallback<T>T doInCallableStatement(CallableStatement cs)执行存储过程cs 由框架关闭
RowMapper<T>T mapRow(ResultSet rs, int rowNum)将当前行映射为对象仅关注单行，无需处理遍历
ResultSetExtractor<T>T extractData(ResultSet rs)提取整个 ResultSet，返回任意结果ResultSet 由调用者（框架）关闭
RowCallbackHandlervoid processRow(ResultSet rs)纯处理每行，无返回值同 RowMapper，但适合流式
PreparedStatementSettervoid setValues(PreparedStatement ps)设置 SQL 参数一次性设置所有参数
BatchPreparedStatementSettervoid setValues(PreparedStatement ps, int i)
int getBatchSize()		批量设置多组参数每组调用一次，后执行批处理

延伸阅读：

  • Spring Framework 官方文档：Data Access with JDBC 章节。
  • 《Spring 揭秘》相关 JDBC 模板章节。
  • GoF 设计模式：模板方法模式、策略模式。

本文系统地剖析了 JdbcTemplate 的设计，从原生 JDBC 的痛点出发，沿着模板方法骨架、回调体系、资源管理、异常翻译、线程安全再到事务协同和技术实践，层层递进。希望读者不仅能学会使用，更能理解其背后面向对象设计模式的精妙缝合，并在自己的工程中写出同样优雅、健壮的代码。

avatar
文章
阅读
粉丝