MyBatis 多參數傳遞三種方案詳解與最佳實踐

MyBatis Mapper 多參數綁定：三種核心方案對比與選型指南

在 MyBatis 開發中，DAO 方法需要傳遞多個參數時，XML 中如何正確綁定是常見困惑點。本文詳細解析三種主流方案的語法、原理、優缺點，並給出生產環境選型建議。

方案一：索引佔位符 #{0}、#{1}...

DAO 介面

public interface UserMapper {
    User selectUser(String name, String area);
}

Mapper XML

    SELECT * FROM user_user_t 
    WHERE user_name = #{0} AND user_area = #{1}

原理解析

• MyBatis 將多參數封裝為 Object[] args 或 Map<String, Object>
• #{0} 對應 args[0]，#{1} 對應 args[1]，以此類推
• 底層調用 ParamNameResolver.getNamedParams() 解析

優缺點

方案二：Map 封裝參數

DAO 介面

public interface UserMapper {
    User selectUser(Map paramMap);
}

Mapper XML

    SELECT * FROM user_user_t 
    WHERE user_name = #{userName, jdbcType=VARCHAR} 
    AND user_area = #{userArea, jdbcType=VARCHAR}

Service 調用

public User queryUser(String name, String area) {
    Map paramMap = new HashMap<>();
    paramMap.put("userName", name);
    paramMap.put("userArea", area);
    return userMapper.selectUser(paramMap);
}

優缺點

方案三：@Param 註解綁定（推薦）

DAO 介面

public interface UserMapper {
    User selectUser(
        @Param("userName") String name, 
        @Param("userArea") String area
    );
}

Mapper XML

    SELECT * FROM user_user_t 
    WHERE user_name = #{userName, jdbcType=VARCHAR} 
    AND user_area = #{userArea, jdbcType=VARCHAR}

原理解析

• @Param 值成為參數 Map 的 Key
• MyBatis ParamNameResolver 掃描註解構建 Map<String, Object> namedParams
• JDK 8+ 編譯時加 -parameters 可省略 @Param（參數名保留在字節碼）

優缺點

進階方案：參數對象（POJO/DTO）

當參數超過 4-5 個或邏輯相關時，強烈建議封裝為參數對象：

DTO 類

public class UserQueryDTO {
    private String userName;
    private String userArea;
    private Integer ageMin;
    private Integer ageMax;
    private List statusList;
    // getter/setter
}

DAO 介面

public interface UserMapper {
    List selectUsers(UserQueryDTO dto);
    // 或用 @Param("dto") UserQueryDTO dto
}

Mapper XML

    SELECT * FROM user_user_t 
    WHERE 1=1
    
        AND user_name = #{dto.userName}
    
    
        AND age >= #{dto.ageMin}
    
    

三方案綜合對比與選型建議

最佳實踐總結

1. 1-2 參數：可用 @Param 或 JDK 8+ -parameters 省略註解
2. 3-4 參數：首選 @Param，介面清晰、XML 語義化
3. >4 參數或複雜查詢：封裝 DTO，配合動態 SQL <if>、<where>
4. 避免：直接用 Map 作為介面參數（失去契約約束）
5. 規範：團隊統一風格，納入 Code Review 檢查項

常見坑點提醒

• 參數名衝突：@Param 值與實體屬性名衝突時，XML 中用 #{paramName.property} 區分
• 集合參數：List ids 配合 foreach，MyBatis 自動封裝為 collection
• jdbcType 指定：對於可為 null 的列，建議顯式指定 jdbcType=VARCHAR 避免某些驅動報錯
• 特殊字符：參數名含特殊字符需在 XML 中用 #{'user-name'} 引用

掌握 MyBatis 多參數綁定本質，選對方案能顯著提升代碼可讀性、維護性與團隊協作效率。建立團隊統一規範，將參數傳遞風格納入架構設計文檔，是成熟工程團隊的標誌。