JetCache 集成 Jedis 完全指南:单机、集群与哨兵模式的配置、原理与最佳实践

原创2026-10-11 22:34:071,450 阅读
文章标签:后端缓存抽象

JetCache 集成 Jedis 完全指南:单机、集群与哨兵模式的配置、原理与最佳实践

导读

本文围绕 JetCache 官方文档 RedisWithJedis.md 展开,系统讲解如何在 JetCache 中以 Jedis 作为 Redis 客户端,完成远程缓存区的接入。文章覆盖 Spring Boot 自动配置与纯手工配置两条路线、JedisPool / JedisCluster / JedisSentinelPool 三种连接形态、RedisCacheBuilder 手写缓存与 unwrap() 底层对象获取等实战要点,并结合 jetcache-redis 模块源码解释其内部实现原理。读完本文,你将能够独立完成 JetCache + Jedis 从依赖引入、配置调优到源码级排障的完整落地。

一、JetCache 对 Redis 客户端的支持背景

JetCache 是一个 Java 缓存框架,其远程缓存(remote cache)层支持多种 Redis 客户端。官方文档明确指出,JetCache 支持 jedis、lettuce 与 redisson 三类客户端:

  • Jedis:JetCache 最早使用的 Redis 客户端(JetCache 2.2 以前即用它访问 Redis),同步阻塞模型,API 简单直接;
  • Lettuce:自 JetCache 2.2 起支持,带来异步访问与 Redis 集群能力;
  • Redisson:自 JetCache 2.7 起支持。

选择 Jedis 时,对应的 Maven Artifact 有两个:

  • jetcache-redis:非 Spring Boot 场景下直接使用;
  • jetcache-starter-redis:Spring Boot 场景下的 Starter 封装。

从 jetcache-redis/pom.xml 可以看到,该模块核心依赖只有两项:jetcache-core(JetCache 核心)与 redis.clients:jedis,也就是说 Jedis 支持层完全构建在 JetCache 核心之上,所有缓存语义(过期、序列化、广播、多级缓存等)均由核心层提供,Jedis 模块只负责将底层命令翻译为 Redis 协议调用。

二、Spring Boot 环境下的 Jedis 支持

2.1 引入依赖

在 Spring Boot 项目中,向 pom.xml 添加:

<dependency>
    <groupId>com.alicp.jetcache</groupId>
    <artifactId>jetcache-starter-redis</artifactId>
    <version>${jetcache.version}</version>
</dependency>

2.2 最小化 application.yml 配置

以下配置省去了 local(本地缓存)相关配置,只保留 remote(远程缓存)部分,足以让 JetCache 以 Jedis 连接一台 Redis 单机:

jetcache:
  areaInCacheName: false
  remote:
    default:
      type: redis
      keyConvertor: fastjson2 #其他可选:fastjson(等同fastjson2)/jackson/jackson3
      broadcastChannel: projectA
      poolConfig:
        minIdle: 5
        maxIdle: 20
        maxTotal: 50
      host: ${redis.host}
      port: ${redis.port}
      #password:***
      #sentinels: 127.0.0.1:26379 , 127.0.0.1:26380, 127.0.0.1:26381
      #masterName: mymaster

各配置项的含义与取值说明如下:

配置项 说明 默认值/可选值
areaInCacheName 是否将 area 名称拼入远程缓存 key 前缀(已标记废弃,为兼容历史版本保留) 2.7.0.RC 起默认 false
remote.default.type 远程缓存区类型,Jedis 场景固定为 redis redis
keyConvertor key 转换器,决定业务 key 如何被序列化 fastjson2(默认,与 fastjson 等同)/ jackson / jackson3
broadcastChannel 广播频道名,用于多实例本地缓存失效通知 任意字符串,如 projectA
poolConfig Jedis 连接池(GenericObjectPoolConfig)参数 见下文说明
host / port 单机模式下的 Redis 地址 必填(单机模式)
password Redis 密码(可选) 无
sentinels / masterName 哨兵模式专用配置(可选) 无

关于 poolConfig,从 RedisAutoConfiguration.java 的 parsePoolConfig() 实现可以看到,该段配置会被直接绑定到 Apache Commons Pool 的 GenericObjectPoolConfig 上:Spring Boot 2.0+ 通过 Binder 反射绑定,Spring Boot 1.x 通过 RelaxedDataBinder 绑定,因此 minIdle、maxIdle、maxTotal 等参数完全遵循 commons-pool2 的语义。其中 maxTotal 是连接池最大连接数,maxIdle 是最大空闲连接数,minIdle 是最小空闲连接数,它们共同决定了高并发下可用 Jedis 连接的上限,应根据业务 QPS 与 Redis 实例负载合理设置。

注意:配置中 host、port 使用了 ${redis.host}、${redis.port} 这样的占位符,实际部署时请替换为真实的 Redis 地址与端口(或使用 Spring 配置占位符注入)。

2.3 以 Spring Bean 方式获取 JedisPool

JetCache 的自动装配会把解析好的连接池对象放入 AutoConfigureBeans 的 customContainer 容器(key 形如 jedisPool.remote.default),随后通过 JedisPoolFactory 暴露为 Spring Bean:

@Bean(name = "defaultPool")
@DependsOn(RedisAutoConfiguration.AUTO_INIT_BEAN_NAME)//jetcache2.2+
//@DependsOn("redisAutoInit")//jetcache2.1
public JedisPoolFactory defaultPool() {
    return new JedisPoolFactory("remote.default", JedisPool.class);
}

说明:

  • 构造参数第一个是配置中的 cache area 路径,即 remote.default;第二个是期望返回的池类型 JedisPool.class;
  • @DependsOn(RedisAutoConfiguration.AUTO_INIT_BEAN_NAME)(即 "redisAutoInit")确保连接池在 JetCache 自动初始化完成之后才被创建,JetCache 2.2+ 使用常量引用,2.1 时代直接写字符串;
  • JedisPoolFactory.java 实现了 FactoryBean<Pool<Jedis>>,内部从 AutoConfigureBeans.getCustomContainer() 中按 "jedisPool." + key 取出真正的 JedisPool 实例,并保证单例。

之后即可在任意 Bean 中注入使用:

@Autowired
private Pool<Jedis> defaultPool;

由于 JedisPool 实现了 redis.clients.jedis.util.Pool<Jedis>,这里推荐以 Pool<Jedis> 接口类型接收,便于切换实现与单元测试。

2.4 通过 Cache.unwrap() 获取底层 JedisPool

如果你不想额外声明 defaultPool Bean,也可以直接从 Cache 接口的 <T> T unwrap(Class<T> clazz) 方法拿到底层连接池。看 RedisCache.unwrap 的实现:

@Override
public <T> T unwrap(Class<T> clazz) {
    if (UnifiedJedis.class.isAssignableFrom(clazz)) {
        return (T) config.getJedis();
    }
    if (Pool.class.isAssignableFrom(clazz)) {
        return (T) config.getJedisPool();
    }
    throw new IllegalArgumentException(clazz.getName());
}

即:

  • 传入 UnifiedJedis(或其子类 JedisCluster、JedisPooled 等)时,返回配置中持有的 UnifiedJedis 客户端;
  • 传入 Pool.class(或其子类 JedisPool、JedisSentinelPool 等)时,返回配置中的连接池;
  • 传入其他类型则抛出 IllegalArgumentException。

典型用法:

Cache<Long, OrderDO> cache = ...;
JedisPool pool = cache.unwrap(JedisPool.class);

测试 RedisCacheTest.java 也验证了 unwrap 的行为:使用 JedisPooled、JedisCluster、Pool 构建缓存后,cache.unwrap(...) 返回的正是同一实例(assertSame)。

三、不使用 Spring Boot 时的纯手工配置

如果不依赖 Spring Boot 自动装配,可以通过 @Configuration 类手工组装 JetCache 的缓存构建器。文档给出的完整示例:

@Configuration
@EnableMethodCache(basePackages = "com.company.mypackage")
@EnableCreateCacheAnnotation
@Import(JetCacheBaseBeans.class) //need since jetcache 2.7+
public class JetCacheConfig {

    @Bean
    public Pool<Jedis> pool(){
        // build jedis pool ...
    }

    //@Bean for jetcache <=2.6
    //public SpringConfigProvider springConfigProvider() {
    //    return new SpringConfigProvider();
    //}

    @Bean
    public GlobalCacheConfig config(Pool<Jedis> pool){
        Map localBuilders = new HashMap();
        EmbeddedCacheBuilder localBuilder = LinkedHashMapCacheBuilder
                .createLinkedHashMapCacheBuilder()
                .keyConvertor(Fastjson2KeyConvertor.INSTANCE);
        localBuilders.put(CacheConsts.DEFAULT_AREA, localBuilder);

        Map remoteBuilders = new HashMap();
        RedisCacheBuilder remoteCacheBuilder = RedisCacheBuilder.createRedisCacheBuilder()
                .keyConvertor(Fastjson2KeyConvertor.INSTANCE)
                .valueEncoder(JavaValueEncoder.INSTANCE)
                .valueDecoder(JavaValueDecoder.INSTANCE)
                .broadcastChannel("projectA")
                .jedisPool(pool);
        remoteBuilders.put(CacheConsts.DEFAULT_AREA, remoteCacheBuilder);

        GlobalCacheConfig globalCacheConfig = new GlobalCacheConfig();
        globalCacheConfig.setLocalCacheBuilders(localBuilders);
        globalCacheConfig.setRemoteCacheBuilders(remoteBuilders);
        globalCacheConfig.setStatIntervalMinutes(15);
        globalCacheConfig.setAreaInCacheName(false);

        return globalCacheConfig;
    }
}

这段配置的几个关键点:

  1. 注解驱动:@EnableMethodCache 开启方法级缓存(@Cached 等注解),@EnableCreateCacheAnnotation 开启 @CreateCache 字段注入;自 JetCache 2.7 起还需 @Import(JetCacheBaseBeans.class) 引入基础 Bean(JetCache 2.6 及以前则需手工声明 SpringConfigProvider Bean);
  2. 两级缓存构建器:localBuilders 注册本地缓存(此处用 LinkedHashMapCacheBuilder,key 转换用 Fastjson2KeyConvertor.INSTANCE),remoteBuilders 注册远程缓存(RedisCacheBuilder);
  3. 远程缓存必须配置序列化器:valueEncoder / valueDecoder 负责缓存值在写入 Redis 前的编码与读取后的解码,示例使用 Java 原生序列化 JavaValueEncoder.INSTANCE / JavaValueDecoder.INSTANCE(位于 JavaValueEncoder.java)。AbstractExternalCache.checkConfig() 会强制校验:缺少 encoder、decoder 或 keyPrefix 都会抛出 CacheConfigException;
  4. area 与统计:CacheConsts.DEFAULT_AREA 即 "default"(见 CacheConsts.java),statIntervalMinutes = 15 表示每 15 分钟输出一次缓存统计,areaInCacheName = false 控制 area 是否进入 key 前缀。

从 GlobalCacheConfig.java 源码可见,areaInCacheName 为兼容历史版本而保留:2.4.3 及以前 area 固定进入 key 前缀,2.4.3~2.7 默认 true,2.7.0.RC 起默认改为 false,未来版本将移除该属性。

四、Builder API:不依赖注解直接构建 RedisCache

如果不使用 @CreateCache / @Cached 注解,可以直接通过 RedisCacheBuilder 手写构建 RedisCache。文档给出的完整示例:

GenericObjectPoolConfig pc = new GenericObjectPoolConfig();
pc.setMinIdle(2);
pc.setMaxIdle(10);
pc.setMaxTotal(10);
JedisPool pool = new JedisPool(pc, "localhost", 6379);

Cache<Long, OrderDO> orderCache = RedisCacheBuilder.createRedisCacheBuilder()
        .keyConvertor(Fastjson2KeyConvertor.INSTANCE)
        .valueEncoder(JavaValueEncoder.INSTANCE)
        .valueDecoder(JavaValueDecoder.INSTANCE)
        .jedisPool(pool)
        .keyPrefix("orderCache")
        .expireAfterWrite(200, TimeUnit.SECONDS)
        .buildCache();

要点说明:

  • keyPrefix 是远程缓存的必填项:通过注解创建的缓存会自动生成 keyPrefix,而手工创建时必须显式指定,否则不同 Cache 实例的 key 会互相冲突。AbstractExternalCache.checkConfig()(见 AbstractExternalCache.java)会强制校验 keyPrefix 非空;
  • key 的组装流程:buildKey() 先经过 keyConvertor 将业务 key 转换,再由 ExternalKeyUtil.buildKeyAfterConvert() 将 keyPrefix 以 UTF-8 字节拼接到 key 前部。String、byte[]、Number、Date、Boolean 均有专门的字节转换规则,其他类型要求实现 Serializable,否则抛出 CacheException;
  • expireAfterWrite(200, TimeUnit.SECONDS) 设置写入后 200 秒过期,内部转换为毫秒存入 CacheConfig(expireAfterWriteInMillis);
  • 连接池参数:GenericObjectPoolConfig 的 minIdle=2、maxIdle=10、maxTotal=10 与 Spring Boot 配置中的 poolConfig 语义完全一致。

值得注意:RedisCacheBuilder(见 RedisCacheBuilder.java)在 RedisCacheConfig 基础上还提供了 jedis(UnifiedJedis)、readFromSlave(boolean)、jedisSlavePools(...)、slaves(...)、slaveReadWeights(...) 等方法,用于从从库读取、多从库加权负载等高级场景(详见第六节)。测试 RedisCacheTest.java 分别以 JedisPool 与 JedisPooled 走通了这一构建链路。

五、Spring Boot 环境下的 Jedis 集群模式

Cluster 模式下,绝大部分配置与单机模式通用,唯一差异是:需要配置 cluster 节点列表(以及可选的 maxAttempt),而单机模式只需填写 host 和 port。

application.yml 示例(省去 local 配置):

jetcache:
  areaInCacheName: false
  remote:
    default:
      type: redis
      keyConvertor: fastjson2 #其他可选:fastjson(等同fastjson2)/jackson/jackson3
      broadcastChannel: projectA
      poolConfig:
        minIdle: 5
        maxIdle: 20
        maxTotal: 50
      # 通用配置
      timeout: 2000
      connectionTimeout: 2000
      soTimeout: 2000
      # 按需选配的通用配置
      #user: ***
      #password:***
      #clientName:
      #ssl: false
      # 集群特定配置
      cluster:
        - 127.0.0.1:6379
        - 127.0.0.1:6378
        - 127.0.0.1:6377
      maxAttempt: 5

配置说明:

  • timeout 为统一超时基准(毫秒),connectionTimeout / soTimeout 若未单独指定则默认取 timeout 值;从 RedisAutoConfiguration.java 可以看到,解析时 connectionTimeout 与 soTimeout 的默认值都是 timeout,而 timeout 的默认值又来自 Protocol.DEFAULT_TIMEOUT(Jedis 协议默认超时);
  • user / password / clientName / ssl 为按需选配的通用连接参数;
  • cluster 列表逐行列出集群节点(ip:port),maxAttempt 为单次命令在集群中的最大重试次数,默认 5。

获取 JedisCluster 作为 Spring Bean 的方式:

@Bean(name = "defaultCluster")
@DependsOn(RedisAutoConfiguration.AUTO_INIT_BEAN_NAME)//jetcache2.2+
//@DependsOn("redisAutoInit")//jetcache2.1
public JedisFactory defaultCluster() {
    return new JedisFactory("remote.default", JedisCluster.class);
}

与 JedisPoolFactory 不同,这里使用的是 JedisFactory(见 JedisFactory.java),它实现 FactoryBean<UnifiedJedis>,从 customContainer 中按 "jedis." + key 取出 JedisCluster。原因在于集群客户端是无池化的 UnifiedJedis 子类。随后即可注入:

@Autowired
private JedisCluster defaultCluster;

集群模式的底层行为

在 RedisCache.java 的构造函数中可以看到,当检测到传入的 UnifiedJedis 是 JedisCluster 时,会通过反射从 UnifiedJedis 中取出 provider(ClusterConnectionProvider),用于批量操作时构建 ClusterPipeline(见 doWithPipeline 方法 L429-L455)。这意味着 GET_ALL、PUT_ALL、REMOVE_ALL 等批量操作在集群模式下会走 ClusterPipeline 向各节点并行发送命令。

六、Spring Boot 环境下的 Jedis 哨兵模式

哨兵(Sentinel)模式下,大部分配置同样与单机模式通用,但需要额外配置哨兵相关属性。

application.yml 示例:

jetcache:
  areaInCacheName: false
  remote:
    default:
      type: redis
      keyConvertor: fastjson2 #其他可选:fastjson(等同fastjson2)/jackson/jackson3
      broadcastChannel: projectA
      poolConfig:
        minIdle: 5
        maxIdle: 20
        maxTotal: 50
      # 通用配置
      timeout: 2000
      connectionTimeout: 2000
      soTimeout: 2000
      # 按需选配的通用配置
      #user: ***
      #password:***
      #clientName:
      #ssl: false
      # 哨兵特定配置
      sentinels: 127.0.0.1:26379 , 127.0.0.1:26380, 127.0.0.1:26381
      masterName: mymaster
      sentinelConnectionTimeout: 2000
      sentinelSoTimeout: 2000
      # 哨兵可选配置
      #sentinelUser: ***
      #sentinelPassword: ***
      #sentinelClientName:

配置说明:

  • sentinels:逗号分隔的哨兵节点列表(ip:port),解析时(见 RedisAutoConfiguration.java)会按逗号切分、去空白后放入 HashSet;
  • masterName:哨兵监控的主节点名称,必填,缺失时直接 Objects.requireNonNull 报错;
  • sentinelConnectionTimeout / sentinelSoTimeout:与哨兵建立连接及读写超时,默认均为 2000 毫秒;
  • sentinelUser / sentinelPassword / sentinelClientName:哨兵自身的认证与客户端名(可选)。

获取 JedisSentinelPool 作为 Spring Bean 的方式(仍使用 JedisPoolFactory,因为 JedisSentinelPool 同样实现了 Pool<Jedis>):

@Bean(name = "defaultSentinelPool")
@DependsOn(RedisAutoConfiguration.AUTO_INIT_BEAN_NAME)//jetcache2.2+
//@DependsOn("redisAutoInit")//jetcache2.1
public JedisSentinelPool defaultSentinelPool() {
    return new JedisPoolFactory("remote.default", JedisSentinelPool.class);
}

注入使用:

@Autowired
private JedisSentinelPool defaultSentinelPool;

测试 RedisStarterTest.java 验证了:通过 @Bean(name = "A1Pool") 使用 JedisPoolFactory("remote.default", JedisSentinelPool.class) 得到的 Bean 确实是 JedisSentinelPool 实例,且与 defaultPool 不是同一实例。单元测试 RedisCacheTest.testSentinel() 则直接以 JedisSentinelPool 走通了完整的缓存读写、过期与刷新测试。

七、源码级原理:RedisCache 如何工作

7.1 连接对象的三选一约束

RedisCache 构造函数(RedisCache.java)对连接配置做了严格校验:

  • jedis 与 jedisPool 至少设置一个,否则报 "no jedis";
  • 两者不能同时设置('jedis' and 'jedisPool' can't set simultaneously);
  • jedisSlavePools 只能与 jedisPool 搭配,slaves 只能与 jedis 搭配;
  • 若开启 readFromSlave 而未配置任何从库,或权重数组长度与从库数量不一致,都会抛错或回退默认权重(默认每个从库权重 100);
  • expireAfterAccess 在 Redis 场景不受支持,直接抛 CacheConfigException。

7.2 读写命令与从库读

writeCommands() 在有 jedis 时直接使用该 UnifiedJedis 客户端,否则从 jedisPool 中 getResource() 借出一个 Jedis 连接;readCommands() 在未开启 readFromSlave 时等价于写命令通道,开启后则按 slaveReadWeights 加权随机挑选从库(randomIndex 实现见 L157-L171)。测试 RedisCacheTest.readFromSlaveTest() 验证了从库读路径确实不会命中主库连接。

7.3 缓存值结构与底层命令

远程缓存写入时,JetCache 会把 CacheValueHolder(内含值、过期时间等元数据)经 valueEncoder 序列化后通过 psetex 写入;读取时用 valueDecoder 反序列化并判断是否过期。核心命令映射包括:

JetCache 操作 底层 Redis 命令 说明
GET GET 单键读取,超期返回 EXPIRED_WITHOUT_MSG
GET_ALL MGET 或 Pipeline GET 批量读取,部分失败返回 PART_SUCCESS
PUT PSETEX 写入并设置毫秒级过期
PUT_ALL Pipeline PSETEX 批量写入,统计失败数返回成功/部分成功/失败
REMOVE DEL 删除,返回 NOT_EXISTS / SUCCESS / FAIL
PUT_IF_ABSENT SET ... NX PX 原子「不存在才写入」,用于分布式锁等场景

doWithPipeline(L429-L455)对批处理做了优化:普通 Jedis 直接用 Pipeline,JedisPooled 会从池中借出连接包一个 Pipeline,JedisCluster 则基于反射拿到的 provider 构造 ClusterPipeline,并在 finally 中统一归还/关闭资源。另外,源码注释(L413-L427)特别提示:对于 mget、del 这类原生批量命令,在非集群客户端上直接调用原生方法通常比 Pipeline 性能更好。

7.4 广播与本地缓存失效

broadcastChannel: projectA 的作用是让各 JetCache 实例的本地缓存保持同步。RedisCacheBuilder.supportBroadcast() 返回 true,并通过 createBroadcastManager() 创建 RedisBroadcastManager:它启动一个守护线程通过 subscribe 订阅频道,收到 CacheMessage 后触发本地缓存失效;publish() 则把失效消息经 valueEncoder 序列化后 publish 到同一频道。开启该功能的前提是所有实例的 broadcastChannel 配置一致,且都使用同一 Redis 实例/集群。

八、故障行为与监控

JetCache 对 Redis 故障采取「缓存不致命」的设计:所有 do_* 方法都捕获异常并返回带 FAIL 结果码的 CacheResult/CacheGetResult,同时通过 logError 记录日志,业务侧仍可继续访问本地缓存或直接回源。测试 RedisCacheFailTest.java 用 Mock 的 Jedis 抛 JedisConnectionException / JedisDataException,断言 GET 返回 CacheResultCode.FAIL 且值为 null,验证了异常不会向上抛出而是被封装为结果码。

此外,AbstractCacheBuilder.buildCache()(见 AbstractCacheBuilder.java)支持 loader(...) 与 refreshPolicy(...) 组合:配置了 loader 后,RedisCache 会被包装为 LoadingCache;若同时配置了刷新策略,则包装为 RefreshCache,从而在 Redis 之上构建出「读回源 + 后台刷新」的能力。

九、常见问题速查

  1. keyPrefix is required 报错:手工 RedisCacheBuilder 构建时遗漏 .keyPrefix(...)。注解场景(@CreateCache/@Cached)会自动生成前缀,手工场景必须显式指定,避免不同 Cache 实例 key 冲突。
  2. no jedis 或 'jedis' and 'jedisPool' can't set simultaneously:RedisCacheConfig 中连接对象缺失或重复配置,检查 builder 链上 jedisPool(...) / jedis(...) 的使用。
  3. expireAfterAccess is not supported:RedisCache 不支持访问后过期,请改用 expireAfterWrite 或 @Cached(expire = ...)。
  4. 集群模式连接失败:确认 cluster 节点可达、maxAttempt 合理;Jedis 集群客户端通过反射获取 provider 失败时会抛 IllegalStateException。
  5. 广播不生效:确认所有实例 broadcastChannel 一致;广播订阅线程是 daemon 线程,断线后会休眠 1 秒自动重连(见 RedisBroadcastManager.java)。

十、相关文档导航

登录后查看全文
jetcache