Spring Boot集成Redis：单机、哨兵、集群三种模式统一配置实战

一、前言在微服务架构中Redis作为高性能的缓存数据库被广泛应用。Spring Boot提供了spring-boot-starter-data-redis来简化Redis的集成但在实际项目中我们往往需要根据不同的环境开发、测试、生产切换不同的Redis部署模式单机、哨兵、集群。本文将详细介绍如何在Spring Boot中实现Redis三种模式的统一配置通过一个配置参数即可灵活切换大大提高项目的可维护性和灵活性。二、技术栈Spring Boot 2.x/3.xRedis 6.x/7.xLettuce连接池Jackson2Json序列化三、项目依赖首先在pom.xml中添加Redis相关依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency四、配置文件设计4.1 application.yml 完整配置spring: data: redis: # Redis 运行模式standalone单机sentinel哨兵cluster集群 mode: standalone # 数据库索引0-15 database: 0 # 连接超时时间毫秒 timeout: 60000 # Redis 服务器密码 password: your_password # 连接池配置 lettuce: pool: max-active: 8 # 最大连接数 max-idle: 8 # 最大空闲连接 min-idle: 0 # 最小空闲连接 max-wait: -1ms # 连接池满时等待时间-1表示一直等待 # 单机模式配置 host: 127.0.0.1 port: 6379 # 哨兵模式配置 sentinel: master: mymaster nodes: - 127.0.0.1:26379 - 127.0.0.1:26380 - 127.0.0.1:26381 # 集群模式配置 cluster: nodes: - 127.0.0.1:7001 - 127.0.0.1:7002 - 127.0.0.1:7003 - 127.0.0.1:7004 - 127.0.0.1:7005 - 127.0.0.1:7006 max-redirects: 3 # 最大重定向次数五、核心代码实现5.1 配置属性类import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; import java.time.Duration; import java.util.List; Data Component ConfigurationProperties(prefix spring.data.redis) public class RedisProperties { // 通用配置 private String mode standalone; private int database 0; private Duration timeout Duration.ofSeconds(60); private String password; // 单机模式配置 private String host 127.0.0.1; private int port 6379; // 哨兵模式配置 private Sentinel sentinel new Sentinel(); // 集群模式配置 private Cluster cluster new Cluster(); // Lettuce连接池配置 private Lettuce lettuce new Lettuce(); Data public static class Sentinel { private String master; private ListString nodes; } Data public static class Cluster { private ListString nodes; private int maxRedirects 3; } Data public static class Lettuce { private Pool pool new Pool(); Data public static class Pool { private int maxActive 8; private int maxIdle 8; private int minIdle 0; private Duration maxWait Duration.ofMillis(-1); } } }5.2 统一Redis配置类import com.fasterxml.jackson.annotation.JsonAutoDetect; import com.fasterxml.jackson.annotation.JsonTypeInfo; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.jsontype.impl.LaissezFaireSubTypeValidator; import lombok.extern.slf4j.Slf4j; import org.apache.commons.pool2.impl.GenericObjectPoolConfig; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.data.redis.connection.*; import org.springframework.data.redis.connection.lettuce.LettuceClientConfiguration; import org.springframework.data.redis.connection.lettuce.LettuceConnectionFactory; import org.springframework.data.redis.connection.lettuce.LettucePoolingClientConfiguration; import org.springframework.data.redis.core.RedisTemplate; import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer; import org.springframework.data.redis.serializer.StringRedisSerializer; import org.springframework.util.StringUtils; import java.time.Duration; import java.util.List; Slf4j Configuration public class UnifiedRedisConfig { Autowired private RedisProperties redisProperties; /** * 创建 Redis 连接工厂统一入口 */ Bean public RedisConnectionFactory redisConnectionFactory() { String mode redisProperties.getMode().toLowerCase(); log.info(初始化Redis连接工厂当前模式: {}, mode); RedisConnectionFactory connectionFactory; switch (mode) { case sentinel: connectionFactory createSentinelConnectionFactory(); break; case cluster: connectionFactory createClusterConnectionFactory(); break; case standalone: default: connectionFactory createStandaloneConnectionFactory(); break; } log.info(Redis连接工厂初始化完成); return connectionFactory; } /** * 创建单机模式连接工厂 */ private RedisConnectionFactory createStandaloneConnectionFactory() { RedisStandaloneConfiguration config new RedisStandaloneConfiguration(); config.setHostName(redisProperties.getHost()); config.setPort(redisProperties.getPort()); config.setDatabase(redisProperties.getDatabase()); if (StringUtils.hasText(redisProperties.getPassword())) { config.setPassword(redisProperties.getPassword()); } return createLettuceConnectionFactory(config); } /** * 创建哨兵模式连接工厂 */ private RedisConnectionFactory createSentinelConnectionFactory() { RedisSentinelConfiguration config new RedisSentinelConfiguration(); config.master(redisProperties.getSentinel().getMaster()); config.setDatabase(redisProperties.getDatabase()); if (StringUtils.hasText(redisProperties.getPassword())) { config.setPassword(redisProperties.getPassword()); } // 配置哨兵节点 ListString sentinelNodes redisProperties.getSentinel().getNodes(); if (sentinelNodes ! null !sentinelNodes.isEmpty()) { for (String node : sentinelNodes) { String[] parts node.split(:); if (parts.length 2) { config.sentinel(parts[0], Integer.parseInt(parts[1])); } else { log.warn(哨兵节点格式错误应为 host:port实际: {}, node); } } } return createLettuceConnectionFactory(config); } /** * 创建集群模式连接工厂 */ private RedisConnectionFactory createClusterConnectionFactory() { RedisClusterConfiguration config new RedisClusterConfiguration(); config.setMaxRedirects(redisProperties.getCluster().getMaxRedirects()); if (StringUtils.hasText(redisProperties.getPassword())) { config.setPassword(redisProperties.getPassword()); } // 配置集群节点 ListString clusterNodes redisProperties.getCluster().getNodes(); if (clusterNodes ! null !clusterNodes.isEmpty()) { for (String node : clusterNodes) { String[] parts node.split(:); if (parts.length 2) { config.clusterNode(parts[0], Integer.parseInt(parts[1])); } else { log.warn(集群节点格式错误应为 host:port实际: {}, node); } } } return createLettuceConnectionFactory(config); } /** * 创建Lettuce连接工厂通用方法 */ private LettuceConnectionFactory createLettuceConnectionFactory(Object redisConfig) { LettuceClientConfiguration clientConfig createLettuceClientConfiguration(); if (redisConfig instanceof RedisStandaloneConfiguration) { return new LettuceConnectionFactory((RedisStandaloneConfiguration) redisConfig, clientConfig); } else if (redisConfig instanceof RedisSentinelConfiguration) { return new LettuceConnectionFactory((RedisSentinelConfiguration) redisConfig, clientConfig); } else if (redisConfig instanceof RedisClusterConfiguration) { return new LettuceConnectionFactory((RedisClusterConfiguration) redisConfig, clientConfig); } else { throw new IllegalArgumentException(不支持的Redis配置类型); } } /** * 创建Lettuce客户端配置包含连接池和超时配置 */ private LettuceClientConfiguration createLettuceClientConfiguration() { GenericObjectPoolConfig? poolConfig createPoolConfig(); LettuceClientConfiguration.LettuceClientConfigurationBuilder builder LettucePoolingClientConfiguration.builder() .poolConfig(poolConfig); // 设置命令超时时间 if (redisProperties.getTimeout() ! null) { builder.commandTimeout(redisProperties.getTimeout()); } // 集群模式特殊配置启用集群拓扑刷新 if (cluster.equalsIgnoreCase(redisProperties.getMode())) { builder.clientOptions(io.lettuce.core.cluster.ClusterClientOptions.builder() .topologyRefreshOptions( io.lettuce.core.cluster.ClusterTopologyRefreshOptions.builder() .enableAdaptiveRefresh(true) // 启用自适应刷新 .enablePeriodicRefresh(Duration.ofSeconds(60)) // 周期性刷新 .refreshPeriod(Duration.ofSeconds(60)) .build() ) .build()); log.info(集群模式已启用拓扑自动刷新); } return builder.build(); } /** * 创建连接池配置 */ private GenericObjectPoolConfig? createPoolConfig() { GenericObjectPoolConfig? poolConfig new GenericObjectPoolConfig(); RedisProperties.Lettuce.Pool pool redisProperties.getLettuce().getPool(); poolConfig.setMaxTotal(pool.getMaxActive()); poolConfig.setMaxIdle(pool.getMaxIdle()); poolConfig.setMinIdle(pool.getMinIdle()); poolConfig.setMaxWait(pool.getMaxWait()); // 连接池优化配置 poolConfig.setTestOnBorrow(true); // 获取连接时测试连接可用性 poolConfig.setTestOnReturn(false); poolConfig.setTestWhileIdle(true); // 空闲时测试连接 poolConfig.setTimeBetweenEvictionRuns(Duration.ofSeconds(30)); // 空闲连接检测周期 return poolConfig; } /** * 创建 RedisTemplate */ Bean public RedisTemplateString, Object redisTemplate(RedisConnectionFactory redisConnectionFactory) { RedisTemplateString, Object template new RedisTemplate(); template.setConnectionFactory(redisConnectionFactory); // 使用 StringRedisSerializer 序列化 key StringRedisSerializer stringSerializer new StringRedisSerializer(); template.setKeySerializer(stringSerializer); template.setHashKeySerializer(stringSerializer); // 使用 Jackson2JsonRedisSerializer 序列化 value GenericJackson2JsonRedisSerializer jacksonSerializer getJacksonSerializer(); template.setValueSerializer(jacksonSerializer); template.setHashValueSerializer(jacksonSerializer); template.afterPropertiesSet(); return template; } /** * 创建并配置 Jackson2JsonRedisSerializer */ private GenericJackson2JsonRedisSerializer getJacksonSerializer() { ObjectMapper objectMapper new ObjectMapper(); // 设置序列化可见性 objectMapper.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY); // 启用类型信息便于反序列化 objectMapper.activateDefaultTyping( LaissezFaireSubTypeValidator.instance, ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY ); return new GenericJackson2JsonRedisSerializer(objectMapper); } }5.3 Redis健康检查可选import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.redis.connection.RedisConnection; import org.springframework.data.redis.core.RedisTemplate; import org.springframework.stereotype.Component; import javax.annotation.PostConstruct; import java.util.concurrent.TimeUnit; Slf4j Component public class RedisHealthChecker { Autowired private RedisTemplateString, Object redisTemplate; PostConstruct public void init() { checkRedisConnection(); } /** * 检查Redis连接状态 */ public boolean checkRedisConnection() { try { RedisConnection connection redisTemplate.getConnectionFactory().getConnection(); String pong connection.ping(); connection.close(); if (PONG.equals(pong)) { log.info(Redis连接成功); return true; } else { log.error(Redis连接失败); return false; } } catch (Exception e) { log.error(Redis连接异常: {}, e.getMessage()); return false; } } /** * 定期健康检查 */ org.springframework.scheduling.annotation.Scheduled(fixedDelay 30, timeUnit TimeUnit.SECONDS) public void scheduledHealthCheck() { checkRedisConnection(); } }六、使用示例6.1 基础操作Serviceimport lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.redis.core.RedisTemplate; import org.springframework.stereotype.Service; import java.util.concurrent.TimeUnit; Slf4j Service public class RedisService { Autowired private RedisTemplateString, Object redisTemplate; /** * 设置值 */ public void set(String key, Object value) { redisTemplate.opsForValue().set(key, value); } /** * 设置值并指定过期时间 */ public void set(String key, Object value, long timeout, TimeUnit unit) { redisTemplate.opsForValue().set(key, value, timeout, unit); } /** * 获取值 */ public Object get(String key) { return redisTemplate.opsForValue().get(key); } /** * 删除key */ public Boolean delete(String key) { return redisTemplate.delete(key); } /** * 判断key是否存在 */ public Boolean hasKey(String key) { return redisTemplate.hasKey(key); } /** * 设置过期时间 */ public Boolean expire(String key, long timeout, TimeUnit unit) { return redisTemplate.expire(key, timeout, unit); } }