系列文章目录

MyBatis缓存原理
Mybatis plugin 的使用及原理
MyBatis+Springboot 启动到SQL执行全流程
数据库操作不再困难，MyBatis动态Sql标签解析
Mybatis的CachingExecutor与二级缓存
使用MybatisPlus还是MyBaits ，开发者应该如何选择？
巧用MybatisPlus的SQL注入器提升批量插入性能

---

前几天组内一名同事在项目中发现了一个报错：Parameter 'id' not found. Available parameters are [userId, param1]，说白了也就是也就是在xml中使用'id'参数，但实际上Mapper层方法却用的@Param("userId")，这就是明显对MyBtais的参数映射不太了解了。相信这一部分内容同样有不少同学是疏忽的，那么本期我们来看一下@Param注解的使用与原理

📕作者简介：战斧，从事金融IT行业，有着多年一线开发、架构经验；爱好广泛，乐于分享，致力于创作更多高质量内容
📗本文收录于 MyBatis专栏 专栏，有需要者，可直接订阅专栏实时获取更新
📘高质量专栏 云原生、RabbitMQ、Spring全家桶 等仍在更新，欢迎指导
📙Zookeeper Redis kafka docker netty等诸多框架，以及架构与分布式专题即将上线，敬请期待

---

一、MyBatis 里 SQL执行的过程

1. 核心对象 BoundSql

我们之前其实多次讨论 MyBatis 里执行SQL的原理： MyBatis+Springboot 启动到SQL执行全流程，这里我们再简单复习。其简要步骤就是
获取会话-> 会话执行-> 执行器执行 -> statement -> jdbc

我们主要来看这一段：

在真正执行SQL的时候，我们拿到了MapperStatement后，还需要做三步：
① 把可执行的语句准备好，注意此时SQL没有参数；
② 把外界提供的参数进行整理与保存
③ 把整理好的入参，按一定规则代入上述SQL的指定位置

其实前两步，它们会构成这样一个对象：

// StaticSqlSource.java@Overridepublic BoundSql getBoundSql(Object parameterObject) {// sql 就是缺参数的可执行SQL// parameterMappings 是从xml解析出来的所需要的参数列表// parameterObject 实际执行到该方法的参数内容return new BoundSql(configuration, sql, parameterMappings, parameterObject);}public BoundSql(Configuration configuration, String sql, List<ParameterMapping> parameterMappings, Object parameterObject) {this.sql = sql;this.parameterMappings = parameterMappings;this.parameterObject = parameterObject;// additionalParameters 部分只有动态SQL才会用到this.additionalParameters = new HashMap<>();this.metaParameters = configuration.newMetaObject(additionalParameters);}

这个对象中含有MyBatis配置、对应SQL，SQL中需要的参数，现在实际提供的参数，那么我们现在只需要关注 SQL中需要的参数 和 现在实际提供的参数 即可

2. 解析出 parameterMappings

parameterMappings 实际保存的就是 从xml解析出的关于SQL所需要的参数列表，这个所需参数的对象由下面几个属性构成：

List<ParameterMapping> parameterMappings;public class ParameterMapping {private String property;private ParameterMode mode;private Class<?> javaType = Object.class;private JdbcType jdbcType;private Integer numericScale;private TypeHandler<?> typeHandler;private String resultMapId;private String jdbcTypeName;private String expression;}

在一般场景下，最核心的就是 property ParameterMode 和 jdbcType 三个字段了，比如说我们在xml里如果写了这样一段SQL

<select id="findUserById" resultType="com.zhanfu.springboot.demo.entity.User" parameterType="int">SELECT * FROM user where id =#{idy}
</select>

此时我们只需要一个参数，因此解析出来只会有一个 ParameterMapping ：
① 它的 property 就是我们设定的变量名 ‘idy’，
② ParameterMode 是参数模式，我们这里是入参，也就是 ‘IN’ ；除此以外还有 ‘OUT’ 和 ‘INOUT’
③ jdbcType 因为我们指定了参数的 parameterType， javaType 就是 Integer

3. 整理方法入参 parameterObject

刚刚我们说了，parameterObject 就是我们实际提供的参数，也就是我们实际调用Mapper方法时传入的参数组，直白的说，MyBatis会把我们传入的参数数组转化为一个参数Map对象，key是参数名，value是参数值。

  // MapperMethod.java // Mapper层代理类执行方法时调用的就是此类Object param = method.convertArgsToSqlCommandParam(args);result = sqlSession.selectOne(command.getName(), param);// 将传入方法的arg数组，转为一个参数对象，实际上就是一个HashMappublic Object convertArgsToSqlCommandParam(Object[] args) {return paramNameResolver.getNamedParams(args);}

对于这个Map，参数值自然是我们传的参数值，而参数名是怎么获取的，又有什么规则呢? 我们来看下所谓的 name 是怎么设计的。

 // ParamNameResolver.javapublic ParamNameResolver(Configuration config, Method method) {this.useActualParamName = config.isUseActualParamName();final Class<?>[] paramTypes = method.getParameterTypes();final Annotation[][] paramAnnotations = method.getParameterAnnotations();final SortedMap<Integer, String> map = new TreeMap<>();int paramCount = paramAnnotations.length;// get names from @Param annotationsfor (int paramIndex = 0; paramIndex < paramCount; paramIndex++) {if (isSpecialParameter(paramTypes[paramIndex])) {// skip special parameterscontinue;}String name = null;for (Annotation annotation : paramAnnotations[paramIndex]) {if (annotation instanceof Param) {hasParamAnnotation = true;name = ((Param) annotation).value();break;}}if (name == null) {// @Param was not specified.if (useActualParamName) {name = getActualParamName(method, paramIndex);}if (name == null) {// use the parameter index as the name ("0", "1", ...)// gcode issue #71name = String.valueOf(map.size());}}map.put(paramIndex, name);}names = Collections.unmodifiableSortedMap(map);}

从上述代码中，我们看到了所谓参数name的制取流程，对于每一个参数，其实都分为三个优先级:
①优先取@Param里的value值作为参数名;
②其次如果myBtais的配置里配置了 useActualParamName = true（默认是开启的）， 则取方法中写的形参名;
③如果上述都没有值，最后取该参数在所有入参中的序号，从0开始，计值0，1，2…作为参数的名称

 public Object getNamedParams(Object[] args) {final int paramCount = names.size();if (args == null || paramCount == 0) {return null;} else if (!hasParamAnnotation && paramCount == 1) {// 仅有一个参数，且该参数没有使用 @Param注解Object value = args[names.firstKey()];return wrapToMapIfCollection(value, useActualParamName ? names.get(0) : null);} else {// 对于一般场景，则会为参数提供两个名称，一个是我们上面获取的名称，一个是‘param+序号’的名称final Map<String, Object> param = new ParamMap<>();int i = 0;for (Map.Entry<Integer, String> entry : names.entrySet()) {param.put(entry.getValue(), args[entry.getKey()]);// add generic param names (param1, param2, ...)final String genericParamName = GENERIC_NAME_PREFIX + (i + 1);// ensure not to overwrite parameter named with @Paramif (!names.containsValue(genericParamName)) {param.put(genericParamName, args[entry.getKey()]);}i++;}return param;}}// 如果参数是集合，则构建map，形成<参数名, 参数值>的map, 并且额外为参数补充如 ‘list’、‘collection’ 这样的的参数名；
// 如果不是集合，直接返回对象public static Object wrapToMapIfCollection(Object object, String actualParamName) {if (object instanceof Collection) {ParamMap<Object> map = new ParamMap<>();map.put("collection", object);if (object instanceof List) {map.put("list", object);}Optional.ofNullable(actualParamName).ifPresent(name -> map.put(name, object));return map;} else if (object != null && object.getClass().isArray()) {ParamMap<Object> map = new ParamMap<>();map.put("array", object);Optional.ofNullable(actualParamName).ifPresent(name -> map.put(name, object));return map;}return object;}

通过对源码的分析，我们不难看出对参数的处理其实分成了两种逻辑：

（1） 整理结果1： 仅有一个参数，且该参数没有使用 @Param注解

• 此时，如果该参数是集合类型的，则还是构建一个<参数名，参数值>这样的map，把参数及其名称放入其中。而且还给他补充几个参数名， 如 ‘list’、‘collection’，当然参数值都是一样的。这样，该参数其实就有多个别名了。
• 如果该参数不是集合，就直接使用参数值本体，而不再使用map的形式

（2） 整理结果2：（即有多个参数，或者有参数使用了@Param注解）

• 构建一个<参数名，参数值>这样的map，使用我们上面获取到的参数名，同时为每一个参数添加一个别名，即param1, param2 等。

总结的说，就是如果你这个方法仅有一个参数，且参数不是集合，而我们也没有使用@Param，那它就会直接使用这个参数值。除此以外我们的参数值全部是以map的形式存储的，而参数名正是我们的@Param的值、方法形参名，或者单纯的次序号‘0’、‘1’、‘2’；除了这些参数名外，Mybatis还会为我们增加这些参数的别名，如param1, param2等。

4. 参数的代入

我们现在知道了需要的参数，也整理好了方法的入参，那接下来自然就是把参数代入SQL的指定位置了，它的核心方法如下：

  // DefaultParameterHandler.javapublic void setParameters(PreparedStatement ps) {ErrorContext.instance().activity("setting parameters").object(mappedStatement.getParameterMap().getId());List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();if (parameterMappings != null) {for (int i = 0; i < parameterMappings.size(); i++) {ParameterMapping parameterMapping = parameterMappings.get(i);if (parameterMapping.getMode() != ParameterMode.OUT) {Object value;String propertyName = parameterMapping.getProperty();if (boundSql.hasAdditionalParameter(propertyName)) { // issue #448 ask first for additional paramsvalue = boundSql.getAdditionalParameter(propertyName);} else if (parameterObject == null) {value = null;} else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {value = parameterObject;} else {MetaObject metaObject = configuration.newMetaObject(parameterObject);value = metaObject.getValue(propertyName);}TypeHandler typeHandler = parameterMapping.getTypeHandler();JdbcType jdbcType = parameterMapping.getJdbcType();if (value == null && jdbcType == null) {jdbcType = configuration.getJdbcTypeForNull();}try {typeHandler.setParameter(ps, i + 1, value, jdbcType);} catch (TypeException | SQLException e) {throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e);}}}}}

不难看出，他就是遍历SQL里每一个需要参数的位置，然后再去我们整理的入参中去找合适的，把入参的值填入该位置：这一步其实含有不少细节，我们把它做个梳理，找参数值可以按照方法里的逻辑归纳为3个优先级：

• 代入场景1：优先去 AdditionalParameter 找有没有符合的参数，AdditionalParameter 是动态SQL的产物，它
• 代入场景2：直接使用 parameterObject 作为参数值 ，注意直接使用 parameterObject 仅会发生在方法仅有一个非集合参数的情况下，上面我们已经讲过，此时parameterObject 就是入参传的对象；① 若入参为 null 则 parameterObject 为 null ; ② 若 parameterObject 不为 null 且是简单类型，能直接被Mybatis 处理则直接将其处理，得到参数值
• 代入场景3：从 parameterObject 中找符合的参数，注意此种情况下，parameterObject 其实是一个复杂对象 或者是 map，需要根据所需参数名，在 对象 中或者 map 找到对应的参数值。

5. 动态SQL的特殊处理

我们上面说的其实是静态SQL的处理逻辑，而我们也曾介绍过动态SQL，可见《数据库操作不再困难，MyBatis动态Sql标签解析》。

静态SQL比较简单，给参数预留的位置与个数是一目了然，不会变的，只要从xml里写的SQL里进行解析就好了。
而动态SQL则不然，动态SQL直到执行前一刻，获取到了入参，结合了入参的情况才能确定SQL需要几个参数，以及参数的位置。

因此在获取了BoundSql 后，还需要对 BoundSql 做一步操作

  public BoundSql getBoundSql(Object parameterObject) {DynamicContext context = new DynamicContext(configuration, parameterObject);// 结合xml的动态SQL标签，以及当前入参的情况，构造出动态SQL，// 并整理SQL内需要的参数个数及位置，将信息保存在 上下文的binding 中rootSqlNode.apply(context);SqlSourceBuilder sqlSourceParser = new SqlSourceBuilder(configuration);Class<?> parameterType = parameterObject == null ? Object.class : parameterObject.getClass();SqlSource sqlSource = sqlSourceParser.parse(context.getSql(), parameterType, context.getBindings());// 获取了 boundSql BoundSql boundSql = sqlSource.getBoundSql(parameterObject);// 处理 boundSql ，将动态上下文的 binding 部分赋值给 boundSql 的 AdditionalParameters 中context.getBindings().forEach(boundSql::setAdditionalParameter);return boundSql;}

比方说对于这样一个接口 及其 xml

boolean batchAddUser(List<User> userList)

<insert id="batchAddUser" parameterType="com.zhanfu.springboot.demo.entity.User">insert into user(id,username,password) values<foreach collection="list" item="user" separator=",">(#{user.id}, #{user.username}, #{user.password})</foreach>
</insert>

就利用了 动态标签，此时如果我们插入两条数据（list 长度等于2），上下文的bing 部分就会变成如下。我们主要关系上面的 __frch_user_0 以及 __frch_user_1 。这两条就是结合原SQL与入参情况产生的新SQL中，所需要储存着的参数名 - 参数值映射关系。

二、@Param注解在各场景下的效果

1. 单个参数 - 简单类型

（1）加@Param注解之前

此时 Mapper 层方法为：

User findUserById(int id)

此时xml语句为：

<select id="findUserById" resultType="com.zhanfu.springboot.demo.entity.User" parameterType="int">SELECT * FROM user where id =#{id}
</select>

此时我们的入参是单个的简单对象，所以会使用整理结果1，导致 parameterObject 就直接是我们的 id 对象（基础类型会变为包装类型Integer）， 而 parameterMappings 需要的参数为一个，即‘id’，所以最终走入代入场景2，直接把我们传入的id，放进SQL中的 #{id} 位置，值得一提的是，此时其实根本没有用到parameterMapping里的属性名，也就是说，即使xml中你的SQL写的是

<select id="findUserById" resultType="com.zhanfu.springboot.demo.entity.User" parameterType="int">SELECT * FROM user where id =#{niuAAAAAA}
</select>

也没事，仍然能把外界传的id，放进 #{niuAAAAAA} 这个位置

（2）加@Param注解之后

此时 Mapper 层方法为：

User findUserById(@Param("id")int id);

此时xml语句为：

<select id="findUserById" resultType="com.zhanfu.springboot.demo.entity.User" parameterType="int">SELECT * FROM user where id =#{id}
</select>

此时因为加入了@Param，所以会使用整理结果2，导致 parameterObject 成为了一个map，内含两个键值对，两个键值对的 value 值都是我们传入的 id 对象，而 key 值一个是我们设定的参数名 ‘idr’，一个是Mybatis 为我们加的别名 ‘param1’

所以此时会进入代入场景3，然后从 map 中以 ‘id’ 去取值。就取到了我们的传入的 id 对象。因此在这种情况下，我们的 #{id} 就不能写成 #{niuAAAAAA} 了，必须和 @Param 注解里写的参数名保持一致

2. 单个参数 - 复杂对象

（1）加@Param注解之前

此时 Mapper 层方法为：

boolean addUser(User user)

此时xml语句为：

 <insert id="addUser" parameterType="com.zhanfu.springboot.demo.entity.User" >insert  into user(id,username,password) values (#{id},#{username},#{password})
</insert>

此时我们的入参是单个的对象，且没有使用@Param， 所以会使用整理结果1，导致 parameterObject 就直接是我们的 user 对象， 而 parameterMappings 需要的参数为三个，即‘id’ 、‘username’ 、 ‘password’，

所以最终则会循环走入代入场景3，然后从我们的入参对象中分别取出 ‘id’ 、‘username’ 、 ‘password’，更具体的，其获取值的方式自然是使用对象的get属性值的方法。注意，如果你使用的是@lombok来自动补足get set方法的话，需要注意里面的一些坑，详情见《【问题处理】—— lombok 的 @Data 大小写区分不敏感》

（2）加@Param注解之后

此时 Mapper 层方法为：

boolean addUser(@Param("user") User user);

此时xml语句为：

 <insert id="addUser" parameterType="com.zhanfu.springboot.demo.entity.User" >insert  into user(id,username,password) values (#{id},#{username},#{password})
</insert>

此时我们的入参是单个的复杂对象，但因为加入了@Param，所以会使用整理结果2，导致 parameterObject 成为了一个map，内含两个键值对，两个键值对的 value 值都是我们传入的 user 对象，而 key 值一个是我们设定的参数名 ‘user’，一个是Mybatis 为我们加的别名 ‘param1’

此时同样的 parameterMappings 需要的参数为三个，所以还是会循环走入代入场景3，然后从 map 中以 ‘id’ 去取值。自然，我们都知道，map 里此时并没有一个key 值叫 ‘id’，所以这样的使用方式最终会报错 Parameter 'id' not found. Available parameters are [user, param1].如果这种场景下一定要使用@Param注解，则需要将xml语句写成

<insert id="addUser" parameterType="com.zhanfu.springboot.demo.entity.User" >insert  into user(id,username,password) values (#{user.id},#{user.username},#{user.password})
</insert>

MyBatis能自动以 . 为界进行分割，前面的部分作为对象，后面作为属性不断递归，此处就能获取 user 对象的 id 属性了。

3. 多个参数

（1）加@Param注解之前

此时 Mapper 层方法为：

User findUser(int id, String name)

此时xml语句为：

<select id="findUser" resultType="com.zhanfu.springboot.demo.entity.User">SELECT * FROM user where id =#{id} and username =#{name}
</select>

此时我们的入参是多个对象， 所以会使用整理结果2，导致 parameterObject 成为了一个map，.内含四个键值对，如下：其中“name” 、“id” 键值对是来源于形参名， ‘param1’、 ‘param2’ 是MyBtais为我们添加的别名

而 parameterMappings 需要的参数为三个，即‘id’ 、‘name’

所以最终则会循环走入代入场景3，然后从我们的map中分别取出 ‘id’ 、‘name’ ，放入对应的位置，因此此时必须要保证 #{id} 与方法的 User findUser(int id, String name) 形参名 id 是同样的，不能随便写。

（2）加@Param注解之后

此时 Mapper 层方法为：

User findUser(@Param("id")int id, @Param("name")String name)

此时xml语句为：

<select id="findUser" resultType="com.zhanfu.springboot.demo.entity.User">SELECT * FROM user where id =#{id} and username =#{name}
</select>

此时我们的入参是多个对象， 所以会使用整理结果2，最终 parameterObject 成为了一个map，.内含四个键值对，如下：其中“name” 、“id” 键值对是来源于我们@Param里填的字符串， ‘param1’、 ‘param2’ 是MyBtais为我们添加的别名

最终它的表现是和没加@Param一致的，同样会循环走入代入场景3，然后从 map 中以 ‘id’ 、‘name’ 去取值。

4. 集合参数与动态SQL

我们向集合中添加两个User元素，然后调用Mapper

（1）加@Param注解之前

此时 Mapper 层方法为：

boolean batchAddUser(List<User> userList);

此时xml语句为：

<insert id="batchAddUser" parameterType="com.zhanfu.springboot.demo.entity.User">insert into user(id,username,password) values<foreach collection="list" item="user" separator=",">(#{user.id}, #{user.username}, #{user.password})</foreach>
</insert>

此时我们的入参是个单独对象，没有@Param，所以会使用整理结果1，但因为对象是集合类型，最终 parameterObject 还是成为了一个map，需要注意的是，此时除了 还有了一个parameterObject ，还有 additionalParameters 如下:

而从动态SQL中解析出的 parameterMappings 需要的参数为2 * 3 = 6个，如下：

因为有了 additionalParameters ，所以最终则会循环走入代入场景1，即从 additionalParameters 获取 __frch_user_0.username。这样也是可以取到的，和我们最开始取user.id是一样的。

需要注意的是，我们在 xml 中的动态SQL里使用了 collection=“list” ，这里也不是乱填的，list 正是parameterObject 的三个key 之一，因此此处还可以替换成 collection=“collection” 、collection = ”userList“

（2）加@Param注解之后

此时 Mapper 层方法为：

boolean batchAddUser(@Param("uList")List<User> userList);

此时xml语句为：

<insert id="batchAddUser" parameterType="com.zhanfu.springboot.demo.entity.User">insert into user(id,username,password) values<foreach collection="uList" item="user" separator=",">(#{user.id}, #{user.username}, #{user.password})</foreach>
</insert>

此时我们的入参是个单独对象，有@Param。所以会使用整理结果2，导致 parameterObject 成为了一个map，也还有 additionalParameters， 如下:

而从动态SQL中解析出的 parameterMappings 需要的参数还是一样的，为2 * 3 = 6个，如下：

因为有了 additionalParameters ，所以最终则会循环走入代入场景1，即从 additionalParameters 获取 __frch_user_0.username。

此时不同的因为parameterObject 里现在的key 只有 ‘ulist’ 和 ‘param1’ ，所以我们的动态SQL里使用的 collection=“ulist” ,就只能填这个或 collection=“param1” 了。

三、总结

本次的涉及的知识点比较琐碎，如果刨去动态SQL的那部分来说，我们其实可以归纳一下 @Param 注解的作用：就是对方法的参数名做一个重命名:

①使用了 @Param("AAA")，就需要在xml中使用到参数的部分，也与此保持一致，如#{AAA}
②特别的，对于方法仅有一个入参对象（如User对象）的情况，如果你使用了 @Param("AAA")，那么你在xml中，如果要使用对象的属性，如User对象的id属性，那就只能使用#{AAA.id}。如果你此时不使用 @Param 注解，在xml中反而能直接使用 #{id} 来表示入参的id属性