MyBatis多参数传递与最佳实践指南

在MyBatis的实际开发中，处理多参数传递是每个开发者必须掌握的技能。不同于单参数的简单处理，多参数场景需要特别注意参数映射的准确性和代码的可维护性。以下是七种经过实战检验的参数传递方式及其底层原理分析。

一、原始顺序传参模式（慎用）

User selectUser(String name, Integer age);

<select id="selectUser" resultType="User">
  SELECT * FROM user 
  WHERE name = #{0} AND age = #{1}
</select>

技术内幕：

1. 参数通过ParamNameResolver进行解析
2. 默认使用arg0, arg1或param1, param2作为键值
3. MyBatis 3.4.1之前使用索引方式，3.4.1之后推荐命名方式

致命缺陷：

• 参数顺序敏感：调整方法参数顺序会导致XML映射失效
• 可读性差：数字索引无法体现参数业务含义
• 维护成本高：新增参数需要重新调整所有索引

二、@Param注解标准方案

User selectUser(@Param("userName") String name, 
                @Param("userAge") Integer age);

<select id="selectUser" resultType="User">
  SELECT * FROM user 
  WHERE name = #{userName} AND age = #{userAge}
</select>

实现原理：

1. ParamNameResolver解析器处理注解
2. 生成参数映射字典：{"userName": param1, "userAge": param2}
3. 最终封装成Map<String, Object>对象

性能优化技巧：

• 注解命名遵循驼峰规则，提升代码可读性
• 相同业务含义参数保持命名一致性
• 避免过度缩写导致语义模糊

三、Map容器传参方案

Map<String, Object> params = new HashMap<>();
params.put("name", "John");
params.put("age", 25);
User user = mapper.selectUserByMap(params);

<select id="selectUserByMap" resultType="User">
  SELECT * FROM user 
  WHERE name = #{name} AND age = #{age}
</select>

适用场景：

• 动态字段查询（字段数量不确定）
• 多条件组合查询
• 跨服务参数收集

类型安全陷阱：

// 错误示例：类型不匹配不会在编译期发现
params.put("age", "25"); // 应该是Integer类型

建议使用Guava的ImmutableMap或自定义参数对象替代纯Map结构

四、JavaBean对象封装

public class UserQuery {
  private String name;
  private Integer age;
  // 省略getter/setter
}

User selectUserByBean(UserQuery query);

<select id="selectUserByBean" resultType="User">
  SELECT * FROM user 
  WHERE name = #{name} AND age = #{age}
</select>

架构优势：

• 强类型校验：编译期发现参数类型错误
• 业务语义明确：参数对象命名反映查询意图
• 扩展性强：新增参数只需修改JavaBean

对象嵌套处理：

public class AdvancedQuery {
  private UserQuery user;
  private Date createTimeRange;
}

// XML中使用：#{user.name}

五、参数自动装箱机制

User selectUser(@Param("name") String name, int age);

<!-- 混合使用命名参数和位置参数 -->
WHERE name = #{name} AND age = #{param2}

装箱规则：

1. 当使用@Param注解时，参数会同时存在于两种命名空间：
   • 注解定义的名称
   • param1, param2,...的索引名称
2. 未注解参数默认使用param索引命名

危险操作：

<!-- 错误示范：混合命名方式导致维护困难 -->
WHERE name = #{name} AND age = #{param2} AND status = #{param3}

六、集合类型参数处理

List传参示例：

List<User> batchSelect(@Param("ids") List<Long> ids);

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

Map高级用法：

void updateProfile(@Param("params") Map<String, Object> updates);

<update id="updateProfile">
  UPDATE user
  <set>
    <foreach collection="params" index="key" item="value" separator=",">
      ${key} = #{value}
    </foreach>
  </set>
  WHERE id = #{userId}
</update>

七、多参数动态SQL技巧

条件分支处理：

<select id="dynamicSearch" resultType="User">
  SELECT * FROM user
  <where>
    <if test="name != null">
      AND name LIKE CONCAT(#{name}, '%')
    </if>
    <if test="minAge != null">
      AND age >= #{minAge}
    </if>
    <if test="maxAge != null">
      AND age &lt;= #{maxAge}
    </if>
  </where>
  ORDER BY create_time DESC
</select>

参数类型检查：

<if test="type == 'VIP'.toString()">
  AND membership_level > 3
</if>

八、参数处理器扩展

自定义类型处理器示例：

@MappedTypes(PhoneNumber.class)
public class PhoneTypeHandler extends BaseTypeHandler<PhoneNumber> {
  @Override
  public void setNonNullParameter(PreparedStatement ps, int i, 
      PhoneNumber parameter, JdbcType jdbcType) {
    ps.setString(i, parameter.getValue());
  }
  // 其他方法实现...
}

注册自定义处理器：

<typeHandlers>
  <typeHandler handler="com.example.PhoneTypeHandler"/>
</typeHandlers>

九、性能优化关键点

1. 参数缓存策略：

   • MyBatis使用ParamNameResolver缓存参数元数据
   • 避免频繁创建参数Map，推荐复用参数对象

2. 批量操作优化：

@Insert("<script>INSERT INTO user (name, age) VALUES " +
    "<foreach collection='users' item='user' separator=','>" +
    "(#{user.name}, #{user.age})</foreach></script>")
void batchInsert(@Param("users") List<User> users);

3. 类型转换优化：
   • 优先使用基本类型参数（int vs Integer）
   • 避免不必要的类型转换开销

十、常见陷阱与解决方案

陷阱1：参数命名冲突

// 错误示例
User select(@Param("user") User user, @Param("name") String name);

WHERE username = #{name} AND ... <!-- 与user.name冲突 -->

解决方案：使用明确的命名空间

WHERE username = #{name} AND department = #{user.dept}

陷阱2：集合参数空值

List<User> searchUsers(@Param("ids") List<Long> ids);

<if test="ids != null and ids.size() > 0">
  ...
</if>

改进方案：使用MyBatis内置方法

<if test="ids != null and !ids.isEmpty()">
  ...
</if>

陷阱3：日期参数处理

// 需要明确指定jdbcType
void updateTime(@Param("time") Date time);

#{time, jdbcType=TIMESTAMP}

十一、Spring Boot集成最佳实践

1. 配置参数别名：

mybatis.type-aliases-package=com.example.model

2. 自动映射配置：

@Configuration
public class MyBatisConfig {
  @Bean
  public ConfigurationCustomizer configurationCustomizer() {
    return configuration -> {
      configuration.setMapUnderscoreToCamelCase(true);
      configuration.setDefaultFetchSize(100);
    };
  }
}

3. 参数校验集成：

@Validated
public interface UserMapper {
  User selectByAge(@Min(1) @Max(150) int age);
}

十二、未来演进方向

1. 响应式编程支持：MyBatis 3.5+支持RxJava
2. 注解增强：@Lang注解支持动态SQL
3. Kotlin DSL支持：类型安全的SQL构建

通过深入理解这些参数传递机制，开发者可以编写出更健壮、更高效的MyBatis代码。在实际项目中，建议根据以下标准选择传参方式：

• 参数数量：<=3使用@Param，>3使用JavaBean
• 复用频率：高频复用参数封装为对象
• 业务场景：动态查询推荐Map或参数对象