多租户 SaaS 架构：隔离模型与租户上下文传递

租户数量 × 单租户数据量 → 隔离级别：
  租户少 + 数据量大  → 独立数据库（金融、政企大客户）
  租户中等 + 数据中  → 独立 Schema（中型 SaaS）
  租户海量 + 数据小  → 共享表 + tenant_id（C 端 SaaS）
  混合              → 独立库给 VIP，共享表给长尾

public final class TenantContext {

    private static final ThreadLocal<String> CURRENT = new ThreadLocal<>();

    private TenantContext() {}

    public static void setTenantId(String tenantId) {
        CURRENT.set(tenantId);
    }

    public static String getTenantId() {
        return CURRENT.get();
    }

    public static void clear() {
        CURRENT.remove();
    }
}

@Component
public class TenantFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String tenantId = request.getHeader("X-Tenant-Id");
        if (!StringUtils.hasText(tenantId)) {
            tenantId = resolveTenantFromToken(request);   // 从 JWT 或子域名解析
        }
        TenantContext.setTenantId(tenantId);
        try {
            chain.doFilter(request, response);
        } finally {
            TenantContext.clear();                        // 防止线程池串租户
        }
    }
}

@Component
public class TenantTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        String tenantId = TenantContext.getTenantId();
        return () -> {
            TenantContext.setTenantId(tenantId);
            try {
                runnable.run();
            } finally {
                TenantContext.clear();
            }
        };
    }
}

// 配置异步线程池使用装饰器
@Bean
public ThreadPoolTaskExecutor taskExecutor(TenantTaskDecorator decorator) {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setTaskDecorator(decorator);
    return executor;
}

// 独立库路由：按租户选择数据源
public DataSource resolveDataSource(String tenantId) {
    if (vipTenants.contains(tenantId)) {
        return vipDataSourceMap.get(tenantId);   // VIP 独立库
    }
    return sharedDataSource;                     // 长尾共享库
}

public class TenantIdentifierResolver implements CurrentTenantIdentifierResolver<String> {
    @Override
    public String resolveCurrentTenantIdentifier() {
        return TenantContext.getTenantId();
    }

    @Override
    public boolean validateExistingCurrentSessions() {
        return true;
    }
}

public class SchemaConnectionProvider implements MultiTenantConnectionProvider {
    // 每次 getConnection 时根据租户切换 schema
    @Override
    public Connection getConnection(String tenantIdentifier) throws SQLException {
        Connection conn = sharedDataSource.getConnection();
        try (Statement st = conn.createStatement()) {
            st.execute("USE `schema_" + tenantIdentifier + "`");
        }
        return conn;
    }
}

@Intercepts({
    @Signature(type = StatementHandler.class,
              method = "prepare",
              args = {Connection.class, Integer.class})
})
public class TenantLineInterceptor implements Interceptor {

    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        StatementHandler handler = (StatementHandler) invocation.getTarget();
        BoundSql boundSql = handler.getBoundSql();
        String sql = boundSql.getSql();
        String tenantId = TenantContext.getTenantId();
        if (isTenantTable(boundSql) && !sql.contains("tenant_id")) {
            // 重写 SQL：插入 tenant_id 过滤条件
            String rewritten = rewriteSql(sql, tenantId);
            ReflectUtil.setField(boundSql, "sql", rewritten);
        }
        return invocation.proceed();
    }
}

SELECT  → 追加 WHERE tenant_id = ?
UPDATE  → 追加 WHERE tenant_id = ?
DELETE  → 追加 WHERE tenant_id = ?
INSERT  → 自动填充 tenant_id 列
JOIN 子查询 → 需要表别名识别，复杂查询可能需人工标注

@TableName(value = "tenant_config", ignoreTenant = true)
public class TenantConfig { }

@Component
public class TenantDataSourceRouter {

    private final Map<String, DataSource> tenantDataSources = new ConcurrentHashMap<>();

    public DataSource getDataSource(String tenantId) {
        return tenantDataSources.computeIfAbsent(tenantId, this::createPooledSource);
    }

    private DataSource createPooledSource(String tenantId) {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:mysql://db-shard-" + shardOf(tenantId) + "/schema_" + tenantId);
        config.setMaximumPoolSize(8);
        return new HikariDataSource(config);
    }
}

public String tenantKey(String tenantId, String rawKey) {
    return "t:" + tenantId + ":" + rawKey;
}

// Flyway 对每个租户 schema 执行迁移
public void migrateTenant(String tenantId) {
    Flyway flyway = Flyway.configure()
            .dataSource(dataSource)
            .schemas("schema_" + tenantId)
            .locations("classpath:db/migration")
            .load();
    flyway.migrate();
}

1. 目标 schema 建表并预迁移
2. 业务低峰停止该租户写入
3. 全量拷贝数据并校验行数
4. 切换路由，灰度放量
5. 保留原共享表数据一段时间用于回滚