MyBatis中CDATA段为何无法正确解析SQL中的特殊字符？

Question

在MyBatis中，开发者常误以为将SQL语句包裹在``内即可无条件规避XML解析异常（如 `<`, `>`, `&` 等特殊字符报错），但实际仍频繁出现“Invalid content was found starting with element 'if'”或SQL语法错误。根本原因在于：**MyBatis的XML映射文件需先经DOM/SAX解析器预处理，而CDATA仅保护其内部文本不被XML解析器转义——却无法阻止MyBatis自身对SQL片段的动态标签（如``、``）进行二次解析**。一旦CDATA块内混入MyBatis动态SQL标签（如` #{minStatus} ]]>`），这些标签将被当作纯文本而非指令，导致逻辑失效；反之，若将整个`

`体误包进CDATA，则MyBatis根本无法识别任何动态节点。简言之：CDATA解决的是XML合法性问题，而非MyBatis动态SQL的语法兼容性问题——二者作用域与解析阶段不同，不可混用。

Answer 1

```html

一、现象层：XML解析异常的典型表征

• 开发者在<select>标签内将含<、>、&的SQL（如status >= #{minStatus} AND status < 100）直接包裹在<![CDATA[...]]>中，却仍报错：Invalid content was found starting with element 'if'；
• SQL执行时抛出org.apache.ibatis.builder.BuilderException，提示“dynamic tag not allowed here”或生成的SQL含未解析的#{...}字面量；
• 日志显示MyBatis生成的最终SQL中出现AND status >= ?（实体转义残留），或#{id} < 5被原样输出而非替换。

二、机制层：双阶段解析模型与作用域隔离

MyBatis XML映射文件经历两个正交解析阶段：

1. XML预解析阶段（由JDK SAX/DOM完成）：校验XML结构合法性，将<![CDATA[...]]>内所有内容视为字符数据（PCDATA），跳过实体转义与标签识别；
2. MyBatis动态SQL构建阶段（由XmlStatementBuilder驱动）：遍历DOM节点树，仅对非CDATA子节点中的<if>、<where>、#{...}等进行语法识别与AST构建。

graph LR
A[XML文件加载] --> B{SAX解析器}
B -->|合法XML| C[DOM树：含CDATA节点]
B -->|非法XML| D[抛出SAXParseException]
C --> E[MyBatis遍历DOM节点]
E -->|遇到<if>节点| F[解析为SqlNode]
E -->|遇到CDATASection节点| G[跳过，不递归子节点]
G --> H[内部#{...}、<if>均成纯文本]

三、误区层：三大典型误用模式

误用场景	错误写法示例	后果
① 在CDATA内混用动态标签	<![CDATA[ WHERE status >= #{minStatus} <if test="maxStatus != null"> AND status <= #{maxStatus} </if> ]]	<if>被当作文本，条件逻辑完全失效
② 将整个SQL块包裹CDATA但保留外部动态节点	<where><![CDATA[ status >= #{minStatus} ]]></where>	<where>节点存在，但其内容为空（CDATA不贡献子节点）
③ 用CDATA替代XML转义，却忽略标签嵌套规则	<select><![CDATA[ SELECT * FROM user WHERE id < 10 ]]></select>	虽解决<报错，但<select>内必须含有效子元素（不能只有CDATA）

四、解法层：分层治理策略

• XML合法性问题 → 使用</>/&显式转义（推荐用于静态SQL片段）；
• 动态SQL语法兼容性 → 坚持MyBatis原生语法：用<where>替代WHERE硬编码，用<bind>预计算表达式；
• 复杂SQL转义需求 → 拆分为两层：<script>标签（支持内联脚本语法）+ 外部<![CDATA[...]]>包裹SQL主体（仅限无动态标签的纯SQL）；
• 终极方案 → 迁移至@SelectProvider注解或SqlProvider类，将SQL构造完全交由Java代码控制，彻底脱离XML解析约束。

五、验证层：可落地的诊断清单

1. 检查报错堆栈是否含SAXParseException（XML层）或BuilderException（MyBatis层）；
2. 启用MyBatis日志logging.level.org.apache.ibatis=DEBUG，观察Parsing SQL Mapping阶段输出的原始XML节点结构；
3. 使用DocumentBuilder.parse()独立加载Mapper XML，验证是否能通过W3C DOM校验；
4. 在IDE中安装MyBatisX插件，实时高亮动态标签作用域边界；
5. 对含大量比较运算符的SQL，优先采用<bind name="cond" value="'status >= ' + minStatus"/>解耦转义与逻辑。

```