① 情景引入:凌晨一点的“XML 解析异常”
那晚上线前最后一次回归,系统一启动就抛 org.apache.ibatis.builder.BuilderException: Error parsing SQL Mapper Configuration。我盯着这行红字,第一反应是“配置文件又写错了?”检查 mybatis-config.xml,没问题;检查数据源,正常。开始二分排查:把新加的 Mapper 一个个注释掉,最后锁定到一个刚写的动态 SQL 上——就是那个 <if> 判断里多写了一对双引号。改动只有一行,排查花了一个半小时。
这种低级错误,白天写代码时手一滑就进去了:想判断“姓名不能为空字符串”,顺手写了 name != "";想判断“状态是 ACTIVE”,写了 status != "ACTIVE"。在 Java 代码里这完全合法,可这里是 MyBatis 的 XML。
② 根因:XML 属性值的边界被双引号提前终止
MyBatis 的动态 SQL 写在 XML 里,<if> 的 test 属性值用双引号包裹。比如:
<if test="name != null and name != "">
XML 解析器读到 test=" 时,认为属性值从第二个双引号开始,然后扫描到 name != 后面的双引号时,认为属性值结束了。后面的 "> 部分变成了非法内容,整个标签结构被破坏。解析器直接抛异常,或者更糟——在某些宽松模式下把属性截断,导致 OGNL 表达式解析出完全不同的逻辑。
关键点:XML 的属性值语法只认双引号(或单引号)作为边界。内部再出现同一种引号,解析器不会自动“智能配对”,而是就近闭合。所以 test="name != "" 被解析成属性值是 name != ,剩下 ""> 成了没意义的尾巴。
③ 为什么难查:报错信息经常指向别处
这类问题的迷惑性在于,报错位置和实际错误行往往对不上。XML 解析异常可能报在 <mapper> 起始标签,而不是出错的那一行;OGNL 表达式错误可能报“属性未定义”或“类型转换失败”,让你去查 Java 对象的方法,而不是 XML 字符串的引号。更隐蔽的情况是:如果引号内外的字符串拼接结果恰好能通过 OGNL 解析,SQL 会在运行时才出错,比如 where status = "PUBLISHED" 这行在 XML 里如果没被截断,传到数据库可能被当成列名或标识符,报出完全无关的 SQL 错误。
④ 快速定位:先手动扫描再切半排查
遇到 MyBatis 启动报 BuilderException 或 XMLMapperBuilder 相关异常,先别急着翻原理,直接跑这些命令:
# 扫描 XML 中所有双引号包字符串的常见错误模式
grep -rn '!= ""' src/main/resources/mapper/ --include="*.xml"
grep -rn '= ""' src/main/resources/mapper/ --include="*.xml"
grep -rn '= "[A-Za-z]' src/main/resources/mapper/ --include="*.xml"
# 如果已经锁定某个 Mapper,打印行号快速定位
grep -n '"' UserMapper.xml | head -20
如果这些扫描没找到,再用二分注释法:把新加的 <select>、<insert>、<update> 段落块注释掉一半,慢慢缩小范围。注意 XML 注释是 <!-- -->,别把结束标签也注释掉。
⑤ 修复与避坑:字符串用单引号,数字别加引号
把所有 test 属性里的字符串字面量改成单引号:
<!-- ❌ 错误 -->
<if test="name != null and name != "">
<if test="status != "ACTIVE"">
where status = "PUBLISHED"
<!-- ✅ 正确 -->
<if test="name != null and name != ''">
<if test="status != null and status != ''">
where status = 'PUBLISHED'
where is_featured = '1'
规则很简单:字符串字面量用单引号,数字类型不要加引号。 比如 where is_featured = '1' 这里 '1' 是字符串,但如果字段是整形,应该写成 where is_featured = 1 不加引号。空串判断就写 != '',不要写 != ""。另外,</mapper>、</select> 这类结束标签必须独占一行,不能拼在标签内容后面,否则解析器会把标签内容末尾的空白当成结束标签的一部分,引发另一个隐蔽错误。
⑥ 验收铁律
写完 MyBatis 动态 SQL 后,用下面清单过一遍,避免双引号坑:
❌ 这些写法会出事
test属性内部出现"双引号,比如name != ""、status != "ACTIVE"- 把 Java 的字符串比较习惯直接搬到 XML 里,不区分引号类型
- 字符串和数字混用引号规则,如给数字字段加
'1'(除非字段本身就是字符串类型) - 结束标签不独占一行,拼在标签内容后面
- 只依赖 IDE 的 XML 格式检查,不手动扫描双引号模式
✅ 这些写法才能过
test属性内所有字符串字面量用单引号:name != ''、status != 'ACTIVE'- XML 属性本身用双引号包裹,内部字符串用单引号,两种引号不冲突
- 数字类型比较直接写
!= null,不加引号 - 每个
</mapper>、</select>、</update>都独占一行 - 每次新增或修改 Mapper XML 后,跑一遍上面的 grep 扫描命令
如果已经踩了这个坑,或者不确定自己的 XML 里还有没有隐藏的双引号,可以把自己的 Mapper 文件贴出来,我帮你扫一眼引号模式。