代码拉取完成，页面将自动刷新
一个支持SaaS多租户动态添加和切换数据源的快速启动工具。
完整解决方案现已重磅发布！请前往 Airboot-SaaS-DataSource
简单示例项目请前往 saas-datasource-samples
目前1.x版本主要支持Druid，后续会考虑增加对HikariCp、BeeCp及Dbcp2的支持。
saas-datasource-spring-boot-starter（以下简称“本工具”）适用于SaaS场景中 共享数据源，独立Schema 或 独立数据源 的多租户架构，支持多种方式自动或手动切换租户数据源，并可在运行时动态添加租户数据源，使用轻量，简单方便。
注意，本工具并不适用于 共享Schema，共享数据表 的SaaS多租户架构（即租户仅在表中用tenantId来区分），如果想采用此架构，可参考或直接使用 Airboot-SaaS ，是基于Mybatis-Plus的一套完整解决方案。
数据源是一个较抽象的概念，比如一个共享VIP的数据库集群算一个数据源，一个独立的数据库服务器，一个服务器上的Mysql或Oracle服务实例，甚至一个数据服务中的独立Schema，都可以称为一个数据源，这取决于架构设计时所考虑的切分粒度，具体业务具体分析。
现在为方便起见，我们假设一个数据源指的是一台数据服务器，那么上述提到的三种SaaS架构的主要区别如下：
| 独立数据源 | 共享数据源，独立Schema | 共享Schema，共享数据表 | |
|---|---|---|---|
| 特性 | 每个租户都有自己独立的数据服务器，相互之间完全隔离 | 每一台数据服务器上都存在数量不定的多个租户，每个租户拥有自己的Schema，Schema之间完全隔离 | 所有租户都在一台数据服务器上的一个Schema中，仅通过数据表内的tenantId来做租户区分 |
| 优点 | 拥有最高的隔离性、安全性和性能 | 具备一定的隔离性和安全性，成本适中，性能较高，扩展方便 | 成本最低，设计简单，全局数据统计方便 |
| 缺点 | 成本太高，全局数据统计不方便 | 一个数据服务器有问题会影响到多个租户，全局数据统计不方便 | 隔离性和安全性最低，编码时必须严格注意tenantId，如有误操作很容易影响大片租户，随着租户数据量增加性能容易到达瓶颈 |
| 适用场景 | 混合云，对隔离性和安全性要求较高的租户，土豪 | 比较适中的方案，适合大部分SaaS场景，但在全局数据统计上要自己进行架构设计 | 适合低成本的小型项目，对隔离性和安全性要求不高，在可预见的未来数据量不大 |
本工具兼容 共享数据源，独立Schema 和 独立数据源 两种架构（本质上取决于你提供什么样的jdbcUrl），使用本工具后，通常情况下开发者无需关心租户切换或tenantId等问题，在开发体验上与单租户（即非SaaS）开发无异。
请根据自身产品的业务特点及架构选型决定是否使用本工具。
本工具基于 dynamic-datasource-spring-boot-starter 和 Druid数据库连接池开发，可整合 Mybatis-Plus 或 Mybatis ，由于这些开源项目也在不断更新中，尤其像dynamic-datasource-spring-boot-starter这几年经历过数次大小重构，因此本工具需要针对其不同版本做出适配。
为了兼容可能存在的老旧项目，本工具在起始版本会对应dynamic-datasource-spring-boot-starter较早期的版本，而后续更新中会逐步对应不同的版本区间，使用本工具的开发者请务必确认好当前项目中这几个jar包所对应的版本区间，具体对应关系如下：
| saas-datasource-spring-boot-starter | dynamic-datasource-spring-boot-starter | mybatis-plus-boot-starter | mybatis-spring-boot-starter |
|---|---|---|---|
| 1.5.0 & 1.4.0 | version in (3.4.1, 3.5.1 (latest)] | version <= 3.5.1 (latest) | version <= 2.2.2 (latest) |
| 1.3.0 | version in (3.1.1, 3.4.1] | version <= 3.5.1 (latest) | version <= 2.2.2 (latest) |
| 1.2.0 | version in (2.4.2, 3.1.1] | version <= 3.5.1 (latest) | version <= 2.2.2 (latest) |
| 1.1.0 & 1.0.0 | version <= 2.4.2 | 根据 @SaaS注解的位置分为两种情况：1. 如果注解在Mapper上，则 version <= 3.0.7.1，若高于此版本dynamic-datasource会报错； 2. 如果注解不在Mapper上，则可使用目前最新版本 version <= 3.5.1 (latest)。 按最佳实践，推荐上述第二种情况，注解不要放在Mapper上。 |
version <= 2.2.2 (latest) |
<dependency>
<groupId>com.air-software</groupId>
<artifactId>saas-datasource-spring-boot-starter</artifactId>
<version>1.5.0</version>
</dependency>
通常情况下，我们会将租户数据源配置保存在一个公共库里，不必担心在切换数据源时会频繁查库，因为本工具会将已获取过的数据源缓存起来，如果切换时缓存中没有对应数据源，才会查库（具体看你的SaaSDataSourceProvider怎么实现）。
当然，有时我们也需要对数据源缓存池进行管理，关于这方面参见 管理数据源缓存池。
因此，项目启动时的默认数据源推荐配置为公共库，此处的配置风格参照dynamic-datasource-spring-boot-starter，举例如下：
spring:
datasource:
dynamic:
primary: common
datasource:
common:
url: jdbc:mysql://localhost/saas_common?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8&autoReconnect=true&autoReconnectForPools=true&allowMultiQueries=true&allowPublicKeyRetrieval=true
username: root
password: 123456
druid:
initial-size: 5
min-idle: 10
max-active: 20
max-wait: 60000
time-between-eviction-runs-millis: 60000
min-evictable-idle-time-millis: 300000
max-evictable-idle-time-millis: 900000
validation-query: select 1 from dual
test-while-idle: true
test-on-borrow: false
test-on-return: false
注意，如果你使用的dynamic-datasource-spring-boot-starter版本在3.3.3以下，则仍需要手动排除DruidDataSourceAutoConfigure。你可以在@SpringBootApplication注解中exclude，或者在配置文件中添加：
spring:
autoconfigure:
exclude: com.alibaba.druid.spring.boot.autoconfigure.DruidDataSourceAutoConfigure
开发者需自行实现SaaS多租户数据源提供者，一个简单的实现示例如下：
import com.airsoftware.saas.datasource.core.SaaSDataSourceCreator;
import com.airsoftware.saas.datasource.provider.SaaSDataSourceProvider;
import com.airsoftware.saas.datasource.sample.entity.DataSourceConfig;
import com.airsoftware.saas.datasource.sample.mapper.DataSourceConfigMapper;
import com.baomidou.dynamic.datasource.spring.boot.autoconfigure.DataSourceProperty;
import org.springframework.stereotype.Component;
import javax.annotation.Resource;
import javax.sql.DataSource;
@Component
public class MySaaSDataSourceProvider implements SaaSDataSourceProvider {
@Resource
private DataSourceConfigMapper dataSourceConfigMapper;
@Resource
private SaaSDataSourceCreator saasDataSourceCreator;
public static String JDBC_URL_PREFIX = "jdbc:mysql://";
public static String JDBC_URL_SUFFIX = "?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8&autoReconnect=true&autoReconnectForPools=true&allowMultiQueries=true&allowPublicKeyRetrieval=true";
@Override
public DataSource createDataSource(String dsKey) {
DataSourceConfig dataSourceConfig = dataSourceConfigMapper.selectById(dsKey);
String jdbcUrl = JDBC_URL_PREFIX + dataSourceConfig.getHost() + "/" + dataSourceConfig.getSchemaName() + JDBC_URL_SUFFIX;
DataSourceProperty dataSourceProperty = new DataSourceProperty();
dataSourceProperty.setUrl(jdbcUrl);
dataSourceProperty.setUsername(dataSourceConfig.getUsername());
dataSourceProperty.setPassword(dataSourceConfig.getPassword());
dataSourceProperty.setPoolName(dsKey);
return saasDataSourceCreator.createDruidDataSource(dataSourceProperty);
}
}
注意，为保证数据源提供者查询数据源时能够正确访问到公共库，而不受其他已切换数据源的影响，建议为查询数据源的Mapper添加dynamic-datasource-spring-boot-starter自带的@DS注解，强制使用公共库：
@DS("common")
public interface DataSourceConfigMapper
另外如果你使用的是1.1.0及以上版本，也可以直接使用SaaSDataSource.switchTo来强制切换至公共库，记得切换后立即调用clearCurrent清理一下：
SaaSDataSource.switchTo("common");
DataSourceConfig dataSourceConfig = dataSourceConfigMapper.selectById(dsKey);
SaaSDataSource.clearCurrent();
不建议在1.0.0采用此方法，因为1.0.0版本的SaaSDataSource.switchTo方法并未被优化。
在SpringBoot主启动类上添加@EnableSaaSDataSource注解，表示启用SaaS数据源功能。
@SpringBootApplication
@EnableSaaSDataSource
public class SaaSApplication {
public static void main(String[] args) {
SpringApplication.run(SaaSApplication.class, args);
}
}
如果你想使用Request Session或Header的方式切换数据源，则在需要切换数据源的类或方法上标记@SaaS注解，使用此注解时必须显式指定租户标识字段名称。举例如下：
@SaaS("tenantId")
@RestController
@RequestMapping("/user")
public class UserController {
......
......
}
比如我在使用注解时设置为@SaaS("tenantId")，那么我在Request Session或Header中就需要用tenantId字段来设置租户标识，而这个租户标识在首次切换至此租户时，会传递至我自己实现的SaaSDataSourceProvider中，以此来获取租户对应数据源。
本工具共提供三种方式来切换数据源，按优先级从高到底排列如下：
你可以在任意地方多次调用SaaSDataSource.switchTo来手动切换数据源，他会影响到你下一次即将执行的数据库操作，常用于拦截器、定时任务、异步操作、循环刷库，跨库统计、消息消费等场景。
SaaSDataSource内部使用了栈来存储多次切换的数据源，switchTo方法入栈，current方法获取当前栈顶数据，clearCurrent方法会让当前栈顶数据出栈，clearAll方法会清理整个栈。
建议在每次手动切换完成，且对应数据源的业务处理完成后，调用clearCurrent来清理刚刚手动切换的数据源，以避免对后续流程产生影响。或者也可以在整个业务流程的最后调用clearAll。
注意：在1.1.0及以上版本，如果你只使用SaaSDataSource来手动切换数据库，则不需要再标记@SaaS注解，即使标记了注解，注解中的值也会被忽略。
而在1.0.0版本，则仍需要在调用SaaSDataSource.switchTo之后的流程中标记@SaaS注解，即必须在注解生效前执行SaaSDataSource.switchTo。
每个数据源都只会在第一次切换时调用到你自己实现的SaaSDataSourceProvider，之后就会被缓存。
假设你的数据源配置存在数据库中，你修改了库中的某个数据源配置，但是这个配置已经被缓存了。此时如果你想在不重新启动服务的情况下让此数据源使用到最新的配置，可以使用SaaSDataSourcePool.remove(dsKey)方法来移除数据源缓存池中的指定数据源。那么下一次再切换至此数据源时就会再次调用你自己实现的SaaSDataSourceProvider，获取到最新的配置。
SaaSDataSourcePool就是用来管理数据源缓存池的工具，包含了多种操作方法，注意它仅在1.5.0以上版本可用。
本节所列注意事项非常重要，请开发者务必仔细阅读：
@SaaS的标记位置，至少应在最外层事务或更上一层的调用方标记此注解，即保证注解在事务开启前发挥作用，以切换到正确的数据源。其次不要在事务内调用SaaSDataSource.switchTo，而应在事务开启前调用。如果没有在事务开启前通过注解或手动切换至正确的数据源，则事务会在默认数据源上执行。
SaaSDataSource.switchTo来手动切换至想要操作的数据源。spring-boot在2.6.x版本后默认禁止了循环依赖，这可能会导致使用本工具时启动报错，我在1.4.0版本中修复了此问题。如果你使用的是1.3.0及以下版本，可在配置文件中显式指定：spring:
main:
allow-circular-references: true
或在实现数据源提供者SaaSDataSourceProvider时，将SaaSDataSourceCreator标记为懒加载：
@Lazy
@Resource
private SaaSDataSourceCreator saasDataSourceCreator;
基于上述注意事项，结合现代Web开发的技术倾向，可以得出以下几条最佳实践：
@SaaS标记在Controller层，一般这就是事务的顶层了。大部分项目中都会有一个BaseController作为所有Controller的父类，将@SaaS注解标记在父类上，对所有Controller都会起作用。dsKey放入Token中，或为安全起见将dsKey放入Redis，而Redis Key放入Token中。随后我们在拦截器中解析Token之后，使用获得的dsKey调用SaaSDataSource.switchTo来切换数据源，这样在编写业务代码时就无需关心租户切换问题了，最后不要忘了在拦截器的afterCompletion中调用SaaSDataSource.clearAll方法（1.0.0版本是SaaSDataSource.clear）。SaaSDataSourcePool，用于管理已被缓存至池中的数据源，可能的使用场景参见 管理数据源缓存池；druid-spring-boot-starter至1.2.9版本（目前最新版）；spring-boot-starter-web至2.6.7版本（目前最新版），但pom scope为provided，即最终以你项目中实际使用的spring-boot版本为准。dynamic-datasource-spring-boot-starter至3.5.1版本（目前最新版）；druid-spring-boot-starter至1.2.8版本；spring-boot-starter-web至2.6.5版本，但pom scope为provided，即最终以你项目中实际使用的spring-boot版本为准；@SaaS注解的默认值，现在使用此注解时必须显式指定租户标识字段名称。dynamic-datasource-spring-boot-starter至3.4.1版本；spring-boot-starter-web至2.1.1.RELEASE版本，但pom scope为provided，即最终以你项目中实际使用的spring-boot版本为准；SaaSDataSourceClassResolver来解析注解标记的类，原因是dynamic-datasource-spring-boot-starter在3.1.1版本后删除了本工具之前使用的对应API，所以只能本工具自己再实现一个；SPI，开发者可以省略driverClassName配置了。dynamic-datasource-spring-boot-starter至3.1.1版本；SaaSDataSource，底层改为使用ArrayDeque来实现栈；SaaSDataSource.removeAll方法，可强制移除所有数据源，包含DynamicDataSource上下文中的数据源。如果你不确定业务流程完成后是否还有残留数据，可在最后（比如拦截器的afterCompletion中）调用此方法来确保移除。SaaSDataSource，现在可以随时强制切换数据源，不再依赖@SaaS注解；SaaSDataSource手动切换数据源，但需要在切换后的调用流程中存在@SaaS注解标记来触发。此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。