MyBatis中公用SQL片段通过定义+引用实现复用；本文件内引用直接写id，跨XML需用namespace.id全限定格式，嵌套引用也须带namespace，动态传参用配合${}（仅限安全结构参数）。

MyBatis 中引入公用 SQL 片段，核心靠 <sql></sql> 定义 + <include></include> 引用，分本文件内复用和跨 XML 复用两种场景，关键在 refid 的写法和参数传递方式。

本 XML 内引用：直接用 id

只要 `` 和 `` 在同一个 mapper 文件里，`refid` 只需写片段的 `id`：

<sql id="userColumns">id, username, email</sql>
<p><select id="listUsers" resultType="User">
SELECT <include refid="userColumns"/> FROM user
</select>

跨 XML 文件引用：必须带 namespace

要引用其他 mapper XML 中的 ``，`refid` 必须是 namespace.id 的完整形式（类似 Java 全限定类名）：

• A.xml 定义：

  <mapper namespace="com.example.dao.UserMapper">
    <sql id="baseQuery">SELECT id, name FROM user</sql>
  </mapper>

• B.xml 引用：

  <select id="getUserByDept" resultType="User">
    <include refid="com.example.dao.UserMapper.baseQuery"/>
    WHERE dept_id = #{deptId}
  </select>

注意：如果被引用的 `` 内部还嵌套了 ``，这些嵌套引用也得写成带 namespace 的全路径，否则启动时会找不到。

Java Api Extractor

从 Java 项目中提取 Controller 层接口定义为 JSON 数据。

下载

动态传参：用 给片段注入别名或表名

当不同查询中表别名不一致（如 u、o），可在 `` 里传参，片段内用 ${} 接收：

• 定义可变片段：

  <sql id="byNameCondition">AND ${alias}.name LIKE CONCAT('%', #{keyword}, '%')</sql>

• 调用时指定别名：

  <select id="searchUsers" resultType="User">
    SELECT * FROM user u
    <where>
      <include refid="byNameCondition">
        <property name="alias" value="u"/>
      </include>
    </where>
  </select>

⚠️ 注意：`${}` 是字符串拼接，不能防 SQL 注入，只适合传固定别名、表名等结构信息，别名应来自配置或白名单，不可由用户输入直接传入。

集中管理公共片段：单独建 common-mapper.xml

推荐把通用 SQL 提取到一个独立 XML 文件中，比如 CommonMapper.xml：

<mapper namespace="common">
  <sql id="pagination">LIMIT #{offset}, #{limit}</sql>
  <sql id="softDelete">AND deleted = 0</sql>
</mapper>

业务 mapper 中引用：

<include refid="common.pagination"/>

确保 Spring Boot 的 `mybatis.mapper-locations` 配置能扫描到这个文件（如 `classpath*:mybatis/**/*Mapper.xml`）。