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 = '[email protected]';
3. @Param 在 XML 中使用
如果使用 XML 方式编写 SQL，同样需要 @Param 进行参数映射。
示例：XML 配置
Mapper 接口
@Mapper
public interface UserMapper {
User findUserByName(@Param("name") String name);
}
UserMapper.xml
#{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", "[email protected]");
执行的 SQL：
UPDATE users SET email = '[email protected]' WHERE username = 'Tom';
5. 适用于 IN 查询（列表参数）
如果 SQL 需要 IN 语句，@Param 也可以用于传递 List。
示例：批量查询用户
@Select("")
List findUsersByIds(@Param("ids") List ids);
调用：
List userIds = Arrays.asList(1L, 2L, 3L);
List 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 param);
调用：
Map paramMap = new HashMap<>();
paramMap.put("username", "Tom");
paramMap.put("email", "[email protected]");
User user = userMapper.findByMap(paramMap);
执行的 SQL：
SELECT * FROM users WHERE username = 'Tom' AND email = '[email protected]';
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", "[email protected]");
userMapper.insertUser(user);
执行的 SQL：
INSERT INTO users(username, email) VALUES('Alice', '[email protected]');
总结
| 用法 | 示例 | 适用场景 |
|---|---|---|
| 单个参数 | @Param("userId") Long id |
传递单个参数，避免 SQL 中参数混乱 |
| 多个参数 | @Param("username") String name, @Param("email") String email |
传递多个参数，保证 SQL 解析正确 |
| XML 方式 | #{name} 对应 @Param("name") |
XML 中映射参数 |
| 列表参数 | @Param("ids") List |
IN 查询 |
| Map 参数 | @Param("param") Map |
传递多个参数，简化方法参数列表 |
| 对象参数 | @Param("user") User user |
直接使用对象字段 |
什么时候必须用 @Param？
✅ 必须用 @Param 的情况
- 多个参数，否则 MyBatis 可能无法正确解析
- SQL 中参数命名和方法参数不同
- XML 方式，参数需要手动映射
- List/Map 参数，用于
IN查询或动态 SQL
❌ 不需要 @Param 的情况
- 只有 一个参数 时，可以直接使用
#{参数名} - 参数是 对象，可以直接
#{对象.字段}访问
总结：
@Param 主要用于 多参数方法，保证 MyBatis 正确解析 SQL 参数，提高可读性和维护性。