JetCache 集成 Jedis 完全指南:单机、集群与哨兵模式的配置、原理与最佳实践
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;
}
}
这段配置的几个关键点:
- 注解驱动:
@EnableMethodCache开启方法级缓存(@Cached等注解),@EnableCreateCacheAnnotation开启@CreateCache字段注入;自 JetCache 2.7 起还需@Import(JetCacheBaseBeans.class)引入基础 Bean(JetCache 2.6 及以前则需手工声明SpringConfigProviderBean); - 两级缓存构建器:
localBuilders注册本地缓存(此处用LinkedHashMapCacheBuilder,key 转换用Fastjson2KeyConvertor.INSTANCE),remoteBuilders注册远程缓存(RedisCacheBuilder); - 远程缓存必须配置序列化器:
valueEncoder/valueDecoder负责缓存值在写入 Redis 前的编码与读取后的解码,示例使用 Java 原生序列化JavaValueEncoder.INSTANCE/JavaValueDecoder.INSTANCE(位于 JavaValueEncoder.java)。AbstractExternalCache.checkConfig()会强制校验:缺少 encoder、decoder 或 keyPrefix 都会抛出CacheConfigException; - 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 之上构建出「读回源 + 后台刷新」的能力。
九、常见问题速查
keyPrefix is required报错:手工RedisCacheBuilder构建时遗漏.keyPrefix(...)。注解场景(@CreateCache/@Cached)会自动生成前缀,手工场景必须显式指定,避免不同 Cache 实例 key 冲突。no jedis或'jedis' and 'jedisPool' can't set simultaneously:RedisCacheConfig中连接对象缺失或重复配置,检查 builder 链上jedisPool(...)/jedis(...)的使用。expireAfterAccess is not supported:RedisCache不支持访问后过期,请改用expireAfterWrite或@Cached(expire = ...)。- 集群模式连接失败:确认
cluster节点可达、maxAttempt合理;Jedis 集群客户端通过反射获取provider失败时会抛IllegalStateException。 - 广播不生效:确认所有实例
broadcastChannel一致;广播订阅线程是 daemon 线程,断线后会休眠 1 秒自动重连(见 RedisBroadcastManager.java)。
十、相关文档导航
- 缓存注解与声明式缓存:见 MethodCache.md、CreateCache.md
- 全局配置与参数说明:见 Config.md
- 嵌入式(本地)缓存配置:见 Embedded.md
- 其他 Redis 客户端接入:见 RedisWithLettuce.md、RedisWithRedisson.md
- 中文版对应文档:见 RedisWithJedis.md