多数据源方案
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 开发库为例,使用环境变量承载连接信息:
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
不要把真实账号密码提交到仓库。生产环境使用部署平台密钥、环境变量或受权限控制的外置配置。连接池上限应结合数据库最大连接数和应用实例数计算,不能简单复制主库配置。
启用前需要同步处理:
- 保留当前
mybatis-flex.configuration、逻辑删除和 ID 配置。 - 确认默认数据源与
DB_TYPE、Maven profile 使用同一种数据库类型。 - 确认 Liquibase 最终连接的是预期主库,而不是仅看到应用启动成功。
- 为附加数据源单独设置最小权限账号和连接池大小。
选择数据源
MyBatis-Flex 支持 DataSourceKey、@UseDataSource 和 @Table(dataSource = "...")。在 Sz-Admin 二开项目中,优先把数据源边界放在 Mapper 类或 Mapper 方法上,避免 Service 层一次切换影响过多查询。
@UseDataSource("archive")
public interface ArchiveOrderMapper extends BaseMapper<ArchiveOrder> {
}只有某个实体始终属于固定数据源时,才在实体上声明:
@Table(value = "archive_order", dataSource = "archive")
public class ArchiveOrder {
// fields
}需要在很小的代码片段中临时切换时,使用带回调的方法,或确保 finally 清理上下文:
List<Row> rows = DataSourceKey.use(
"archive",
() -> Db.selectAll("archive_order")
);数据源选择优先级为:
DataSourceKey.use()
> 方法上的 @UseDataSource
> 类上的 @UseDataSource
> @Table(dataSource = "...")
> 默认数据源同一调用链混用多种切换方式会增加排查成本。一个业务边界内应尽量保持一种清晰策略。
Liquibase 与事务
Liquibase
当前 spring.liquibase 默认只管理主数据源。附加数据源如果也需要版本管理,应分别提供:
- 独立
SpringLiquibase配置。 - 独立 changelog 入口和 changeSet ID 命名空间。
- 独立的
DATABASECHANGELOG/DATABASECHANGELOGLOCK表或明确的表名策略。 - 与目标数据库匹配的账号权限、方言和回滚方案。
不要让同一份 changelog 在两个数据库上被无意执行,也不要用应用启动成功代替迁移结果核对。
事务
MyBatis-Flex 可以让同一 @Transactional 中的多个数据源执行相同的提交或回滚动作,但这不等于多个数据库之间具备分布式原子性。网络、数据库或回滚故障仍可能导致部分数据源成功、部分失败。
跨库写入至少选择一种明确策略:
- 避免同步跨库写,改为事件、消息或任务最终一致。
- 使用幂等操作、补偿任务和人工恢复台账。
- 业务确实要求强一致时,经过专项评估后引入分布式事务方案。
验证清单
多数据源改造不能只以“应用启动成功”为验收。至少验证:
- 默认查询只访问主库,指定查询只访问目标附加库。
- 不存在的数据源名称会明确失败,不会静默回退到主库。
- 并发请求之间的数据源上下文不会串用。
- 主库 Liquibase 只执行一次,附加库迁移符合各自设计。
- 数据权限、逻辑删除、自动填充和自定义 TypeHandler 在目标数据源生效。
- 跨库事务的成功、异常、超时和恢复路径都有可观察结果。
- 连接池总连接数、数据库账号权限和密钥管理符合目标环境要求。
- 代码生成器只在已确认的数据源上读取元数据,生成后的 SQL 与目标方言一致。
更多切换方式和事务限制请参考 MyBatis-Flex 官方文档:
