Skip to content

多数据源方案 ​

Sz-Admin 当前主线默认使用一个主数据源:DB_TYPE=mysql|postgresql 决定运行时加载的连接配置,Maven 的 mysql / postgresql profile 决定构建时装配的数据库模块。这个机制用于在 MySQL 与 PostgreSQL 之间二选一,不等于同时连接多个数据库。

MyBatis-Flex 本身支持多数据源。如果项目确实需要按业务域访问多个数据库,可以在二开项目中启用,但它属于专项扩展,不是当前主线的开箱即用能力。

IMPORTANT

多数据源不仅是增加几段连接配置。落地前必须同时设计事务、Liquibase、数据权限方言、代码生成器、连接池容量、故障隔离和密钥管理。没有明确多库需求时,继续使用单主数据源更容易维护。

适用场景 ​

适合:

  • 新旧系统迁移期间,只读访问历史库。
  • 报表、归档或审计数据与核心业务库物理隔离。
  • 独立业务模块拥有自己的数据库,并能接受明确的跨库一致性策略。

不建议直接套用:

  • 只是从 MySQL 切换到 PostgreSQL:使用 DB_TYPE 与 Maven profile。
  • 只是按租户隔离数据:先评估多租户或分库分表方案。
  • 一次业务写入必须跨多个数据库保持强一致:需要额外的分布式事务或业务补偿设计。

当前实现边界 ​

能力当前主线情况多数据源项目需要补充
主数据库spring.datasource + DB_TYPE调整为 MyBatis-Flex 多数据源配置,并明确默认数据源
数据库依赖Maven profile 二选一优先保持同一数据库厂商;混合厂商需要同时处理驱动、方言和 TypeHandler
Liquibase默认管理主数据源为每个需要迁移的数据源单独配置 changelog、版本表和权限
数据权限方言按主数据源驱动激活混合 MySQL/PostgreSQL 时需要实现按实际数据源选择方言并补测试
代码生成器元数据服务使用注入的默认 DataSource不应假设生成器可以自动浏览或导入所有附加数据源
事务支持 Spring @Transactional多库提交/回滚不是分布式原子事务,必须设计异常恢复

仓库仍保留 datasource 示例分支,但它是 2025 年形成的历史示例,不能直接当作当前 main / preview 的可合并补丁。使用时应以当前分支的 POM、配置和代码为基线重新适配。

配置思路 ​

MyBatis-Flex 使用 mybatis-flex.datasource.<name> 声明数据源。下面以两个 MySQL 开发库为例,使用环境变量承载连接信息:

yaml
mybatis-flex:
  datasource:
    primary:
      type: com.zaxxer.hikari.HikariDataSource
      driver-class-name: com.mysql.cj.jdbc.Driver
      url: ${PRIMARY_DB_URL}
      username: ${PRIMARY_DB_USERNAME}
      password: ${PRIMARY_DB_PASSWORD}
      pool-name: HikariPrimary
      maximum-pool-size: 10

    archive:
      type: com.zaxxer.hikari.HikariDataSource
      driver-class-name: com.mysql.cj.jdbc.Driver
      url: ${ARCHIVE_DB_URL}
      username: ${ARCHIVE_DB_USERNAME}
      password: ${ARCHIVE_DB_PASSWORD}
      pool-name: HikariArchive
      maximum-pool-size: 5

配置顺序中的第一个数据源是默认数据源。名称应使用稳定的业务含义,例如 primary、archive、reporting,不要使用会随环境变化的 IP、库名或人员名称。

WARNING

不要把真实账号密码提交到仓库。生产环境使用部署平台密钥、环境变量或受权限控制的外置配置。连接池上限应结合数据库最大连接数和应用实例数计算,不能简单复制主库配置。

启用前需要同步处理:

  1. 保留当前 mybatis-flex.configuration、逻辑删除和 ID 配置。
  2. 确认默认数据源与 DB_TYPE、Maven profile 使用同一种数据库类型。
  3. 确认 Liquibase 最终连接的是预期主库,而不是仅看到应用启动成功。
  4. 为附加数据源单独设置最小权限账号和连接池大小。

选择数据源 ​

MyBatis-Flex 支持 DataSourceKey、@UseDataSource 和 @Table(dataSource = "...")。在 Sz-Admin 二开项目中,优先把数据源边界放在 Mapper 类或 Mapper 方法上,避免 Service 层一次切换影响过多查询。

java
@UseDataSource("archive")
public interface ArchiveOrderMapper extends BaseMapper<ArchiveOrder> {
}

只有某个实体始终属于固定数据源时,才在实体上声明:

java
@Table(value = "archive_order", dataSource = "archive")
public class ArchiveOrder {
    // fields
}

需要在很小的代码片段中临时切换时,使用带回调的方法,或确保 finally 清理上下文:

java
List<Row> rows = DataSourceKey.use(
    "archive",
    () -> Db.selectAll("archive_order")
);

数据源选择优先级为:

text
DataSourceKey.use()
  > 方法上的 @UseDataSource
  > 类上的 @UseDataSource
  > @Table(dataSource = "...")
  > 默认数据源

同一调用链混用多种切换方式会增加排查成本。一个业务边界内应尽量保持一种清晰策略。

Liquibase 与事务 ​

Liquibase ​

当前 spring.liquibase 默认只管理主数据源。附加数据源如果也需要版本管理,应分别提供:

  • 独立 SpringLiquibase 配置。
  • 独立 changelog 入口和 changeSet ID 命名空间。
  • 独立的 DATABASECHANGELOG / DATABASECHANGELOGLOCK 表或明确的表名策略。
  • 与目标数据库匹配的账号权限、方言和回滚方案。

不要让同一份 changelog 在两个数据库上被无意执行,也不要用应用启动成功代替迁移结果核对。

事务 ​

MyBatis-Flex 可以让同一 @Transactional 中的多个数据源执行相同的提交或回滚动作,但这不等于多个数据库之间具备分布式原子性。网络、数据库或回滚故障仍可能导致部分数据源成功、部分失败。

跨库写入至少选择一种明确策略:

  • 避免同步跨库写,改为事件、消息或任务最终一致。
  • 使用幂等操作、补偿任务和人工恢复台账。
  • 业务确实要求强一致时,经过专项评估后引入分布式事务方案。

验证清单 ​

多数据源改造不能只以“应用启动成功”为验收。至少验证:

  1. 默认查询只访问主库,指定查询只访问目标附加库。
  2. 不存在的数据源名称会明确失败,不会静默回退到主库。
  3. 并发请求之间的数据源上下文不会串用。
  4. 主库 Liquibase 只执行一次,附加库迁移符合各自设计。
  5. 数据权限、逻辑删除、自动填充和自定义 TypeHandler 在目标数据源生效。
  6. 跨库事务的成功、异常、超时和恢复路径都有可观察结果。
  7. 连接池总连接数、数据库账号权限和密钥管理符合目标环境要求。
  8. 代码生成器只在已确认的数据源上读取元数据,生成后的 SQL 与目标方言一致。

更多切换方式和事务限制请参考 MyBatis-Flex 官方文档: