MyBatis 使用手册：从入门到精通的完整指南

一、MyBatis 核心概念与架构解析

MyBatis 是一款基于 Java 的持久层框架，通过 XML 或注解方式将 SQL 与 Java 对象映射，实现数据库操作的解耦。其核心组件包括：

1. SqlSessionFactory：全局单例对象，负责创建 SqlSession 实例，通常通过 SqlSessionFactoryBuilder 解析配置文件生成。

   String resource = "mybatis-config.xml";
   InputStream inputStream = Resources.getResourceAsStream(resource);
   SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

2. SqlSession：线程不安全的操作接口，提供数据库 CRUD 方法，需在方法内创建并关闭。

   try (SqlSession session = sqlSessionFactory.openSession()) {
       UserMapper mapper = session.getMapper(UserMapper.class);
       User user = mapper.selectById(1);
   }

3. Mapper 接口：定义数据库操作的抽象方法，通过动态代理实现 SQL 执行。

二、环境配置与初始化流程

1. 基础依赖管理

Maven 项目需引入核心依赖：

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.13</version>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

2. 核心配置文件详解

mybatis-config.xml 配置示例：

<configuration>
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="com.mysql.cj.jdbc.Driver"/>
                <property name="url" value="jdbc:mysql://localhost:3306/test"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

3. 动态数据源配置

通过 AbstractDataSource 实现多数据源切换：

public class DynamicDataSource extends AbstractRoutingDataSource {
    @Override
    protected Object determineCurrentLookupKey() {
        return DataSourceContextHolder.getDataSourceType();
    }
}

三、SQL 映射与结果集处理

1. XML 映射文件规范

UserMapper.xml 示例：

<mapper namespace="com.example.mapper.UserMapper">
    <resultMap id="userResultMap" type="User">
        <id property="id" column="user_id"/>
        <result property="name" column="user_name"/>
        <result property="email" column="user_email"/>
    </resultMap>
    <select id="selectById" resultMap="userResultMap">
        SELECT * FROM users WHERE user_id = #{id}
    </select>
</mapper>

2. 注解方式开发

使用 @Select 等注解简化配置：

public interface UserMapper {
    @Select("SELECT * FROM users WHERE user_id = #{id}")
    User selectById(@Param("id") Long id);
    @Insert("INSERT INTO users(user_name, user_email) VALUES(#{name}, #{email})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    int insert(User user);
}

3. 动态 SQL 实现

通过 <if>、<foreach> 等标签构建灵活查询：

<select id="selectByCondition" resultMap="userResultMap">
    SELECT * FROM users
    <where>
        <if test="name != null">
            AND user_name LIKE CONCAT('%', #{name}, '%')
        </if>
        <if test="ids != null and ids.size() > 0">
            AND user_id IN
            <foreach collection="ids" item="id" open="(" separator="," close=")">
                #{id}
            </foreach>
        </if>
    </where>
</select>

四、高级特性与性能优化

1. 缓存机制配置

• 一级缓存：SqlSession 级别，默认开启，可通过 sqlSession.clearCache() 手动清除。
• 二级缓存：Mapper 级别，需在配置中启用：

  <mapper namespace="...">
      <cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>
  </mapper>

2. 批量操作优化

使用 ExecutorType.BATCH 提升批量插入性能：

try (SqlSession session = sqlSessionFactory.openSession(ExecutorType.BATCH)) {
    UserMapper mapper = session.getMapper(UserMapper.class);
    for (int i = 0; i < 1000; i++) {
        mapper.insert(new User("name" + i, "email" + i + "@test.com"));
    }
    session.commit();
}

3. 插件机制开发

实现 Interceptor 接口开发自定义插件：

@Intercepts({
    @Signature(type = Executor.class, method = "update", args = {MappedStatement.class, Object.class})
})
public class SqlCostPlugin implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        long start = System.currentTimeMillis();
        Object result = invocation.proceed();
        long cost = System.currentTimeMillis() - start;
        System.out.println("SQL执行耗时：" + cost + "ms");
        return result;
    }
}

五、常见问题与解决方案

1. 空指针异常排查

• 检查 SqlSessionFactory 是否正确初始化
• 验证 Mapper XML 文件路径是否配置正确
• 确保接口方法名与 XML 中的 id 属性一致

2. 数据库连接泄漏处理

使用 try-with-resources 确保资源释放：

try (SqlSession session = sqlSessionFactory.openSession()) {
    // 业务逻辑
    session.commit();
} catch (Exception e) {
    session.rollback();
}

3. 分页查询优化

结合 PageHelper 实现物理分页：

PageHelper.startPage(1, 10);
List<User> users = userMapper.selectAll();
PageInfo<User> pageInfo = new PageInfo<>(users);

六、最佳实践建议

1. 命名规范统一：Mapper 接口与 XML 文件保持相同命名空间
2. SQL 编写规范：复杂查询使用 <sql> 片段复用
3. 版本管理：定期更新 MyBatis 版本获取性能改进
4. 日志配置：开启 MyBatis 日志排查问题

   logging.level.org.mybatis=DEBUG

本手册涵盖了 MyBatis 从基础配置到高级优化的完整知识体系，通过实际代码示例和问题解决方案，帮助开发者快速掌握框架核心技能。建议结合官方文档和实际项目进行实践验证，持续提升数据库操作效率。