MyBatis 使用手册：从基础到进阶的完整指南

一、MyBatis 核心架构解析

MyBatis 是一款支持普通 SQL 查询、存储过程和高级映射的持久层框架，其核心设计理念是”SQL 与代码分离”。与 Hibernate 的全自动化 ORM 不同，MyBatis 采用半自动化模式，开发者需要手动编写 SQL 语句，但通过 XML 或注解方式实现了 SQL 与 Java 代码的解耦。

1.1 工作流程详解

MyBatis 的执行流程可分为五个关键阶段：

1. 配置加载阶段：读取全局配置文件（mybatis-config.xml）和映射文件（Mapper XML）
2. SQL 解析阶段：将 XML 中的 SQL 语句解析为 SqlSource 对象
3. 参数处理阶段：通过 ParameterHandler 将 Java 对象转换为 JDBC 所需参数类型
4. SQL 执行阶段：由 Executor 执行器完成数据库操作
5. 结果处理阶段：通过 ResultSetHandler 将查询结果映射为 Java 对象

典型配置示例：

<!-- mybatis-config.xml 核心配置 -->
<configuration>
    <settings>
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <setting name="cacheEnabled" value="true"/>
    </settings>
    <typeAliases>
        <package name="com.example.model"/>
    </typeAliases>
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
        <mapper class="com.example.mapper.UserMapper"/>
    </mappers>
</configuration>

二、动态 SQL 高级应用

MyBatis 的动态 SQL 功能通过 <if>, <choose>, <foreach> 等标签实现条件化 SQL 构建，这是其区别于传统 JDBC 的核心优势之一。

2.1 条件判断语法

<!-- 用户查询示例 -->
<select id="findUsers" resultType="User">
    SELECT * FROM user
    WHERE 1=1
    <if test="name != null">
        AND name LIKE CONCAT('%', #{name}, '%')
    </if>
    <if test="minAge != null">
        AND age >= #{minAge}
    </if>
    <choose>
        <when test="status == 'ACTIVE'">
            AND status = 1
        </when>
        <when test="status == 'INACTIVE'">
            AND status = 0
        </when>
        <otherwise>
            AND status IS NOT NULL
        </otherwise>
    </choose>
</select>

2.2 批量操作优化

使用 <foreach> 实现高效批量插入：

<insert id="batchInsert" parameterType="java.util.List">
    INSERT INTO user (name, age) VALUES
    <foreach collection="list" item="user" separator=",">
        (#{user.name}, #{user.age})
    </foreach>
</insert>

三、高级映射技术

MyBatis 提供了三种结果映射方式：自动映射、简单结果映射和复杂结果映射。

3.1 关联查询处理

一对一关联：

<resultMap id="userWithProfile" type="User">
    <id property="id" column="user_id"/>
    <result property="name" column="user_name"/>
    <association property="profile" javaType="UserProfile">
        <id property="id" column="profile_id"/>
        <result property="address" column="address"/>
    </association>
</resultMap>
<select id="getUserWithProfile" resultMap="userWithProfile">
    SELECT u.*, p.* FROM user u
    LEFT JOIN user_profile p ON u.id = p.user_id
    WHERE u.id = #{id}
</select>

一对多关联：

<resultMap id="departmentWithEmployees" type="Department">
    <id property="id" column="dept_id"/>
    <collection property="employees" ofType="Employee">
        <id property="id" column="emp_id"/>
        <result property="name" column="emp_name"/>
    </collection>
</resultMap>

四、性能优化策略

4.1 缓存机制配置

MyBatis 提供两级缓存：

• 一级缓存：SqlSession 级别，默认开启
• 二级缓存：Mapper 级别，需手动配置

<!-- 启用二级缓存 -->
<mapper namespace="com.example.mapper.UserMapper">
    <cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>
</mapper>

4.2 批量操作优化

// 使用 ExecutorType.BATCH 模式
SqlSession sqlSession = sqlSessionFactory.openSession(ExecutorType.BATCH);
try {
    UserMapper mapper = sqlSession.getMapper(UserMapper.class);
    for (User user : users) {
        mapper.insert(user);
    }
    sqlSession.commit();
} finally {
    sqlSession.close();
}

五、常见问题解决方案

5.1 N+1 查询问题

问题表现：查询主对象后，再执行 N 次查询获取关联对象

解决方案：

1. 使用 <join> 标签进行联表查询
2. 启用延迟加载（lazyLoadingEnabled=true）
3. 合理使用 <collection> 的 fetchType 属性

5.2 类型处理器定制

当默认类型转换不满足需求时，可自定义 TypeHandler：

public class BooleanToIntTypeHandler extends BaseTypeHandler<Boolean> {
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, 
                                   Boolean parameter, JdbcType jdbcType) throws SQLException {
        ps.setInt(i, parameter ? 1 : 0);
    }
    @Override
    public Boolean getNullableResult(ResultSet rs, String columnName) throws SQLException {
        int value = rs.getInt(columnName);
        return value != 0;
    }
    // 其他必要方法实现...
}

六、最佳实践建议

1. SQL 编写规范：

   • 表名和字段名使用小写下划线命名法
   • 复杂查询添加注释说明业务逻辑
   • 避免在 SQL 中使用函数处理字段（影响索引使用）

2. Mapper 接口设计：

   • 遵循单一职责原则，每个 Mapper 对应一个业务实体
   • 方法命名遵循”动词+名词”规范（如 selectByUserId）
   • 批量操作方法统一命名（batchInsert/batchUpdate）

3. 异常处理机制：

   • 捕获 PersistenceException 并进行适当处理
   • 日志记录完整的 SQL 语句和参数（开发环境）
   • 实现自定义异常转换器

七、生态工具集成

7.1 MyBatis-Plus 增强

MyBatis-Plus 提供了代码生成器、Lambda 表达式查询等增强功能：

// Lambda 查询示例
List<User> users = userMapper.selectList(
    Wrappers.<User>lambdaQuery()
        .eq(User::getStatus, 1)
        .between(User::getAge, 18, 30)
);

7.2 PageHelper 分页插件

// 分页查询示例
PageHelper.startPage(1, 10);
List<User> users = userMapper.selectAll();
PageInfo<User> pageInfo = new PageInfo<>(users);

本手册系统阐述了 MyBatis 的核心机制与高级应用，开发者通过掌握这些技术要点，能够构建出高效、可维护的数据库访问层。建议结合官方文档与实际项目进行深入实践，逐步提升对框架的理解深度。