growth-manager/ADB_MULTI_DATASOURCE_README.md

Growth Manager 多数据源配置说明

概述

本项目已集成阿里云 AnalyticDB (ADB) 并实现多数据源数据库访问功能。支持在同一个应用中同时访问 MySQL 主数据源和 ADB 数据源。

功能特性

• ✅ 支持多数据源动态切换
• ✅ 基于注解的声明式数据源切换
• ✅ 支持手动编程式数据源切换
• ✅ 线程安全的数据源上下文管理
• ✅ 完整的 Spring 事务支持

配置说明

1. 数据源配置

在 application.properties 和相关环境配置文件中，需要配置两个数据源：

主数据源（MySQL）

# 主数据源配置
spring.datasource.primary.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.primary.url=jdbc:mysql://your-mysql-host:3306/your_database
spring.datasource.primary.username=your_username
spring.datasource.primary.password=your_password
spring.datasource.primary.initialSize=5
spring.datasource.primary.maxActive=20

ADB 数据源

# ADB 数据源配置
spring.datasource.adb.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.adb.url=jdbc:mysql://your-adb-instance-address:3306/your_database?useSSL=true&serverTimezone=Asia/Shanghai
spring.datasource.adb.username=your_adb_username
spring.datasource.adb.password=your_adb_password
spring.datasource.adb.initialSize=5
spring.datasource.adb.maxActive=20

2. ADB 连接信息获取

1. 登录阿里云控制台
2. 进入 AnalyticDB 控制台
3. 选择对应的 ADB 实例
4. 在实例详情中获取：
   • 连接地址（VPC 地址或公网地址）
   • 端口（通常为 3306）
   • 数据库名称
   • 用户名和密码
5. 确保应用服务器 IP 已添加到 ADB 白名单

使用方式

方式一：使用 @DataSource 注解（推荐）

在 Service 方法或类上使用 @DataSource 注解指定数据源：

@Service
public class YourService {
    
    @Autowired
    private YourMapper yourMapper;
    
    // 方法级别注解
    @DataSource("adb")
    public List<YourEntity> queryFromAdb() {
        return yourMapper.selectAll();
    }
    
    // 默认使用主数据源
    public List<YourEntity> queryFromPrimary() {
        return yourMapper.selectAll();
    }
}

方式二：类级别注解

在整个类上使用 @DataSource 注解，该类所有方法都使用指定数据源：

@Service
@DataSource("adb")
public class AdbService {
    // 所有方法都使用 ADB 数据源
    public List<YourEntity> query() {
        return yourMapper.selectAll();
    }
}

方式三：手动切换数据源

在需要动态切换数据源的场景下，可以手动设置：

@Service
public class YourService {
    
    public void queryWithManualSwitch() {
        try {
            // 切换到 ADB 数据源
            DynamicDataSourceContextHolder.setDataSource("adb");
            // 执行数据库操作
            List<YourEntity> result = yourMapper.selectAll();
            return result;
        } finally {
            // 务必清除数据源标识
            DynamicDataSourceContextHolder.clearDataSource();
        }
    }
}

数据源标识

系统预定义了以下数据源标识：

• primary - 主数据源（MySQL），默认数据源
• adb - ADB 数据源

示例代码

项目已包含完整的示例代码，位于：

• AdbExampleMapper - ADB Mapper 示例
• AdbExampleService - ADB Service 使用示例
• AdbExampleController - ADB Controller 测试接口

测试接口

启动应用后，可以通过以下接口测试多数据源功能：

GET /adb/example/query?tableName=test_table&limit=10
GET /adb/example/count?tableName=test_table

注意事项

1. 数据源切换是线程安全的：使用 ThreadLocal 实现，每个线程独立的数据源上下文
2. 务必在 finally 中清除数据源：手动切换数据源时，必须在 finally 块中调用 clearDataSource()
3. 事务管理：多数据源场景下，每个数据源有独立的事务管理器
4. ADB 连接配置：ADB 通常需要 SSL 连接，URL 中建议添加 useSSL=true
5. 驱动兼容性：ADB for MySQL 兼容 MySQL 协议，可以使用标准 MySQL JDBC 驱动
6. 白名单配置：确保应用服务器 IP 已添加到 ADB 实例白名单

核心组件说明

DynamicDataSource

动态数据源路由类，继承自 AbstractRoutingDataSource，根据上下文决定使用哪个数据源。

DynamicDataSourceContextHolder

数据源上下文持有者，使用 ThreadLocal 保存当前线程的数据源标识。

DataSourceAspect

AOP 切面，自动拦截 @DataSource 注解并切换数据源。

DataSourceConfig

数据源配置类，定义主数据源、ADB 数据源和动态数据源 Bean。

扩展更多数据源

如需添加更多数据源，按以下步骤操作：

1. 在配置文件中添加新数据源的配置
2. 在 DataSourceConfig 中创建新的 DataSource Bean
3. 在 DynamicDataSource 的 targetDataSources 中添加新数据源
4. 在 DynamicDataSourceContextHolder 中添加新的数据源常量
5. 使用 @DataSource("新数据源名称") 注解切换

故障排查

连接失败

• 检查 ADB 实例是否正常运行
• 确认 IP 白名单配置正确
• 验证用户名密码是否正确
• 检查网络连通性

数据源切换不生效

• 确认 @DataSource 注解使用正确
• 检查 AOP 是否生效（确认 spring-boot-starter-aop 依赖存在）
• 查看日志确认数据源切换信息

事务问题

• 多数据源场景下，跨数据源操作不支持分布式事务
• 如需分布式事务，考虑使用 Seata 等分布式事务框架

相关文档

• 阿里云 AnalyticDB 官方文档
• Spring Boot 多数据源配置