MyBatis代码生成器覆盖自定义SQL，如何安全保留手写SQL？

Question

**常见技术问题：** 使用 MyBatis Generator（MBG）进行数据库表映射时，若将 `mapper.xml` 或 `@Select/@Update` 等手写 SQL 与自动生成的 XML/接口混置于同一文件（如 `UserMapper.xml`），每次执行 MBG 生成会**无差别覆盖整个文件**，导致精心编写的复杂查询、动态 SQL、关联分页等逻辑被清空，引发线上故障。尤其在团队协作中，开发人员易误操作或 CI/CD 流程自动触发生成，加剧风险。根本矛盾在于 MBG 默认不支持“增量合并”或“区域保留”，其 `` 片段、`` 扩展及多表联查等高频自定义内容缺乏安全隔离机制。如何在保障代码生成效率的同时，确保手写 SQL 的完整性、可维护性与版本可控性，成为落地 MBG 的关键瓶颈。

Answer 1

```html

一、问题本质剖析：MBG 的“全量覆盖”设计哲学与工程现实的冲突

MyBatis Generator 本质上是一个代码模板引擎，而非增量同步工具。其核心逻辑是「销毁旧文件 → 渲染新模板 → 写入磁盘」，不解析已有 XML 结构，也不识别 <!-- @MBG_START --> 等保留标记。当开发者将手写 <select id="findWithOrders"> 插入 UserMapper.xml 后，MBG 下次执行即彻底抹除该节点——这并非 Bug，而是设计契约的必然结果。团队中若存在 CI/CD 自动触发（如 Git push 后调用 mvn mybatis-generator:generate），风险呈指数级放大。

二、典型误用场景与故障链路（含 Mermaid 流程图）

flowchart LR
A[开发人员新增关联查询] --> B[手动编辑 UserMapper.xml]
B --> C[提交代码至 Git]
C --> D[CI/CD 检测到 pom.xml 变更]
D --> E[自动执行 MBG 生成]
E --> F[覆盖整个 UserMapper.xml]
F --> G[手写 SQL 永久丢失]
G --> H[测试环境分页查询报 NPE]
H --> I[线上订单列表白屏]

三、行业主流解决方案对比表

方案	原理	MBG 覆盖风险	维护成本	适用阶段
✅ 接口继承法	自定义 UserExtMapper 继承 MBG 生成的 UserMapper	零风险（XML 完全分离）	低（仅需定义新接口+XML）	所有项目
✅ 注解驱动法	手写 SQL 全部移至 @SelectProvider 或 @Select 注解	零风险（注解在 Java 文件，MBG 不触碰）	中（动态 SQL 需抽象为 Provider 类）	Spring Boot 2.3+
⚠️ 自定义插件法	扩展 MBG Plugin，解析并合并 XML 中的 <!-- MBG-KEEP-BEGIN --> 区域	可控（需严格约定标记语法）	高（需维护插件+团队培训）	大型遗留系统迁移期

四、推荐落地实践：接口继承 + XML 分离架构

以 User 表为例，构建双层 Mapper 体系：

1. MBG 生成层：UserMapper.java + UserMapper.xml（仅含 CRUD）
2. 业务扩展层：UserExtMapper.java（继承 UserMapper）
3. 独立 XML：UserExtMapper.xml（仅存 <select id="searchWithRoles"> 等复杂 SQL）
4. Spring 配置：在 mybatis-config.xml 中显式注册 UserExtMapper.xml
5. CI/CD 安全策略：在 Maven profile 中禁用生产环境的 MBG 自动生成

<!-- UserExtMapper.xml 示例 -->
<mapper namespace="com.example.mapper.UserExtMapper">
  <resultMap id="UserWithRoles" type="User">
    <id property="id" column="user_id"/>
    <collection property="roles" ofType="Role" column="user_id"
                select="com.example.mapper.RoleMapper.selectByUserId"/>
  </resultMap>
  <select id="searchWithRoles" resultMap="UserWithRoles">
    SELECT u.* FROM user u WHERE u.status = #{status}
  </select>
</mapper>

五、高阶防御机制：Git Hooks + 静态检查

在团队级防护层面，可部署以下组合策略：

• Pre-commit Hook：扫描所有 *Mapper.xml 文件，若检测到 <select> 标签但无对应 ExtMapper 命名，则阻断提交
• CI 阶段 Checkstyle：校验 MBG 配置文件 generatorConfig.xml 中是否启用 <property name="enableSubPackages" value="true"/>，强制模块隔离
• GitLab MR Pipeline：添加 verify-mbg-safety job，使用 XPath 解析 XML 并报告手写 SQL 存量

```