跳到主要内容

多数据源配置

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 组件详解
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向 yudao-cloud 的多数据源架构，系统性阐述 MySQL 主从分离、TDengine 时序数据库集成、Redis 缓存配置的设计与落地。重点覆盖：

  • 数据源路由机制与注解使用
  • 连接池管理策略与参数调优
  • 事务传播行为处理
  • 数据源切换注解与手动切换
  • 配置文件示例与最佳实践
  • 健康检查、故障转移与性能监控

项目结构​

围绕多数据源的关键目录与文件如下：

  • 配置层
    • 本地开发配置：datasource.yaml
    • 生产环境配置：deploy/yml/prod/datasource.yaml
  • 自动装配与监控
    • YudaoDataSourceAutoConfiguration：Druid 广告移除过滤器注册、事务管理启用
    • IdTypeEnvironmentPostProcessor：动态识别主数据源 URL 并推断数据库类型
  • 数据源枚举与常量
    • DataSourceEnum：多数据源标识（master/slave）
  • 数据源配置管理
    • DataSourceConfigServiceImpl：从数据库加载数据源配置，补充主库配置
    • DataSourceConfigDO：数据源配置实体
  • TDengine 集成
    • TDEngineBaseMapper：通过 @DS 指定 TDengine 数据源
    • GoViewTDEngineDataServiceImpl / GoViewMysqlDataServiceImpl：演示手动切换与注解切换
  • Redis 缓存
    • YudaoCacheProperties：缓存相关配置项
    • YudaoCacheAutoConfiguration：缓存配置与序列化策略
    • TimeoutRedisCacheManager：支持 cacheName#ttl 的过期时间解析
    • Gateway 层 RedisConfig：注入 TimeoutRedisCacheManager

Mermaid Diagram Code:

graph TB
subgraph "配置层"
A["datasource.yaml<br/>本地开发配置"]
B["deploy/yml/prod/datasource.yaml<br/>生产环境配置"]
end
subgraph "自动装配与监控"
C["YudaoDataSourceAutoConfiguration<br/>事务管理/Druid过滤器"]
D["IdTypeEnvironmentPostProcessor<br/>推断数据库类型"]
end
subgraph "数据源管理"
E["DataSourceConfigServiceImpl<br/>加载/补全数据源配置"]
F["DataSourceConfigDO<br/>数据源配置实体"]
G["DataSourceEnum<br/>数据源标识(master/slave)"]
end
subgraph "TDengine 集成"
H["TDEngineBaseMapper<br/>@DS 指向 TDengine"]
I["GoViewTDEngineDataServiceImpl<br/>手动切换TDengine"]
J["GoViewMysqlDataServiceImpl<br/>手动切换MySQL"]
end
subgraph "Redis 缓存"
K["YudaoCacheProperties<br/>缓存配置项"]
L["YudaoCacheAutoConfiguration<br/>缓存配置/序列化"]
M["TimeoutRedisCacheManager<br/>支持cacheName#ttl"]
N["Gateway RedisConfig<br/>注入TimeoutRedisCacheManager"]
end
A --> C
B --> C
C --> D
C --> E
E --> F
G --> H
G --> I
G --> J
K --> L
L --> M
N --> M

图表来源

章节来源

核心组件​

  • 多数据源配置与监控
    • 通过 spring.datasource.dynamic.druid 全局配置连接池参数；spring.datasource.druid.stat-view-servlet 控制台开启与白名单
    • YudaoDataSourceAutoConfiguration 启用事务管理，并注册 DruidAdRemoveFilter 过滤器，移除监控页面广告脚本
  • 数据源枚举与常量
    • DataSourceEnum 定义 master/slave 标识，配合 @DS 注解进行方法级数据源选择
  • 数据源配置管理
    • DataSourceConfigServiceImpl 从数据库加载数据源配置，若 ID 为特殊主库标识则构建主库配置并前置插入
  • TDengine 集成
    • TDEngineBaseMapper 使用 @DS 指定 TDengine 数据源
    • GoViewTDEngineDataServiceImpl / GoViewMysqlDataServiceImpl 演示两种切换方式：注解与手动切换
  • Redis 缓存
    • YudaoCacheProperties 定义缓存扫描批次、随机过期范围等
    • YudaoCacheAutoConfiguration 统一缓存配置与序列化策略
    • TimeoutRedisCacheManager 支持 cacheName#ttl 的过期时间解析
    • Gateway 层注入 TimeoutRedisCacheManager

章节来源

架构总览​

多数据源架构由“配置层 → 自动装配 → 路由与切换 → 业务访问”构成闭环。MySQL 采用主从分离，TDengine 作为独立时序数据源，Redis 提供统一缓存层。

Mermaid Diagram Code:

graph TB
Client["客户端/网关"] --> Router["数据源路由/切换"]
Router --> MySQL_Master["MySQL 主库"]
Router --> MySQL_Slave["MySQL 从库"]
Router --> TD["TDengine 时序库"]
Router --> Cache["Redis 缓存"]
subgraph "配置层"
Cfg1["datasource.yaml"]
Cfg2["deploy/yml/prod/datasource.yaml"]
end
subgraph "自动装配"
Auto["YudaoDataSourceAutoConfiguration"]
Env["IdTypeEnvironmentPostProcessor"]
end
subgraph "数据源管理"
DSvc["DataSourceConfigServiceImpl"]
DDo["DataSourceConfigDO"]
end
Cfg1 --> Auto
Cfg2 --> Auto
Auto --> Router
Env --> Router
DSvc --> Router
DDo --> DSvc

图表来源

组件详解​

数据源路由与注解使用​

  • 方法级注解
    • 使用 @DS 指定数据源名称，如 master、slave 或 TDengine 名称
    • DataSourceEnum 提供 MASTER/SLAVE 常量，便于统一管理
  • 手动切换
    • 通过 DynamicDataSourceContextHolder.push("数据源名") 切换，结束后需清理
    • 示例：GoViewMysqlDataServiceImpl.getDataBySQL 中手动切换 MySQL；GoViewTDEngineDataServiceImpl 中演示切换 TDengine

Mermaid Diagram Code:

sequenceDiagram
participant C as "调用方"
participant S as "服务实现"
participant H as "DynamicDataSourceContextHolder"
participant R as "数据源路由"
C->>S : "调用方法"
S->>H : "push(目标数据源)"
H->>R : "设置上下文"
R-->>S : "绑定目标数据源"
S-->>C : "返回结果"
S->>H : "clear() 清理"

图表来源

章节来源

MySQL 主从分离配置​

  • 配置要点
    • 在 datasource.yaml 中配置多个数据源（如 system、infra、bpm 等）
    • spring.datasource.dynamic.druid 下设置连接池参数（初始连接数、最小空闲、最大活跃、获取连接超时、空闲检测周期、空闲生存时间等）
    • 开启 Druid 监控控制台与慢 SQL 记录
  • 主从路由
    • 通过 @DS(MASTER/SLAVE) 或手动切换实现读写分离
    • DataSourceConfigServiceImpl 会补充主库配置并前置插入，确保默认数据源可用

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> LoadCfg["加载 datasource.yaml 配置"]
LoadCfg --> InitPool["初始化 Druid 连接池参数"]
InitPool --> RegisterCtl["注册 Druid 监控控制台"]
RegisterCtl --> MasterSlave["主从路由策略"]
MasterSlave --> PushCtx["方法级/手动切换数据源"]
PushCtx --> ExecSQL["执行 SQL"]
ExecSQL --> ClearCtx["清理上下文"]
ClearCtx --> End(["结束"])

图表来源

章节来源

TDengine 时序数据库集成​

  • 数据源配置
    • 在 deploy/yml/prod/datasource.yaml 中新增 TDengine 数据源（Restful JDBC URL、用户名、密码）
  • Mapper 层切换
    • TDEngineBaseMapper 使用 @DS 指定 TDengine 数据源
  • 服务层切换
    • GoViewTDEngineDataServiceImpl 演示手动切换 TDengine 数据源执行 SQL
  • 时序写入注意事项
    • 文档强调“时间基本有序”的重要性，避免乱序写入导致压缩比异常与磁盘占用激增

Mermaid Diagram Code:

sequenceDiagram
participant S as "服务实现"
participant M as "TDEngineBaseMapper"
participant DS as "数据源路由"
participant TD as "TDengine"
S->>DS : "push(TDengine 数据源名)"
DS->>M : "绑定 Mapper 到 TDengine"
M->>TD : "执行 TDengine SQL"
TD-->>M : "返回结果"
M-->>S : "返回结果"
S->>DS : "clear() 清理"

图表来源

章节来源

Redis 缓存配置​

  • 配置项
    • YudaoCacheProperties：redisScanBatchSize、randomKeyExpireMinSecond、randomKeyExpireMaxSecond
  • 缓存配置
    • YudaoCacheAutoConfiguration：统一缓存前缀、JSON 序列化、entryTtl、禁用空值缓存、禁用 key 前缀等
  • 动态过期
    • TimeoutRedisCacheManager：支持 cacheName#ttl（如 user#2h）动态解析过期时间
  • 网关层集成
    • Gateway RedisConfig：注入 TimeoutRedisCacheManager，使用非阻塞 RedisCacheWriter 与 Scan 批策略

Mermaid Diagram Code:

classDiagram
class YudaoCacheProperties {
+Integer redisScanBatchSize
+Long randomKeyExpireMinSecond
+Long randomKeyExpireMaxSecond
}
class YudaoCacheAutoConfiguration {
+RedisCacheConfiguration redisCacheConfiguration()
+RedisCacheManager redisCacheManager(...)
}
class TimeoutRedisCacheManager {
+createRedisCache(name, cacheConfig)
-parseDuration(ttlStr)
}
class RedisConfig {
+redisCacheManager(...)
}
YudaoCacheAutoConfiguration --> TimeoutRedisCacheManager : "创建"
RedisConfig --> TimeoutRedisCacheManager : "注入"
YudaoCacheAutoConfiguration --> YudaoCacheProperties : "读取配置"

图表来源

章节来源

连接池管理策略与参数调优​

  • 关键参数
    • initial-size：初始连接数
    • min-idle：最小空闲连接
    • max-active：最大活跃连接
    • max-wait：获取连接的最大等待时间
    • time-between-eviction-runs-millis：空闲检测间隔
    • min/max-evictable-idle-time-millis：空闲连接存活时间
    • test-while-idle/test-on-borrow/test-on-return：空闲检测与借用/归还检测
  • 调优建议
    • 根据 QPS 与并发请求峰值设置 max-active，结合 max-wait 防止排队过长
    • 合理设置 evict 检测参数，平衡资源回收与性能
    • 开启慢 SQL 记录与合并 SQL，辅助定位热点 SQL

章节来源

事务传播行为处理​

  • 事务管理
    • YudaoDataSourceAutoConfiguration 启用 @EnableTransactionManagement(proxyTargetClass = true)，确保基于 CGLIB 的代理生效
  • 传播行为
    • 在多数据源场景下，跨数据源的事务需谨慎设计；建议：
      • 同一事务内避免跨数据源提交
      • 对只读操作可使用 REQUIRES_NEW 或 SUPPORTS，减少锁竞争
      • 对关键写操作使用 REQUIRED，确保一致性

章节来源

数据源健康检查与故障转移​

  • 健康检查
    • DataSourceConfigServiceImpl.validateConnectionOK 通过 JDBC URL、用户名、密码尝试建立连接，失败抛出异常
  • 故障转移
    • 建议在应用层或网关层实现：
      • 读库失败降级到主库或备用从库
      • 对 TDengine 写入失败时，记录重试队列或延迟补偿
    • 结合监控面板（Druid 控制台）观察连接池状态与慢 SQL

章节来源

性能监控指标​

  • Druid 监控
    • 控制台地址与白名单配置
    • 慢 SQL 记录阈值与合并开关
  • Redis 监控
    • 非阻塞写入与 Scan 批策略，降低批量扫描对性能的影响
    • cacheName#ttl 动态过期，避免缓存雪崩

章节来源

依赖关系分析​

  • 组件耦合
    • 自动装配层与配置层强关联，监控与连接池参数集中配置
    • 数据源管理服务与配置实体双向依赖
    • TDengine 与业务 Mapper 通过注解解耦
    • Redis 缓存配置与网关层注入形成清晰边界
  • 外部依赖
    • Druid 连接池与监控
    • TDengine Restful JDBC
    • Spring Cache 与 Redis

Mermaid Diagram Code:

graph LR
A["YudaoDataSourceAutoConfiguration"] --> B["IdTypeEnvironmentPostProcessor"]
A --> C["DataSourceConfigServiceImpl"]
C --> D["DataSourceConfigDO"]
E["TDEngineBaseMapper"] --> F["GoViewTDEngineDataServiceImpl"]
G["YudaoCacheAutoConfiguration"] --> H["TimeoutRedisCacheManager"]
I["RedisConfig"] --> H

图表来源

章节来源

性能考量​

  • 连接池参数
    • 根据业务峰值合理设置 max-active 与 max-wait，避免连接池耗尽
    • 启用空闲检测与合理的 evict 时间，降低无效连接占用
  • Redis 缓存
    • 使用非阻塞写入与 Scan 批策略，减少批量操作对主线程的影响
    • cacheName#ttl 动态过期，结合随机过期范围，缓解缓存雪崩
  • TDengine 写入
    • 保持时间有序写入，避免乱序导致的压缩比异常与磁盘占用上升

[本节为通用指导，无需列出具体文件来源]

故障排查指南​

  • 数据源连通性
    • 使用 DataSourceConfigServiceImpl.validateConnectionOK 快速验证 URL、账号、密码是否正确
  • Druid 监控
    • 检查控制台白名单与登录凭据，关注慢 SQL 与连接池状态
  • TDengine 写入异常
    • 核查写入顺序与时间戳，避免乱序；参考文档中的乱序写入影响分析
  • 缓存过期异常
    • 确认 cacheName#ttl 语法与单位（d/h/m/s）

章节来源

结论​

yudao-cloud 的多数据源架构通过“集中配置 + 自动装配 + 明确路由 + 业务解耦”实现了 MySQL 主从分离、TDengine 时序库与 Redis 缓存的协同工作。建议在生产中结合监控面板与健康检查，持续优化连接池参数与缓存策略，并严格遵循 TDengine 写入顺序规范，确保系统稳定性与性能。

[本节为总结性内容，无需列出具体文件来源]

附录​

数据源配置文件示例​

  • 本地开发配置
    • 参考路径：datasource.yaml
    • 关键点：spring.datasource.dynamic.druid、spring.datasource.druid.stat-view-servlet、datasource.system.*
  • 生产环境配置
    • 参考路径：deploy/yml/prod/datasource.yaml
    • 关键点：多数据源（system/infra/bpm/report 等）、TDengine 数据源（Restful JDBC）

章节来源

数据源切换注解使用方法​

  • 注解方式
    • 在 Mapper 或 Service 方法上使用 @DS 指定数据源名称（如 master、slave、TDengine 名称）
  • 手动切换方式
    • 使用 DynamicDataSourceContextHolder.push("数据源名") 切换，结束后调用 clear() 清理

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答