Apache DbUtils 查詢方法詳解：如何將結果封裝為實體類

前言

Apache DbUtils 是一個輕量級的 JDBC 工具庫，旨在簡化資料庫操作的樣板代碼。開發者常遇到的需求是將查詢結果直接映射為 Java 實體類（POJO），而不必手動處理 ResultSet。本文將介紹 DbUtils 中常用的查詢方法，並示範如何實現自動封裝。

核心類：QueryRunner

QueryRunner 是 DbUtils 的核心類，提供了多種 query 方法重載，配合不同的 ResultSetHandler 實現，可輕鬆完成從單行到多行、從陣列到 Bean 的轉換。

1. 查詢單行並封裝為 Bean — BeanHandler

String sql = "SELECT id, username, email FROM users WHERE id = ?";
QueryRunner runner = new QueryRunner(dataSource);
User user = runner.query(sql, new BeanHandler<User>(User.class), 1L);

BeanHandler 會將結果集的第一行映射為指定類的實例，屬性名需與欄位名一致（或透過別名對應）。

2. 查詢多行並封裝為 List<Bean> — BeanListHandler

String sql = "SELECT id, username, email FROM users WHERE status = ?";
List<User> users = runner.query(sql, new BeanListHandler<User>(User.class), 1);

此處回傳 List<User>，每一行對應一個 User 物件，適合分頁或批次處理場景。

3. 通用 Map 封裝 — MapHandler / MapListHandler

若無實體類，可使用 MapHandler（單行）或 MapListHandler（多行），結果鍵為欄位名，值為欄位值，靈活性極高。

進階技巧：自定義 ResultSetHandler

當預設處理器無法滿足需求（如複雜巢狀物件、多表關聯）時，可實作 ResultSetHandler<T> 介面，在 handle(ResultSet rs) 中自行組裝邏輯，最大化彈性。

圖示說明

最佳實踐建議

• 實體類屬性命名遵循駝峰式，資料庫欄位建議使用下劃線，DbUtils 預設支援自動轉換。
• 搭配連線池（如 HikariCP）使用 QueryRunner，提升效能。
• 針對大量資料查詢，考慮使用 RowProcessor 自訂類型轉換，避免效能瓶頸。

參考資源

更多詳細範例請參考：DbUtils 實戰指南