MyBatis——选择混合模式还是全注解模式?

theme: cyanosis

MyBatis——选择混合模式还是全注解模式?

在使用 MyBatis 开发项目时，Mapper 接口是为数据库操作提供最直观的方法，但在实现方式上，我们有两种选择：全注解模式和混合模式。那么，他们有什么区别，应该如何选择？我们一起来讨论一下。

一、全注解模式

全注解模式，两个字：直接。不过在 Mapper 接口中加上注解，将数据库操作直接通过 SQL 语句控制，想查询就用 @Select，想插入就用 @Insert，完全是一样的操作体验。

实现样例

这里有一个基础的用户操作 Mapper：

@Mapper
public interface UserMapper {
   

    @Insert("INSERT INTO user (username, password, role) VALUES (#{username}, #{password}, #{role})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    void insertUser(User user);

    @Select("SELECT * FROM user WHERE username = #{username}")
    User findByUsername(String username);

    @Update("UPDATE user SET password = #{password} WHERE id = #{id}")
    void updatePassword(@Param("id") Integer id, @Param("password") String password);
}

优势

• 文件构成简单，文件自带直观性。
• SQL 语句在全注解模式下直观且清晰，这种方式能够减少错误的发生，尤其是在接口简单、逻辑清晰的情况下。
• 适合小应用或数据库表规模较简单的场景。

不足

• SQL 语句直接嵌入代码中，容易导致代码臃肿：当查询逻辑变复杂时，大量 SQL 会堆积在接口文件中，导致文件过长且难以维护。
• 扩展性差：复杂的查询条件需要硬编码在注解中，无法灵活调整，尤其对于需要动态拼接 SQL 的场景显得力不从心。
• 团队协作时难以分工：开发人员需要同时熟悉 SQL 和 Java，且 SQL 的变更可能需要修改接口文件，增加沟通成本。

二、混合模式

混合模式，是使用“接口声明 + XML 配置文件”的方式实现。Mapper 接口直接定义操作类型，而 SQL 语句则存在于配置文件中。

实现样例

一个复杂旅游线路查询 Mapper:

@Mapper
public interface TourLineMapper {

    List<TourLine> filterTourLines(@Param("destination") String destination,
                                   @Param("minPrice") Double minPrice,
                                   @Param("maxPrice") Double maxPrice,
                                   @Param("minDuration") Integer minDuration,
                                   @Param("maxDuration") Integer maxDuration);
}

优势体现在 XML 配置文件中：

<select id="filterTourLines" parameterType="map" resultType="TourLine">
    SELECT * FROM tour_line
    WHERE 1 = 1
    <if test="destination != null">AND destination = #{destination}</if>
    <if test="minPrice != null">AND price >= #{minPrice}</if>
    <if test="maxPrice != null">AND price <= #{maxPrice}</if>
    <if test="minDuration != null">AND duration >= #{minDuration}</if>
    <if test="maxDuration != null">AND duration <= #{maxDuration}</if>
</select>

结构解读

1. <select> 标签

   • 定义了一个 filterTourLines 查询方法，与 Java 中的接口方法对应。
   • parameterType="map" 指定了传入的参数类型是一个 Map（常见场景中，通过 @Param 传递多个参数时，MyBatis 会将其转换为 Map）。
   • resultType="TourLine" 定义了查询结果的返回类型为 TourLine 对象。

2. WHERE 1 = 1

   • 这是一种防止 SQL 拼接错误的技巧，为后续条件拼接提供基础，即使没有后续条件，SQL 也不会因为没有 WHERE 子句而报错。

3. 动态条件（<if> 标签）

   • <if> 是 MyBatis 动态 SQL 的重要组成部分，用于判断条件是否为 true，从而决定是否拼接该部分 SQL。

   • 例如：

     <if test="destination != null">AND destination = #{destination}</if>
     

     如果 destination 参数不为空，就会将 AND destination = #{destination} 拼接到最终的 SQL 语句中。

4. 参数替换

   • 每个条件中的 #{} 会被传入的参数动态替换为具体值，保证查询的安全性，防止 SQL 注入。

编写技巧

• SQL 拼接优雅性 使用 <if> 标签时，可以避免在 Java 代码中手动拼接 SQL，提高代码的可读性和维护性。

• 参数命名一致性 确保 XML 文件中的参数名称与 Java 接口方法中 @Param 注解指定的名称一致，否则会导致参数映射失败。

• 灵活性

  • 如果需要更多动态条件，比如基于某个字段的排序，可以在 <if> 标签外部增加 <choose> 和 <when> 标签实现更复杂的逻辑。

  • 例如：

    <choose>
        <when test="sortField != null and sortDirection != null">
            ORDER BY ${sortField} ${sortDirection}
        </when>
        <otherwise>
            ORDER BY id ASC
        </otherwise>
    </choose>
    

适用场景

这段动态 SQL 非常适合以下场景：

• 参数较多且查询条件可能动态变化，比如多字段过滤、范围查询等。
• 查询的复杂度较高，不适合直接写在 Java 中，分离到 XML 更易维护。

优势

• 加强了 SQL 实现的优雅性：复杂的查询可以在 XML 文件中通过加入条件转换，条件拼接更加灵活，避免硬编码。
• 分离关注点，降低耦合：Java 和 SQL 各司其职，Java 专注业务逻辑，SQL 专注数据操作，改动时互不干扰。
• 适合复杂查询与大项目：对于动态查询需求较高的大型项目，混合模式显得尤为重要，XML 配置文件支持强大的动态 SQL 功能（如 <if>、<choose> 等）。

不足

• 学习成本较高：需要同时掌握接口声明和 XML 文件配置的语法，对初学者来说可能较难上手。
• 文件分散，调试不便：SQL 语句分散在 XML 文件中，可能导致维护时需要在多个文件间切换。
• 开发速度稍慢：相比全注解模式，混合模式的开发速度会稍有降低，尤其是在小型项目中。

三、如何选择？

• 如果你的项目规模较小，数据表结构简单，查询逻辑以基础的增删改查为主，可以选择全注解模式。它能够快速上手，开发效率高，适合对时间要求较高的场景。
• 如果你的项目规模较大，查询逻辑复杂且动态变化较多，建议选择混合模式。它的灵活性和可维护性更强，能够为复杂需求提供更好的支持。
• 团队协作时，混合模式的分离设计可以降低沟通成本，尤其对于 SQL 改动频繁的项目。

无论选择哪种模式，最重要的是根据项目需求灵活运用，选择最适合自己团队和业务的方式。