Spring Boot项目中如何优雅地实现多数据源JPA配置？

在现代企业级应用开发中，随着业务复杂度的提升，单一数据源有时已无法满足需求，为了实现读写分离以提高数据库性能，或是需要整合多个独立业务系统的数据，甚至是在微服务架构中，一个服务需要访问不同数据库的多个模块，在这些场景下，配置和管理多个数据源便成为一个至关重要的技术课题，Spring Boot 与 JPA（Java Persistence API）的组合极大地简化了数据访问层的开发，但其默认的自动配置仅支持单一数据源，本文将深入探讨如何在 Spring Boot 项目中，清晰、高效地完成多数据源的 JPA 配置。

配置多数据源的核心思路

Spring Boot 的自动配置魔法在于 DataSourceAutoConfiguration，它会根据 classpath 中的依赖和 application.properties 中的配置创建一个默认的 DataSource，当存在多个数据源时，我们需要接管这部分配置，手动创建多个 DataSource Bean，并为它们分别配置独立的 JPA 环境，包括 EntityManagerFactory 和 PlatformTransactionManager，核心思路是“拆分”与“绑定”：将原本统一配置的组件拆分为多套，然后将每一套组件（数据源、实体管理器、事务管理器）与对应的 Repository 接口进行绑定。

第一步：依赖与基础属性配置

确保你的项目中包含了必要的依赖，除了 spring-boot-starter-web 和 spring-boot-starter-data-jpa，还需要根据你使用的数据库添加相应的 JDBC 驱动，mysql-connector-java。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <scope>runtime</scope>
</dependency>

在 application.yml（或 application.properties）中定义两个数据源的连接信息，为了清晰地区分，我们使用自定义的前缀，primary 和 secondary。

# 主数据源配置
primary:
  datasource:
    url: jdbc:mysql://localhost:3306/primary_db?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
    username: root
    password: password
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      maximum-pool-size: 10
# 从数据源配置
secondary:
  datasource:
    url: jdbc:mysql://localhost:3306/secondary_db?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
    username: root
    password: password
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      maximum-pool-size: 8
# JPA 基础配置，可以共用
spring:
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect
        format_sql: true

第二步：创建数据源配置类

这是整个配置过程的核心，我们需要创建一个配置类，来手动实例化 DataSource Bean，通过 @ConfigurationProperties 注解，我们可以将 YAML 中定义的属性自动绑定到 DataSource 对象上。

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.jdbc.DataSourceBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import javax.sql.DataSource;
@Configuration
public class DataSourceConfig {
    @Primary // 标记为主数据源，当Spring需要注入一个DataSource时，会优先选择这个
    @Bean(name = "primaryDataSource")
    @ConfigurationProperties(prefix = "primary.datasource") // 绑定primary.datasource开头的配置
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }
    @Bean(name = "secondaryDataSource")
    @ConfigurationProperties(prefix = "secondary.datasource") // 绑定secondary.datasource开头的配置
    public DataSource secondaryDataSource() {
        return DataSourceBuilder.create().build();
    }
}

关键点：@Primary 注解至关重要，当 Spring 容器中存在多个同类型的 Bean（这里是 DataSource）时，如果没有指定 @Primary，在自动注入的地方（如某个 @Autowired DataSource dataSource）Spring 会因为不知道选择哪一个而抛出 NoUniqueBeanDefinitionException 异常,导致启动失败。

第三步：配置独立的 JPA 环境

每一个数据源都需要一套独立的 JPA 运行环境，这意味着我们需要为每个数据源分别配置 EntityManagerFactory 和 PlatformTransactionManager,最佳实践是为每个数据源创建一个独立的配置类。

主数据源 JPA 配置：

import org.springframework.orm.jpa.JpaTransactionManager;
import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
import org.springframework.boot.orm.jpa.EntityManagerFactoryBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.transaction.PlatformTransactionManager;
import javax.persistence.EntityManagerFactory;
import javax.sql.DataSource;
@Configuration
@EnableJpaRepositories(
    basePackages = "com.example.repository.primary", // 指定主数据源Repository的包路径
    entityManagerFactoryRef = "primaryEntityManagerFactory",
    transactionManagerRef = "primaryTransactionManager"
)
public class PrimaryDataSourceConfig {
    @Primary
    @Bean(name = "primaryEntityManagerFactory")
    public LocalContainerEntityManagerFactoryBean primaryEntityManagerFactory(
            EntityManagerFactoryBuilder builder, @Qualifier("primaryDataSource") DataSource dataSource) {
        return builder
                .dataSource(dataSource)
                .packages("com.example.entity.primary") // 指定主数据源Entity的包路径
                .persistenceUnit("primary")
                .build();
    }
    @Primary
    @Bean(name = "primaryTransactionManager")
    public PlatformTransactionManager primaryTransactionManager(
            @Qualifier("primaryEntityManagerFactory") EntityManagerFactory entityManagerFactory) {
        return new JpaTransactionManager(entityManagerFactory);
    }
}

从数据源 JPA 配置：

import org.springframework.orm.jpa.JpaTransactionManager;
import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
import org.springframework.boot.orm.jpa.EntityManagerFactoryBuilder;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.transaction.PlatformTransactionManager;
import javax.persistence.EntityManagerFactory;
import javax.sql.DataSource;
@Configuration
@EnableJpaRepositories(
    basePackages = "com.example.repository.secondary", // 指定从数据源Repository的包路径
    entityManagerFactoryRef = "secondaryEntityManagerFactory",
    transactionManagerRef = "secondaryTransactionManager"
)
public class SecondaryDataSourceConfig {
    @Bean(name = "secondaryEntityManagerFactory")
    public LocalContainerEntityManagerFactoryBean secondaryEntityManagerFactory(
            EntityManagerFactoryBuilder builder, @Qualifier("secondaryDataSource") DataSource dataSource) {
        return builder
                .dataSource(dataSource)
                .packages("com.example.entity.secondary") // 指定从数据源Entity的包路径
                .persistenceUnit("secondary")
                .build();
    }
    @Bean(name = "secondaryTransactionManager")
    public PlatformTransactionManager secondaryTransactionManager(
            @Qualifier("secondaryEntityManagerFactory") EntityManagerFactory entityManagerFactory) {
        return new JpaTransactionManager(entityManagerFactory);
    }
}

关键点：

1. 包路径隔离：通过 @EnableJpaRepositories 的 basePackages 属性和 EntityManagerFactoryBuilder 的 packages 方法，将不同数据源的 Repository 接口和 Entity 实体类严格划分在不同的包下，这是 Spring Data JPA 识别和路由请求到正确数据源的依据。
2. 引用绑定：entityManagerFactoryRef 和 transactionManagerRef 明确指定了该包下的 Repository 应该使用哪个 EntityManagerFactory 和 PlatformTransactionManager。
3. 依赖注入：使用 @Qualifier 注解来指定注入哪个名称的 DataSource Bean，避免因存在多个 DataSource 而产生混淆。

至此，多数据源 JPA 的配置已经全部完成，你可以在相应的 Service 层中注入对应包下的 Repository，Spring Data JPA 会自动为你路由到正确的数据库执行操作。

相关问答FAQs

问题1：为什么必须将一个数据源及其相关的 JPA 组件标记为 @Primary？如果不标记会怎么样？

解答：Spring 框架的依赖注入容器在管理 Bean 时，如果遇到一个类型（如 DataSource）存在多个实例的情况，它不知道应该选择哪一个注入到需要该类型的地方。@Primary 注解就是用来解决这个“选择困难症”的，它告诉 Spring：“当有多个候选者时，请优先使用我标记的这个。” 如果不使用 @Primary，并且也没有在所有注入点都通过 @Qualifier 明确指定 Bean 的名称，Spring 容器在启动时会抛出 NoUniqueBeanDefinitionException 异常，因为存在多个符合条件的 Bean 定义，导致应用无法正常启动，将主数据源（通常是写库或核心业务库）设为 @Primary,可以简化大部分默认情况下对数据源的引用。

问题2：我可以在一个 Service 方法中同时操作两个不同的数据源，并保证事务的一致性吗？

解答：这是一个复杂的问题，默认情况下，Spring 的 @Transactional 注解管理的是“本地事务”，它依赖于单一的资源管理器（如一个数据库连接），在一个方法中，即使你操作了两个不同数据源的 Repository，Spring 也会为它们各自创建独立的事务，这意味着，如果对数据源 A 的操作成功，而对数据源 B 的操作失败，A 的操作不会被回滚,从而导致数据不一致。

要实现跨多个数据源的原子性事务（即分布式事务），你需要引入 JTA（Java Transaction API）规范，在 Spring 中，可以通过配置 JtaTransactionManager 来实现，这通常需要依赖一个外部的 JTA 事务管理器，如 Atomikos、Narayana 或应用服务器（如 WebLogic, WebSphere）提供的 JTA 服务，配置和使用分布式事务会比本地事务复杂得多，并且会带来一定的性能开销，在架构设计时应尽量避免跨数据源的强一致性事务，转而采用最终一致性等柔性事务方案，只有在业务逻辑确实无法避免时,才考虑引入分布式事务。