MyBatis @Param 注解详解：多参数传递与正确使用方式

@Param 注解主要用于 MyBatis 进行参数传递时给 SQL 语句中的参数 起别名，通常用于 多参数 方法，使参数在 XML Mapper 文件或注解 SQL 语句中更清晰易用。

---

1. 基本用法

在 @Mapper 接口中使用 @Param 来为参数命名，避免 MyBatis 解析时出现参数名丢失的问题（尤其是多个参数时）。

示例：查询用户

@Mapper
public interface UserMapper {@Select("SELECT * FROM users WHERE id = #{userId}")User findUserById(@Param("userId") Long id);
}

解释：

• @Param("userId") 给方法参数 id 取别名 userId，
• SQL 语句 #{userId} 通过 MyBatis 解析参数值。

---

2. 多参数使用 @Param

如果方法有 多个参数，MyBatis 默认无法识别参数名，必须使用 @Param 指定。

示例：根据用户名和邮箱查询用户

@Mapper
public interface UserMapper {@Select("SELECT * FROM users WHERE username = #{username} AND email = #{email}")User findByUsernameAndEmail(@Param("username") String username, @Param("email") String email);
}

相当于 SQL

SELECT * FROM users WHERE username = 'Tom' AND email = '[e-mail]';

---

3. @Param 在 XML 中使用

如果使用 XML 方式编写 SQL，同样需要 @Param 进行参数映射。

示例：XML 配置

Mapper 接口

@Mapper
public interface UserMapper {User findUserByName(@Param("name") String name);
}

UserMapper.xml

<select id="findUserByName" parameterType="string" resultType="User">SELECT * FROM users WHERE username = #{name}
</select>

#{name} 对应 @Param("name")，MyBatis 能正确解析参数。

---

4. 适用于 INSERT、UPDATE、DELETE

示例：更新用户信息

@Update("UPDATE users SET email = #{email} WHERE username = #{username}")
void updateUserEmail(@Param("username") String username, @Param("email") String email);

调用：

userMapper.updateUserEmail("Tom", "[e-mail]");

执行的 SQL：

UPDATE users SET email = '[e-mail]' WHERE username = 'Tom';

---

5. 适用于 IN 查询（列表参数）

如果 SQL 需要 IN 语句，@Param 也可以用于传递 List。

示例：批量查询用户

@Select("<script>SELECT * FROM users WHERE id IN " +"<foreach collection='ids' item='id' open='(' separator=',' close=')'>#{id}</foreach>" +"</script>")
List<User> findUsersByIds(@Param("ids") List<Long> ids);

调用：

List<Long> userIds = Arrays.asList(1L, 2L, 3L);
List<User> users = userMapper.findUsersByIds(userIds);

执行的 SQL：

SELECT * FROM users WHERE id IN (1, 2, 3);

---

6. 适用于 Map 作为参数

如果方法参数是 Map，@Param 可以简化参数获取。

示例：传递 Map 查询

@Select("SELECT * FROM users WHERE username = #{param.username} AND email = #{param.email}")
User findByMap(@Param("param") Map<String, Object> param);

调用：

Map<String, Object> paramMap = new HashMap<>();
paramMap.put("username", "Tom");
paramMap.put("email", "[e-mail]");User user = userMapper.findByMap(paramMap);

执行的 SQL：

SELECT * FROM users WHERE username = 'Tom' AND email = '[e-mail]';

---

7. 适用于对象参数（拆分对象字段）

如果参数是对象，可以直接使用 #{对象.字段} 访问属性，但 @Param 仍然可用于 明确参数名称。

示例：传递 User 对象

@Insert("INSERT INTO users(username, email) VALUES(#{user.username}, #{user.email})")
void insertUser(@Param("user") User user);

调用：

User user = new User("Alice", "[e-mail]");
userMapper.insertUser(user);

执行的 SQL：

INSERT INTO users(username, email) VALUES('Alice', '[e-mail]');

---

总结

用法	示例	适用场景
单个参数	@Param("userId") Long id	传递单个参数，避免 SQL 中参数混乱
多个参数	@Param("username") String name, @Param("email") String email	传递多个参数，保证 SQL 解析正确
XML 方式	#{name} 对应 @Param("name")	XML 中映射参数
列表参数	@Param("ids") List<Long> ids	IN 查询
Map 参数	@Param("param") Map<String, Object>	传递多个参数，简化方法参数列表
对象参数	@Param("user") User user	直接使用对象字段

---

什么时候必须用 @Param？

✅ 必须用 @Param 的情况

1. 多个参数，否则 MyBatis 可能无法正确解析
2. SQL 中参数命名和方法参数不同
3. XML 方式，参数需要手动映射
4. List/Map 参数，用于 IN 查询或动态 SQL

❌ 不需要 @Param 的情况

• 只有 一个参数 时，可以直接使用 #{参数名}
• 参数是 对象，可以直接 #{对象.字段} 访问

💡 总结：
@Param 主要用于 多参数方法，保证 MyBatis 正确解析 SQL 参数，提高可读性和维护性。