080-缓存模块-Spring Cache缓存键前缀设计与租户隔离实践

Spring Cache缓存键前缀设计与租户隔离实践

在企业级Spring Boot应用中，Redis作为缓存中间件被广泛使用。当多个业务模块或租户共享同一Redis集群时，缓存键的命名规范与隔离策略就变得至关重要。本文基于一套自定义的缓存工具类（RedisUtils、CacheNamePrefix、TenantContextHolder），深入剖析其设计思路、实现原理及最佳实践，帮助读者构建灵活、可扩展的缓存键前缀管理方案。

一、背景与需求

在使用@Cacheable等Spring Cache注解时，默认的缓存键生成逻辑往往只包含缓存名称和键值，缺乏对环境的区分。实际生产环境中，我们通常面临以下挑战：

多租户隔离：SaaS系统中，不同租户的数据必须物理或逻辑隔离，缓存键需自动携带租户标识。
环境区分：开发、测试、预发布环境共用Redis时，需通过前缀避免键冲突。
动态调整：缓存前缀可能需要根据部署环境、版本号或业务上下文动态拼接，而不是写死在配置中。
可测试性：单元测试中需灵活控制前缀生成逻辑，便于断言。

上述需求催生了CacheNamePrefix接口及其工具类的设计，它采用函数式组合 与装饰器模式，使得前缀构建过程既类型安全又高度可定制。

二、CacheNamePrefix：函数式接口的优雅设计

2.1 接口定义

java 复制代码

public interface CacheNamePrefix {
    String SEPARATOR = SymbolConsts.COLON;      // ":"
    String DOUBLE_SEPARATOR = "::";             // "::"
    String compute(String cacheName);
    // ... 静态工厂和默认方法
}

CacheNamePrefix是一个@FunctionalInterface（虽未显式标注，但符合单抽象方法条件），核心方法compute(String cacheName)接收原始缓存名称，返回经过变换后的完整前缀字符串。这种设计允许我们将前缀生成逻辑抽象为函数的组合，而非传统的继承或硬编码。

2.2 静态工厂方法

接口提供了三种基础工厂方法：

simple()：恒等变换，直接返回原缓存名，适用于无需任何前缀的场景。
prefix(String prefix) ：在缓存名前添加固定字符串，如"v1:"。
tenant() ：从TenantContextHolder获取当前租户代码（大写），并拼接分隔符。例如租户T001，缓存名users，生成T001:users。

2.3 组合能力：装饰器模式

通过默认方法，接口支持链式组合，形成强大的前缀流水线：

suffix(String suffix) ：在当前变换结果之前插入一段后缀（注意命名易混淆，实际效果为"在原有基础上再套一层前缀"）。其实现为prefix(suffix).andThen(this)，即先应用suffix作为前缀，再应用当前变换。例如：
java 复制代码
```
CacheNamePrefix.simple().suffix("env:").suffix("ver:")
// 对 "users" 计算 => "env:ver:users"
```
compose(CacheNamePrefix before) ：将另一个CacheNamePrefix先应用于缓存名，再将结果传入当前函数。数学上等价于f.compose(g) => f(g(x))。
andThen(CacheNamePrefix after) ：先将当前函数应用于缓存名，再将结果传给after。数学上等价于f.andThen(g) => g(f(x))。
end() ：在最终结果末尾追加"::"，这是Spring Data Redis用于区分缓存名称与键值的惯用分隔符（如myCache::myKey）。使用end()后，后续仍可继续组合其他前缀，但通常置于链式末尾。

这些方法组合起来，可以构造出任意复杂的前缀生成策略，而无需创建大量子类。

2.4 实际测试用例分析

java 复制代码

@Test
void end() {
    CacheNamePrefix cacheNamePrefix = 
        CacheNamePrefix.tenant().suffix("prefix1:").suffix("prefix2:").end();
    assertThat(cacheNamePrefix.compute("cacheName1"))
        .isEqualTo("DEFAULT:prefix1:prefix2:cacheName1::");
}

tenant()从上下文获取租户，若无则返回DEFAULT。
.suffix("prefix1:")相当于在现有变换前再套一层，顺序依次为prefix1:，再.suffix("prefix2:")，最终顺序为 租户:prefix1:prefix2:原始名。
.end()追加::，符合Spring Cache默认前缀格式。

这展示了函数复合的顺序性 ：后调用的suffix实际作用于更外层（靠近原始缓存名），因为prefix(suffix).andThen(this)让当前变换（原函数）后执行，即新加的suffix先于原函数执行。读者可结合andThen的定义理解。

三、TenantContextHolder：线程级租户传递

3.1 TransmittableThreadLocal 的应用

java 复制代码

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

使用阿里开源的TransmittableThreadLocal（TTL）替代原生ThreadLocal，主要解决线程池场景下上下文丢失的问题。在微服务或异步处理中，租户信息需跨线程传递，TTL能在任务提交时捕获父线程的值，并在子线程中恢复，是分布式链路追踪的常见组件。

3.2 默认值与大小写转换

get()方法在空值时返回DefaultConsts.DEFAULT_TENTANT_CODE（通常为"DEFAULT"），并强制转为大写。这保证了即使未显式设置租户，也能生成一个统一的默认前缀，避免空指针且满足键名规范。

3.3 使用建议

在Web拦截器或网关层，通过解析请求头或JWT设置租户：

java 复制代码

TenantContextHolder.set(tenantCode);
try {
    // 业务处理
} finally {
    TenantContextHolder.clear(); // 防止内存泄漏
}

四、RedisUtils：配置填充与缓存管理集成

4.1 核心方法 fillConfiguration

java 复制代码

public static RedisCacheConfiguration fillConfiguration(
    RedisCacheConfiguration configuration,
    NamedCacheOptions prop,
    NamedCacheProperties properties)

该方法负责将业务配置（NamedCacheOptions）与全局配置（NamedCacheProperties）合并，并生成最终RedisCacheConfiguration。关键步骤：

应用默认值 ：prop.applyDefaults(properties.getDefaults())将全局默认配置（如过期时间、是否允许空值等）应用到特定缓存选项，实现"全局默认+局部覆盖"策略。
TTL设置 ：如果prop指定了timeToLive，则覆盖默认值。
空值缓存开关 ：enableStatistics名称虽含"统计"，实际此处用作是否缓存null值的开关。当设为false时，调用disableCachingNullValues()，避免缓存穿透带来的内存浪费。
前缀构造：这是核心亮点。
java 复制代码
```
CacheNamePrefix cacheNamePrefix =
    CacheNamePrefix.tenant().suffix(properties.getCacheNamePrefix());
configuration = configuration.computePrefixWith(convert(cacheNamePrefix));
```
- 首先组合租户前缀和全局配置的cacheNamePrefix（例如环境标识），形成链：tenant() -> suffix(全局前缀)。
- convert方法将CacheNamePrefix适配为Spring Data Redis的CacheKeyPrefix函数式接口：
  java 复制代码
```
static CacheKeyPrefix convert(CacheNamePrefix cacheNamePrefix) {
    return name -> CacheKeyPrefix.simple().compute(cacheNamePrefix.compute(name));
}
```
  这里先调用CacheKeyPrefix.simple()（Spring内置的简单前缀，仅返回缓存名），然后套上我们的自定义前缀逻辑，相当于双重前缀。

4.2 设计思想

关注点分离 ：CacheNamePrefix专注字符串转换，RedisUtils专注配置组装，职责清晰。
扩展性 ：未来如需添加其他前缀维度（如版本、区域），只需组合新的CacheNamePrefix实例，无需修改核心代码。
与Spring生态无缝集成 ：通过computePrefixWith注入自定义CacheKeyPrefix，完全遵循Spring Cache SPI。

五、整体架构与数据流

应用启动 时，NamedCacheProperties加载全局配置（如cacheNamePrefix: "prod:"）。
每个缓存区域（如users、orders）可定义独立的NamedCacheOptions，覆盖TTL等。
当执行缓存操作时，RedisCacheManager使用RedisUtils.fillConfiguration生成的RedisCacheConfiguration创建RedisCache实例。
写入/读取键时，computePrefixWith生成最终前缀，例如租户T001，全局前缀prod:，缓存名users，最终缓存键为T001:prod:users::key123。
这样，不同租户、不同环境的缓存键自动隔离，避免冲突。

六、测试驱动与可维护性

CacheNamePrefixTest给出了组合场景的测试，不仅验证正确性，也充当了文档作用。在实际项目中，建议为fillConfiguration补充单元测试，模拟不同租户上下文，验证配置覆盖逻辑。

七、最佳实践与注意事项

前缀顺序设计 ：建议将变化频率低的维度放在外层（靠近原始名），高频维度（如租户）放在内层，但实际顺序需根据业务规划。例如本例中tenant在全局前缀之前，便于按租户扫描或删除缓存。
分隔符统一 ：使用冒号:作为各部分分隔符，双冒号::作为缓存名与键的分隔，与Spring Data Redis默认行为保持一致，便于运维工具解析。
性能考量 ：compute方法在每次缓存访问时调用，应确保内部操作轻量（如字符串拼接），避免复杂IO或远程调用。本实现中均基于内存操作，性能影响微乎其微。
线程安全 ：CacheNamePrefix接口实现均无状态，线程安全。TenantContextHolder使用TTL，确保异步场景的上下文传递。
空值处理 ：enableStatistics命名虽不够直观，但实际控制空值缓存，建议后续版本重命名以避免误导。
扩展方向：可增加对SpEL表达式的支持，使前缀能动态引用方法参数或当前用户信息，进一步提升灵活性。

八、总结

本文通过分析RedisUtils、CacheNamePrefix和TenantContextHolder三个核心组件，展示了一套基于函数式组合的缓存键前缀管理方案。其精妙之处在于：

将前缀生成抽象为函数的链式组合，取代繁重的继承体系；
利用ThreadLocal（TTL） 无侵入地传递租户上下文；
与Spring Cache配置无缝对接，实现"全局默认+局部覆盖"的配置模型。

这种设计不仅满足了多租户、多环境的隔离需求，更提供了良好的扩展性和可测试性，是构建企业级缓存基础设施的优秀范例。读者可借鉴此思路，在自己的项目中构建类似的前缀管理工具，让缓存键的生成变得优雅而可控。