MyBatis SqlSessionFactory创建过程解析

SqlSessionFactory 由 SqlSessionFactoryBuilder 构建而非手动 new，它解析配置生成 Configuration 后创建 DefaultSqlSessionFactory 实例；builder 一次性使用，需确保 XML 路径正确、environments 有 default 属性，且 Configuration 不可变。

SqlSessionFactory 是怎么 new 出来的？不是手动 new 的

MyBatis 不允许你直接 new SqlSessionFactory()，它必须由 SqlSessionFactoryBuilder 构建。这个 builder 本质是把配置（XML 或 Java Config）解析成内存中的 Configuration 对象，再用它实例化 DefaultSqlSessionFactory —— 这才是真正的实现类。

常见错误现象：NullPointerException 在调用 openSession() 前就抛出，往往是因为 builder 拿到的 InputStream 为 null（比如 Resources.getResourceAsStream("mybatis-config.xml") 路径写错或资源没进 classpath）。

• 确保配置文件在 src/main/resources 下，且路径传给 Resources.getResourceAsStream() 时**不带前导 /**（"mybatis-config.xml" ✅，"/mybatis-config.xml" ❌）
• SqlSessionFactoryBuilder.build() 有多个重载，最常用的是接收 InputStream 和可选的 Properties；如果传入 null InputStream，会直接 NPE
• builder 是一次性的，构建完 SqlSessionFactory 后别缓存它——它不持有状态，也没必要

XML 配置怎么变成 Configuration 对象？靠 XPath + 自定义 NodeHandler

MyBatis 解析 mybatis-config.xml 不用 DOM/SAX，而是用 DocumentBuilder 得到原生 org.w3c.dom.Document，再用 XPath 定位节点，每个标签对应一个 NodeHandler（如 EnvironmentHandler、MappersHandler）。这不是黑盒，你可以通过继承 XMLConfigBuilder 并重写 handlerMap 来插手解析逻辑（极少数场景需要）。

容易踩的坑：<mapper> 标签的 resource、url、class 三者互斥，同时出现会导致 BuilderException：“Duplicate property 'xxx'”。另外，typeAliases 中的别名如果和 JDK 类同名（比如起名 String），运行时不会报错，但后续映射会静默失败。

• mapper 的 resource 路径是相对于 classpath 的，不是文件系统路径；写成 "com/example/mapper/UserMapper.xml" ✅，"./mappers/UserMapper.xml" ❌
• environments 必须指定 default 属性，否则抛 IllegalArgumentException：“Environment can't be null”
• 自定义 TypeHandler 必须在 <typeHandlers> 中显式注册，不会自动扫描；未注册却在 resultMap 里用了 javaType+jdbcType 组合，会 fallback 到默认 handler，可能类型不匹配

为什么 SqlSessionFactory 要设计成单例？它真线程安全吗

SqlSessionFactory 是典型的线程安全单例——它的所有方法都不修改内部状态，所有可变逻辑都委托给每次创建的 SqlSession 实例。也就是说，你可以在整个应用生命周期中只持有一个 SqlSessionFactory 实例，反复调用 openSession()。

但要注意：它的线程安全性**不等于**你代码的安全性。比如你在 Spring 中误把 SqlSessionTemplate 注入为 singleton 作用域（虽然它本身是线程安全的），但若在多线程下共享同一个 SqlSession 实例（比如把它设为类字段又没加锁），就会触发 Executor 内部状态冲突，抛 ExecutorException：“Executor was closed” 或 “Transaction is already committed”。

• Spring Boot 默认用 SqlSessionFactoryBean 创建 SqlSessionFactory，它本身就是 singleton，无需额外包装
• 手动管理时，务必用 static final 或依赖注入容器托管，避免重复解析 XML 创建多个 factory（浪费内存+影响性能）
• 不要尝试对 SqlSessionFactory 做双重检查锁单例——它构造成本高，但构建后无状态，没必要“懒汉式”

Configuration 对象里藏了哪些关键信息？别只盯着 mappers

Configuration 是 MyBatis 的核心上下文容器，不只是 mapper 映射的集合。它还持有 mappedStatements（SQL 语句元数据）、typeAliasRegistry（别名表）、interceptorChain（插件链）、languageDriverRegistry（动态 SQL 解析器），甚至包括全局开关如 cacheEnabled、lazyLoadingEnabled。

最容易被忽略的一点：当你调用 configuration.addMapper(UserMapper.class) 时，MyBatis 不仅注册接口，还会扫描其所有 @Select 等注解方法，并生成对应的 MappedStatement；但如果该接口继承了其他接口（比如 BaseMapper<T>），而 BaseMapper 没被 addMapper，那么子接口里的默认方法（Java 8+）不会被识别——因为 MyBatis 只解析显式注册的接口。

• Configuration 在 SqlSessionFactory 创建后就不可变（immutable），后续调用 addMappedStatement() 等方法会抛 UnsupportedOperationException
• 插件（Interceptor）必须在 SqlSessionFactory 构建前注册到 Configuration，即调用 configuration.addInterceptor(...)；build 之后再加无效
• 如果你用 MapperScannerConfigurer（Spring），它底层也是循环调用 configuration.addMapper()，所以扫描路径要精确，避免漏扫或重复扫同一接口

真正复杂的不是创建过程，而是 Configuration 初始化时那些隐式依赖：比如 ObjectFactory 默认用 DefaultObjectFactory，但它依赖 ReflectorFactory，而后者又跟 JVM 版本、是否启用 useActualParamName 强相关——这些细节不出错时没人注意，一出就是 ReflectionException 或参数绑定为空。