MyBatis XML Mapper 特殊字符处理方案

jiayong232025-12-05 9:01

1. 问题描述

1.1 错误现象

后端服务启动时抛出 MyBatis XML Mapper 解析异常，导致应用无法正常启动。

1.2 错误堆栈

复制代码 
Caused by: org.apache.ibatis.builder.BuilderException: Error creating document instance.
  Cause: org.xml.sax.SAXParseException; lineNumber: 34; columnNumber: 28;
  元素内容必须由格式正确的字符数据或标记组成。
    at org.apache.ibatis.parsing.XPathParser.createDocument(XPathParser.java:262)
    at org.apache.ibatis.parsing.XPathParser.<init>(XPathParser.java:127)
    at com.baomidou.mybatisplus.core.MybatisXMLMapperBuilder.<init>(MybatisXMLMapperBuilder.java:87)
    at com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean.buildSqlSessionFactory(MybatisSqlSessionFactoryBean.java:681)
    ... 105 common frames omitted
Caused by: org.xml.sax.SAXParseException: 元素内容必须由格式正确的字符数据或标记组成。

1.3 错误位置

  • 文件 : smart-auth/src/main/resources/mapper/SmsCodeMapper.xml
  • 行号: 第 34 行，第 28 列
  • 错误语句 : WHERE expire_time < NOW()

2. 问题根因分析

2.1 XML 特殊字符冲突

在 XML 文档中，以下字符具有特殊含义，不能直接在元素内容中使用：

字符 含义 XML实体 说明
< 标签开始 &lt; Less Than
> 标签结束 &gt; Greater Than
& 实体引用开始 &amp; Ampersand
" 属性值引号 &quot; Quotation
' 属性值引号 ' Apostrophe

2.2 问题代码示例

错误写法 ❌：

xml 复制代码 
<select id="selectLatestUnusedByMobile" resultMap="BaseResultMap">
    SELECT * FROM sms_code
    WHERE mobile = #{mobile}
    AND used_status = 0
    AND expire_time > NOW()    <!-- XML解析器会将 > 视为标签结束符 -->
    ORDER BY create_time DESC
    LIMIT 1
</select>

<delete id="deleteExpired">
    DELETE FROM sms_code
    WHERE expire_time < NOW()   <!-- XML解析器会将 < 视为标签开始符 -->
</delete>

2.3 问题原因

XML 解析器在解析 Mapper 文件时，遇到 < 或 > 符号会误认为是 XML 标签的一部分，导致解析失败：

  • expire_time > NOW() → 解析器认为 > 是标签结束符
  • expire_time < NOW() → 解析器认为 < 是新标签的开始
  • 实际这些符号是 SQL 比较运算符，应作为普通文本处理

3. 解决方案

3.1 方案一：使用 XML 实体转义（不推荐）

将特殊字符替换为对应的 XML 实体：

xml 复制代码 
<select id="selectLatestUnusedByMobile" resultMap="BaseResultMap">
    SELECT * FROM sms_code
    WHERE mobile = #{mobile}
    AND used_status = 0
    AND expire_time &gt; NOW()    <!-- 使用 &gt; 代替 > -->
    ORDER BY create_time DESC
    LIMIT 1
</select>

<delete id="deleteExpired">
    DELETE FROM sms_code
    WHERE expire_time &lt; NOW()  <!-- 使用 &lt; 代替 < -->
</delete>

优点：

  • 符合 XML 规范
  • 无需额外语法

缺点：

  • 可读性差
  • 容易遗漏
  • 维护成本高

3.2 方案二：使用 CDATA 区段（推荐）✅

使用 <![CDATA[]]> 包裹 SQL 语句，CDATA 内的内容不会被 XML 解析器处理：

xml 复制代码 
<select id="selectLatestUnusedByMobile" resultMap="BaseResultMap">
    <![CDATA[
    SELECT * FROM sms_code
    WHERE mobile = #{mobile}
    AND used_status = 0
    AND expire_time > NOW()    <!-- 可以直接使用 > 符号 -->
    ORDER BY create_time DESC
    LIMIT 1
    ]]>
</select>

<delete id="deleteExpired">
    <![CDATA[
    DELETE FROM sms_code
    WHERE expire_time < NOW()  <!-- 可以直接使用 < 符号 -->
    ]]>
</delete>

优点：

  • ✅ 可读性强，SQL 语句保持原样
  • ✅ 无需转义，减少出错概率
  • ✅ MyBatis 官方推荐写法
  • ✅ 支持所有特殊字符（<, >, &, ", '）
  • ✅ 便于维护和调试

缺点：

  • 需要额外包裹语法（可忽略）

4. 实施步骤

4.1 修复 SmsCodeMapper.xml

文件路径 : smart-auth/src/main/resources/mapper/SmsCodeMapper.xml

修改前:

xml 复制代码 
<select id="selectLatestUnusedByMobile" resultMap="BaseResultMap">
    SELECT * FROM sms_code
    WHERE mobile = #{mobile}
    AND used_status = 0
    AND expire_time > NOW()
    ORDER BY create_time DESC
    LIMIT 1
</select>

<delete id="deleteExpired">
    DELETE FROM sms_code
    WHERE expire_time < NOW()
</delete>

修改后:

xml 复制代码 
<select id="selectLatestUnusedByMobile" resultMap="BaseResultMap">
    <![CDATA[
    SELECT * FROM sms_code
    WHERE mobile = #{mobile}
    AND used_status = 0
    AND expire_time > NOW()
    ORDER BY create_time DESC
    LIMIT 1
    ]]>
</select>

<delete id="deleteExpired">
    <![CDATA[
    DELETE FROM sms_code
    WHERE expire_time < NOW()
    ]]>
</delete>

4.2 验证修复

  1. 编译项目:

    bash 复制代码 
    mvn clean compile

  2. 启动应用:

    bash 复制代码 
    cd smart-api
mvn spring-boot:run

  3. 确认无异常:

    复制代码 
    ✅ Application started successfully
✅ No XML parsing errors

5. 最佳实践与规范

5.1 MyBatis XML Mapper 编码规范

5.1.1 SQL 语句统一使用 CDATA

强制要求 ：所有包含特殊字符的 SQL 语句必须使用 <![CDATA[]]> 包裹

xml 复制代码 
<!-- 正确示例 ✅ -->
<select id="queryUsers" resultType="User">
    <![CDATA[
    SELECT * FROM users
    WHERE age > 18
    AND status <> 'DELETED'
    AND name LIKE CONCAT('%', #{keyword}, '%')
    ]]>
</select>

<!-- 错误示例 ❌ -->
<select id="queryUsers" resultType="User">
    SELECT * FROM users
    WHERE age > 18           <!-- XML 解析错误 -->
    AND status <> 'DELETED'  <!-- XML 解析错误 -->
</select>
5.1.2 特殊字符清单

需要使用 CDATA 或转义的场景：

SQL 语句 特殊字符 原因
age > 18 > 标签结束符
age < 18 < 标签开始符
status <> 'DELETED' <> 不等于运算符
value >= 100 >= 大于等于
value <= 100 <= 小于等于
name LIKE 'A&B' & 实体引用开始
动态拼接多个条件 多个特殊字符 复杂SQL

5.2 CDATA 使用注意事项

✅ 推荐做法
xml 复制代码 
<!-- 1. 整体包裹 SQL -->
<select id="query" resultMap="BaseResultMap">
    <![CDATA[
    SELECT * FROM table
    WHERE condition > 0
    ]]>
</select>

<!-- 2. 保持缩进美观 -->
<select id="query" resultMap="BaseResultMap">
    <![CDATA[
        SELECT
            id, name, age
        FROM users
        WHERE age > 18
        AND status <> 'DELETED'
        ORDER BY create_time DESC
    ]]>
</select>

<!-- 3. 复杂SQL分段处理 -->
<select id="complexQuery" resultMap="BaseResultMap">
    SELECT * FROM users
    <where>
        <if test="age != null">
            <![CDATA[ AND age >= #{age} ]]>
        </if>
        <if test="status != null">
            AND status = #{status}
        </if>
    </where>
</select>
❌ 错误做法
xml 复制代码 
<!-- 1. 嵌套CDATA（不支持） -->
<select id="query">
    <![CDATA[
        SELECT * FROM (
            <![CDATA[ SELECT id FROM temp ]]>  <!-- ❌ CDATA不能嵌套 -->
        ) t
    ]]>
</select>

<!-- 2. CDATA内使用动态SQL标签（无效） -->
<select id="query">
    <![CDATA[
        SELECT * FROM users
        <if test="age != null">  <!-- ❌ 动态标签在CDATA内不生效 -->
            AND age > #{age}
        </if>
    ]]>
</select>

5.3 代码审查检查清单

在代码审查（Code Review）时，检查以下内容：

  • 所有 Mapper XML 文件中的比较运算符（<, >, <=, >=, <>）是否使用了 CDATA 或正确转义
  • CDATA 区段是否正确闭合
  • 动态 SQL 标签是否在 CDATA 外部
  • SQL 缩进是否规范、可读性是否良好
  • 是否有不必要的 CDATA（无特殊字符的SQL不需要CDATA）

6. 相关知识扩展

6.1 XML 规范（W3C标准）

根据 XML 1.0 规范：

2.4 Character Data and Markup

Text consists of intermingled character data and markup. Markup takes the form of start-tags, end-tags, empty-element tags, entity references, character references, comments, CDATA section delimiters, document type declarations, processing instructions, XML declarations, text declarations, and any white space that is at the top level of the document entity.

6.2 MyBatis 官方文档

MyBatis 官方文档对 CDATA 的说明：

Mapper XML Files - SQL

If you need to use special characters like <, > in your SQL, you should either escape them (using &lt;, &gt;) or wrap the SQL in a CDATA section.

参考链接：

6.3 常见框架对比

框架 XML特殊字符处理 推荐方案
MyBatis 支持CDATA、实体转义 CDATA
Hibernate HQL中无此问题 -
Spring JDBC Java代码中无此问题 -
JPA/JPQL JPQL中无此问题 -

7. 总结

7.1 问题回顾

  • 问题 : MyBatis XML Mapper 中使用 <, > 等 SQL 比较运算符导致 XML 解析失败
  • 原因: XML 将这些符号视为标签定界符，而非文本内容
  • 影响: 应用无法启动，阻塞开发和部署

7.2 解决方案

  • ✅ 推荐方案 : 使用 <![CDATA[]]> 包裹 SQL 语句
  • ⚠️ 备选方案 : 使用 XML 实体转义（&lt;, &gt;等）

7.3 预防措施

  1. 开发规范: 团队统一使用 CDATA 包裹 SQL 语句
  2. 代码审查: CR时重点检查 Mapper XML 文件
  3. 单元测试: 为每个 Mapper 方法编写单元测试，及早发现问题
  4. CI/CD: 在 CI 流水线中集成 XML 语法检查工具
  5. IDE配置: 使用支持 MyBatis 的 IDE 插件（如 MyBatisX），自动提示错误
相关推荐
i***683214 小时前
【MyBatis】spring整合mybatis教程（详细易懂）
java·spring·mybatis
旷野说16 小时前
为什么 MyBatis 原生二级缓存“难以修复”？
java·java-ee·mybatis
abments19 小时前
mybatis-plus 在lambdaUpdate中使用ypeHandler
mybatis
S***q37720 小时前
【Springboot】@Autowired和@Resource的区别
java·spring boot·mybatis
e***193521 小时前
【mybatis】基本操作：详解Spring通过注解和XML的方式来操作mybatis
xml·spring·mybatis
编程修仙21 小时前
第七篇 java的注解以及使用反射实现自定义注解功能
xml·java·开发语言·spring
7ioik1 天前
Spring框架整合MyBatis框架？（超级详细）
java·spring·mybatis
踏浪无痕1 天前
你真的懂泛型吗？手写 MyBatis-Plus + Jackson，揭秘框架设计的精髓
后端·json·mybatis
热门推荐
01GitHub 镜像站点02【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）03UV安装并设置国内源04React CVE-2025-55182漏洞排查与修复指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06BongoCat - 跨平台键盘猫动画工具07本地部署阿里最新开源的Z-Image08Linux下V2Ray安装配置指南09智能库存管理的需求预测模型：从业务痛点到落地代码的完整实践10Labelme从安装到标注：零基础完整指南