当前位置：首页 > news >正文

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

news 2025/8/28 15:00:55

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. 最佳实践

单简单类型参数：
- 若编译保留参数名（添加 -parameters），可不加 @Param。
- 否则建议显式添加 @Param。
多参数：
- 始终使用 @Param 明确参数名，避免依赖 param1 或 arg0。
对象或 Map 参数：
- 直接通过属性或键访问（如 #{user.id}），无需 @Param。
- 若需别名，可加 @Param 并调整访问路径（如 @Param("u") User user → #{u.id}）。
动态 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};