Spring Boot 多数据源配置全面指南

在现代企业应用中，多数据源配置已成为常见需求，无论是为了业务模块分离、读写分离还是历史数据归档。本文将详细介绍在 Spring Boot 项目中配置多数据源的多种方法，从基础配置到高级动态切换，帮助您根据实际需求选择最适合的方案。

一、基础多数据源配置

1. 添加必要依赖

首先在pom.xml中添加基础依赖：

<dependencies>
    <!-- Spring Boot JDBC Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-jdbc</artifactId>
    </dependency>
    
    <!-- MySQL驱动 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.33</version>
    </dependency>
    
    <!-- 可选：HikariCP连接池 -->
    <dependency>
        <groupId>com.zaxxer</groupId>
        <artifactId>HikariCP</artifactId>
    </dependency>
</dependencies>

2. 配置数据源信息

在application.yml中定义多个数据源：

spring:
  datasource:
    primary:
      url: jdbc:mysql://localhost:3306/db_primary
      username: root
      password: 123456
      driver-class-name: com.mysql.cj.jdbc.Driver
      hikari:
        maximum-pool-size: 10
        
    secondary:
      url: jdbc:mysql://localhost:3306/db_secondary
      username: root
      password: 123456
      driver-class-name: com.mysql.cj.jdbc.Driver
      hikari:
        maximum-pool-size: 5

3. 创建数据源Bean

通过@Configuration类创建不同的数据源：

@Configuration
public class DataSourceConfig {

    @Primary
    @Bean("primaryDataSource")
    @ConfigurationProperties(prefix = "spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean("secondaryDataSource")
    @ConfigurationProperties(prefix = "spring.datasource.secondary")
    public DataSource secondaryDataSource() {
        return DataSourceBuilder.create().build();
    }
}

二、JPA多数据源配置

1. 主数据源JPA配置

@Configuration
@EnableTransactionManagement
@EnableJpaRepositories(
    basePackages = "com.example.repository.primary",
    entityManagerFactoryRef = "primaryEntityManagerFactory",
    transactionManagerRef = "primaryTransactionManager"
)
public class PrimaryJpaConfig {

    @Autowired
    @Qualifier("primaryDataSource")
    private DataSource primaryDataSource;

    @Primary
    @Bean
    public LocalContainerEntityManagerFactoryBean primaryEntityManagerFactory(
            EntityManagerFactoryBuilder builder) {
        return builder
            .dataSource(primaryDataSource)
            .packages("com.example.entity.primary")
            .persistenceUnit("primaryPersistenceUnit")
            .properties(jpaProperties())
            .build();
    }

    private Map<String, Object> jpaProperties() {
        Map<String, Object> props = new HashMap<>();
        props.put("hibernate.hbm2ddl.auto", "update");
        props.put("hibernate.dialect", "org.hibernate.dialect.MySQL8Dialect");
        return props;
    }

    @Primary
    @Bean
    public PlatformTransactionManager primaryTransactionManager(
            @Qualifier("primaryEntityManagerFactory") EntityManagerFactory emf) {
        return new JpaTransactionManager(emf);
    }
}

2. 次数据源JPA配置

@Configuration
@EnableTransactionManagement
@EnableJpaRepositories(
    basePackages = "com.example.repository.secondary",
    entityManagerFactoryRef = "secondaryEntityManagerFactory",
    transactionManagerRef = "secondaryTransactionManager"
)
public class SecondaryJpaConfig {

    @Autowired
    @Qualifier("secondaryDataSource")
    private DataSource secondaryDataSource;

    @Bean
    public LocalContainerEntityManagerFactoryBean secondaryEntityManagerFactory(
            EntityManagerFactoryBuilder builder) {
        return builder
            .dataSource(secondaryDataSource)
            .packages("com.example.entity.secondary")
            .persistenceUnit("secondaryPersistenceUnit")
            .properties(jpaProperties())
            .build();
    }

    private Map<String, Object> jpaProperties() {
        Map<String, Object> props = new HashMap<>();
        props.put("hibernate.hbm2ddl.auto", "update");
        props.put("hibernate.dialect", "org.hibernate.dialect.MySQL8Dialect");
        return props;
    }

    @Bean
    public PlatformTransactionManager secondaryTransactionManager(
            @Qualifier("secondaryEntityManagerFactory") EntityManagerFactory emf) {
        return new JpaTransactionManager(emf);
    }
}

三、MyBatis多数据源配置

1. 主数据源MyBatis配置

@Configuration
@MapperScan(
    basePackages = "com.example.mapper.primary",
    sqlSessionFactoryRef = "primarySqlSessionFactory"
)
public class PrimaryMyBatisConfig {

    @Primary
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Primary
    @Bean
    public SqlSessionFactory primarySqlSessionFactory(
            @Qualifier("primaryDataSource") DataSource dataSource) throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource);
        sessionFactory.setMapperLocations(
            new PathMatchingResourcePatternResolver()
                .getResources("classpath:mapper/primary/*.xml"));
        return sessionFactory.getObject();
    }

    @Primary
    @Bean
    public SqlSessionTemplate primarySqlSessionTemplate(
            @Qualifier("primarySqlSessionFactory") SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory);
    }
}

2. 次数据源MyBatis配置

@Configuration
@MapperScan(
    basePackages = "com.example.mapper.secondary",
    sqlSessionFactoryRef = "secondarySqlSessionFactory"
)
public class SecondaryMyBatisConfig {

    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.secondary")
    public DataSource secondaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean
    public SqlSessionFactory secondarySqlSessionFactory(
            @Qualifier("secondaryDataSource") DataSource dataSource) throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource);
        sessionFactory.setMapperLocations(
            new PathMatchingResourcePatternResolver()
                .getResources("classpath:mapper/secondary/*.xml"));
        return sessionFactory.getObject();
    }

    @Bean
    public SqlSessionTemplate secondarySqlSessionTemplate(
            @Qualifier("secondarySqlSessionFactory") SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory);
    }
}

四、动态数据源配置（运行时切换）

1. 抽象路由数据源

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

2. 数据源上下文持有者

public class DataSourceContextHolder {
    private static final ThreadLocal<String> contextHolder = new ThreadLocal<>();

    public static void setDataSourceType(String dataSourceType) {
        contextHolder.set(dataSourceType);
    }

    public static String getDataSourceType() {
        return contextHolder.get();
    }

    public static void clearDataSourceType() {
        contextHolder.remove();
    }
}

3. 配置动态数据源

@Configuration
public class DynamicDataSourceConfig {

    @Bean
    @ConfigurationProperties(prefix="spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean
    @ConfigurationProperties(prefix="spring.datasource.secondary")
    public DataSource secondaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Primary
    @Bean
    public DataSource dynamicDataSource(
            @Qualifier("primaryDataSource") DataSource primaryDataSource,
            @Qualifier("secondaryDataSource") DataSource secondaryDataSource) {
        Map<Object, Object> targetDataSources = new HashMap<>();
        targetDataSources.put("primary", primaryDataSource);
        targetDataSources.put("secondary", secondaryDataSource);
        
        DynamicDataSource dynamicDataSource = new DynamicDataSource();
        dynamicDataSource.setTargetDataSources(targetDataSources);
        dynamicDataSource.setDefaultTargetDataSource(primaryDataSource);
        return dynamicDataSource;
    }
}

4. 使用AOP切换数据源

@Aspect
@Component
public class DataSourceAspect {
    @Pointcut("@annotation(com.example.annotation.TargetDataSource)")
    public void dataSourcePointCut() {}

    @Before("dataSourcePointCut()")
    public void before(JoinPoint point) {
        MethodSignature signature = (MethodSignature) point.getSignature();
        Method method = signature.getMethod();
        TargetDataSource ds = method.getAnnotation(TargetDataSource.class);
        
        if (ds == null) {
            DataSourceContextHolder.setDataSourceType("primary");
        } else {
            DataSourceContextHolder.setDataSourceType(ds.value());
        }
    }

    @After("dataSourcePointCut()")
    public void after(JoinPoint point) {
        DataSourceContextHolder.clearDataSourceType();
    }
}

5. 自定义注解

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface TargetDataSource {
    String value() default "primary";
}

6. 使用示例

@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;

    // 使用主数据源
    public User getPrimaryUser(Long id) {
        return userMapper.selectById(id);
    }

    // 使用次数据源
    @TargetDataSource("secondary")
    public User getSecondaryUser(Long id) {
        return userMapper.selectById(id);
    }
}

五、使用dynamic-datasource-spring-boot-starter简化配置

1. 添加依赖

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>dynamic-datasource-spring-boot-starter</artifactId>
    <version>3.1.0</version>
</dependency>

2. 配置数据源

spring:
  datasource:
    dynamic:
      primary: master1
      strict: false
      datasource:
        master1:
          url: jdbc:mysql://127.0.0.1:3306/master1
          username: root
          password: andrew
          driver-class-name: com.mysql.cj.jdbc.Driver
        master2:
          url: jdbc:mysql://127.0.0.1:3306/master2
          username: root
          password: andrew
          driver-class-name: com.mysql.cj.jdbc.Driver

3. 使用@DS注解切换数据源

@Service
@DS("slave")
public class UserServiceImpl implements UserService {

    @Autowired
    private JdbcTemplate jdbcTemplate;

    public List selectAll() {
        return jdbcTemplate.queryForList("select * from user");
    }

    @Override
    @DS("slave_1")
    public List selectByCondition() {
        return jdbcTemplate.queryForList("select * from user where age >10");
    }
}

六、多数据源事务管理

1. JTA分布式事务(Atomikos)

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jta-atomikos</artifactId>
</dependency>

2. 配置JTA数据源

# 主数据源
spring.jta.atomikos.datasource.primary.unique-resource-name: primaryDS
spring.jta.atomikos.datasource.primary.xa-data-source-class-name: com.mysql.cj.jdbc.MysqlXADataSource
spring.jta.atomikos.datasource.primary.xa-properties.url: jdbc:mysql://localhost:3306/db1
spring.jta.atomikos.datasource.primary.xa-properties.user: root
spring.jta.atomikos.datasource.primary.xa-properties.password: 123456

# 次数据源
spring.jta.atomikos.datasource.secondary.unique-resource-name: secondaryDS
spring.jta.atomikos.datasource.secondary.xa-data-source-class-name: com.mysql.cj.jdbc.MysqlXADataSource
spring.jta.atomikos.datasource.secondary.xa-properties.url: jdbc:mysql://localhost:3306/db2
spring.jta.atomikos.datasource.secondary.xa-properties.user: root
spring.jta.atomikos.datasource.secondary.xa-properties.password: 123456

3. 使用分布式事务

@Service
public class OrderService {
    @Transactional // 跨数据源事务
    public void placeOrder(Order order) {
        // 操作主数据源
        primaryRepository.save(order);
        // 操作次数据源
        auditRepository.logOrder(order);
        // 如果此处抛出异常,两个操作都会回滚
    }
}

七、最佳实践与常见问题

1. 最佳实践

命名规范：为每个数据源使用清晰的命名 (如 customerDS, orderDS)
包结构分离：按数据源分离包结构 (com.example.repository.primary / .secondary)
连接池配置：根据访问频率配置不同的连接池大小
监控指标：为每个数据源配置独立的监控
性能考虑：高频访问的数据源使用更大的连接池
测试策略：为每个数据源编写独立的测试类

2. 常见问题解决

问题 1：循环依赖

// 解决方法:使用@DependsOn
@Bean
@DependsOn("dynamicDataSource")
public PlatformTransactionManager transactionManager() {
    return new DataSourceTransactionManager(dynamicDataSource());
}

问题 2：MyBatis 缓存冲突

// 解决方法:为每个SqlSessionFactory配置独立的缓存环境
sqlSessionFactory.setConfiguration(configuration);
configuration.setEnvironment(new Environment(
    "primaryEnv", transactionFactory, dataSource));

问题 3：事务传播行为异常

// 解决方法:明确指定事务管理器
@Transactional(transactionManager = "primaryTransactionManager")
public void primaryOperation() {
    // ...
}

通过以上配置，Spring Boot 应用可以灵活地支持多数据源场景，无论是简单的多库连接还是复杂的动态数据源切换需求。根据实际业务场景选择最适合的配置方式，并注意事务管理和性能调优。

#后端

Spring Boot 多数据源配置全面指南

https://uniomo.com/archives/spring-boot-duo-shu-ju-yuan-pei-zhi-quan-mian-zhi-nan

作者

雨落秋垣

发布于

2025年06月25日

许可协议

Mac 上安装与配置 Harbor 的完整指南上一篇

Python 去除 IP 端口号并去重下一篇