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

文章目录

  • 1.问题描述
  • 2.问题场景模拟再现
    • 2.1 场景环境
    • 2.2 数据库与表创建
    • 2.3 Maven环境搭建
      • pom.xml导入依赖
      • jdbc.properties
      • mybatis-config.xml
      • User实体类
      • Mapper 接口
      • UserMapper.xml 映射文件
    • 2.4 测试报错
  • 3.问题分析
    • 3.1 SQL解析原理
    • 3.2 mybatis底层源码追踪之map集合创建
  • 4.问题最佳解决方案-@Param
  • 5.一张图解释源码
  • 6.拓展-单参数情况
  • 7.不同 mybatis 版本下的默认 key 变化
  • 8.总结

1.问题描述

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

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

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导入依赖


<dependency>
    <groupId>junitgroupId>
    <artifactId>junitartifactId>
    <version>4.11version>
    <scope>testscope>
dependency>

<dependency>
    <groupId>mysqlgroupId>
    <artifactId>mysql-connector-javaartifactId>
    <version>8.0.31version>
dependency>

<dependency>
    <groupId>org.mybatisgroupId>
    <artifactId>mybatisartifactId>
    <version>3.5.11version>
dependency>

<dependency>
    <groupId>org.projectlombokgroupId>
    <artifactId>lombokartifactId>
    <version>1.18.24version>
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 配置文件。


DOCTYPE configuration
        PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    
    <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 映射文件。


DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<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 测试方法,则会报错:

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

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多参数传递报错问题分析+硬核mybatis底层源码分析+@Param注解+图文实战环境分析【4500字详解打通,没有比这更详细的了!】_第3张图片

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

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

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

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

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

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

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

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

// 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 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
);

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

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

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

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

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

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

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

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

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

5.一张图解释源码

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

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 的 数据信息。

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

关于底层实现,我们依旧以 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 方法的标签是