Spring NamedParameterJdbcTemplate 完整指南：命名參數與 BeanPropertySqlParameterSource 實戰

Spring NamedParameterJdbcTemplate 完整指南：命名參數與 BeanPropertySqlParameterSource 實戰

NamedParameterJdbcTemplate 是 Spring 對 JdbcTemplate 的增強封裝，支援 SQL 中使用命名參數（如 :name）替代傳統佔位符（?），大幅提升 SQL 可讀性與維護性。本文詳細介紹其核心用法與兩種參數綁定方式。

核心優勢

• SQL 可讀性高：參數名稱具備業務含義
• 參數順序無關：不需擔心佔位符順序錯誤
• 支援複雜型別：可直接綁定 JavaBean 屬性

初始化方式

// 方式一：使用 DataSource
NamedParameterJdbcTemplate npjt = new NamedParameterJdbcTemplate(dataSource);

// 方式二：使用現有 JdbcTemplate（推薦，復用連線池）
NamedParameterJdbcTemplate npjt = new NamedParameterJdbcTemplate(jdbcTemplate);

基本用法：Map 綁定參數

String insertSql = "INSERT INTO test(name) VALUES(:name)";
String selectSql = "SELECT * FROM test WHERE name=:name";
String deleteSql = "DELETE FROM test WHERE name=:name";

Map<String, Object> paramMap = new HashMap<>();
paramMap.put("name", "name5");

// 執行更新
npjt.update(insertSql, paramMap);

// 查詢
List<Integer> result = new ArrayList<>();
npjt.query(selectSql, paramMap, new RowCallbackHandler() {
    @Override
    public void processRow(ResultSet rs) throws SQLException {
        result.add(rs.getInt("id"));
    }
});

// 使用 SqlParameterSource 刪除
SqlParameterSource paramSource = new MapSqlParameterSource(paramMap);
npjt.update(deleteSql, paramSource);

進階用法：BeanPropertySqlParameterSource 綁定 JavaBean

定義實體類別：

public class UserModel {
    private int id;
    private String myName;
    // getter/setter 省略
}

直接綁定物件屬性：

UserModel model = new UserModel();
model.setMyName("name5");

String insertSql = "INSERT INTO test(name) VALUES(:myName)";
SqlParameterSource paramSource = new BeanPropertySqlParameterSource(model);
npjt.update(insertSql, paramSource);

關鍵規則：SQL 中的命名參數（:myName）必須與 JavaBean 屬性名稱（myName）完全一致。

兩種參數來源比較

批次操作支援

NamedParameterJdbcTemplate 同樣支援 batchUpdate()，參數來源可為 SqlParameterSource[] 陣列，適合大量資料匯入場景。

總結

NamedParameterJdbcTemplate 是 Spring JDBC 開發的利器。實務中建議：

1. 優先復用現有 JdbcTemplate 初始化
2. 簡單查詢使用 Map 綁定
3. 實體物件操作使用 BeanPropertySqlParameterSource，實現零樣板碼參數綁定
4. 複雜動態 SQL 考慮搭配 MyBatis 等 ORM 框架

掌握命名參數綁定技巧，能讓資料庫操作程式碼更清晰、更安全、更易維護。