2.5 SQL 片段 (SQL Fragment)

文档摘要

2.5 SQL 片段 (SQL Fragment) MyBatis 映射器深入：2.5 SQL 片段 (SQL Fragment) 在 MyBatis 中，SQL 片段 (SQL Fragment) 是一种强大的工具，用于定义可重用的 SQL 代码块。通过定义 SQL 片段，我们可以避免在多个映射文件中重复编写相同的 SQL 代码，从而提高代码的可维护性和可读性。 2.5.1 SQL 片段的定义与引用 SQL 片段使用标签定义，并使用属性为其指定一个唯一的标识符。然后，可以使用标签通过属性引用该 SQL 片段。 2.5.1.1 定义 SQL 片段在上面的例子中，我们定义了一个名为的 SQL 片段，它包含了表的基本列名。 2.5.1.

2.5 SQL 片段 (SQL Fragment)

MyBatis 映射器深入：2.5 SQL 片段 (SQL Fragment)

在 MyBatis 中，SQL 片段 (SQL Fragment) 是一种强大的工具，用于定义可重用的 SQL 代码块。通过定义 SQL 片段，我们可以避免在多个映射文件中重复编写相同的 SQL 代码，从而提高代码的可维护性和可读性。

2.5.1 SQL 片段的定义与引用

SQL 片段使用 <sql> 标签定义，并使用 id 属性为其指定一个唯一的标识符。然后，可以使用 <include> 标签通过 refid 属性引用该 SQL 片段。

2.5.1.1 定义 SQL 片段


<sql id="baseUserColumns">
  id, username, password, email, create_time, update_time
</sql>

在上面的例子中，我们定义了一个名为 baseUserColumns 的 SQL 片段，它包含了 user 表的基本列名。

2.5.1.2 引用 SQL 片段


<select id="getUserById" resultType="User">
  SELECT
    <include refid="baseUserColumns"/>
  FROM
    user
  WHERE
    id = #{id}
</select>
<select id="getAllUsers" resultType="User">
  SELECT
    <include refid="baseUserColumns"/>
  FROM
    user
</select>

在上面的例子中，我们在 getUserById 和 getAllUsers 这两个 select 语句中都引用了 baseUserColumns SQL 片段。这样，我们就不需要在每个 select 语句中都重复编写相同的列名，而是通过引用 SQL 片段来实现代码的重用。

2.5.2 SQL 片段的优点

提高代码的可维护性: 当需要修改 SQL 代码时，只需要修改 SQL 片段的定义，而不需要修改所有引用该 SQL 片段的地方。
提高代码的可读性: 通过将复杂的 SQL 代码分解为多个 SQL 片段，可以提高代码的可读性。
减少代码的重复: 可以避免在多个映射文件中重复编写相同的 SQL 代码。

2.5.3 SQL 片段的应用场景

定义公共的列名列表: 可以定义一个 SQL 片段来包含所有表的公共列名，然后在所有的 select 语句中引用该 SQL 片段。
定义公共的 where 子句: 可以定义一个 SQL 片段来包含公共的 where 子句，然后在多个 select 语句中引用该 SQL 片段。
定义公共的 order by 子句: 可以定义一个 SQL 片段来包含公共的 order by 子句，然后在多个 select 语句中引用该 SQL 片段。
动态SQL的构建: SQL 片段可以与其他动态 SQL 标签（如 <if>, <choose>, <when>, <otherwise>, <trim>, <where>, <set>, <foreach>）结合使用，以构建更复杂的动态 SQL 语句。

2.5.4 代码实践与详解

假设我们有一个 user 表，包含以下字段：id, username, password, email, create_time, update_time, status。我们希望定义一些 SQL 片段来简化我们的映射文件。

2.5.4.1 定义常用的 SQL 片段


<mapper namespace="com.example.UserMapper">
  <sql id="baseUserColumns">
    id, username, password, email, create_time, update_time, status
  </sql>
  <sql id="baseUserWhereClause">
    <where>
      <if test="id != null">
        id = #{id}
      </if>
      <if test="username != null and username != ''">
        AND username = #{username}
      </if>
      <if test="email != null and email != ''">
        AND email = #{email}
      </if>
      <if test="status != null">
        AND status = #{status}
      </if>
    </where>
  </sql>
  <!-- 其他映射语句 -->
</mapper>

baseUserColumns: 定义了 user 表的所有列。
baseUserWhereClause: 定义了一个动态的 where 子句，可以根据传入的参数动态生成 SQL 语句。使用了 <where> 标签，该标签会自动处理 where 关键字和 AND 关键字。

2.5.4.2 使用 SQL 片段


<select id="getUserById" resultType="User">
  SELECT
  <include refid="baseUserColumns"/>
  FROM user
  WHERE id = #{id}
</select>
<select id="getUserByUsername" resultType="User">
  SELECT
  <include refid="baseUserColumns"/>
  FROM user
  WHERE username = #{username}
</select>
<select id="findUsers" parameterType="map" resultType="User">
  SELECT
  <include refid="baseUserColumns"/>
  FROM user
  <include refid="baseUserWhereClause"/>
</select>
<update id="updateUserStatus" parameterType="map">
  UPDATE user
  SET status = #{status}
  <where>
    id = #{id}
  </where>
</update>

getUserById 和 getUserByUsername: 这两个查询语句都使用了 baseUserColumns SQL 片段来获取 user 表的所有列。
findUsers: 这个查询语句使用了 baseUserColumns 和 baseUserWhereClause SQL 片段。 baseUserWhereClause 会根据传入的 map 参数动态生成 where 子句。
updateUserStatus: 这里展示了在 update 语句中使用 <where> 标签的例子，虽然没有使用 SQL 片段，但是和 SQL 片段的动态构建思想类似，可以减少代码重复。

2.5.5 SQL 片段的覆盖

MyBatis 允许在引用 SQL 片段时覆盖其内容。这可以通过在 <include> 标签内添加 <property> 标签来实现。

示例：

假设我们想在 getUserById 查询中只返回 id 和 username 两个字段，我们可以这样做：


<select id="getUserById" resultType="User">
  SELECT
  <include refid="baseUserColumns">
    <property name="id" value="id"/>
    <property name="username" value="username"/>
  </include>
  FROM user
  WHERE id = #{id}
</select>

但是，上面的例子是错误的。 <property> 标签并非用来选择需要包含的列，而是用来动态替换 SQL 片段中的变量。要实现只返回部分字段，应该修改 baseUserColumns 片段本身，或者创建新的 SQL 片段。

更合适的做法是，创建一个新的SQL片段，或者修改原来的SQL片段：


<sql id="userIdAndUsernameColumns">
  id, username
</sql>
<select id="getUserById" resultType="User">
  SELECT
  <include refid="userIdAndUsernameColumns"/>
  FROM user
  WHERE id = #{id}
</select>

或者，在原来的 baseUserColumns 中使用动态 SQL 来控制返回的字段（虽然通常不建议这么做，因为会增加复杂性）：


<sql id="baseUserColumns">
  <if test="includeAllColumns == null or includeAllColumns">
    id, username, password, email, create_time, update_time, status
  </if>
  <if test="includeIdAndUsername != null and includeIdAndUsername">
    id, username
  </if>
</sql>
<select id="getUserById" resultType="User">
  SELECT
  <include refid="baseUserColumns">
    <property name="includeIdAndUsername" value="true"/>
  </include>
  FROM user
  WHERE id = #{id}
</select>

注意：第二种方法需要你传递一个参数 includeIdAndUsername 到 SQL 片段中，这会使代码更加复杂，所以通常不推荐使用。

2.5.6 SQL 片段与动态 SQL 的结合

SQL 片段可以与 MyBatis 的动态 SQL 功能结合使用，以创建更加灵活和强大的 SQL 语句。例如，我们可以使用 <if> 标签来根据条件包含不同的 SQL 片段。

示例：


<sql id="userSearchCriteria">
  <where>
    <if test="username != null and username != ''">
      username LIKE #{username}
    </if>
    <if test="email != null and email != ''">
      AND email LIKE #{email}
    </if>
    <if test="status != null">
      AND status = #{status}
    </if>
  </where>
</sql>
<select id="searchUsers" parameterType="map" resultType="User">
  SELECT
  <include refid="baseUserColumns"/>
  FROM user
  <include refid="userSearchCriteria"/>
</select>

在这个例子中，userSearchCriteria SQL 片段包含了一个动态的 where 子句，它可以根据传入的 username, email 和 status 参数来生成不同的 SQL 语句。

2.5.7 SQL 片段的命名空间

SQL 片段的作用域是定义它的映射器文件。如果需要在不同的映射器文件中引用 SQL 片段，可以使用命名空间来指定 SQL 片段的来源。

示例：

假设我们在 UserMapper.xml 文件中定义了一个名为 baseUserColumns 的 SQL 片段，我们可以在另一个名为 OrderMapper.xml 的文件中这样引用它：


<select id="getOrderWithUser" resultType="Order">
  SELECT
  o.*,
  <include refid="com.example.UserMapper.baseUserColumns"/>
  FROM orders o
  JOIN user u ON o.user_id = u.id
  WHERE o.id = #{id}
</select>

注意：我们需要使用完整的命名空间 com.example.UserMapper.baseUserColumns 来指定 SQL 片段的来源。

2.5.8 SQL 片段的注意事项

SQL 片段的 id 必须是唯一的，在同一个命名空间内。
避免在 SQL 片段中包含完整的 SQL 语句，尽量只包含 SQL 代码块。
合理使用 SQL 片段可以提高代码的可维护性和可读性，但是过度使用 SQL 片段可能会导致代码难以理解。

2.5.9 流程图示例

总结

SQL 片段是 MyBatis 中一个非常有用的特性，它可以帮助我们提高代码的可维护性、可读性和可重用性。通过合理使用 SQL 片段，我们可以编写更加简洁、高效的 MyBatis 映射文件。掌握SQL片段的定义、引用、覆盖以及与动态SQL的结合使用，是成为一名优秀的 MyBatis 开发者的重要一步。

作者与出处

原作者：灏天文库

来源：灏天文库

原文： https://aiknowledge.cn/collection/211-mybatis%E6%8C%81%E4%B9%85%E5%B1%82%E6%A1%86%E6%9E%B6%E5%BC%80%E5%8F%91%E6%95%99%E7%A8%8B

整理：灏天文库整理

由灏天文库平台收录，内容或由平台用户上传，仅供学习交流