Spring Boot 整合 MyBatis 完整教程：從基礎到進階實戰

項目目標與技術棧

本教程演示一個基於 Spring Boot 的完整項目，集成了以下核心技術：

• MyBatis - 持久層框架
• Druid - 高性能數據庫連接池與監控
• JPA - 自動建表功能
• 註解式事務 - 聲明式事務管理
• 動態數據源 - 註解實現多數據源切換
• 全局異常處理 - 統一錯誤響應
• 參數校驗 - JSR-303 校驗 + JSON 錯誤返回
• Log4j2 - 日誌框架

為什麼選擇 MyBatis？

1. 動態 SQL 強大：<if>、<choose>、<trim> 等標籤靈活構建複雜查詢
2. 原生 SQL 可控：寫原生 SQL，性能調優透明，後期維護一目瞭然
3. 團隊習慣：企業級項目主流選擇，生態成熟

項目啟動方式

# 方式一：IDE 直接運行 Application 主類

# 方式二：Maven 打包運行
mvn clean install package
cd web
java -jar target/web-1.0-SNAPSHOT-exec.jar

核心功能模塊詳解

1. Druid 數據源配置與監控

引入 druid-spring-boot-starter，在 application.yml 配置：

spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      url: jdbc:mysql://localhost:3306/test?useSSL=false
      username: root
      password: 123456
      # 監控配置
      stat-view-servlet:
        enabled: true
        url-pattern: /druid/*
        login-username: admin
        login-password: admin
      web-stat-filter:
        enabled: true
        url-pattern: /*
        exclusions: "*.js,*.gif,*.jpg,*.css,/druid/*"

訪問 https://localhost:8080/druid/ 即可查看 SQL 監控、連接池狀態、慢查詢等。

2. 多數據源動態切換（註解方式）

核心思路：自定義註解 @TargetDataSource + AOP 切面 + AbstractRoutingDataSource

// 1. 定義數據源枚舉
public enum DataSourceType {
    MASTER, SLAVE
}

// 2. 自定義註解
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface TargetDataSource {
    DataSourceType value() default DataSourceType.MASTER;
}

// 3. 動態數據源路由
public class DynamicDataSource extends AbstractRoutingDataSource {
    @Override
    protected Object determineCurrentLookupKey() {
        return DataSourceContextHolder.getDataSourceType();
    }
}

// 4. AOP 切面攔截
@Aspect
@Order(-1)
@Component
public class DataSourceAspect {
    @Before("@annotation(targetDataSource)")
    public void switchDataSource(TargetDataSource targetDataSource) {
        DataSourceContextHolder.setDataSourceType(targetDataSource.value());
    }
    
    @After("@annotation(targetDataSource)")
    public void restoreDataSource() {
        DataSourceContextHolder.clear();
    }
}

// 5. 使用示例
@Service
public class UserService {
    @TargetDataSource(DataSourceType.SLAVE)
    public User findById(Long id) { ... }
    
    @TargetDataSource(DataSourceType.MASTER)
    @Transactional
    public void save(User user) { ... }
}

3. JPA 自動建表

實體類添加 @Entity 註解，配置 spring.jpa.hibernate.ddl-auto=update，啟動時自動建表。

4. 全局異常處理 + 參數校驗

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result handleValidException(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
            .map(FieldError::getDefaultMessage)
            .collect(Collectors.joining("; "));
        return Result.error(msg);
    }
    
    @ExceptionHandler(Exception.class)
    public Result handleException(Exception e) {
        log.error("系統異常", e);
        return Result.error("系統內部錯誤");
    }
}

// Controller 使用 @Valid 校驗
@PostMapping("/user")
public Result save(@Valid @RequestBody UserDTO dto) { ... }

5. 打包 JAR 後資源文件讀取問題（SpringBootVFS 解決）

MyBatis XML 映射文件打包進 JAR 後無法讀取，需配置 SpringBootVFS：

@Configuration
public class MyBatisConfig {
    @Bean
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
        SqlSessionFactoryBean bean = new SqlSessionFactoryBean();
        bean.setDataSource(dataSource);
        // 關鍵：設置 VFS 解決 JAR 包中 XML 讀取問題
        bean.setVfs(SpringBootVFS.class);
        bean.setMapperLocations(new PathMatchingResourcePatternResolver()
            .getResources("classpath*:mapper/**/*.xml"));
        return bean.getObject();
    }
}

項目結構

├── web (啟動模塊)
│   └── Application.java
├── common (公共模塊)
│   ├── exception
│   ├── result
│   └── util
├── dao (數據訪問層)
│   └── mapper
├── service (業務邏輯層)
└── model (實體類)

關鍵配置文件

application.yml 包含：數據源、MyBatis、Druid、JPA、Log4j2、多數據源等完整配置。

總結

本項目展示了 Spring Boot 整合 MyBatis 的企業級最佳實踐，涵蓋從基礎 CRUD 到動態數據源、分布式事務、監控治理的完整技術棧。代碼結構清晰，註解詳盡，適合作為項目脚手架或學習參考。

源碼獲取：項目已開源至 GitHub，歡迎 Star/Fork 學習交流。