MyBatis 学习路线

本目录回答五个问题：Mapper 接口为什么不用实现类、SQL 参数怎么绑定、插件在哪拦截、两级缓存什么时候生效、和 Spring 整合后事务与连接归谁管。

适用版本：MyBatis 3.5.x；Spring Boot 3.x 搭配 mybatis-spring-boot-starter 3.0.x。版本差异以官方文档为准。

读前准备

• 能用 JDK 17 跑 Maven 工程，了解 JDBC 的 Connection、PreparedStatement、ResultSet。
• 知道 JDK 动态代理的基本用法；不要求读过 MyBatis 源码。

java -version    # 期望 17 或更高
mvn -v           # 期望 Maven 3.9+

篇目

篇	回答的问题	前置	建议阅读方式
01-核心原理	四大组件怎么串起来；#{} 与 ${} 的区别；Mapper 代理和延迟加载	JDBC、JDK 动态代理	先跑最小工程，再读机制
02-插件机制	四个拦截点、责任链顺序、插件状态为什么会被并发污染	01、JDK 动态代理	对照 @Intercepts 写一个耗时插件
03-缓存机制	一级缓存跟事务什么关系；二级缓存怎么接 Redis	01、Spring 事务	先看 scope，再看失效条件
04-与Spring整合	SqlSessionTemplate、MapperScannerConfigurer、事务怎么接	01、Spring IoC/事务	从最小整合配置读起
05-生产踩坑	N+1、缓存脏读、延迟加载、大字段、精度问题的因果链	01–04	按“现象 → 证据 → 根因”读
99-生产检查清单	上线前、运行中、故障时各查什么	01–05	当成操作清单，不替代正文

推荐顺序

1. 01 → 03 → 02 → 04 → 05：先理解执行链路和缓存作用域，再看插件如何插入链路，最后看 Spring 整合和生产故障。
2. 只排查 SQL 问题：01 的 #{}/${} 与 05 的 N+1、精度问题优先；插件和缓存可以后读。
3. 只排查事务/连接问题：04 的事务整合 + 03 的一级缓存作用域一起读，二者都取决于 SqlSession 的生命周期。
4. 准备接 Redis 二级缓存：先读 03 的 cache-ref 与 Cache 接口，再读 99 的上线前检查项。

每篇的验证动作

篇	读完应当能独立完成
01	用 H2 跑通一个 Mapper 接口，日志里看到 Preparing: ... ? 与 Parameters:
02	写一个 Executor.query 拦截器，验证两个插件的执行顺序与配置顺序相反
03	在同一事务内连续查两次，确认第二次命中一级缓存；提交后再查确认缓存失效
04	用 @MapperScan 或 Boot starter 注入 Mapper，确认事务内复用同一个 SqlSession
05	用 SQL 日志数出一次列表查询的实际 SQL 条数，定位 N+1

与相邻目录的关系

• Java 基础：12_Java 提供反射、注解、动态代理和 SPI；MyBatis 的 Mapper 代理与插件都建立在这些机制上。
• Spring：26_Spring 的 IoC 与事务模型决定 Mapper 如何被注入、SqlSession 如何跟随事务。
• 分库分表：ShardingSphere 深度配置 讲分片路由；MyBatis 插件与它配合时要注意 SQL 改写顺序。
• 设计模式：25_设计模式 讲代理、责任链、装饰器本身；本目录只讲 MyBatis 在哪些类上用了它们。

版本与前提

• 示例以 MyBatis 3.5.x + Java 17 + H2 2.x 为主；生产数据库以 MySQL 8.x / PostgreSQL 15+ 为例。
• 二级缓存、延迟加载的默认值随小版本可能调整，正文标注默认值；不确定时以官方文档为准。
• mybatis-spring-boot-starter 3.0.x 对应 Spring Boot 3.x；2.3.x 对应 Boot 2.x，不要混用。
• 插件、TypeHandler、Cache 的实现都受 MyBatis 版本影响，升级前先看 Release Notes。

不在本目录展开

• JDBC 驱动、连接池、数据库锁与 MVCC：见 S03 数据与存储。
• Spring 容器与事务的完整机制：见 26_Spring。
• 分库分表的路由与扩容：见 15_分库分表。
• 具体业务表的索引设计：见对应数据库专题。

维护约定：新增篇目时同步更新本页表格和验证动作；删除篇目时先合并独有内容，再清理本页与相邻目录的链接。