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

伯灵

发布于 2026-01-21 09:41:49

1240

@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 = 'tom@example.com';

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", "newemail@example.com");

执行的 SQL：

UPDATE users SET email = 'newemail@example.com' 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", "tom@example.com");

User user = userMapper.findByMap(paramMap);

执行的 SQL：

SELECT * FROM users WHERE username = 'Tom' AND email = 'tom@example.com';

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", "alice@example.com");
userMapper.insertUser(user);

执行的 SQL：

INSERT INTO users(username, email) VALUES('Alice', 'alice@example.com');

总结

用法	示例	适用场景
单个参数	@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 的情况

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

❌ 不需要 @Param 的情况

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

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

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2025-03-06，如有侵权请联系 cloudcommunity@tencent.com 删除

mybatis

对象

接口

注解

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度