MyBatis 報錯「Parameter 'params' not found」完整排查指南

錯誤現場

執行 MyBatis 查詢時拋出異常：

Parameter 'params' not found. Available parameters are [param1, page]

代碼結構分析

Mapper 接口

public int queryCount(@Param("page") CompanyForm page) throws DaoException;

Service 實現類

@Override
public int queryCount(CompanyForm page) throws ServiceException {
    try {
        return companyExtMapper.queryCount(page);
    } catch (Exception e) {
        throw new ServiceException(e.getMessage(), e);
    }
}

Mapper XML

<select id="queryCount" resultType="java.lang.Integer" 
        parameterType="classroom.common.form.CompanyForm">
    select count(1) from company 
    <include refid="condition" />
</select>

根因定位

核心問題：Mapper XML 中引用了 page 參數的屬性（如 page.someProperty），但實際傳遞的參數名稱為 param1（MyBatis 默認命名），而非預期的 page。

原因鏈：

1. Mapper 接口使用 @Param("page") 指定參數名為 "page"
2. 但 XML 中 parameterType 宣告為具體類型，導致 MyBatis 嘗試直接訪問對象屬性
3. 若 SQL 中使用 #{page.property} 卻未正確綁定參數名，會找不到 "page"
4. 可用參數列表顯示 [param1, page] 表明：MyBatis 同時生成了默認參數名 "param1" 和註解指定的 "page"

解決方案

方案一：統一使用 @Param 註解（推薦）

在 XML 中引用參數時，嚴格使用註解指定的名稱：

<select id="queryCount" resultType="java.lang.Integer">
    select count(1) from company 
    <where>
        <if test="page != null and page.someProperty != null">
            and some_column = #{page.someProperty}
        </if>
    </where>
</select>

方案二：移除 parameterType 宣告

讓 MyBatis 自動推斷參數類型，直接使用 @Param 綁定的名稱：

<select id="queryCount" resultType="java.lang.Integer">
    select count(1) from company 
    <include refid="condition" />
</select>

方案三：使用單一參數對象（無 @Param）

若只有一個參數，可移除 @Param，MyBatis 會將對象屬性直接映射：

// 接口
public int queryCount(CompanyForm page) throws DaoException;

// XML 中直接訪問屬性
<if test="someProperty != null">...#{someProperty}...</if>

最佳實踐總結

• 多參數方法必須使用 @Param 指定名稱
• XML 中引用參數時，嚴格匹配 @Param 值（區分大小寫）
• 避免同時使用 parameterType 和 @Param 混淆映射關係
• 啟用 MyBatis 日誌（DEBUG 級別）觀察實際執行 SQL 及參數綁定情況