以下是一份系统化的 MyBatis 整合 Spring Boot 学习笔记，结合官方文档与最佳实践整理，涵盖配置、核心功能、实战示例及常见问题解决。
一、整合基础与依赖配置
1. 核心依赖
在 pom.xml 中添加：
<dependency><groupId>org.mybatis.spring.boot</groupId><artifactId>mybatis-spring-boot-starter</artifactId><version>2.3.2</version> <!-- 推荐 ≥2.3.x -->
</dependency>
<dependency><groupId>mysql</groupId><artifactId>mysql-connector-java</artifactId><scope>runtime</scope>
</dependency>- 作用：自动引入 MyBatis 核心库、Spring JDBC、HikariCP 连接池。
2. 数据源配置
在 application.yml 中配置：
spring:datasource:url: jdbc:mysql://localhost:3306/test?serverTimezone=UTCusername: rootpassword: rootdriver-class-name: com.mysql.cj.jdbc.Drivermybatis:mapper-locations: classpath:mapper/**/*.xml # XML 映射文件路径type-aliases-package: com.example.entity # 实体类别名包configuration:map-underscore-to-camel-case: true # 开启驼峰命名映射注：无需手动配置
SqlSessionFactory，starter 自动创建。
二、核心组件与数据操作
1. 实体类与 Mapper 接口
-
实体类（使用 Lombok 简化）：
@Data public class User {private Long id;private String name;private Integer age; } -
Mapper 接口（两种注册方式）：
// 方式1：单接口添加 @Mapper @Mapper public interface UserMapper {User selectById(Long id); }// 方式2：启动类批量扫描 @SpringBootApplication @MapperScan("com.example.mapper") // 扫描包下所有接口 public class Application { ... }注册方式 优点 缺点 @Mapper无需全局扫描配置 每个接口需单独注解 @MapperScan批量注册，避免警告 需指定包路径
2. SQL 映射方式
-
注解方式（简单查询）：
@Select("SELECT * FROM user WHERE id = #{id}") User selectById(Long id); -
XML 方式（复杂 SQL）：
<!-- resources/mapper/UserMapper.xml --> <mapper namespace="com.example.mapper.UserMapper"><select id="selectByName" resultType="User">SELECT * FROM user WHERE name LIKE CONCAT('%', #{name}, '%')</select> </mapper>
三、高级特性与优化
1. 事务管理
- 直接使用 Spring 的
@Transactional：@Service public class UserService {@Autowiredprivate UserMapper userMapper;@Transactionalpublic void updateUser(User user) {userMapper.update(user);} }默认使用
DataSourceTransactionManager。
2. 类型处理器（TypeHandler）
处理特殊类型转换（如枚举↔数据库字段）：
@MappedTypes(SexEnum.class)
public class SexTypeHandler extends BaseTypeHandler<SexEnum> {@Overridepublic void setNonNullParameter(PreparedStatement ps, int i, SexEnum sex, JdbcType jdbcType) {ps.setInt(i, sex.getId()); // 将枚举值存储为整数}// 其他方法实现...
}在配置中启用：
mybatis:type-handlers-package: com.example.handler # 类型处理器包路径3. 二级缓存
- 启用步骤：
- 全局配置开启缓存：
mybatis:configuration:cache-enabled: true- 在 Mapper XML 中添加
<cache/>标签：
<mapper namespace="com.example.mapper.UserMapper"><cache/> </mapper>
四、常见问题与解决
| 问题 | 原因 | 解决方案 |
|---|---|---|
| Mapper 接口注入失败 | 未扫描到接口 | 添加 @MapperScan 或 @Mapper |
SQL 参数 #{} 报错 | 参数名未匹配 | 使用 @Param("name") 明确命名 |
| 时区错误（ServerTimezone） | MySQL 驱动版本问题 | URL 添加 ?serverTimezone=UTC |
| 驼峰命名未生效 | 配置未开启 | 设置 map-underscore-to-camel-case: true |
五、项目结构示例
src/
├── main/
│ ├── java/
│ │ ├── com.example.Application.java # 启动类
│ │ ├── entity/User.java # 实体类
│ │ ├── mapper/UserMapper.java # Mapper 接口
│ │ └── service/UserService.java # 业务层
│ └── resources/
│ ├── mapper/UserMapper.xml # XML 映射文件
│ └── application.yml # 配置文件六、扩展：多数据源配置
@Configuration
@MapperScan(basePackages = "com.example.primary", sqlSessionFactoryRef = "sqlSessionFactory1")
public class PrimaryDataSourceConfig {@Bean@ConfigurationProperties(prefix = "spring.datasource.primary")public DataSource primaryDataSource() {return DataSourceBuilder.create().build();}@Beanpublic SqlSessionFactory sqlSessionFactory1(@Qualifier("primaryDataSource") DataSource dataSource) throws Exception {SqlSessionFactoryBean factory = new SqlSessionFactoryBean();factory.setDataSource(dataSource);return factory.getObject();}
}需为每个数据源独立配置
SqlSessionFactory和事务管理器。
参考资料
- MyBatis 二级缓存与事务整合
- Spring Boot 多数据源实战
完整代码示例可参考 。
