我刚入行那会儿第一次翻mybatis-config.xml满脑子都是“这玩意儿到底怎么跑起来的”。网上搜出来的教程清一色在教你写settings、mappers但没人告诉你这些标签从 XML 变成Configuration对象的过程中MyBatis 到底做了哪些事。后来因为要排查一个启动报错被逼着把XMLConfigBuilder的源码从头到尾啃了一遍才发现这条解析链路远比我想象中精巧。这篇文章就把我整理的“全局配置文件解析全流程”完整拆给你看包括解析顺序、核心类职责、配置项背后的设计意图以及我踩过的几个坑。不管是想看明白源码、准备面试还是想排查配置问题应该都能用得上。1. 全局配置文件的角色与整体设计思路1.1 为什么需要全局配置文件MyBatis 的核心对象是SqlSessionFactory而SqlSessionFactory又是基于Configuration构建的。Configuration这个类几乎承载了 MyBatis 运行期的全部状态数据源、事务管理器、映射器注册表、类型别名、类型处理器、插件拦截器、全局缓存开关、懒加载策略……可以说MyBatis所有运行时行为都能在Configuration上找到对应的字段。全局配置文件mybatis-config.xml的作用就是用一种声明式的方式把这些运行期状态从代码里剥离出来。你不用在 Java 里一个个set而是写一段 XML由框架负责把 XML 解析成Configuration对象。这样做的好处很直接配置与代码解耦环境切换开发、测试、生产只需要换配置文件不需要重新编译。很多初学者会把全局配置文件和 Mapper XML 配置文件搞混。其实两者是不同层级的东西全局配置负责“框架本身怎么跑”Mapper 配置负责“某一条 SQL 怎么执行”。全局配置的解析入口是XMLConfigBuilderMapper 配置的解析入口是XMLMapperBuilder后者的调用时机多数发生在全局配置解析到mappers标签时。理解这条主链路后面的源码读起来就顺了。1.2 配置文件的整体分层MyBatis 全局配置文件的解析有一个显著特征对配置项顺序极其敏感。这不是 MyBatis 故意搞事而是因为XMLConfigBuilder在解析时用了XNode的evalNode来逐个获取子节点而底层依赖的 XML 解析器在定位节点时也依赖文档结构。从官网的 DTD 定义的顺序来看configuration下允许出现的子元素顺序是!ELEMENT configuration (properties?, settings?, typeAliases?, typeHandlers?, objectFactory?, objectWrapperFactory?, reflectorFactory?, plugins?, environments?, databaseIdProvider?, mappers?)也就是说properties必须放在最前面接着是settings、typeAliases、typeHandlers、objectFactory等最后才是mappers。为什么顺序这么关键因为解析过程是“边解析边构建”的。解析到typeAliases时Configuration的TypeAliasRegistry需要已经被初始化解析到settings时Configuration需要已经准备好对应的属性 setter。如果顺序乱了比如把mappers放到settings前面解析器在解析 Mapper 时可能依赖某些尚未注册的别名或类型处理器就会直接报错。从我实际排查过的案例来看TypeAlias 注册顺序导致的问题最隐蔽。.xml配置里mappers使用package方式扫描时如果 XML 文件里有未注册的 resultType 简写别名而 typeAliases 又排在后面MyBatis 解析 Mapper 时就会抛出TypeException提示找不到对应的别名。所以我的建议是严格按照 DTD 顺序书写别耍小聪明调整顺序。2. XML 解析链路拆解从 XML 到 Configuration 对象2.1 入口SqlSessionFactoryBuilder 与 XMLConfigBuilder使用 MyBatis 时最常见的一段启动代码是这样String resource mybatis-config.xml; InputStream inputStream Resources.getResourceAsStream(resource); SqlSessionFactory sqlSessionFactory new SqlSessionFactoryBuilder().build(inputStream);很多人没意识到Resources.getResourceAsStream这一步其实已经干了件大事它通过类加载器把mybatis-config.xml从 classpath 中定位并打开成二进制流。这里有一个很容易被忽略的细节Resources会尝试多个类加载器包括当前线程的contextClassLoader、当前类的加载器、系统类加载器逐个试错直到成功。这在高动态类加载环境比如应用服务器里很关键如果只用一个类加载器资源可能就找不到了。SqlSessionFactoryBuilder.build()里发生的事情更集中。它会创建XMLConfigBuilder并调用它的parse()方法得到Configuration对象再用这个Configuration构建DefaultSqlSessionFactory。public SqlSessionFactory build(InputStream inputStream, String environment, Properties properties) { XMLConfigBuilder parser new XMLConfigBuilder(inputStream, environment, properties); return build(parser.parse()); }XMLConfigBuilder的构造过程本身就有玄机。它会先创建一个XPathParser然后在构造方法里立刻调用parserContext.getXPathParser().evalNode(/configuration)把根节点拿出来再通过new Configuration()初始化一个全新的Configuration实例。这一步同时决定了后面所有配置项的落点。2.2 parse() 方法的执行流程XMLConfigBuilder.parse()是解析全流程的核心源码逻辑非常清晰public Configuration parse() { if (parsed) { throw new BuilderException(Each XMLConfigBuilder can only be used once.); } parsed true; parseConfiguration(parser.evalNode(/configuration)); return configuration; }注意parsed标识位这个字段是用来防止同一个XMLConfigBuilder实例被重复使用的。如果你在代码里手动创建XMLConfigBuilder并调了两次parse()第二次直接抛BuilderException。真正的干活方法是parseConfiguration它把每个子标签的解析拆成了独立方法private void parseConfiguration(XNode root) { try { propertiesElement(root.evalNode(properties)); Properties settings settingsAsProperties(root.evalNode(settings)); loadCustomVfs(settings); loadCustomLogImpl(settings); typeAliasesElement(root.evalNode(typeAliases)); pluginsElement(root.evalNode(plugins)); objectFactoryElement(root.evalNode(objectFactory)); objectWrapperFactoryElement(root.evalNode(objectWrapperFactory)); reflectorFactoryElement(root.evalNode(reflectorFactory)); settingsElement(settings); environmentsElement(root.evalNode(environments)); databaseIdProviderElement(root.evalNode(databaseIdProvider)); typeHandlerElement(root.evalNode(typeHandlers)); mappersElement(root.evalNode(mappers)); } catch (Exception e) { throw new BuilderException(Error parsing SQL Mapper Configuration. Cause: e, e); } }看到没有虽然parseConfiguration内部按顺序执行但实际执行顺序和 DTD 顺序略有出入。尤其是typeHandlers居然排在environments之后才解析这在配置的使用层面很容易产生误区。很多人写配置文件时把 typeHandlers 放在 settings 之后以为解析顺序也是如此其实源码里它是在后面才被加载的。如果你在 typeHandlers 里注册了一个自定义 TypeHandler而在 environments 阶段就想用它做数据源连接配置那必然是不行的。还有一个细节settingsAsProperties会先把所有 settings 的值读成Properties对象然后传给settingsElement统一设置到Configuration上。这中间做了一步容错——如果某个属性名在Configuration上没有对应的 setter会直接跳过而不报错。这个“静默忽略”的设计我后面再展开讲。2.3 XPathParserMyBatis 自研 XML 解析器XMLConfigBuilder之所以能这么从容地逐段解析底层依赖的是 MyBatis 自研的XPathParser。这个类封装了 Java 标准库的XMLMapperEntityResolver和XPath表达式求值能力。XPathParser的核心是createDocument方法它使用 Java 的DocumentBuilderFactory创建 DOM 文档对象。这里有个关键配置factory.setFeature(http://apache.org/xml/features/disallow-doctype-decl, false); factory.setFeature(http://xml.org/sax/features/external-general-entities, false); factory.setFeature(http://xml.org/sax/features/external-parameter-entities, false); factory.setXIncludeAware(false); factory.setExpandEntityReferences(false);这套配置是为了在解析 XML 时禁用外部实体和 XInclude防止 XXE 攻击。同时它注册了XMLMapperEntityResolver——这个类的作用是当 XML 文件里出现http://mybatis.org/dtd/mybatis-3-config.dtd这类 DTD 引用时不真正去网络上下载而是从 MyBatis jar 包里的本地资源直接加载。这既保证了配置合法性校验又避免了启动时依赖外网。理解了XPathParser你就知道 MyBatis 解析 XML 不是用一堆正则硬拆字符串而是把整个文档加载成 DOM再用 XPath 精准定位节点。这样的好处是标签嵌套结构天然合法属性值可以走标准 XML 转义解析逻辑写起来也清晰得多。3. 核心配置项逐个解析与背后原理3.1 settings全局行为开关settings标签是日常开发里用得最多的配置像mapUnderscoreToCamelCase、cacheEnabled、lazyLoadingEnabled都在这里。前面说过settingsAsProperties会先把子标签拼成Properties然后通过settingsElement统一设置。settingsElement里面有个很有意思的机制它先给Configuration设了一堆默认值再用反射逐个匹配属性名调用 setter。Properties defaults new Properties(); defaults.put(cacheEnabled, true); defaults.put(lazyLoadingEnabled, false); defaults.put(aggressiveLazyLoading, true); defaults.put(multipleResultSetsEnabled, true); defaults.put(useColumnLabel, true); defaults.put(useGeneratedKeys, false); defaults.put(autoMappingBehavior, PARTIAL); defaults.put(autoMappingUnknownColumnBehavior, NONE); // ... 还有一堆核心逻辑是Configuration configuration new Configuration(environments); for (Map.EntryObject, Object entry : props.entrySet()) { MetaObject metaObject configuration.getSystemMetaObject(); Object value convertValue(metaObject, entry.getKey().toString(), entry.getValue().toString()); metaObject.setValue(entry.getKey().toString(), value); }这里用的是MetaObject反射工具。convertValue会根据目标属性的类型做转换比如布尔值、Integer、Long 等。所以哪怕配置文件里写的是字符串true最终也能赋给boolean类型的属性。如果Configuration上根本没有这个属性setValue会抛出反射异常。但前面说它“静默忽略”是因为在settingsAsProperties阶段已经对未知配置做过过滤并不是所有非法配置都会直接成功——具体行为取决于 MyBatis 版本和异常处理方式。但这引出一个常见误区MyBatis 对拼错的配置项名称容忍度很高拼错了可能不会报错但配置不生效排查起来非常恶心。最好启动后主动打印一份生效配置做对照。3.2 typeAliases 与 typeHandlers注册规则与加载时机typeAliases解析时有三种写法typeAliases typeAlias aliasuser typecom.example.model.User/ package namecom.example.model/ /typeAliases解析逻辑有两个分支typeAlias标签逐个注册package标签则扫描包下的所有类。对于包扫描MyBatis 会过滤掉匿名类、内部类、接口并且只注册能被class.isAnnotationPresent(Alias.class)注解标记的类如果没有注解就用类名首字母小写作为别名。这里有个细节包扫描默认不注册没有Alias注解的类但如果有Alias注解就以注解值为准。typeHandlers的解析比 typeAliases 晚但策略类似。它支持三种注册方式typeHandlers typeHandler handlercom.example.MyTypeHandler/ typeHandler javaTypejava.time.LocalDate handlercom.example.LocalDateTypeHandler jdbcTypeDATE/ package namecom.example.handler/ /typeHandlers源码里typeHandlerElement会根据是否有javaType属性决定注册范围。没有javaType时只会把 handler 和对应的MappedJdbcTypes如果存在注册有javaType时则用typeHandlerRegistry.register(javaType, jdbcType, handler)做精确注册。自定义 TypeHandler 最容易被坑的点是如果你既没有在 handler 类上写MappedJdbcTypes也没有在 XML 里指定javaType和jdbcType那么注册后 MyBatis 并不知道这个 handler 该用在哪种类型上结果就是怎么都不生效。3.3 plugins拦截器解析与动态代理链全局配置里的plugins就是很多人说的 MyBatis 拦截器配置入口。它的解析代码很短private void pluginsElement(XNode parent) throws Exception { if (parent ! null) { for (XNode child : parent.getChildren()) { String interceptor child.getStringAttribute(interceptor); Properties properties child.getChildrenAsProperties(); Interceptor interceptorInstance (Interceptor) resolveClass(interceptor).getDeclaredConstructor().newInstance(); interceptorInstance.setProperties(properties); configuration.addInterceptor(interceptorInstance); } } }注意它在这里只是把拦截器实例化并放进configuration的拦截器链里真正创建动态代理是在后面构建Executor、StatementHandler、ParameterHandler、ResultSetHandler时才发生。这是很多面试官爱问的点插件解析不是“配置完就代理”而是延迟到对象创建时通过InterceptorChain.pluginAll()一步步包装。3.4 environments数据源与事务工厂的组装environments标签我单独拿出来讲是因为它的解析直接关系到最后SqlSessionFactory使用哪个数据源、哪种事务管理器。源码先是读取default属性确定默认环境 ID然后遍历子节点找匹配的environmentprivate void environmentsElement(XNode context) throws Exception { if (context ! null) { if (environment null) { environment context.getStringAttribute(default); } for (XNode child : context.getChildren()) { String id child.getStringAttribute(id); if (isSpecifiedEnvironment(id)) { TransactionFactory txFactory transactionManagerElement(child.evalNode(transactionManager)); DataSourceFactory dsFactory dataSourceElement(child.evalNode(dataSource)); DataSource dataSource dsFactory.getDataSource(); Environment.Builder environmentBuilder new Environment.Builder(id).transactionFactory(txFactory).dataSource(dataSource); configuration.setEnvironment(environmentBuilder.build()); break; } } } }这里DataSourceFactory有三种内置实现UNPOOLED、POOLED、JNDI。POOLED是 MyBatis 自带的连接池实现很多人以为 MyBatis 只依赖第三方连接池其实它自己有一套简易连接池。UnpooledDataSource则是每用一次连接就新建一个Connection性能开销大多用于测试环境。3.5 mappers映射器的加载与绑定mappers是解析流程的压轴环节也是最容易引发级联问题的地方。mappersElement支持四种子标签mapper resource、mapper url、mapper class、package name。resource从 classpath 加载 Mapper XML 文件最常见。url从文件系统或网络 URL 加载测试时常用。class直接指定 Mapper 接口如果接口和 XML 同包同名能自动找到 XML。package扫描整个包按接口关联 XML需要接口和 XML 同名同路径。解析到resource时会调用XMLMapperBuilder.parse()。这一步会把 Mapper XML 里的cache、resultMap、sql、select|insert|update|delete全部解析注册进Configuration。同时bindMapperForNamespace()会做接口绑定。如果 Mapper XML 的 namespace 对应的接口存在会调用configuration.addMapper()最终通过MapperAnnotationBuilder解析接口上的注解 SQL。这里常会遇到一个经典报错Invalid bound statement (not found)。大部分原因就是 Mapper XML 没被加载进来。你可以检查全局配置里mappers的resource路径是否和 classpath 对得上或者用package方式时接口和 XML 是否放在同一目录、同名文件。4. 解析过程中的扩展点与设计精髓4.1 为什么 MyBatis 要自研 XPathParser 而不是直接用 DOM/SAX很多初学者会问既然 Java 自带DocumentBuilderFactoryMyBatis 为什么不直接用非得搞个XPathParser其实XPathParser本质上还是用 JAXP 的 DOM 能力但包了一层“XPath 友好”的 API。原来的DocumentBuilderFactory用起来要用NodeList反复遍历子节点代码写一大坨。XPathParser直接用evalNode(/configuration/settings)一步到位再通过XNode封装了getStringAttribute、getChildrenAsProperties、evalString这些常用操作。XNode这个类是阅读配置解析源码时绕不开的它把 DOM 的Node包装成更实用的模型底层存了xpathParser、node、attributes、name、body、children等字段所有取值操作都经过它。我在读源码时最佩服的一点是XNode的evalString方法会调用PropertyParser做变量替换。这意味着你在配置里写的${jdbc.url}这类占位符不是靠 Spring 处理而是PropertyParser从Properties里查出来替换掉。这跟properties标签里配置的外部文件、property子项以及构造时传入的Properties参数都有关系。解析顺序不同占位符能否解析成功也不一样。理解这一点你就明白为什么properties要放在配置最前面了。4.2 懒加载资源与失败容忍机制XMLConfigBuilder里还有两个容易被忽视的细节VFS和Log的加载。loadCustomVfs(settings)允许你通过配置vfsImpl自定义虚拟文件系统。MyBatis 默认用DefaultVFS扫描包下的类文件但在某些容器环境比如老的 WebLogic里默认扫描不到需要自定义 VFS。loadCustomLogImpl(settings)根据配置的logImpl决定使用 Slf4j、Log4j2、JDK Logging 还是 StdOut。没有配置时会按优先级自动探测这个探测结果会全局决定你看到的 SQL 日志长什么样。这两个加载动作同样走“反射实例化 设置属性”的套路失败会抛BuilderException。但相比 settings 的“静默容错”它们对错误更敏感。毕竟 VFS 和日志实现挂了后面解析和运行都没法玩。4.3 二级缓存初始化与解析的关系想搞懂 MyBatis 二级缓存建议从Configuration的cacheEnabled字段看起。settingsElement里会把它设成true但二级缓存的真正注册发生在 Mapper XML 解析时也就是说全局配置只负责开关每个 Mapper 里要不要开缓存、用什么淘汰策略都是在mappers解析阶段完成的。XMLMapperBuilder.cacheElement()会读取cache标签的eviction、flushInterval、size、readOnly、blocking等属性并用CacheBuilder构建缓存实例。perpetualCache是所有缓存的底层层结构再按配置包裹上LruCache、FifoCache、SoftCache、WeakCache等装饰器。很多人面试被问“MyBatis 一级二级缓存有什么区别”如果只背结论不如顺着这个解析链路理解一级缓存是Executor内部自带的LocalCache二级缓存是Configuration上维护的Cache对象两者生命周期完全不同。我遇到过一个问题某个 Mapper 明明配置了cache但查询结果一直没走二级缓存。后来排查发现全局配置的cacheEnabled被设置成了false导致Executor构建时直接绕过了二级缓存逻辑。所以排查缓存问题时第一件事永远是看cacheEnabled到底是不是true再看 Mapper 有没有flushCachefalse、有没有在增删改后清缓存。只盯着全局配置或只盯着 Mapper 配置都会掉坑。5. 实战配置调优与自定义扩展点5.1 启动后打印实际生效的 Configuration前面提到 settings 对拼写错误容忍度高那怎么快速知道实际配置最简单的方法是写一个启动监听器或直接在初始化代码里输出SqlSessionFactory factory new SqlSessionFactoryBuilder().build(inputStream); Configuration configuration factory.getConfiguration(); System.out.println(cacheEnabled configuration.isCacheEnabled()); System.out.println(lazyLoadingEnabled configuration.isLazyLoadingEnabled()); System.out.println(mapUnderscoreToCamelCase configuration.isMapUnderscoreToCamelCase()); System.out.println(defaultExecutorType configuration.getDefaultExecutorType());像我前面说的热词里“mybatis配置打印”相关的问题多半就是想搞清楚当前生效值。除了逐个 getter也可以看Configuration类的settings相关字段或反射遍历所有属性。不过日常排查用 getter 就足够了重点对照你想验证的那几个开关。5.2 自定义 TypeHandler 的正确姿势我建议自定义 TypeHandler 时统一用BaseTypeHandler这比实现TypeHandler接口省事得多。比如定义一个把LocalDateTime转成字符串的 handlerMappedTypes(LocalDateTime.class) MappedJdbcTypes(JdbcType.VARCHAR) public class LocalDateTimeStringTypeHandler extends BaseTypeHandlerLocalDateTime { private static final DateTimeFormatter FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); Override public void setNonNullParameter(PreparedStatement ps, int i, LocalDateTime parameter, JdbcType jdbcType) throws SQLException { ps.setString(i, parameter.format(FORMATTER)); } Override public LocalDateTime getNullableResult(ResultSet rs, String columnName) throws SQLException { String value rs.getString(columnName); return value null ? null : LocalDateTime.parse(value, FORMATTER); } Override public LocalDateTime getNullableResult(ResultSet rs, int columnIndex) throws SQLException { String value rs.getString(columnIndex); return value null ? null : LocalDateTime.parse(value, FORMATTER); } Override public LocalDateTime getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { String value cs.getString(columnIndex); return value null ? null : LocalDateTime.parse(value, FORMATTER); } }注册时建议用 XML 显式指定javaType和jdbcType不要只靠注解。注解只在 MyBatis 扫描时生效而MappedJdbcTypes的值如果没匹配上实际 JDBC 类型还是会走默认处理器。也别在包扫描的目录里放太多“半成品” handler扫描到非TypeHandler类型会直接注册失败拖慢启动。5.3 自定义配置项直接改源码还是另起炉灶有时候全局配置满足不了团队定制需求比如想在配置里加一个audit标签。直接改XMLConfigBuilder源码是最彻底的方案但升级 MyBatis 时会有冲突。更推荐的做法是不要在全局配置里乱加标签而是在 Spring 里用ConfigurationCustomizer或者在构建完成后手动往Configuration里塞自定义对象。如果你确实需要完整的自定义解析链路一种思路是复制一份XMLConfigBuilder在parseConfiguration里插入自定义节点解析逻辑然后让SqlSessionFactoryBuilder使用自定义 Builder。但这种方案离“改框架”不远团队里必须有人持续维护。我的经验是除非需求极其特殊否则尽可能复用 MyBatis 已有的扩展点比如Interceptor、TypeHandler、ObjectFactory这些扩展点覆盖了绝大多数字段映射和 SQL 执行场景。6. 常见问题与排查技巧实录6.1 “元素类型必须由匹配的结束标记终止”我见过最多人问的报错就是The element type settings must be terminated by the matching end-tag /settings。绝大多数情况是标签闭合写错了或者标签之间大小写不对。MyBatis 的 DTD 对大小写敏感settings写成了Settings一样报错。另一个常见原因是 XML 注释没写好!-- 这里注释了 settings 标签但没注释完整 -- settings setting namemapUnderscoreToCamelCase valuetrue/ !-- /settings --这种注释错误很难发现建议用 IDE 的 XML 校验功能提前检查。6.2 Configuration 解析顺序报错严格按 DTD 顺序写配置是最省心的习惯。我见过一个项目把mappers写在settings前面结果启动时 Mapper 里引用的别名还没注册直接抛TypeException。这里记一个排查技巧看到BuilderException: Error parsing SQL Mapper Configuration先不要急大概率不是 Mapper 的 SQL 写错了而是全局配置阶段有问题。用--debug启动应用在XMLConfigBuilder.parseConfiguration打上断点一步步看是哪个方法抛的异常。顺序相关的报错还有一个The content of element type configuration must match ...这是 DTD 校验直接拦截了顺序错误。这时去看 XML 中 configuration 下的子元素顺序按 DTD 调整即可。6.3 typeAliases/typeHandlers 不生效不生效基本只有三种情况包扫描路径写错扫描不到目标类。类上没有注解并且没在 XML 里显式指定 type。注意包扫描对没有Alias的类默认不按短类名注册但如果你显式使用typeAlias指定是可以注册的。字段类型和 TypeHandler 的javaType对不上。调试方法很简单在启动代码里打印configuration.getTypeAliasRegistry().getTypeAliases()或者configuration.getTypeHandlerRegistry().getTypeHandlers()。这些 Map 的 key 就是当前能识别的别名和处理器类型一眼就能看出注册结果。我踩过一次最离谱的坑是在typeHandlers里包扫描配置了某个目录但目录里连着一个旧的、异常的 handler 类MyBatis 扫描时直接抛了InstantiationException整个启动流程挂掉。排查时才意识到扫描机制会把目录下所有满足条件的类都实例化这个行为相当于“有多少注册多少”目录别放无关类。6.4 settings 配置“静默失效”拼错配置名、值类型不对、格式不对都可能导致 settings 配置不生效。比如lazyLoadingEnabled写成lazyLoadingEnableMyBatis 很大概率不会报错但功能不生效。为了避免这种“不知道改没改上”的困惑我建议团队统一在启动日志里输出关键配置项或者写个单测去读SqlSessionFactoryBuilder得到的Configuration对象断言关键开关的值。如果遇到 “配置了mapUnderscoreToCamelCasetrue但查询结果 map 的 key 仍然带下划线” 这种问题还有一个可能你在代码里手动用ResultSetHandler或Map接收结果MyBatis 并不会对Map的 key 做驼峰转换这个开关只对自动映射到 POJO 属性时生效。很多人忽略了这个边界。6.5 不同版本之间解析差异MyBatis 3.4、3.5 这些大版本之间配置解析的容错行为有明显差异。比如早期版本遇到未知 settings 配置项可能直接抛异常后续版本改成了更宽松的处理。升级版本后如果发现“之前跑得好好的配置文件突然报错”多半是版本差异导致的。建议升级时先读一下对应版本的release notes重点看Configuration类字段和XMLConfigBuilder的解析逻辑有没有变化。另外mybatis-config.dtd里的元素顺序也可能调整如果升级后 DTD 校验报错直接重新生成一份配置文件别手动猜。下面整理一个速查表方便直接对照报错现象大概率原因快速解法The content of element type configuration must matchconfiguration 子元素顺序不符合 DTD按 properties - settings - typeAliases - ... - mappers 顺序调整BuilderException: Error parsing SQL Mapper Configuration全局配置阶段出错常见为别名/TypeHandler 未注册断点定位XMLConfigBuilder.parseConfiguration看具体方法TypeException: Could not resolve type alias类型别名未注册或包扫描路径错误打印TypeAliasRegistry的注册表核对路径Invalid bound statement (not found)Mapper XML 没被mappers加载检查 resource 路径、package 扫描目录、namespace 与接口全限定名自定义 TypeHandler 不生效缺少javaType/jdbcType指定或MappedJdbcTypes不匹配显式在 XML 中指定并在注册后打印 TypeHandlerRegistrysettings 配置未生效配置名拼错或值类型不对用Configuration的 getter 打印实际值断点调试settingsElement7. 从源码回到日常我的几点实操体会把XMLConfigBuilder这段源码啃完最大的收获不是“哦原来有个类叫这个”而是以后看到配置相关报错脑子里会自动浮现出解析流程的先后顺序知道该在哪个环节打断点。我个人的习惯是新建项目时永远保持一份最小可用的mybatis-config.xml里面只放当前真正需要的配置项。MyBatis 有大量默认值不需要的配置不写反而能减少拼写错误和配置漂移的问题。等线上出现性能或行为异常再按需往里面加配置并用启动日志验证。最后再分享一个小技巧读这类源码时先跑一个最简单的 Demo用--debug跟着SqlSessionFactoryBuilder进一遍再回到XMLConfigBuilder.parseConfiguration()里逐行看每个方法的执行路径比你对着源码干想效率高得多。亲自跑一遍比我在这里讲一万字都管用。
