Mybatis参数传递全攻略：从@Param到Map的5种实战写法（附避坑指南）

Mybatis参数传递全攻略：从@Param到Map的5种实战写法（附避坑指南）

在Java持久层框架中，Mybatis因其灵活性和高性能备受开发者青睐。然而，当面对多参数传递场景时，不少中高级开发者仍会在各种传参方式的选择上产生困惑。本文将深入剖析五种主流传参方式的实现原理、适用场景和性能差异，并通过真实业务代码演示如何规避常见陷阱。

1. 基础传参方式与原理剖析

Mybatis的参数传递机制本质上是在Java方法和SQL语句之间建立桥梁。理解其底层原理能帮助开发者在复杂场景下做出更合理的选择。

简单参数传递是最基础的形式，适用于DAO接口方法仅有一个基本类型或String类型参数的情况。此时Mapper文件中#{任意字符}的命名与Java方法参数名无关，但建议保持语义一致性便于维护。

// DAO接口示例 public User selectUserById(Integer userId); // Mapper文件对应SQL <select id="selectUserById" resultType="User"> SELECT * FROM user WHERE id = #{identifier} </select>

注意：虽然#{identifier}可以与参数名不同，但在团队协作中保持命名一致性能显著提升代码可读性。

parameterType属性在现代Mybatis版本中已成为可选配置，因为框架通过反射机制能够自动推断参数类型。但在以下两种情况下显式声明仍有价值：

1. 需要覆盖Mybatis的类型推断结果时
2. 使用存储过程需要指定特定参数模式时

类型处理器(TypeHandler)在参数传递过程中扮演着关键角色。当遇到以下复杂场景时，自定义类型处理器往往能简化开发：

• Java 8时间API与数据库类型的转换
• 枚举类型的特殊处理
• 复杂JSON对象与数据库字段的映射

2. 多参数传递的五种实战方案

2.1 @Param注解方式

这是Mybatis官方推荐的多参数传递方式，通过在接口方法参数前添加@Param注解显式声明参数名，解决了Java编译后参数名丢失的问题。

public List<Product> searchProducts( @Param("category") String category, @Param("minPrice") BigDecimal minPrice, @Param("maxPrice") BigDecimal maxPrice, @Param("statusList") List<Integer> statusList);

对应的Mapper文件应使用注解定义的参数名：

<select id="searchProducts" resultType="Product"> SELECT * FROM product WHERE category = #{category} AND price BETWEEN #{minPrice} AND #{maxPrice} AND status IN <foreach item="status" collection="statusList" open="(" separator="," close=")"> #{status} </foreach> </select>

优势对比表：

2.2 Java Bean对象封装

当参数超过5个或具有明确业务含义时，建议采用值对象(VO)封装。这种方式符合面向对象设计原则，能显著提升代码可维护性。

// 查询参数封装对象 @Data public class ProductQueryVO { private String category; private String brand; private BigDecimal minPrice; private BigDecimal maxPrice; private Date createTimeStart; private Date createTimeEnd; // 其他查询条件... } // DAO接口方法 public List<Product> queryProducts(ProductQueryVO query);

Mapper文件中直接引用VO属性：

<select id="queryProducts" resultType="Product"> SELECT * FROM product WHERE 1=1 <if test="category != null"> AND category = #{category} </if> <if test="brand != null"> AND brand = #{brand} </if> <!-- 其他条件判断 --> </select>

2.3 Map集合传参

Map方式在动态查询场景下非常灵活，特别适合前端传参不确定的情况。但需要注意类型安全问题。

public List<Product> dynamicQuery(Map<String, Object> params);

Mapper文件示例：

<select id="dynamicQuery" resultType="Product"> SELECT * FROM product WHERE <foreach collection="params" index="key" item="value" separator=" AND "> ${key} = #{value} </foreach> </select>

警告：直接使用${key}拼接字段名存在SQL注入风险，应确保key值来自可信源或进行严格校验。

2.4 位置参数传递

Mybatis 3.4+版本使用#{arg0}、#{arg1}方式引用参数，适用于参数较少且变化不频繁的场景。

public List<User> selectUsersByNameAndStatus(String name, Integer status);

Mapper文件对应写法：

<select id="selectUsersByNameAndStatus" resultType="User"> SELECT * FROM user WHERE username = #{arg0} AND status = #{arg1} </select>

2.5 参数传递的混合使用

实际开发中经常需要组合使用多种传参方式。例如，结合@Param注解和Java对象：

public List<Order> searchOrders( @Param("query") OrderQuery query, @Param("page") PageParam page);

对应Mapper文件：

<select id="searchOrders" resultType="Order"> SELECT * FROM order WHERE <include refid="orderQueryCondition"/> LIMIT #{page.offset}, #{page.size} </select>

3. 参数传递中的性能与安全

3.1 #{}与${}的本质区别

这两种占位符在Mybatis中有着根本性的差异：

• #{}采用预编译方式，能有效防止SQL注入，是绝大多数场景的首选
• ${}直接进行字符串替换，适用于动态表名、列名等无法使用预编译的场景

安全对比实验：

// 危险示例：使用${}拼接用户输入 public List<User> unsafeQuery(@Param("condition") String condition); // Mapper中的危险SQL <select id="unsafeQuery" resultType="User"> SELECT * FROM user WHERE ${condition} </select> // 攻击者可能传入：1=1 OR DELETE FROM user

3.2 批量操作参数处理

Mybatis处理批量插入时有多种参数传递方式，性能差异显著：

// 方式一：单条INSERT语句 public int batchInsert(@Param("list") List<User> users); // 方式二：批量INSERT语句 public int bulkInsert(@Param("list") List<User> users);

对应的Mapper实现：

<!-- 方式一对应的SQL --> <insert id="batchInsert"> INSERT INTO user(name,age) VALUES <foreach collection="list" item="user" separator=","> (#{user.name},#{user.age}) </foreach> </insert> <!-- 方式二对应的SQL --> <insert id="bulkInsert"> <foreach collection="list" item="user" separator=";"> INSERT INTO user(name,age) VALUES(#{user.name},#{user.age}) </foreach> </insert>

批量操作性能对比：

4. 复杂场景参数处理技巧

4.1 集合类型参数的特殊处理

Mybatis为集合类型参数提供了专用处理方式，特别是在IN查询中：

public List<Product> findProductsByIds(@Param("ids") Set<Long> ids);

Mapper文件中的智能处理：

<select id="findProductsByIds" resultType="Product"> SELECT * FROM product WHERE id IN <foreach collection="ids" item="id" open="(" separator="," close=")"> #{id} </foreach> </select>

4.2 嵌套对象参数处理

当参数对象包含其他复杂对象时，可以使用点号导航：

@Data public class OrderQuery { private User user; private DateRange createTime; // 其他字段... } @Data public class DateRange { private Date start; private Date end; }

Mapper中的引用方式：

<select id="searchOrders" resultType="Order"> SELECT * FROM order WHERE user_id = #{user.id} AND create_time BETWEEN #{createTime.start} AND #{createTime.end} </select>

4.3 枚举类型参数的最佳实践

Mybatis对枚举类型的处理有多种方式，推荐使用自定义类型处理器：

public enum UserStatus { ACTIVE(1), INACTIVE(0), LOCKED(-1); private final int code; // 构造方法、getter等 } // 自定义类型处理器 public class UserStatusTypeHandler extends BaseTypeHandler<UserStatus> { // 实现抽象方法... }

在配置文件中注册类型处理器后，即可直接使用枚举作为参数：

public List<User> selectByStatus(@Param("status") UserStatus status);

5. 版本差异与兼容性处理

Mybatis不同版本在参数处理上存在细微差异，特别是3.4版本的位置参数变化：

版本差异对照表：

对于需要兼容多版本的项目，建议统一使用@Param注解方式，这是最稳定的跨版本方案。在遇到必须使用位置参数的场景时，可以通过Mybatis配置参数useActualParamName来控制行为：

<settings> <setting name="useActualParamName" value="false"/> </settings>

在处理分页参数等通用参数时，可以创建ThreadLocal包装类来避免每个方法都重复声明分页参数：

public class PageContext { private static final ThreadLocal<PageParam> context = new ThreadLocal<>(); public static void set(PageParam page) { context.set(page); } public static PageParam get() { return context.get(); } public static void clear() { context.remove(); } } // 拦截器中自动注入分页参数 public class PageInterceptor implements Interceptor { // 实现逻辑... }