337 lines
10 KiB
Markdown
337 lines
10 KiB
Markdown
# MyBatis Plus 多数据源配置与使用文档
|
||
|
||
## 1. 环境与依赖
|
||
|
||
### 1.1 环境要求
|
||
- Spring Boot 3.x
|
||
- MyBatis Plus 3.5.x
|
||
- Java 21
|
||
|
||
### 1.2 依赖添加
|
||
添加 MyBatis Plus 动态数据源依赖：
|
||
|
||
```xml
|
||
<!-- Dynamic Datasource -->
|
||
<dependency>
|
||
<groupId>com.baomidou</groupId>
|
||
<artifactId>dynamic-datasource-spring-boot-starter</artifactId>
|
||
<version>3.6.1</version>
|
||
</dependency>
|
||
```
|
||
|
||
## 2. 配置文件修改
|
||
|
||
### 2.1 主配置文件
|
||
配置多数据源：
|
||
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
dynamic:
|
||
primary: master
|
||
strict: false
|
||
datasource:
|
||
master:
|
||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||
url: jdbc:mysql://117.72.94.232:53306/tacit?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
|
||
username: root
|
||
password: fU44GFH5
|
||
slave:
|
||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||
url: jdbc:mysql://localhost:3306/tacit?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
|
||
username: root
|
||
password: root123
|
||
```
|
||
|
||
### 2.2 配置说明
|
||
| 配置项 | 说明 | 示例值 |
|
||
|-------|------|-------|
|
||
| primary | 默认数据源名称 | master |
|
||
| strict | 是否启用严格模式 | false |
|
||
| datasource.master | 主数据源配置 | - |
|
||
| datasource.slave | 从数据源配置 | - |
|
||
| driver-class-name | 数据库驱动类名 | com.mysql.cj.jdbc.Driver |
|
||
| url | 数据库连接地址 | jdbc:mysql://117.72.94.232:53306/tacit |
|
||
| username | 数据库用户名 | root |
|
||
| password | 数据库密码 | password |
|
||
|
||
## 3. 代码实现
|
||
|
||
### 3.1 实体类
|
||
创建测试实体类 `TestEntity`：
|
||
|
||
```java
|
||
package com.tacit.admin.entity;
|
||
|
||
import com.baomidou.mybatisplus.annotation.TableName;
|
||
import com.tacit.common.entity.Base;
|
||
import lombok.Data;
|
||
import lombok.EqualsAndHashCode;
|
||
|
||
@Data
|
||
@EqualsAndHashCode(callSuper = true)
|
||
@TableName("test") // 指定数据库表名
|
||
public class TestEntity extends Base {
|
||
@TableId(type = IdType.AUTO)
|
||
private Long id;
|
||
private String name; // 姓名
|
||
private Integer age; // 年龄
|
||
private String email; // 邮箱
|
||
}
|
||
```
|
||
|
||
### 3.2 Mapper 接口
|
||
创建 Mapper 接口 `TestMapper`：
|
||
|
||
```java
|
||
package com.tacit.admin.mapper;
|
||
|
||
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
|
||
import com.tacit.admin.entity.TestEntity;
|
||
import org.apache.ibatis.annotations.Mapper;
|
||
|
||
@Mapper // 标记为 MyBatis Mapper 接口
|
||
public interface TestMapper extends BaseMapper<TestEntity> {
|
||
// 继承 BaseMapper 后，自动拥有 CRUD 方法
|
||
}
|
||
```
|
||
|
||
### 3.3 Service 接口
|
||
创建 Service 接口 `TestService`：
|
||
|
||
```java
|
||
package com.tacit.admin.service;
|
||
|
||
import com.baomidou.mybatisplus.extension.service.IService;
|
||
import com.tacit.admin.entity.TestEntity;
|
||
|
||
public interface TestService extends IService<TestEntity> {
|
||
/**
|
||
* 根据 ID 查询测试数据
|
||
* @param id 主键 ID
|
||
* @return TestEntity
|
||
*/
|
||
TestEntity getTestById(Long id);
|
||
}
|
||
```
|
||
|
||
### 3.4 Service 实现类
|
||
|
||
#### 3.4.1 主数据源实现类
|
||
创建主数据源 Service 实现类 `TestMasterServiceImpl`：
|
||
|
||
```java
|
||
package com.tacit.admin.service.impl;
|
||
|
||
import com.baomidou.dynamic.datasource.annotation.DS;
|
||
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
|
||
import com.tacit.admin.entity.TestEntity;
|
||
import com.tacit.admin.mapper.TestMapper;
|
||
import com.tacit.admin.service.TestService;
|
||
import org.springframework.stereotype.Service;
|
||
|
||
@Service("testMasterService") // 指定 Bean 名称，方便注入
|
||
@DS("master") // 指定使用主数据源
|
||
public class TestMasterServiceImpl extends ServiceImpl<TestMapper, TestEntity> implements TestService {
|
||
|
||
/**
|
||
* 使用主数据源查询数据
|
||
* @param id 主键 ID
|
||
* @return TestEntity
|
||
*/
|
||
@Override
|
||
public TestEntity getTestById(Long id) {
|
||
return getById(id); // 调用父类方法，自动使用主数据源
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.4.2 从数据源实现类
|
||
创建从数据源 Service 实现类 `TestSlaveServiceImpl`：
|
||
|
||
```java
|
||
package com.tacit.admin.service.impl;
|
||
|
||
import com.baomidou.dynamic.datasource.annotation.DS;
|
||
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
|
||
import com.tacit.admin.entity.TestEntity;
|
||
import com.tacit.admin.mapper.TestMapper;
|
||
import com.tacit.admin.service.TestService;
|
||
import org.springframework.stereotype.Service;
|
||
|
||
@Service("testSlaveService") // 指定 Bean 名称，方便注入
|
||
@DS("slave") // 指定使用从数据源
|
||
public class TestSlaveServiceImpl extends ServiceImpl<TestMapper, TestEntity> implements TestService {
|
||
|
||
/**
|
||
* 使用从数据源查询数据
|
||
* @param id 主键 ID
|
||
* @return TestEntity
|
||
*/
|
||
@Override
|
||
public TestEntity getTestById(Long id) {
|
||
return getById(id); // 调用父类方法，自动使用从数据源
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.5 控制器
|
||
创建测试控制器 `MultiDatasourceTestController`：
|
||
|
||
```java
|
||
package com.tacit.admin.controller;
|
||
|
||
import com.tacit.common.entity.ResponseResult;
|
||
import com.tacit.admin.entity.TestEntity;
|
||
import com.tacit.admin.service.TestService;
|
||
import io.swagger.v3.oas.annotations.Operation;
|
||
import io.swagger.v3.oas.annotations.tags.Tag;
|
||
import org.springframework.beans.factory.annotation.Autowired;
|
||
import org.springframework.beans.factory.annotation.Qualifier;
|
||
import org.springframework.web.bind.annotation.GetMapping;
|
||
import org.springframework.web.bind.annotation.PathVariable;
|
||
import org.springframework.web.bind.annotation.PostMapping;
|
||
import org.springframework.web.bind.annotation.RequestBody;
|
||
import org.springframework.web.bind.annotation.RequestMapping;
|
||
import org.springframework.web.bind.annotation.RestController;
|
||
|
||
@RestController
|
||
@RequestMapping("/multi-datasource")
|
||
@Tag(name = "多数据源测试接口", description = "用于测试多数据源的接口")
|
||
public class MultiDatasourceTestController {
|
||
|
||
@Autowired
|
||
@Qualifier("testMasterService") // 注入主数据源 Service
|
||
private TestService testMasterService;
|
||
|
||
@Autowired
|
||
@Qualifier("testSlaveService") // 注入从数据源 Service
|
||
private TestService testSlaveService;
|
||
|
||
@Operation(summary = "使用主数据源创建测试数据", description = "使用主数据源创建测试数据")
|
||
@PostMapping("/master/create")
|
||
public ResponseResult<TestEntity> createTestDataWithMaster(@RequestBody TestEntity testEntity) {
|
||
testMasterService.save(testEntity); // 使用主数据源保存数据
|
||
return ResponseResult.success(testEntity);
|
||
}
|
||
|
||
@Operation(summary = "使用主数据源查询测试数据", description = "使用主数据源查询测试数据")
|
||
@GetMapping("/master/{id}")
|
||
public ResponseResult<TestEntity> getTestDataWithMaster(@PathVariable Long id) {
|
||
return ResponseResult.success(testMasterService.getTestById(id)); // 使用主数据源查询数据
|
||
}
|
||
|
||
@Operation(summary = "使用从数据源查询测试数据", description = "使用从数据源查询测试数据")
|
||
@GetMapping("/slave/{id}")
|
||
public ResponseResult<TestEntity> getTestDataWithSlave(@PathVariable Long id) {
|
||
return ResponseResult.success(testSlaveService.getTestById(id)); // 使用从数据源查询数据
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. 使用方法
|
||
|
||
### 4.1 注解方式
|
||
使用 `@DS` 注解可以指定方法或类使用的数据源：
|
||
|
||
```java
|
||
// 类级别：整个类的方法都使用 master 数据源
|
||
@Service
|
||
@DS("master")
|
||
public class TestServiceImpl {
|
||
// ...
|
||
}
|
||
|
||
// 方法级别：该方法使用 slave 数据源（优先级高于类级别）
|
||
@DS("slave")
|
||
public TestEntity getTestById(Long id) {
|
||
return getById(id);
|
||
}
|
||
```
|
||
|
||
### 4.2 动态数据源名称
|
||
支持从方法参数或上下文中获取动态数据源名称：
|
||
|
||
```java
|
||
// 从方法参数中获取数据源名称
|
||
@DS("#datasourceName")
|
||
public TestEntity getTestById(Long id, String datasourceName) {
|
||
return getById(id);
|
||
}
|
||
|
||
// 从上下文或SpEL表达式中获取数据源名称
|
||
@DS("#{@systemConfig.getDatasourceName()}")
|
||
public TestEntity getTestById(Long id) {
|
||
return getById(id);
|
||
}
|
||
```
|
||
|
||
### 4.3 数据源优先级
|
||
数据源的优先级顺序为：
|
||
1. 方法上的 `@DS` 注解
|
||
2. 类上的 `@DS` 注解
|
||
3. 全局默认数据源（primary）
|
||
注意：Service 层的 @DS 注解具有更高优先级
|
||
|
||
## 5. 测试验证
|
||
|
||
### 5.1 编译测试
|
||
运行以下命令编译项目，确保配置正确：
|
||
|
||
```bash
|
||
cd d:\workSpace\tacit; mvn clean compile -pl tacit-admin -am
|
||
```
|
||
|
||
### 5.2 运行测试
|
||
启动项目后，通过以下方式测试多数据源：
|
||
|
||
1. **使用主数据源创建数据**：
|
||
```bash
|
||
POST /multi-datasource/master/create
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "测试用户",
|
||
"age": 25,
|
||
"email": "test@example.com"
|
||
}
|
||
```
|
||
|
||
2. **使用主数据源查询数据**：
|
||
```bash
|
||
GET /multi-datasource/master/1
|
||
```
|
||
|
||
3. **使用从数据源查询数据**：
|
||
```bash
|
||
GET /multi-datasource/slave/1
|
||
```
|
||
|
||
## 6. 注意事项
|
||
|
||
1. **依赖冲突**：确保项目中没有其他数据源相关的依赖冲突，如 `spring-boot-starter-jdbc` 或其他动态数据源框架。
|
||
|
||
2. **数据源名称**：数据源名称必须与配置文件中的名称一致，大小写敏感。
|
||
|
||
3. **事务管理**：多数据源环境下，事务管理需要特别注意，建议使用 `@DSTransactional` 注解替代 `@Transactional` 注解。
|
||
|
||
4. **严格模式**：生产环境建议开启严格模式（`strict: true`），确保数据源名称正确。
|
||
|
||
5. **性能考虑**：频繁切换数据源会带来性能开销，建议根据业务场景合理设计数据源使用策略。
|
||
|
||
6. **配置中心**：如果使用配置中心（如 Nacos），可以将数据源配置迁移到配置中心，便于动态调整。
|
||
|
||
## 7. 常见问题
|
||
|
||
### 7.1 数据源切换不生效
|
||
- 检查 `@DS` 注解是否正确添加到方法或类上
|
||
- 检查数据源名称是否与配置文件一致
|
||
- 检查是否开启了严格模式，以及默认数据源是否配置正确
|
||
|
||
### 7.2 事务不生效
|
||
- 使用 `@DSTransactional` 注解替代 `@Transactional` 注解
|
||
- 确保事务方法是 `public` 修饰的
|
||
- 确保事务方法不是通过内部调用的（Spring AOP 代理机制）
|
||
|
||
|