mybatis多参数传递报错问题分析+硬核mybatis底层源码分析+@Param注解+图文实战环境分析【4500字详解打通，没有比这更详细的了！】

1.问题描述

❗操作 mybatis 时报错：org.apache.ibatis.binding.BindingException: Parameter ‘tableName’ not found. Available parameters are [arg1, arg0, param1, param2]

2.问题场景模拟再现

2.1 场景环境

• Maven
• MySQL 8.0.30

2.2 数据库与表创建

在本机 MySQL 中执行：

create database mybatis_demo;

use mybatis_demo;

create table `user`(
	id int primary key auto_increment comment '主键',
	`name` varchar(20) not null comment '姓名',
	sex char(1) not null comment '性别：男或女',
	age tinyint unsigned not null comment '年龄'
);

insert into `user`(`name`,sex,age) values
('狐狸半面添','男',20),
('浪浪','女',18),
('浪浪','女',20);

2.3 Maven环境搭建

🍀 pom.xml导入依赖

<!-- junit单元测试 -->
<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.11</version>
    <scope>test</scope>
</dependency>
<!-- MySQL驱动 -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.31</version>
</dependency>
<!-- MyBatis -->
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.11</version>
</dependency>
<!-- lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.24</version>
</dependency>

🍀 jdbc.properties

在 resources 目录下新建 jdbc.properties 配置文件。

db.driver=com.mysql.cj.jdbc.Driver
db.url=jdbc:mysql://localhost:3306/mybatis_demo?serverTimezone=GMT%2B8
db.username=root
db.password=123456

🍀 mybatis-config.xml

在 resources 目录下新建 mybatis-config.xml 配置文件。

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
        PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    <!-- properties 标签使用 resource 属性引入 jdbc.properties 配置文件 -->
    <properties resource="jdbc.properties"/>
    
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <!--设置驱动类的全类名-->
                <property name="driver" value="${db.driver}"/>
                <!--设置连接数据库的连接地址-->
                <property name="url" value="${db.url}"/>
                <!--设置连接数据库的用户名-->
                <property name="username" value="${db.username}"/>
                <!--设置连接数据库的密码-->
                <property name="password" value="${db.password}"/>
            </dataSource>
        </environment>
    </environments>
    <!--引入映射文件-->
    <mappers>
         <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

🍀 User实体类

在 java 目录下新建 User 类。

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * @author 狐狸半面添
 * @create 2023-07-02 1:24
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    /**
     * 主键 id
     */
    private Integer id;
    /**
     * 姓名
     */
    private String name;
    /**
     * 性别：男或女
     */
    private Character sex;
    /**
     * 年龄
     */
    private Integer age;
}

🍀 Mapper 接口

在 java 目录下新建 UserMapper 接口。

import java.util.List;

/**
 * @author 狐狸半面添
 * @create 2023-07-02 1:27
 */
public interface UserMapper {
    /**
     * 通过 姓名 与 性别 查询所有匹配的用户信息
     *
     * @param name 姓名
     * @param sex  性别
     * @return 用户信息列表
     */
    List<User> selectByNameAndSex(String name, Character sex);
}

🍀 UserMapper.xml 映射文件

在 resources 目录下创建 mapper 目录，再在 mapper 目录下 新建 UserMapper.xml 映射文件。

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<!-- namespace：指定该映射文件对应的持久层接口路径，绑定 mapper.xml 与对应的mapper接口的关系 -->
<mapper namespace="UserMapper">

    <select id="selectByNameAndSex" resultType="User">
        SELECT *
        FROM `user`
        WHERE `name` = #{name}
          and sex = #{sex}
    </select>
</mapper>

2.4 测试报错

我们在 test / java 目录下创建 UserMapperTest.class 测试类。

import org.apache.ibatis.session.SqlSession;
import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.session.SqlSessionFactoryBuilder;
import org.junit.Test;

import java.io.IOException;
import java.io.InputStream;
import java.util.List;

import static org.apache.ibatis.io.Resources.getResourceAsStream;

/**
 * @author 狐狸半面添
 * @create 2023-07-02 1:35
 */
public class UserMapperTest {
    private final static SqlSession sqlSession;

    static {
        // 1.读取 MyBatis 的核心配置文件
        InputStream is = null;
        try {
            is = getResourceAsStream("mybatis-config.xml");
        } catch (IOException e) {
            throw new RuntimeException(e);
        }

        SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(is);
        sqlSession = sqlSessionFactory.openSession(true);
    }

    @Test
    public void testSelect() {
        UserMapper userMapper = sqlSession.getMapper(UserMapper.class);
        List<User> users = userMapper.selectByNameAndSex("浪浪",'女');

        users.forEach(System.out::println);
    }
}

执行 testSelect 测试方法，则会报错：

3.问题分析

3.1 SQL解析原理

List<Student> selectByNameAndSex(String name,Character sex);

共有两个参数：name 与 sex。这是 多参数 的参数传递，那么 mybatis 框架底层怎么做的呢？

实际上，在不给形参加 @param 注解的情况下，每次调用该 selectByNameAndSex 方法时，mybatis 框架都会自动创建一个 map 集合用于存储实际参数，而每个实参都会用 两个键值对进行存储，例如我们传的 name 是 “浪浪”，sex 是 ‘女’，则该 map 集合存储内容为：

map.put("arg0", "浪浪");
map.put("param1", "浪浪");
map.put("arg1", '女');
map.put("param2", '女');

然后 mybatis 在解析我们编写的 SQL 语句时，会从 map 集合中根据 key 去取出数据，替换 SQL 中的 #{...} 或 ${...} 占位符。

例如对于我们在 UserMapper.xml 中写的 SQL 语句：

SELECT * FROM `user` WHERE `name` = #{name} and sex = #{sex}

mybatis 会先从 map 集合中找 key 为 name 的键值对，然而肯定是不存在的，因为只有 key 为 arg0、arg1、param1、param2 。因此从集合中获取到的就是 null 。mybatis 发现了查询为 null，则报错：

org.apache.ibatis.binding.BindingException: Parameter ‘name’ not found. Available parameters are [arg1, arg0, param1, param2]

翻译过来就是：参数 name 没有找到，只有参数为 arg0、arg1、param1、param2 的。

所以我们将映射文件中的 SQL 修改为：

SELECT * FROM `user` WHERE `name` = #{arg0} and sex = #{param2}

这时候就能够顺利查询成功了：

🚩 实现原理总结：实际上在 mybatis 底层会创建一个 map 集合，以 arg0/param1 为key，以方法上的参数为value 。

3.2 mybatis底层源码追踪之map集合创建

前提：本次源码追踪是建立在 第二小节 《问题场景模拟再现》 的基础上，即为 多参数传递 。

我们需要找到创建 map 结合的方法，先通过 ctrl + N 快捷键进行全局类搜索，输入 ParamNameResolver：

找到 ParamNameResolver 类的 getNamedParams 方法，此方法就是用于创建 map 集合，并将此集合作为方法的返回值。

我们在此方法中标记一个断点，对我们的测试方法 testSelect() 进行 debug 调试，便会进入 getNamedParams 方法。

// args 是一个数组，内容为我们传的实际参数：["浪浪", '女']
public Object getNamedParams(Object[] args) {
    /*
    	this.names 也是一个 map 集合，存储的键值对为：
    		1 - arg0
    		2 - arg1
    	
    	因此得到的 paramCount 就是 2，这实际上是统计的 Mapper接口方法的形参个数
    */
    int paramCount = this.names.size();
    
    // 如果存在实参并且形参个数不是0
    if (args != null && paramCount != 0) {
        
        // 如果形参上没有 @Param 注解 并且 形参的个数是 1，就走 if 语句，否则走 else 语句
        // 显然，我们的接口方法：List<User> selectByNameAndSex(String name,Character sex);
        // 是没有 @Param 注解的，但是形参个数为 2，因此 if 语句不成立，执行 else
        if (!this.hasParamAnnotation && paramCount == 1) {
            // 不执行
            
            Object value = args[(Integer)this.names.firstKey()];
            return wrapToMapIfCollection(value, this.useActualParamName ? (String)this.names.get(0) : null);
        } else {
            // 执行
            
            // 创建一个 map 集合，最终返回该 map 集合作为 SQL 解析的占位参数的真实数据来源
            Map<String, Object> param = new MapperMethod.ParamMap();
            
            int i = 0;

            // 迭代器遍历 this.names 这个 map 集合的键值对，我们以第一次循环为例。
            for(Iterator var5 = this.names.entrySet().iterator(); var5.hasNext(); ++i) {
                // 获取一个 键值对，例如第一次循环中，entry.key = 0，entry.value = "arg0"
                Map.Entry<Integer, String> entry = (Map.Entry)var5.next();
                /*
                	(String)entry.getValue() 结果是 "arg0"
                	args[(Integer)entry.getKey()] 即 args[0] ，结果是 "浪浪"
                	因此存入 param 的键值对就是 param.put("arg0", "浪浪")
                */
                param.put((String)entry.getValue(), args[(Integer)entry.getKey()]);
                
                // 设置 genericParamName 为 "param1"
                String genericParamName = "param" + (i + 1);
                
                // 查询 names 中是否包含 value值 为 param1 的键值对，在这里当然是不包含的，因此 if 成立
                if (!this.names.containsValue(genericParamName)) {
                    /*
                    	genericParamName 结果是 "param1"
                    	args[(Integer)entry.getKey()] 即 arg[0] ，结果是 "浪浪"
                    	因此存入 param 的键值对就是 param.put("param1", "浪浪")
                    */
                    param.put(genericParamName, args[(Integer)entry.getKey()] 即 arg[0] ，结果是 "浪浪");
                }
            }
            
            /*
            	以上的 for 循环遍历完毕后，param 集合中存储的键值对为：
            		"arg0" - "浪浪"
            		"param1" - "浪浪"
            		"arg1" - '女'
            		"param2" - '女'
            */

            // 返回这个 map 集合
            return param;
        }
    } else {
        return null;
    }
}

4.问题最佳解决方案-@Param

可以不用 arg0 arg1 param1 param2 吗？这个 map 集合的 key 我们自定义可以吗？

当然可以，其实在配置 SQL 映射时，使用 arg0 、arg1 或 param1 、param2 这样的名称，并不利于我们对代码的阅读和理解，所以 Mybatis 框架提供了 @Param 注解，可以在抽象方法的参数列表中，在每个参数之前添加该注解，并在注解中配置参数的名称，该名称就可以在 SQL 中作为占位参数 使用。这样就增强了代码可读性。

List<User> selectByNameAndSex(
    @Param("userName") String name,
    @Param("userSex") Character sex
);

<!--
    使用了 @Param 注解之后，arg0 和 arg1 失效了
    但 param1 和 param2 还可以用，但其实使用了@Param 注解，再使用 param1 和 param2 也没有什么意义了
-->
<select id="selectByNameAndSex" resultType="User">
    SELECT *
    FROM `user`
    WHERE `name` = #{userName}
      and sex = #{userSex}
</select>

⚠️ 需要注意的是，使用了 @Param 注解之后，arg0 和 arg1 失效了，但 param1 和 param2 还可以使用。这是为什么呢？我们再次看下 map 集合创建方法的源码：

所以最终 map 集合的键值对添加顺序为：

map.put("userName", "浪浪");
map.put("param1", "浪浪");

map.put("userSex", '女');
map.put("param2", '女');

然后解析 SQL 时，遇到 占位参数 则会以 占位参数 作为 key 去 map 集合中查询对应的 value，以替换 占位参数。

🚩 核心：@Param(“**这里填写的其实就是 map 集合的 key **”)

5.一张图解释源码

6.拓展-单参数情况

当抽象方法的参数只有 1 个时，MyBatis 会自动的使用唯一的那一个参数，所以，在配置SQL映射时，使用的 #{} 占位符中的占位参数名称根本就不重要！在开发时，推荐使用规范的名称，但是，从代码是否可以运行的角度来说，这个占位符中写什么都不重要！

我们举一个例子来说明这件事：

• Mapper 接口方法：

  User selectById(Integer id);
  

• UserMapper.xml 映射文件配置：

  <select id="selectById" resultType="User">
      SELECT * FROM `user` WHERE id = #{langLang}
  </select>
  

• 测试方法：

  @Test
  public void testSingleSelect(){
      UserMapper userMapper = sqlSession.getMapper(UserMapper.class);
      User user = userMapper.selectById(2);
      System.out.println(user);
  }
  

很明显，我们在 UserMapper.xml 映射文件中配置的 #{} 中占位参数 langLang 是一个我们从没有见过的参数名，但执行测试方法却能够执行成功查询到 id 为 2 的 数据信息。

关于底层实现，我们依旧以 debug 的方式先来看下 创建 map 集合的 getNamedParams 方法。

// args 是一个数组，内容为我们传的实际参数：[2]
public Object getNamedParams(Object[] args) {
    /*
    	this.names 也是一个 map 集合，存储的键值对为：
    		0 - arg0
    	
    	因此得到的 paramCount 就是 1，这实际上是统计的 Mapper接口方法的形参个数
    */
    int paramCount = this.names.size();
    
    // 如果存在实参并且形参个数不是0
    if (args != null && paramCount != 0) {
        // 如果形参上没有 @Param 注解 并且 形参的个数是 1，就走 if 语句，否则走 else 语句
        // 显然，我们的接口方法：User selectById(Integer id);
        // 是没有 @Param 注解的，并且形参个数为 1，因此 if 语句成立，执行 if
        if (!this.hasParamAnnotation && paramCount == 1) {
            // 执行
            
            // 由于 names 只有一个键值对，因此 (Integer)this.names.firstKey() 获取的第一个key 就是 0
            // 那么 value = args[0] 即 value 为 2
            Object value = args[(Integer)this.names.firstKey()];
            /*
            	1. value：表示需要处理的参数值。
            	2. this.useActualParamName：是一个布尔值，表示是否启用使用实际参数名称。这里为 true。
            	3. (String)this.names.get(0)：这段代码从names列表中获取第一个参数名称，并将其转换为字符串类型。
            	
            	调用本类的wrapToMapIfCollection方法，
            	该方法是根据参数的类型和配置的实际参数名称来进行适当的参数封装，以便正确地在SQL语句中使用。
            	在这里，该方法返回的结果是原 value 值 2，即 getNamedParams 返回的结果是 2
            */
            return wrapToMapIfCollection(value, this.useActualParamName ? (String)this.names.get(0) : null);
        } else {
            // 不执行
            
            // 省略代码...
        }
    } else {
        return null;
    }
}

public static Object wrapToMapIfCollection(Object object, String actualParamName) {
    MapperMethod.ParamMap map;
    // 这里的 object 是 Integer 类型的 2
    
    // 判断 是否为 Collection 类型 --> 不是
    if (object instanceof Collection) {
        map = new MapperMethod.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()) {
        map = new MapperMethod.ParamMap();
        map.put("array", object);
        Optional.ofNullable(actualParamName).ifPresent((name) -> {
            map.put(name, object);
        });
        return map;
    } else {
        // 执行
        
        // 因此返回的就是原对象，最终 getNamedParams 返回的结果就是 2
        return object;
    }
}

还没完噢，我们再找到调用 getNamedParams 方法的位置，找到 MapperMethod 类的 execute 方法：

// execute 方法源码
public Object execute(SqlSession sqlSession, Object[] args) {
    Object result;
    Object param;
    switch (this.command.getType()) {
        case INSERT:
            param = this.method.convertArgsToSqlCommandParam(args);
            result = this.rowCountResult(sqlSession.insert(this.command.getName(), param));
            break;
        case UPDATE:
            param = this.method.convertArgsToSqlCommandParam(args);
            result = this.rowCountResult(sqlSession.update(this.command.getName(), param));
            break;
        case DELETE:
            param = this.method.convertArgsToSqlCommandParam(args);
            result = this.rowCountResult(sqlSession.delete(this.command.getName(), param));
            break;
        // 我们的 UserMapper.xml 映射文件中对应 selectById 方法的标签是 <select>，因此 this.command.getType() 走到这个 case
        case SELECT:
            if (this.method.returnsVoid() && this.method.hasResultHandler()) {
                this.executeWithResultHandler(sqlSession, args);
                result = null;
            } else if (this.method.returnsMany()) {
                result = this.executeForMany(sqlSession, args);
            } else if (this.method.returnsMap()) {
                result = this.executeForMap(sqlSession, args);
            } else if (this.method.returnsCursor()) {
                result = this.executeForCursor(sqlSession, args);
            } else {
                // 执行这里
                
                // convertArgsToSqlCommandParam 方法实际是调用 getNamedParams 方法
                // 那么 param 的值就是 2
                param = this.method.convertArgsToSqlCommandParam(args);
                
                // 将 2 作为 参数进行查询单条数据
                // result 就是查询结果：User(id=2, name=浪浪, sex=女, age=18)
                result = sqlSession.selectOne(this.command.getName(), param);
                
                if (this.method.returnsOptional() && (result == null || !this.method.getReturnType().equals(result.getClass()))) {
                    result = Optional.ofNullable(result);
                }
            }
            break;
        case FLUSH:
            result = sqlSession.flushStatements();
            break;
        default:
            throw new BindingException("Unknown execution method for: " + this.command.getName());
    }

    if (result == null && this.method.getReturnType().isPrimitive() && !this.method.returnsVoid()) {
        throw new BindingException("Mapper method '" + this.command.getName() + "' attempted to return null from a method with a primitive return type (" + this.method.getReturnType() + ").");
    } else {
        return result;
    }
}

那实际上，对于 sqlSession.selectOne(this.command.getName(), param); 的内部实现，由于有些复杂，我们直接看对我们而言的核心部分：

/*
	CachingExecutor 是 MyBatis 中的一个执行器（Executor）实现类，它用于提供查询结果的缓存功能。
	在 MyBatis 中，每次执行 SQL 查询时，都会创建一个执行器来处理查询操作。
	CachingExecutor是其中的一种特殊类型，它负责在执行查询时缓存结果，以提高后续相同查询的性能。
*/
public class CachingExecutor implements Executor {

    // 传入这个方法的参数 parameterObject 就是 我们的实参 2
    public <E> List<E> query(MappedStatement ms, Object parameterObject, RowBounds rowBounds, ResultHandler resultHandler) throws SQLException {
        // getBoundSql 是获取包含 SQL 语句和参数的 BoundSql 对象。
        /*
        	这个 boundSql 实例化对象有两个重要参数：
        		- sql: SELECT * FROM `user` WHERE id = ?
        		- parameterObject: 2
        */
        BoundSql boundSql = ms.getBoundSql(parameterObject);
        CacheKey key = this.createCacheKey(ms, parameterObject, rowBounds, boundSql);
        return this.query(ms, parameterObject, rowBounds, resultHandler, key, boundSql);
    }
    
}

所以我们可以看出，在 MyBatis 中，当只有一个 简单参数 传递给映射语句时，MyBatis 底层不会创建一个额外的参数 Map 集合来维护参数，即是不会去执行 在多参数状况下会执行的 ParamNameResolver 类的 getNamedParams 方法的 。相反，MyBatis 将直接使用传递的参数对象作为映射语句的参数。

⚠️ 注意这里说的是 简单参数 的情况下，那指的是什么呢？比如 参数如果是 Map 集合，那就不是简单参数。

7.不同 mybatis 版本下的默认 key 变化

使用 mybatis-3.4.2 之前的版本，底层创建的 map 集合 默认使用的 key 是：

• 0、1 …
• param1、param2 …

从 mybatis-3.4.2 开始，底层创建的 map 集合 默认使用的 key 是：

• arg0、arg1 …
• param1、param2 …

8.总结

关于以上问题，其根本原因在于 在 Java 源代码文件被编译为字节码文件（.class 文件）时，局部变量的名称通常不会被保留。这意味着即使在编写 Java 抽象方法时使用了具体的参数名，这些名称在最终的 .class 文件中是不会存在的。MyBatis 使用反射和动态代理来创建和执行 SQL 查询。在运行时，MyBatis 需要根据方法参数的位置和类型来匹配具体的 SQL 查询语句。但是，由于编译过程中参数名称的丢失，所以，即使在设计抽象方法时，使用了 name、sex 这样的参数名，在最终运行的 .class 文件中，根本就没有这样的名称！

当抽象方法的参数只有 1 个时，MyBatis 会自动的使用唯一的那一个参数，所以，在配置SQL映射时，使用的 #{} 占位符中的名称根本就不重要！在开发时，推荐使用规范的名称，但是，从代码是否可以运行的角度来说，这个占位符中写什么都不重要！

在 MyBatis3.4.2及以后的版本 的处理过程中，可以根据 arg 或 param 作为前缀，按照顺序来确定参数的值，所以，使用第 1 个参数时，可以使用 arg0 或 param1 作为名称，第 2 个可以使用 arg1 或 param2 作为名称，如果有更多参数，顺序编号即可，序号可参考抽象方法的声明。

但这种方式我们并不推荐，还是建议 使用 @Param 注解的方式。

mybatis 的 map 集合即 默认key 取值，与 mybatis 的版本有关，详细看 第七小节《不同 mybatis 版本下的默认 key 变化》。当然，@Param 这个注解无论是 mybatis3.4.2 以前还是以后都是可以使用的。

🚩 总结：在使用 MyBatis 框架，设计抽象方法时，如果参数的数量超过1个（有2个或更多个），就为每一个参数都添加 @Param 注解。文章来源地址https://www.toymoban.com/news/detail-517936.html

到了这里，关于mybatis多参数传递报错问题分析+硬核mybatis底层源码分析+@Param注解+图文实战环境分析【4500字详解打通，没有比这更详细的了！】的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！