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；如果传入nullInputStream，会直接 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 或参数绑定为空。
