您现在的位置：程式碼之家 >> 數據庫知識 > >> MySQL 資料庫 >> MySQL 綜合教學

Apache Commons DbUtils 使用指南：QueryRunner、ResultSetHandler 七大實現類、DbUtils 工具類完整解析

編輯：MySQL 綜合教學

Apache Commons DbUtils 使用指南：QueryRunner 核心 API、ResultSetHandler 七大實現、DbUtils 工具類完整解析

Commons DbUtils 是對 JDBC 的輕量封裝，不改變 SQL 編寫習慣，卻能消除 90% 的樣板代碼（連接、語句、結果集、關閉、異常處理）。本文系統講解 QueryRunner 構造與執行方法、ResultSetHandler 七大內置實現、DbUtils 關閉工具類，並附帶完整 JUnit 測試代碼。

一、核心類關係

QueryRunner：線程安全的執行入口，持有 DataSource 或接受 Connection。
ResultSetHandler<T>：函數式接口，將 ResultSet 轉換為業務對象 T。
DbUtils：靜態工具類，負責安全關閉 Connection/Statement/ResultSet、載入驅動、提交關閉。

二、QueryRunner 構造方法

// 1. 無參構造：每次執行需傳入 Connection
QueryRunner runner = new QueryRunner();

// 2. DataSource 構造：自動獲取/歸還連接，適合無連接池管理場景
QueryRunner runner = new QueryRunner(dataSource);

三、核心執行方法

方法簽名	用途	連接管理
query(Connection, sql, params[], rsh)	查詢，手動管理連接	調用者負責關閉 Connection
query(sql, params[], rsh)	查詢，自動從 DataSource 獲取連接	內部自動關閉 Connection
query(Connection, sql, rsh)	無參查詢	調用者負責關閉
update(Connection, sql, params[])	增刪改，返回影響行數	調用者負責關閉
update(Connection, sql)	無參增刪改	調用者負責關閉
update(sql, params[])	自動連接增刪改	內部自動關閉
batch(sql, Object[][] params)	批量執行	視構造方式而定

四、ResultSetHandler 七大內置實現

處理器	返回類型	適用場景	示例
BeanHandler<T>	T	單行 → JavaBean	new BeanHandler<>(User.class)
BeanListHandler<T>	List<T>	多行 → List<JavaBean>	new BeanListHandler<>(User.class)
ArrayHandler	Object[]	單行 → 對象數組	new ArrayHandler()
ArrayListHandler	List<Object[]>	多行 → List<數組>	new ArrayListHandler()
MapHandler	Map<String,Object>	單行 → 鍵值對	new MapHandler()
MapListHandler	List<Map<String,Object>>	多行 → List<Map>	new MapListHandler()
ScalarHandler<T>	T	單值聚合	new ScalarHandler<Long>()

五、DbUtils 關閉工具類

// 安全關閉（null 安全、吞噬 SQLException）
DbUtils.close(connection);
DbUtils.close(statement);
DbUtils.close(resultSet);
DbUtils.closeQuietly(connection, statement, resultSet);  // 批量靜默關閉

// 提交並關閉
DbUtils.commitAndCloseQuietly(connection);

// 載入驅動（無需捕獲 ClassNotFoundException）
boolean ok = DbUtils.loadDriver("com.mysql.jdbc.Driver");

六、連接管理關鍵規則

帶 Connection 參數的 update/query：調用者必須手動關閉 Connection，DbUtils 僅關閉 Statement/ResultSet。
不帶 Connection 參數（DataSource 構造）：框架自動獲取並關閉 Connection。
設計初衷：支持事務邊界在外層控制（Service 層開啟事務、傳入 Connection、調用多個 DAO、提交/回滾）。

七、完整 JUnit 測試代碼

public class DbUtilsDemo {
    private QueryRunner runner = new QueryRunner(JdbcUtils.getDataSource());

    @Test public void testBeanHandler() throws SQLException {
        User user = runner.query("SELECT * FROM user_info", new BeanHandler<>(User.class));
        System.out.println("beanHandler: " + user);
    }

    @Test public void testBeanListHandler() throws SQLException {
        List users = runner.query("SELECT * FROM user_info", new BeanListHandler<>(User.class));
        users.forEach(System.out::println);
    }

    @Test public void testArrayHandler() throws SQLException {
        Object[] arr = runner.query("SELECT * FROM user_info", new ArrayHandler());
        System.out.println("ID: " + arr[0] + ", Name: " + arr[1]);
    }

    @Test public void testArrayListHandler() throws SQLException {
        List list = runner.query("SELECT * FROM user_info", new ArrayListHandler());
        list.forEach(arr -> System.out.println("ID: " + arr[0] + ", Name: " + arr[1]));
    }

    @Test public void testMapHandler() throws SQLException {
        Map map = runner.query("SELECT * FROM user_info", new MapHandler());
        System.out.println("Username: " + map.get("username"));
    }

    @Test public void testMapListHandler() throws SQLException {
        List> list = runner.query("SELECT * FROM user_info", new MapListHandler());
        list.forEach(m -> System.out.println("User: " + m.get("username") + ", Salary: " + m.get("salary")));
    }

    @Test public void testScalarHandler() throws SQLException {
        Long count = runner.query("SELECT COUNT(*) FROM user_info", new ScalarHandler());
        System.out.println("Total: " + count);
    }
}