MyBatis入门指南：从零掌握数据库操作

这段文档是 MyBatis 框架的官方入门指南，它系统地介绍了如何从零开始使用 MyBatis 进行数据库操作。下面我们用通俗易懂、结构清晰的方式来逐步解析这段内容，帮助你真正理解 MyBatis 的核心概念和使用方式。

---

🌟 一、MyBatis 是什么？

MyBatis 是一个轻量级的持久层框架（ORM 框架），用于简化 Java 程序与数据库之间的交互。

它不像 Hibernate 那样完全自动化，而是 "半自动化" ------ 你可以写 SQL，同时由 MyBatis 帮你完成参数设置、结果映射等工作。

---

🧩 二、核心组件概览

组件	作用
SqlSessionFactoryBuilder	用来创建 SqlSessionFactory，用完即可丢弃
SqlSessionFactory	创建 SqlSession 的工厂，整个应用只应有一个实例
SqlSession	执行 SQL 的会话对象，每个线程一个，用完必须关闭
Mapper 接口	你定义的接口，MyBatis 自动实现它，用来调用 SQL

我们接下来就按这个流程一步步讲解。

---

🚀 三、第一步：引入 MyBatis（安装）

方法 1：Maven 添加依赖

<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis</artifactId>
  <version>x.x.x</version>
</dependency>

✅ 只需引入一个 JAR 包，就可以使用 MyBatis。

---

🔧 四、第二步：构建 SqlSessionFactory（核心工厂）

每个 MyBatis 应用都围绕一个 SqlSessionFactory 实例运行。

方式 1：通过 XML 配置文件构建

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

📌 关键点：

• mybatis-config.xml 是主配置文件，包含：
  • 数据库连接信息（DataSource）
  • 事务管理器（TransactionManager）
  • 映射文件位置（Mappers）

示例配置文件（mybatis-config.xml）：

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
  PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
  "https://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
  <environments default="development">
    <environment id="development">
      <transactionManager type="JDBC"/>
      <dataSource type="POOLED">
        <property name="driver" value="${driver}"/>
        <property name="url" value="${url}"/>
        <property name="username" value="${username}"/>
        <property name="password" value="${password}"/>
      </dataSource>
    </environment>
  </environments>
  <mappers>
    <mapper resource="org/mybatis/example/BlogMapper.xml"/>
  </mappers>
</configuration>

📌 说明：

• <environments>：定义环境（开发/测试/生产），可切换。
• <dataSource type="POOLED">：使用连接池。
• <mappers>：注册你的 SQL 映射文件。

---

方式 2：纯 Java 代码构建（不用 XML）

DataSource dataSource = BlogDataSourceFactory.getBlogDataSource();
TransactionFactory transactionFactory = new JdbcTransactionFactory();
Environment environment = new Environment("development", transactionFactory, dataSource);
Configuration configuration = new Configuration(environment);
configuration.addMapper(BlogMapper.class); // 注册 Mapper 接口
SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(configuration);

✅ 适用于不想用 XML 的场景，比如 Spring Boot 中常用 Java 配置。

---

💬 五、第三步：获取 SqlSession 并执行 SQL

方法 1：直接通过 SQL ID 执行（老式写法）

try (SqlSession session = sqlSessionFactory.openSession()) {
  Blog blog = session.selectOne("org.mybatis.example.BlogMapper.selectBlog", 101);
}

⚠️ 缺点：

• 使用字符串 "org.mybatis.example.BlogMapper.selectBlog" 容易拼错
• 不类型安全，返回值需要强转

---

方法 2：使用 Mapper 接口（推荐！类型安全）

try (SqlSession session = sqlSessionFactory.openSession()) {
  BlogMapper mapper = session.getMapper(BlogMapper.class);
  Blog blog = mapper.selectBlog(101);
}

✅ 优点：

• 类型安全
• IDE 支持自动补全
• 不怕拼错
• 更像调用方法，而不是写 SQL 字符串

---

📄 六、第四步：定义 SQL 映射（两种方式）

SQL 可以通过 XML 文件 或 Java 注解 定义。

方式 1：XML 映射文件（BlogMapper.xml）

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
  PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
  "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="org.mybatis.example.BlogMapper">
  <select id="selectBlog" resultType="Blog">
    SELECT * FROM Blog WHERE id = #{id}
  </select>
</mapper>

📌 说明：

• namespace：必须对应 Mapper 接口的全类名
• id="selectBlog"：对应接口中的方法名
• #{id}：参数占位符（防 SQL 注入）
• resultType="Blog"：结果自动映射到 Blog 类

---

方式 2：Java 注解（更简洁）

package org.mybatis.example;

public interface BlogMapper {
  @Select("SELECT * FROM Blog WHERE id = #{id}")
  Blog selectBlog(int id);
}

✅ 适合简单 SQL

❌ 不适合复杂 SQL（如多表关联、动态 SQL）

💡 实际项目中：简单 SQL 用注解，复杂 SQL 用 XML

---

🔄 七、命名空间（Namespace）的重要性

• 以前版本中 namespace 是可选的，现在必须写。
• namespace 的作用：
  1. 避免 SQL ID 冲突（类似包名）
  2. 让 MyBatis 能把 XML 或注解绑定到对应的 Mapper 接口

例如：

namespace="org.mybatis.example.BlogMapper"

就会自动绑定到：

public interface BlogMapper { ... }

---

🔍 八、名称解析规则（避免重复写全路径）

MyBatis 支持两种方式调用 SQL：

写法	示例	说明
全限定名	"org.mybatis.example.BlogMapper.selectBlog"	绝对路径，不会冲突
短名称	"selectBlog"	必须保证项目中只有一个叫这个名字的 SQL

⚠️ 如果有两个 selectBlog，就不能用短名，必须用全限定名。

---

⚙️ 九、对象作用域与生命周期（非常重要！）

这是最容易出错的地方，必须严格遵守。

1. SqlSessionFactoryBuilder

• 作用 ：用来创建 SqlSessionFactory
• 生命周期：用完就扔
• 范围：方法内（局部变量）

void buildFactory() {
  SqlSessionFactoryBuilder builder = new SqlSessionFactoryBuilder(); // 方法内使用
  SqlSessionFactory factory = builder.build(inputStream);
}

---

2. SqlSessionFactory

• 作用 ：生产 SqlSession
• 生命周期：整个应用运行期间
• 范围 ：全局唯一，通常用单例模式

public class MyBatisUtil {
  private static SqlSessionFactory sqlSessionFactory;
  
  static {
    // 初始化一次
    sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
  }
  
  public static SqlSessionFactory getSqlSessionFactory() {
    return sqlSessionFactory;
  }
}

✅ 整个应用只创建一次，不要频繁重建。

---

3. SqlSession

• 作用：执行 SQL
• 生命周期：一次请求或一个方法
• 范围 ：每个线程一个，不能共享，不是线程安全的！

try (SqlSession session = sqlSessionFactory.openSession()) {
  BlogMapper mapper = session.getMapper(BlogMapper.class);
  Blog blog = mapper.selectBlog(101);
} // 自动关闭（推荐用 try-with-resources）

✅ 必须在 finally 或 try-with-resources 中关闭，否则会导致连接泄漏！

---

4. Mapper 实例

• 作用：调用 SQL 方法
• 生命周期：在方法中创建，用完即弃
• 范围：方法作用域

try (SqlSession session = sqlSessionFactory.openSession()) {
  BlogMapper mapper = session.getMapper(BlogMapper.class); // 方法内创建
  Blog blog = mapper.selectBlog(101);
} // mapper 自动失效

✅ 不需要手动关闭 Mapper。

---

🧠 十、总结：MyBatis 工作流程图

[ mybatis-config.xml 或 Java 配置 ]
            ↓
   SqlSessionFactoryBuilder
            ↓
   SqlSessionFactory（全局唯一）
            ↓
     SqlSession（每次请求新建）
            ↓
       Mapper 接口（getMapper）
            ↓
   执行 SQL（XML 或注解定义）

---

✅ 十一、最佳实践建议

建议	说明
✅ 使用 Mapper 接口 + XML/注解	类型安全，易于维护
✅ SqlSessionFactory 全局单例	避免重复创建
✅ SqlSession 用 try-with-resources	自动关闭，防止资源泄漏
✅ 复杂 SQL 用 XML，简单 SQL 用注解	各取所长
✅ 使用 namespace 绑定接口	避免命名冲突
✅ 不要共享 SqlSession	非线程安全！

---

💡 十二、常见问题解答

Q1：为什么不能把 SqlSession 放在类成员变量里？

因为 SqlSession 不是线程安全的。多个线程同时使用会导致数据库连接混乱、事务错乱。

Q2：XML 和注解能混用吗？

✅ 可以！MyBatis 会自动查找同名的 XML 文件。例如：

• 接口：BlogMapper.class
• XML：BlogMapper.xml（在同一包下）
  两者会自动合并。

Q3：MyBatis 和 Spring 怎么整合？

使用 MyBatis-Spring 框架，Spring 会自动管理 SqlSessionFactory 和 Mapper，你只需要注入即可。

---

🎯 最后一句话总结

MyBatis 的核心思想是：让你专注于 SQL，而把参数设置、结果映射、连接管理等琐事交给框架处理。

只要记住：

• 一个 SqlSessionFactory
• 每次请求一个 SqlSession
• 用 Mapper 接口调用 SQL
• 用完 SqlSession 就关闭

你就已经掌握了 MyBatis 的精髓！

---

如果你有具体的代码或场景想优化，我可以帮你设计 MyBatis 的使用方案。