标题：扒光MyBatis内部运行机制：从SQL执行到源码底层，一篇吃透核心原理

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>
    <groupId>com.jam.demo</groupId>
    <artifactId>mybatis-core-mechanism</artifactId>
    <version>1.0-SNAPSHOT</version>
    <name>mybatis-core-mechanism</name>
    <description>MyBatis核心运行机制演示</description>
    
    <properties>
        <java.version>17</java.version>
        <mybatis-plus.version>3.5.5</mybatis-plus.version>
        <mysql.version>8.0.36</mysql.version>
        <fastjson2.version>2.0.48</fastjson2.version>
        <guava.version>33.2.1-jre</guava.version>
    </properties>
    
    <dependencies>
        <!-- Spring Boot Starter Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Spring Boot Starter Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!-- MyBatis-Plus Starter -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>${mybatis-plus.version}</version>
        </dependency>
        <!-- MySQL Driver -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>${mysql.version}</version>
            <scope>runtime</scope>
        </dependency>
        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.30</version>
            <scope>provided</scope>
        </dependency>
        <!-- FastJSON2 -->
        <dependency>
            <groupId>com.alibaba.fastjson2</groupId>
            <artifactId>fastjson2</artifactId>
            <version>${fastjson2.version}</version>
        </dependency>
        <!-- Guava -->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>${guava.version}</version>
        </dependency>
        <!-- Swagger3 -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

spring:
  # 数据源配置
datasource:
    url:jdbc:mysql://localhost:3306/mybatis_demo?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username:root
    password:root
    driver-class-name:com.mysql.cj.jdbc.Driver

# MyBatis-Plus配置
mybatis-plus:
# Mapper映射文件路径
mapper-locations:classpath:mapper/**/*.xml
# 实体类别名包
type-aliases-package:com.jam.demo.entity
# 日志配置（打印SQL）
configuration:
    log-impl:org.apache.ibatis.logging.stdout.StdOutImpl
    # 开启驼峰命名转换（数据库下划线→Java驼峰）
    map-underscore-to-camel-case:true

# Swagger3配置
springdoc:
api-docs:
    path:/api-docs
swagger-ui:
    path:/swagger-ui.html
    operationsSorter:method

-- 用户表
CREATETABLE`t_user` (
`id`bigintNOTNULL AUTO_INCREMENT COMMENT'主键ID',
`user_name`varchar(50) NOTNULLCOMMENT'用户名',
`age`intNOTNULLCOMMENT'年龄',
`email`varchar(100) DEFAULTNULLCOMMENT'邮箱',
`create_time` datetime NOTNULLDEFAULTCURRENT_TIMESTAMPCOMMENT'创建时间',
`update_time` datetime NOTNULLDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMPCOMMENT'更新时间',
  PRIMARY KEY (`id`)
) ENGINE=InnoDBDEFAULTCHARSET=utf8mb4 COMMENT='用户表';

-- 插入测试数据
INSERTINTO`t_user` (`user_name`, `age`, `email`) VALUES ('zhangsan', 20, 'zhangsan@demo.com');
INSERTINTO`t_user` (`user_name`, `age`, `email`) VALUES ('lisi', 25, 'lisi@demo.com');

package com.jam.demo.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.time.LocalDateTime;

/**
 * 用户实体类
 *
 * @author ken
 */
@Data
@TableName("t_user")
publicclass User {
    /**
     * 主键ID
     */
    @TableId(type = IdType.AUTO)
    private Long id;

    /**
     * 用户名
     */
    private String userName;

    /**
     * 年龄
     */
    private Integer age;

    /**
     * 邮箱
     */
    private String email;

    /**
     * 创建时间
     */
    private LocalDateTime createTime;

    /**
     * 更新时间
     */
    private LocalDateTime updateTime;
}

package com.jam.demo.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.jam.demo.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 用户Mapper接口
 *
 * @author ken
 */
publicinterface UserMapper extends BaseMapper<User> {
    /**
     * 根据用户名模糊查询用户列表
     *
     * @param userName 用户名
     * @return 用户列表
     */
    @Operation(summary = "根据用户名模糊查询用户", description = "传入用户名关键词，返回匹配的用户列表")
    List<User> selectUserByUserNameLike(
            @Parameter(description = "用户名关键词", required = true)
            @Param("userName") String userName
    );

    /**
     * 批量插入用户
     *
     * @param userList 用户列表
     * @return 插入成功条数
     */
    @Operation(summary = "批量插入用户", description = "传入用户列表，批量插入数据")
    int batchInsertUser(@Param("list") List<User> userList);
}

<?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">
<mapper namespace="com.jam.demo.mapper.UserMapper">
    <!-- 通用查询结果列 -->
    <sql id="Base_Column_List">
        id, user_name, age, email, create_time, update_time
    </sql>

    <!-- 根据用户名模糊查询 -->
    <select id="selectUserByUserNameLike" resultType="com.jam.demo.entity.User">
        SELECT
        <include refid="Base_Column_List"/>
        FROM t_user
        WHERE user_name LIKE CONCAT('%', #{userName}, '%')
    </select>

    <!-- 批量插入用户 -->
    <insert id="batchInsertUser">
        INSERT INTO t_user (user_name, age, email)
        VALUES
        <foreach collection="list" item="item" separator=",">
            (#{item.userName}, #{item.age}, #{item.email})
        </foreach>
    </insert>
</mapper>

package com.jam.demo.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.jam.demo.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;

import java.util.List;

/**
 * 用户服务接口
 *
 * @author ken
 */
publicinterface UserService extends IService<User> {
    /**
     * 根据用户名模糊查询用户列表
     *
     * @param userName 用户名
     * @return 用户列表
     */
    @Operation(summary = "根据用户名模糊查询用户", description = "传入用户名关键词，返回匹配的用户列表")
    List<User> queryUserByUserNameLike(@Parameter(description = "用户名关键词", required = true) String userName);

    /**
     * 批量插入用户
     *
     * @param userList 用户列表
     * @return 插入成功条数
     */
    @Operation(summary = "批量插入用户", description = "传入用户列表，批量插入数据")
    int batchAddUser(@Parameter(description = "用户列表", required = true) List<User> userList);
}

package com.jam.demo.service.impl;

import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.jam.demo.entity.User;
import com.jam.demo.mapper.UserMapper;
import com.jam.demo.service.UserService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.util.CollectionUtils;

import java.util.List;

/**
 * 用户服务实现类
 *
 * @author ken
 */
@Slf4j
@Service
publicclass UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {

    @Override
    public List<User> queryUserByUserNameLike(String userName) {
        // 字符串判空（符合规范：使用org.springframework.util.StringUtils）
        if (!org.springframework.util.StringUtils.hasText(userName)) {
            log.error("查询用户名不能为空");
            thrownew IllegalArgumentException("用户名不能为空");
        }
        log.info("根据用户名模糊查询：{}", userName);
        return baseMapper.selectUserByUserNameLike(userName);
    }

    @Override
    public int batchAddUser(List<User> userList) {
        // 集合判空（符合规范：使用org.springframework.util.CollectionUtils）
        if (CollectionUtils.isEmpty(userList)) {
            log.error("批量插入用户列表不能为空");
            thrownew IllegalArgumentException("用户列表不能为空");
        }
        log.info("批量插入用户数量：{}", userList.size());
        return baseMapper.batchInsertUser(userList);
    }
}

package com.jam.demo.controller;

import com.jam.demo.entity.User;
import com.jam.demo.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.List;

/**
 * 用户控制器
 *
 * @author ken
 */
@Slf4j
@RestController
@RequestMapping("/user")
@Tag(name = "用户管理", description = "用户查询、新增等接口")
publicclass UserController {

    @Resource
    private UserService userService;

    /**
     * 根据用户名模糊查询用户
     */
    @GetMapping("/like/{userName}")
    @Operation(summary = "根据用户名模糊查询", description = "传入用户名关键词，返回匹配的用户列表")
    public ResponseEntity<List<User>> getUserByUserNameLike(
            @Parameter(description = "用户名关键词", required = true)
            @PathVariable String userName
    ) {
        List<User> userList = userService.queryUserByUserNameLike(userName);
        returnnew ResponseEntity<>(userList, HttpStatus.OK);
    }

    /**
     * 批量插入用户
     */
    @PostMapping("/batch")
    @Operation(summary = "批量插入用户", description = "传入用户列表，批量插入数据")
    public ResponseEntity<Integer> batchAddUser(
            @Parameter(description = "用户列表", required = true)
            @RequestBody List<User> userList
    ) {
        int count = userService.batchAddUser(userList);
        returnnew ResponseEntity<>(count, HttpStatus.CREATED);
    }

    /**
     * 根据ID查询用户（MyBatis-Plus自带方法）
     */
    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询用户", description = "传入用户ID，返回单个用户信息")
    public ResponseEntity<User> getUserById(
            @Parameter(description = "用户ID", required = true)
            @PathVariable Long id
    ) {
        User user = userService.getById(id);
        returnnew ResponseEntity<>(user, HttpStatus.OK);
    }
}

package com.jam.demo;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 启动类
 *
 * @author ken
 */
@SpringBootApplication
@MapperScan("com.jam.demo.mapper") // 扫描Mapper接口
publicclass MyBatisCoreMechanismApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyBatisCoreMechanismApplication.class, args);
    }
}

// MybatisAutoConfiguration核心方法
@Bean
@ConditionalOnMissingBean
public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
    SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
    factory.setDataSource(dataSource);
    // 设置Mapper映射文件路径
    factory.setMapperLocations(this.mapperLocations);
    // 其他配置（别名、插件等）
    if (!ObjectUtils.isEmpty(this.configuration)) {
        factory.setConfiguration(this.configuration);
    }
    // 构建SqlSessionFactory
    return factory.getObject();
}

// MapperProxy.invoke方法（动态代理核心）
@Override
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
    // 处理Object类的方法（toString、hashCode等）
    if (Object.class.equals(method.getDeclaringClass())) {
        return method.invoke(this, args);
    }
    // 生成MethodSignature，获取MapperStatement的key
    MethodSignature signature = (MethodSignature) method.getAnnotation(MethodSignature.class);
    String msId = signature.value(); // 即namespace+id
    // 获取SqlSession，执行SQL
    return sqlSession.selectList(msId, args);
}

// DefaultResultSetHandler.handleResultSets方法
@Override
public List<Object> handleResultSets(Statement stmt) throws SQLException {
    List<Object> multipleResults = new ArrayList<>();
    int resultSetCount = 0;
    // 获取第一个结果集
    ResultSet rs = stmt.getResultSet();
    // 处理结果集映射
    while (rs != null) {
        // 获取ResultMap配置
        ResultMap resultMap = resolveResultMap(stmt, ms, rs, null);
        // 映射结果集到Java对象
        handleResultSet(rs, resultMap, multipleResults, null);
        // 处理多结果集（存储过程等场景）
        rs = getNextResultSet(stmt);
        cleanUpAfterHandlingResultSet();
        resultSetCount++;
    }
    return collapseSingleResultList(multipleResults);
}

// BaseExecutor.query方法中的缓存检查逻辑
if (queryStack == 0 && ms.isFlushCacheRequired()) {
    // 增删改操作会设置flushCache=true，清空一级缓存
    clearLocalCache();
}
try {
    queryStack++;
    // 从一级缓存获取结果
    list = resultHandler == null ? (List<E>) localCache.getObject(key) : null;
    if (list != null) {
        // 处理缓存中的结果（输出参数等）
        handleLocallyCachedOutputParameters(ms, key, parameter, boundSql);
    } else {
        // 缓存未命中，执行数据库查询
        list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql);
    }
} finally {
    queryStack--;
}

@Override
public void setParameters(PreparedStatement ps) {
    ErrorContext.instance().activity("setting parameters").object(mappedStatement.getParameterMap().getId());
    List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();
    if (!CollectionUtils.isEmpty(parameterMappings)) {
        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)) {
                    value = boundSql.getAdditionalParameter(propertyName);
                } elseif (parameterObject == null) {
                    value = null;
                } elseif (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {
                    value = parameterObject;
                } else {
                    // 通过反射获取参数对象的属性值
                    MetaObject metaObject = configuration.newMetaObject(parameterObject);
                    value = metaObject.getValue(propertyName);
                }
                // 获取TypeHandler，转换参数类型
                TypeHandler typeHandler = parameterMapping.getTypeHandler();
                JdbcType jdbcType = parameterMapping.getJdbcType();
                if (value == null && jdbcType == null) {
                    jdbcType = configuration.getJdbcTypeForNull();
                }
                // 绑定参数到PreparedStatement
                typeHandler.setParameter(ps, i + 1, value, jdbcType);
            }
        }
    }
}

package com.jam.demo.handler;

import org.apache.ibatis.type.BaseTypeHandler;
import org.apache.ibatis.type.JdbcType;
import org.apache.ibatis.type.MappedJdbcTypes;
import org.apache.ibatis.type.MappedTypes;

import java.sql.*;
import java.time.LocalDateTime;

/**
 * 自定义LocalDateTime类型处理器
 * 实现LocalDateTime与JDBC Timestamp的转换
 *
 * @author ken
 */
@MappedTypes(LocalDateTime.class) // 对应Java类型
@MappedJdbcTypes(JdbcType.TIMESTAMP) // 对应JDBC类型
public class LocalDateTimeTypeHandler extends BaseTypeHandler<LocalDateTime> {

    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, LocalDateTime parameter, JdbcType jdbcType) throws SQLException {
        // Java类型→JDBC类型
        ps.setTimestamp(i, Timestamp.valueOf(parameter));
    }

    @Override
    public LocalDateTime getNullableResult(ResultSet rs, String columnName) throws SQLException {
        // JDBC类型→Java类型（通过列名获取）
        Timestamp timestamp = rs.getTimestamp(columnName);
        return timestamp != null ? timestamp.toLocalDateTime() : null;
    }

    @Override
    public LocalDateTime getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        // JDBC类型→Java类型（通过列索引获取）
        Timestamp timestamp = rs.getTimestamp(columnIndex);
        return timestamp != null ? timestamp.toLocalDateTime() : null;
    }

    @Override
    public LocalDateTime getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        // 存储过程场景
        Timestamp timestamp = cs.getTimestamp(columnIndex);
        return timestamp != null ? timestamp.toLocalDateTime() : null;
    }
}

mybatis-plus:
  configuration:
    # 注册自定义TypeHandler
    type-handlers-package: com.jam.demo.handler

package com.jam.demo.plugin;

import org.apache.ibatis.executor.Executor;
import org.apache.ibatis.mapping.BoundSql;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.plugin.*;
import org.apache.ibatis.session.ResultHandler;
import org.apache.ibatis.session.RowBounds;
import org.springframework.stereotype.Component;

import java.util.Properties;

/**
 * 自定义分页插件（MySQL）
 * 拦截Executor的query方法，添加分页SQL
 *
 * @author ken
 */
@Component
@Intercepts({
        @Signature(
                type = Executor.class,
                method = "query",
                args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}
        )
})
public class MybatisPagePlugin implements Interceptor {

    /**
     * 拦截方法，执行分页逻辑
     */
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // 获取拦截参数
        Object[] args = invocation.getArgs();
        MappedStatement ms = (MappedStatement) args[0];
        Object parameter = args[1];
        RowBounds rowBounds = (RowBounds) args[2];

        // 非默认RowBounds（即传入了分页参数），执行分页
        if (rowBounds != RowBounds.DEFAULT) {
            BoundSql boundSql = ms.getBoundSql(parameter);
            String sql = boundSql.getSql();
            // 拼接MySQL分页SQL（LIMIT offset, limit）
            String pageSql = sql + " LIMIT " + rowBounds.getOffset() + ", " + rowBounds.getLimit();
            // 修改BoundSql中的SQL
            BoundSql newBoundSql = new BoundSql(ms.getConfiguration(), pageSql, boundSql.getParameterMappings(), parameter);
            // 创建新的MappedStatement，替换原有的BoundSql
            MappedStatement newMs = copyFromMappedStatement(ms, new BoundSqlSqlSource(newBoundSql));
            args[0] = newMs;
            // 重置RowBounds（避免后续Executor再次处理分页）
            args[2] = RowBounds.DEFAULT;
        }

        // 执行原方法
        return invocation.proceed();
    }

    /**
     * 生成代理对象
     */
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }

    /**
     * 设置插件属性（从配置文件读取）
     */
    @Override
    public void setProperties(Properties properties) {
        // 可读取配置的分页参数（如默认页码、每页条数）
    }

    /**
     * 复制MappedStatement，替换SqlSource
     */
    private MappedStatement copyFromMappedStatement(MappedStatement ms, SqlSource newSqlSource) {
        MappedStatement.Builder builder = new MappedStatement.Builder(
                ms.getConfiguration(),
                ms.getId(),
                newSqlSource,
                ms.getSqlCommandType()
        );
        // 复制其他属性
        builder.resource(ms.getResource());
        builder.fetchSize(ms.getFetchSize());
        builder.statementType(ms.getStatementType());
        builder.keyGenerator(ms.getKeyGenerator());
        if (ms.getKeyProperties() != null && ms.getKeyProperties().length > 0) {
            builder.keyProperty(ms.getKeyProperties()[0]);
        }
        builder.timeout(ms.getTimeout());
        builder.parameterMap(ms.getParameterMap());
        builder.resultMaps(ms.getResultMaps());
        builder.resultSetType(ms.getResultSetType());
        builder.cache(ms.getCache());
        builder.flushCacheRequired(ms.isFlushCacheRequired());
        builder.useCache(ms.isUseCache());
        return builder.build();
    }

    /**
     * 包装BoundSql为SqlSource
     */
    staticclass BoundSqlSqlSource implements SqlSource {
        privatefinal BoundSql boundSql;

        public BoundSqlSqlSource(BoundSql boundSql) {
            this.boundSql = boundSql;
        }

        @Override
        public BoundSql getBoundSql(Object parameterObject) {
            return boundSql;
        }
    }
}

<insert id="batchInsertUser">
    INSERT INTO t_user (user_name, age, email)
    VALUES
    <foreach collection="list" item="item" separator=",">
        (#{item.userName}, #{item.age}, #{item.email})
    </foreach>
</insert>