Ruoyi多数据源实战：MySQL+PostgreSQL双数据库配置避坑指南

最近在重构一个老项目的技术栈，核心需求是将部分业务模块的数据从MySQL迁移到PostgreSQL，同时保持原有MySQL服务的稳定运行。在技术选型时，我们最终敲定了基于Ruoyi框架进行改造，因为它内置的多数据源支持看起来非常优雅。然而，从“看起来优雅”到“真正跑起来稳定”，中间隔着一片名为“实践细节”的汪洋大海。这篇文章，就是我在那片海里扑腾了几天后，总结出的航线图与避雷手册。如果你也正计划在Ruoyi项目中同时驾驭MySQL和PostgreSQL，希望我的这些经验能让你少走弯路，直达彼岸。

1. 环境准备与依赖管理：从源头规避冲突

在开始配置之前，一个清晰、无冲突的依赖环境是成功的基石。Ruoyi的多数据源机制依赖于Spring Boot的抽象和Druid连接池，而混合使用不同数据库时，驱动版本的兼容性往往是第一个暗礁。

1.1 驱动版本的选择与锁定

很多教程会告诉你，只需要在pom.xml里加入PostgreSQL的依赖就行。这没错，但没说全。关键在于版本。不同版本的PostgreSQL驱动对JDBC规范的支持度、与Spring Boot自动配置的配合度，以及自身可能存在的Bug都不同。

我强烈建议在项目的父POM或依赖管理部分，显式地锁定数据库驱动的版本，而不是依赖Spring Boot的默认版本管理。这样做可以确保在不同环境中构建的一致性。

<properties>
    <mysql.version>8.0.33</mysql.version>
    <postgresql.version>42.6.0</postgresql.version>
</properties>

<dependencies>
    <!-- MySQL驱动 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>${mysql.version}</version>
        <scope>runtime</scope>
    </dependency>
    <!-- PostgreSQL驱动 -->
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>${postgresql.version}</version>
        <scope>runtime</scope>
    </dependency>
    <!-- Druid连接池 (Ruoyi已集成) -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid-spring-boot-starter</artifactId>
        <!-- 版本通常由ruoyi父POM管理 -->
    </dependency>
</dependencies>

注意：PostgreSQL驱动从42.2.0版本开始，其JDBC URL的默认连接属性发生了变化。例如，prepareThreshold的默认值改为5，这可能会影响某些预处理语句的执行计划。如果你遇到性能差异，可能需要调整URL参数。

1.2 检查潜在的依赖冲突

混合数据源时，一个常见但容易被忽略的问题是事务管理器和JPA方言的冲突。虽然Ruoyi默认使用MyBatis，但Spring Boot的自动配置可能会因为检测到多个数据源而尝试配置多个实体管理器工厂。

运行以下命令可以快速检查依赖树，排除不必要的JPA相关依赖：

mvn dependency:tree -Dincludes=*hibernate*,*jpa*

如果发现有不必要的Hibernate或JPA依赖被引入，可以在对应的依赖上使用<exclusions>标签排除。确保项目核心只依赖于spring-boot-starter-jdbc和mybatis-spring-boot-starter（或Ruoyi对应的MyBatis模块），避免自动配置的“好心办坏事”。

2. 核心配置详解：超越基础的YAML文件

配置application-druid.yml文件是第一步，但里面的每一个参数都值得推敲。直接复制粘贴网上的配置模板，很可能为后续的性能问题和连接泄漏埋下伏笔。

2.1 数据源连接参数精细化配置

下面是一个针对生产环境优化的双数据源配置示例，我添加了详细的注释说明每个关键参数的作用：

spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      # 全局Druid监控和过滤器配置（可选但推荐）
      web-stat-filter:
        enabled: true
      stat-view-servlet:
        enabled: true
        allow: 127.0.0.1
        login-username: admin
        login-password: admin

      # 主数据源 (MySQL)
      master:
        url: jdbc:mysql://mysql-host:3306/ruoyi_main?useUnicode=true&characterEncoding=UTF-8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai&rewriteBatchedStatements=true
        username: app_user
        password: ${MASTER_DB_PASSWORD:your_secure_password}
        driver-class-name: com.mysql.cj.jdbc.Driver
        # 连接池核心配置
        initial-size: 5
        min-idle: 5
        max-active: 20
        max-wait: 60000
        time-between-eviction-runs-millis: 60000
        min-evictable-idle-time-millis: 300000
        validation-query: SELECT 1
        test-while-idle: true
        test-on-borrow: false
        test-on-return: false
        pool-prepared-statements: true
        max-pool-prepared-statement-per-connection-size: 20
        filters: stat,wall,slf4j # 启用统计、防御SQL注入、日志过滤器

      # 从数据源 (PostgreSQL) - 特别注意enabled开关
      slave:
        enabled: true # 这个开关至关重要，控制是否初始化该数据源
        url: jdbc:postgresql://pgsql-host:5432/ruoyi_analytics?currentSchema=public&stringtype=unspecified&ApplicationName=RuoyiApp
        username: pg_app_user
        password: ${SLAVE_DB_PASSWORD:your_secure_password}
        driver-class-name: org.postgresql.Driver
        # PostgreSQL连接池配置可以略有不同
        initial-size: 3
        min-idle: 3
        max-active: 15 # PostgreSQL连接开销可能略大，可适当调低
        max-wait: 60000
        validation-query: SELECT 1
        test-while-idle: true
        # PostgreSQL对预处理语句的缓存机制与MySQL不同，以下参数需注意
        pool-prepared-statements: false # PostgreSQL驱动通常自己管理预处理语句缓存，建议关闭
        filters: stat,wall

关键避坑点：

1. enabled开关：这是Ruoyi多数据源设计的一个精妙之处。当slave.enabled=false时，Spring容器根本不会初始化PostgreSQL的DataSource Bean。这在开发、测试环境或某些不需要从库的场景下非常有用，可以避免因从库不可用而导致整个应用启动失败。
2. URL参数：
   • MySQL：rewriteBatchedStatements=true 能大幅提升批量插入的性能。
   • PostgreSQL：stringtype=unspecified 可以避免在设置PreparedStatement参数时因类型推断导致的错误；ApplicationName有助于在数据库端识别连接来源，方便监控。
3. pool-prepared-statements：这是MySQL和PostgreSQL配置的一个重大差异。MySQL开启此选项可以利用连接池级别的预处理语句缓存提升性能。但PostgreSQL的JDBC驱动自身有更完善的语句缓存机制，开启Druid的此功能可能导致重复缓存甚至内存泄漏，通常建议为PostgreSQL数据源关闭此选项。

2.2 连接池监控与诊断

配置好后，如何知道它工作正常？Druid内置了强大的监控功能。访问 http://你的应用地址/druid 即可看到监控页面。这里可以清晰地看到两个数据源的活跃连接数、等待次数、执行SQL统计等信息。

一个健康的指标是：

• 活跃连接数 (ActiveCount) 大部分时间应在 min-idle 和 max-active 之间波动，不会长期顶到 max-active。
• 等待次数 (WaitCount) 应该非常低或为0。如果持续增长，说明 max-active 设置过小，连接不够用。

我曾经遇到过一个坑：从库的查询偶尔超时，监控发现WaitCount很高。起初以为是SQL慢，后来才发现是max-active设置得太小（只有5），而某个批处理任务并发查询较多，导致大量线程在等待获取数据库连接。将其调整到15后问题立解。

3. 动态数据源切换的进阶用法

Ruoyi通过@DataSource注解实现声明式数据源切换，这非常方便。但实际业务场景往往比简单的“这个类用主库，那个类用从库”更复杂。

3.1 基于业务逻辑的动态切换

有时，数据源的选择需要在运行时根据参数决定。例如，根据用户所属租户（tenant）决定连接哪个物理数据库。这时，我们可以扩展Ruoyi的DataSource注解，或者更灵活地，直接操作底层的DynamicDataSource。

首先，理解Ruoyi的核心——DynamicDataSource类（通常位于com.ruoyi.framework.datasource包下）。它继承了AbstractRoutingDataSource，其determineCurrentLookupKey()方法返回的字符串，就是我们在@DataSource注解里写的value（如“SLAVE”）。

我们可以创建一个工具类，允许在代码中动态设置这个“key”：

public class DynamicDataSourceContextHolder {
    /**
     * 使用ThreadLocal为每个线程维护数据源标识
     */
    private static final ThreadLocal<String> CONTEXT_HOLDER = new ThreadLocal<>();

    /**
     * 设置数据源标识
     * @param dsType 数据源类型，对应 DataSourceType 枚举或自定义字符串
     */
    public static void setDataSourceType(String dsType) {
        CONTEXT_HOLDER.set(dsType);
    }

    /**
     * 获取当前数据源标识
     */
    public static String getDataSourceType() {
        return CONTEXT_HOLDER.get();
    }

    /**
     * 清空数据源标识，恢复为默认（主库）
     */
    public static void clearDataSourceType() {
        CONTEXT_HOLDER.remove();
    }
}

然后，你需要自定义一个DynamicDataSource的子类，重写determineCurrentLookupKey()方法，优先从DynamicDataSourceContextHolder中获取数据源标识：

public class CustomDynamicDataSource extends DynamicDataSource {
    @Override
    protected Object determineCurrentLookupKey() {
        String dsKey = DynamicDataSourceContextHolder.getDataSourceType();
        if (StringUtils.isNotBlank(dsKey)) {
            return dsKey; // 优先使用代码动态设置的
        }
        // 否则，回退到基于@DataSource注解的查找逻辑
        // 这里通常需要调用父类或通过其他方式获取注解值，具体取决于Ruoyi版本实现
        // 假设父类有一个方法能获取到注解的key
        return super.determineTargetDataSourceKey();
    }
}

别忘了在DruidConfig中将datasource方法返回的Bean类型改为你的CustomDynamicDataSource。

这样，你就可以在业务代码中灵活切换了：

@Service
public class SomeService {
    @Autowired
    private SomeMapper someMapper;

    public List<Data> getDataByTenant(String tenantId) {
        // 根据租户ID决定使用哪个数据源
        String dsKey = resolveDataSourceKey(tenantId); // 你的解析逻辑
        try {
            DynamicDataSourceContextHolder.setDataSourceType(dsKey);
            // 执行查询，此时会使用你设置的数据源
            return someMapper.selectByCondition(...);
        } finally {
            // 务必清理，避免污染后续操作（特别是线程池场景）
            DynamicDataSourceContextHolder.clearDataSourceType();
        }
    }
}

警告：在使用线程池（如@Async异步方法、ExecutorService）的场景下，必须极其小心。因为ThreadLocal的值会在同一个线程中被复用。不恰当的清理会导致数据源错乱。一个最佳实践是，在提交任务到线程池前，将所需的数据源标识作为任务参数传入，在任务的run或call方法内部最开始处进行设置，并在finally块中清理。

3.2 读写分离与事务边界

多数据源最常见的场景是读写分离：写操作走主库（MySQL），读操作走从库（PostgreSQL）。但这里有一个事务一致性的陷阱。

考虑以下代码：

@Service
public class UserService {
    @Transactional
    public void updateUserAndLog(User user, Log log) {
        // 1. 在主库更新用户
        updateUser(user); // 方法上默认使用主库（或通过注解指定）
        // 2. 切换到从库插入日志
        DynamicDataSourceContextHolder.setDataSourceType("SLAVE");
        try {
            insertLog(log); // 期望在从库执行
        } finally {
            DynamicDataSourceContextHolder.clearDataSourceType();
        }
        // 3. 如果这里抛出异常...
        // throw new RuntimeException("Something wrong!");
    }
}

问题在于：@Transactional注解开启了一个主库上的事务。当你动态切换到从库执行insertLog时，这个操作并不在同一个事务管理器的管理之下（主从库对应两个不同的DataSource，通常也意味着两个独立的PlatformTransactionManager）。更严重的是，如果后续步骤抛出异常，Spring只会回滚主库的事务，而从库的日志插入已经提交，无法回滚，导致数据不一致。

解决方案：

1. 避免在同一个事务方法内跨库写操作。这是最根本的原则。将insertLog改为异步或发消息到队列，后续由另一个消费服务在从库上执行。
2. 如果必须保证一致性，考虑使用分布式事务，如Seata。但这会引入显著的复杂性和性能开销，需谨慎评估。
3. 对于纯读操作，在事务方法内切换数据源是相对安全的，因为即使回滚，读操作本身不产生数据变更。但仍需注意，在事务隔离级别为“可重复读”或以上时，在主库事务中读到的数据视图，和在从库中读到的实时数据视图可能不一致。

4. 性能调优与故障排查实战

配置通了只是开始，跑得稳、跑得快才是目标。混合数据库环境下的性能调优有其特殊性。

4.1 连接池参数调优表

下表总结了针对不同业务场景，MySQL和PostgreSQL连接池关键参数的调优思路：

参数	默认值/通用值	高并发短查询场景	低并发复杂事务/批处理场景	说明与注意事项
initial-size	5-10	10-20	3-5	应用启动时建立的连接数。设大些可避免启动后首批请求的等待。
min-idle	5-10	10-20	3-5	池中保持的最小空闲连接。应与initial-size接近，避免频繁收缩扩张。
max-active	20-50	50-100	20-30	最重要参数。估算公式：最大并发请求数 / (每个请求平均持有连接时间 / 平均请求处理时间)。需密切监控WaitCount。
max-wait	60000ms	3000-5000ms	30000ms	获取连接的最大等待时间。高并发下设短可快速失败，避免线程堆积。
validation-query	SELECT 1	SELECT 1	SELECT 1	简单的验证SQL。PostgreSQL也可用SELECT 1。
test-while-idle	true	true	true	强烈建议开启，定期检测空闲连接是否有效。
time-between-eviction-runs-millis	60000ms	30000ms	120000ms	空闲连接检测线程的运行周期。
min-evictable-idle-time-millis	300000ms	180000ms	600000ms	连接在池中最小生存时间。

特别注意：上表是通用指导，一定要结合Druid监控页面的实际数据进行调整。调优是一个“观察-调整-再观察”的循环过程。

4.2 常见故障排查场景

场景一：应用启动报错 BeanCreationException，提示找不到slaveDatasource Bean。

• 可能原因：application-druid.yml中slave.enabled为true，但PostgreSQL驱动未正确引入或版本冲突，导致无法加载驱动类。
• 排查步骤：
  1. 检查pom.xml中PostgreSQL依赖是否存在，版本是否明确。
  2. 运行mvn clean compile，确认编译无错。
  3. 检查启动日志，看是否有Driver class not found之类的警告。
  4. 临时将slave.enabled改为false，看应用是否能正常启动（排除主库配置问题）。

场景二：使用@DataSource(SLAVE)注解的方法，偶尔报连接超时或连接关闭错误。

• 可能原因：
  1. 连接泄漏：某些操作没有正确关闭Connection、Statement或ResultSet。虽然MyBatis通常会处理，但复杂的手动操作或第三方库可能出错。
  2. 从库网络不稳定或压力大。
  3. 连接池验证失败：validation-query在从库上执行失败（如权限问题），导致Druid认为连接无效并将其丢弃，但新的连接建立又慢。
• 排查步骤：
  1. 开启Druid的log-abandoned和remove-abandoned功能（生产环境慎用，仅临时诊断），看是否有连接未被关闭的警告。
  2. 在Druid监控页查看从库的ActiveCount、PoolingCount和WaitCount历史趋势。如果ActiveCount长期等于max-active，且WaitCount高，则是连接数不足。如果PoolingCount（空闲连接）经常为0，可能是连接被频繁创建销毁，检查test-while-idle和validation-query。
  3. 手动执行从库的validation-query，确保其快速成功。

场景三：动态切换数据源在异步方法中失效，总是跑到默认主库。

• 根本原因：如前所述，ThreadLocal在线程池场景下的传递问题。
• 解决方案：使用“任务装饰器”模式。在配置线程池时，添加一个TaskDecorator，在任务执行前将当前线程的ThreadLocal值复制到子线程。

@Configuration
public class ThreadPoolConfig {
    @Bean("asyncTaskExecutor")
    public Executor asyncTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        // ... 配置核心数、队列等
        // 关键：添加任务装饰器
        executor.setTaskDecorator(new ContextCopyingTaskDecorator());
        executor.initialize();
        return executor;
    }

    static class ContextCopyingTaskDecorator implements TaskDecorator {
        @Override
        public Runnable decorate(Runnable runnable) {
            // 捕获调用方的数据源上下文
            String currentDataSourceKey = DynamicDataSourceContextHolder.getDataSourceType();
            return () -> {
                try {
                    // 在子线程开始时设置
                    if (currentDataSourceKey != null) {
                        DynamicDataSourceContextHolder.setDataSourceType(currentDataSourceKey);
                    }
                    runnable.run();
                } finally {
                    // 子线程结束时清理
                    DynamicDataSourceContextHolder.clearDataSourceType();
                }
            };
        }
    }
}

配置完这些，我项目里的MySQL和PostgreSQL终于可以和谐共处，各司其职了。回顾整个过程，最大的体会就是：多数据源配置，三分在配，七分在调与防。配置文件只是骨架，连接池参数、事务边界、异常处理这些“血肉”才是决定系统是否健壮的关键。尤其是混合不同特性的数据库时，更要尊重它们各自的“脾气”，比如那个pool-prepared-statements的差异，就让我排查了大半天。希望这份融合了具体踩坑经验的指南，能帮你更顺畅地搭建起属于你的双数据库架构。如果在实践中遇到新的问题，不妨多看看Druid监控，数据往往比直觉更可靠。