MyBatis @Param 注解详解：指定的参数找不到？

MyBatis @Param 注解详解

---

1. @Param 注解的作用

@Param 注解用于显式指定方法参数的名称，让 MyBatis 在 SQL 映射文件（XML）或注解中通过该名称访问参数。
核心场景：

• 方法有多个参数时，避免参数名丢失或混淆。
• 参数为简单类型（如 String, int）且未封装成对象时，明确参数名。

---

2. 加与不加 @Param 的区别

场景	不加 @Param	加 @Param
单参数（简单类型）	默认可用参数名（需编译保留参数名）或 _parameter	强制绑定到指定名称（如 @Param("id") → #{id}）
多参数（简单类型）	必须通过 param1, param2 或 arg0, arg1 访问	直接通过注解名称访问（如 #{name}, #{age}）
参数为对象或 Map	直接通过属性名或键访问（如 #{user.id}）	需通过 @Param 别名访问（如 #{user.id} → #{u.id}）

---

3. 常见报错原因分析

情况1：加了 @Param 却报“变量未找到”

• 原因1：注解名称与 XML 占位符不匹配

  // 方法定义
  User getUserById(@Param("userId") int id); // 注解名为 "userId"// XML 错误写法
  SELECT * FROM user WHERE id = #{id}; // 应该用 #{userId}
  

• 原因2：动态 SQL 中错误引用
  在 <if> 或 <foreach> 中未正确使用注解名：

  <select id="getUsers">SELECT * FROM user WHERE name = #{name} <!-- 正确 --><if test="age != null">AND age = #{userAge} <!-- 错误：@Param 未定义 "userAge" --></if>
  </select>
  

情况2：不加 @Param 却报“变量未找到”

• 原因1：编译未保留参数名
  未在编译时添加 -parameters 选项（Java 8+ 支持），导致 MyBatis 无法获取参数名，只能通过 param1 或 arg0 访问：

  // 方法定义
  User getUserByNameAndAge(String name, int age); // XML 错误写法（未启用 -parameters 时）
  SELECT * FROM user WHERE name = #{name} AND age = #{age}; // 正确写法（不加 @Param 时）
  SELECT * FROM user WHERE name = #{param1} AND age = #{param2};
  

• 原因2：多参数未封装成对象或 Map
  若方法有多个简单类型参数且未使用 @Param，必须通过 param1/arg0 或 param2/arg1 访问：

  // 方法定义
  User getUser(String name, int age); // XML 正确写法
  SELECT * FROM user WHERE name = #{param1} AND age = #{param2};
  

---

4. 最佳实践

1. 单简单类型参数：

   • 若编译保留参数名（添加 -parameters），可不加 @Param。
   • 否则建议显式添加 @Param。

2. 多参数：

   • 始终使用 @Param 明确参数名，避免依赖 param1 或 arg0。

3. 对象或 Map 参数：

   • 直接通过属性或键访问（如 #{user.id}），无需 @Param。
   • 若需别名，可加 @Param 并调整访问路径（如 @Param("u") User user → #{u.id}）。

4. 动态 SQL：

   • 在 <if> 或 <foreach> 中，确保 test 表达式中的变量名与 @Param 一致。

---

5. 示例代码

正确使用 @Param

// 方法定义
List<User> findUsers(@Param("name") String name, @Param("minAge") int minAge
);// XML 映射
<select id="findUsers">SELECT * FROM user WHERE name = #{name}AND age >= #{minAge}
</select>

错误示例（不加 @Param 导致问题）

// 方法定义（未启用 -parameters 编译选项）
User getUser(String name, int age);// XML 错误写法
SELECT * FROM user WHERE name = #{name} AND age = #{age}; // 正确写法（通过 param1/param2）
SELECT * FROM user WHERE name = #{param1} AND age = #{param2};

---

总结

@Param 的核心作用是明确参数名称，避免因参数名丢失或歧义导致的错误。报错的根本原因通常是名称不匹配或参数绑定机制不清晰。根据参数类型和数量，合理选择是否使用 @Param，并在 XML 中严格匹配名称即可解决问题。