JetCache 基于 Jedis 访问 Redis 完整实战指南:单机、集群与哨兵模式配置与源码解析

原创2026-10-11 22:06:291,851 阅读
文章标签:后端缓存抽象

JetCache 基于 Jedis 访问 Redis 完整实战指南:单机、集群与哨兵模式配置与源码解析

本文以 JetCache 官方文档 docs/CN/RedisWithJedis.md 为核心骨架,系统讲解 JetCache 通过 Jedis 客户端访问 Redis 的完整方案:涵盖 Spring Boot 环境下的单机、Cluster 集群、Sentinel 哨兵三种部署模式的 yml 配置、编程式获取 JedisPool/JedisCluster/JedisSentinelPool 的 Bean 方式、非 Spring Boot 场景的 JavaConfig 配置,以及 Builder API 手工创建 RedisCache 的实战代码。读完本文,你将能够在一线项目中独立完成 JetCache + Jedis 的接入、调优与底层原理排查。

一、背景:JetCache 的 Redis 客户端选型

Redis 有多种 Java 版本的客户端,JetCache 官方文档明确给出了选型脉络:

  • JetCache 2.2 以前,仅使用 Jedis 客户端访问 Redis;
  • 从 JetCache 2.2 版本开始,增加了对 Lettuce 客户端的支持,Lettuce 支持带来了异步操作和 Redis 集群支持;
  • 从 JetCache 2.7 版本开始,增加了对 Redisson 客户端的支持。

因此,如果项目选用 Jedis 访问 Redis,对应的 Maven Artifact 是 jetcache-redis 和 jetcache-starter-redis(Spring Boot 场景)。从仓库 POM 可以看到二者的依赖构成:

需要说明的是:本文描述的所有配置均以当前仓库(版本 2.8.0.RC)的源码与文档为准,Lettuce、Redisson 的接入方式请参见 docs/CN/RedisWithLettuce.md 与 docs/CN/RedisWithRedisson.md。

二、Spring Boot 环境下使用 Jedis(单机模式)

2.1 引入依赖

在 Spring Boot 项目的 pom.xml 中加入:

<dependency>
    <groupId>com.alicp.jetcache</groupId>
    <artifactId>jetcache-starter-redis</artifactId>
    <version>2.8.0.RC</version>
</dependency>

2.2 application.yml 配置

单机模式下(此处省去了 local 相关的配置),application.yml 内容如下:

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

2.3 配置参数源码级解读

这些 yml 参数最终由 RedisAutoConfiguration.java 中的 parsePool(ConfigTree ct) 方法逐项解析并构造对应的 Jedis 客户端实例,各参数的底层行为如下:

配置项 默认值 底层解析行为
host / port 无 单机模式必填,host 缺失抛 NullPointerException,port 为 0 抛 IllegalStateException
timeout Jedis Protocol.DEFAULT_TIMEOUT 通用超时,作为 connectionTimeout 与 soTimeout 的兜底默认值
connectionTimeout 取 timeout 建连超时
soTimeout 取 timeout 读写超时
user / password null 认证信息(Redis 6+ ACL 用户)
database Jedis Protocol.DEFAULT_DATABASE(0) 选库
clientName null 连接客户端名
ssl false 是否启用 TLS 加密连接
poolConfig.minIdle/maxIdle/maxTotal 绑定到 GenericObjectPoolConfig 见下方说明
sentinels / masterName null 非 null 时走哨兵分支构造 JedisSentinelPool
cluster / maxAttempt maxAttempt 默认 5 非空时走集群分支构造 JedisCluster

关于 poolConfig:parsePoolConfig(ConfigTree ct) 会通过反射调用 Spring Boot 2.0+ 的 Binder(或 Spring Boot 1.x 的 RelaxedDataBinder)把 poolConfig 子树绑定到 commons-pool2 的 GenericObjectPoolConfig 上,从而获得连接池化的 JedisPool。这也解释了为什么 minIdle、maxIdle、maxTotal 是标准的 Apache Commons Pool 语义。

2.4 直接操作 JedisPool

如果业务代码需要直接操作 JedisPool,可以通过 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);
}

然后即可直接注入使用:

@Autowired
private Pool<Jedis> defaultPool;

注意这里的 @DependsOn(RedisAutoConfiguration.AUTO_INIT_BEAN_NAME):自动装配会先完成 redisAutoInit(RedisAutoInit 是 ExternalCacheAutoInit 的子类),把解析好的 Jedis 连接对象放入 AutoConfigureBeans 的 customContainer(以 "jedisPool.remote.default" 为 key),随后 JedisPoolFactory.java 的 getObject() 才可能取到目标对象。JedisPoolFactory 是一个 FactoryBean<Pool<Jedis>>,单例返回,getObjectType() 返回传入的 poolClass。

2.5 通过 Cache.unwrap 获取 JedisPool

除了手动声明 Bean,还可以直接通过 Cache 接口上的 <T> T unwrap(Class<T> clazz) 方法获取底层 Jedis 连接对象。其实现位于 RedisCache.java:

@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());
}

即:向 unwrap 传入 UnifiedJedis.class 或 Pool.class(以及 JedisPool、JedisCluster 等子类型)即可拿到底层对象。测试 RedisCacheTest.java 中也验证了 JedisPooled、JedisCluster、Pool 三种 unwrap 路径。

三、不使用 Spring Boot:JavaConfig 手动装配

在不使用 Spring Boot 的场景下,需要手动编写 @Configuration 类,把本地缓存、远程缓存和 GlobalCacheConfig 全部装配好:

@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;
    }
}

要点说明:

  • 本地缓存使用 LinkedHashMapCacheBuilder,并显式指定 Fastjson2KeyConvertor.INSTANCE 作为 key 转换器(该单例定义在 Fastjson2KeyConvertor.java 中,对 String 原样返回、其他类型走 fastjson2 序列化);
  • 远程缓存使用 RedisCacheBuilder,通过 .jedisPool(pool) 注入连接池,valueEncoder/valueDecoder 采用 JDK Java 序列化;
  • broadcastChannel("projectA") 开启跨 JVM 的本地缓存失效广播(详见第六节);
  • CacheConsts.DEFAULT_AREA 即默认 area "default",与注解上不指定 area 时的默认值一致。

四、Builder API:不依赖注解手工创建 RedisCache

如果不通过 @CreateCache 和 @Cached 注解,可以通过下面的方式创建 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,但手工创建的缓存没有这个自动机制。从源码看,key 的最终形态由 ExternalKeyUtil.java 的 buildKeyAfterConvert 决定:把 keyPrefix 的字节与 keyConvertor 转换后的 key 字节拼接成一个 byte[],作为真正的 Redis key。如果两个不同语义的 Cache 实例共用同一个前缀,就会发生 key 冲突,所以务必为每个远程 Cache 指定唯一的 keyPrefix。

同样的构建流程也出现在官方示例 samples/simple-samples/src/main/java/JedisExample.java 中——它先用 GenericObjectPoolConfig 配置 JedisPool,再通过 RedisCacheBuilder 构建缓存并执行 put/get,是本文 §四 代码可直接运行的完整形态。

RedisCacheBuilder 的可用链式方法(见 RedisCacheBuilder.java)还包括:

  • jedisPool(Pool<Jedis>):指定单机连接池;
  • jedis(UnifiedJedis):直接指定 JedisCluster、JedisPooled 等 UnifiedJedis 实例;
  • readFromSlave(boolean):开启从库读;
  • jedisSlavePools(Pool<Jedis>...) / slaves(UnifiedJedis...):指定多个从库连接对象;
  • slaveReadWeights(int...):从库读权重,默认每个从库权重 100(见 RedisCache.java 的 initDefaultWeights)。

此外 RedisCacheBuilder.supportBroadcast() 返回 true,表示它支持广播机制,createBroadcastManager 会创建 RedisBroadcastManager。

五、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

在 RedisAutoConfiguration.parsePool 的集群分支中,cluster 下的多个 host:port 会被拆分为 Set<HostAndPort>,连同 connectionTimeout、soTimeout、maxAttempt(默认 5)、user/password、clientName、poolConfig、ssl 一起构造 JedisCluster(源码位置)。

如果需要直接操作 JedisCluster,可通过 JedisFactory 获取:

@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);
}

然后直接在 Spring Bean 中使用:

@Autowired
private JedisCluster defaultCluster;

注意这里用的是 JedisFactory(而非 JedisPoolFactory)。从 JedisFactory.java 可以看到,它从 customContainer 中以 "jedis." + key 取对象——RedisAutoInit.initCache 中正是对 UnifiedJedis 类型的客户端额外注册了 "jedis.remote.default" 这个 key(源码位置)。因此 JedisFactory 适用于 JedisCluster、JedisPooled 这类 UnifiedJedis,而 JedisPoolFactory 适用于 JedisPool、JedisSentinelPool 这类 Pool<Jedis>。

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

哨兵模式下,大部分配置和单机模式通用,但需要配置额外的哨兵配置。

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:

在 parsePool 的哨兵分支中(源码位置),sentinels 是逗号分隔的哨兵地址列表(解析时会 trim 并去空),masterName 必填(缺失抛 NullPointerException),随后构造 JedisSentinelPool。sentinelConnectionTimeout 与 sentinelSoTimeout 默认均为 2000 毫秒。

如果需要直接操作 JedisSentinelPool:

@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);
}

然后直接在 Spring Bean 中使用:

@Autowired
private JedisSentinelPool defaultSentinelPool;

三种模式的选型小结:单机用 host/port;集群用 cluster 列表 + 可选 maxAttempt;哨兵用 sentinels + masterName。它们共享 timeout/connectionTimeout/soTimeout/user/password/clientName/ssl/poolConfig 等通用配置,且在 RedisCacheTest.java 中分别有 testSimplePool、testJedisPooled、testSentinel、testCluster 四个测试方法覆盖这几种客户端的构建与读写行为。

七、源码级原理补充

7.1 读从库与加权负载

RedisCacheConfig(RedisCacheConfig.java)除了 jedisPool 外,还支持 jedisSlavePools、slaves、readFromSlave、slaveReadWeights。当 readFromSlave=true 时,RedisCache.java 的 readCommands() 会按权重随机选取一个从库连接执行读操作,写操作始终走主库;权重分配算法 randomIndex 在 RedisCacheTest.java 中通过 10000 次随机抽样验证了分布比例。对应 yml 中可通过 readFromSlave 与 slaves.xxx(含 weight)配置,见 RedisAutoInit.initCache 的解析逻辑(源码位置)。

7.2 broadcastChannel 与跨 JVM 缓存失效

broadcastChannel: projectA 用于 JetCache 两级缓存场景:当某个 JVM 更新/删除了远程缓存后,通过 Redis Pub/Sub 广播失效消息,使其他 JVM 中的本地缓存同步失效。实现位于 RedisBroadcastManager.java:startSubscribe() 启动一个守护线程执行 subscribe;publish(CacheMessage) 向 channel 发布经 valueEncoder 编码的消息;收到消息后由 onMessage 交给 processNotification 处理。多个服务若共用同一个 channel 可能造成广播风暴,所以 broadcastChannel 的取值决定了哪些服务实例之间共享缓存失效通知。

7.3 序列化与 Key 转换

  • keyConvertor:默认 fastjson2,2.8+ 可选 fastjson2 / jackson / jackson3(fastjson 与 fastjson2 均映射到同一个基于 fastjson2 的实现,参见 KeyConvertor.java 中 FASTJSON/FASTJSON2 的注释);
  • valueEncoder / valueDecoder:仅远程缓存需要,默认 java,2.8+ 可选 java / kryo / kryo5(kryo 与 kryo5 均使用 kryo5 实现,见 SerialPolicy.java 的注释说明)。

这些配置在 Spring Boot 场景由 ExternalCacheAutoInit.java 解析并绑定到 builder 上,默认值 CacheConsts.DEFAULT_SERIAL_POLICY(java 序列化)。

7.4 缓存值结构与过期语义

Jedis 模式下写入 Redis 的值并不是裸业务对象,而是 CacheValueHolder<V>(CacheValueHolder.java)经 valueEncoder 序列化后的字节,其中记录了 value、expireTime、accessTime。读取时先反序列化出 holder,再校验 System.currentTimeMillis() >= holder.getExpireTime() 判定是否过期(见 RedisCache.java)。写入使用 Redis PSETEX,PUT_IF_ABSENT 使用 SET NX PX(源码位置),批量读写则视客户端类型选择原生 mget/del 或 Pipeline 通道。

7.5 异常与容错

RedisCacheFailTest.java 用 Mockito 模拟了 JedisConnectionException、JedisDataException 等异常,验证 GET、GET_ALL、PUT、PUT_ALL、REMOVE、REMOVE_ALL、PUT_IF_ABSENT 在 Redis 故障时均返回 CacheResultCode.FAIL 而非抛出未捕获异常——即 JetCache 对 Redis 访问失败采取的是“结果码化”的容错策略,业务侧可通过结果码感知故障。

八、总结

JetCache 通过 jetcache-redis / jetcache-starter-redis 提供了一套覆盖单机、集群、哨兵三种部署形态的 Jedis 集成方案。无论你是 Spring Boot 用户(走自动装配 + yml 声明式配置),还是原生 Java 用户(走 RedisCacheBuilder + GlobalCacheConfig 编程式装配),都能以一致的 Cache 接口获得远程缓存能力,并可通过 unwrap、JedisPoolFactory、JedisFactory 随时拿到底层 Jedis 连接对象。本文涉及的完整配置与源码验证路径均可直接在仓库中对照查阅:

登录后查看全文
jetcache