替换依赖，写 YAML，直接注入：multi-redis-spring-boot-starter 1.0.4 发布

Spring Boot 3.5.x|Java 17+|Standalone + Cluster|Maven Central

在微服务架构中，一个应用连接多个 Redis 实例或集群几乎是常态——订单用 Redis A，用户缓存用 Redis B，Session 用 Redis Cluster。然而，Spring Boot 官方的spring-boot-starter-data-redis只支持配置一个Redis 数据源，想要接入多个 Redis，要么手写一堆@Bean配置，要么自己封装 Starter。

有没有一种方式，只需替换依赖 + 写 YAML，就能自动注册多个RedisTemplate？

multi-redis-spring-boot-starter就是为此而生的。直接替换spring-boot-starter-data-redis的依赖，不用改配置，不用写代码，多 Redis 能力即开即用。

🔄 替换前 vs 替换后

先看效果。同样是连接 2 个 Redis（订单 + 用户），对比一下两种方式的工作量：

不用这个 Starter（手动配置 12 个 Bean）：

@ConfigurationpublicclassRedisConfig{@BeanpublicLettuceConnectionFactoryorderRedisConnectionFactory(){/* ... */}@BeanpublicRedisTemplate<String,Object>orderRedisTemplate(){/* ... */}@BeanpublicStringRedisTemplateorderStringRedisTemplate(){/* ... */}@BeanpublicLettuceConnectionFactoryuserRedisConnectionFactory(){/* ... */}@BeanpublicRedisTemplate<String,Object>userRedisTemplate(){/* ... */}@BeanpublicStringRedisTemplateuserStringRedisTemplate(){/* ... */}// ... 再来两组就是 12 个 Bean}

用这个 Starter（0 行 Java 代码）：

spring:data:redis:clusters:order:host:localhostport:6380user:host:localhostport:6381

Bean 自动注册，直接注入。从 2 个 Redis 扩展到 4 个，只加 YAML，不改一行代码。

🎯 为什么需要这个 Starter？

痛点一：官方 Starter 只支持单个数据源

Spring Boot 的RedisAutoConfiguration只创建一个RedisConnectionFactory和一个RedisTemplate。当需要同时连接多个 Redis 时（订单用 Redis A，用户用 Redis B），必须手动配置多个LettuceConnectionFactory、多个RedisTemplate，代码量急剧膨胀。

痛点二：多 Redis 配置重复且易错

每新增一个 Redis 实例，就要复制粘贴一套ConnectionFactory+RedisTemplate+StringRedisTemplate的 Bean 定义。4 个 Redis 就是 12 个 Bean，配置冗长且容易出错。

痛点三：迁移成本高

已有的项目使用官方配置格式（spring.data.redis.host/port），切换到多 Redis 方案通常意味着要重写所有配置。

如果有一种方案，兼容官方配置格式，零改动迁移呢？

🚀 核心亮点

✨ 1. 一行依赖，即开即用

<dependency><groupId>org.hongxi</groupId><artifactId>multi-redis-spring-boot-starter</artifactId><version>1.0.4</version></dependency>

已发布到Maven Central，无需额外配置仓库地址。

这意味着：任何 Spring Boot 项目，加一行依赖就能获得多 Redis 能力。

✨ 2. Auto-register 零代码模式——写 YAML，直接注入

这是最核心的能力。只需在 YAML 中声明 Redis 集群，所有 Bean 自动注册，不需要写一行 Java 代码：

spring:data:redis:clusters:order:# Standalone → orderRedisTemplatehost:localhostport:6380user:# Standalone → userRedisTemplatehost:localhostport:6381cache:# Redis Cluster → cacheRedisTemplatecluster:nodes:localhost:7001,localhost:7002,localhost:7003session:# Redis Cluster → sessionRedisTemplatecluster:nodes:localhost:7011,localhost:7012,localhost:7013

自动生成的 Bean：

• orderRedisTemplate、orderStringRedisTemplate
• userRedisTemplate、userStringRedisTemplate
• cacheRedisTemplate、cacheStringRedisTemplate
• sessionRedisTemplate、sessionStringRedisTemplate

直接按名称注入使用：

@ServicepublicclassOrderService{privatefinalRedisTemplate<String,Object>orderRedisTemplate;privatefinalStringRedisTemplateuserStringRedisTemplate;publicOrderService(RedisTemplate<String,Object>orderRedisTemplate,StringRedisTemplateuserStringRedisTemplate){this.orderRedisTemplate=orderRedisTemplate;this.userStringRedisTemplate=userStringRedisTemplate;}}

不需要@Configuration类，不需要手动 Bean 定义。

Standalone 和 Redis Cluster 混合部署也没问题——在同一个 YAML 里，有的集群用host/port，有的用cluster.nodes，Starter 自动识别：

spring:data:redis:clusters:order:# Standalone 模式host:localhostport:6379cache:# Cluster 模式cluster:nodes:localhost:7001,localhost:7002,localhost:7003

从 1 个 Redis 扩展到 4 个，只需要加 YAML 配置，不改一行代码。

✨ 3. 自动检测，零配置激活

Auto-register 模式不需要手动开启。Starter 启动时自动扫描 Redis 配置：

优先级：显式auto-register设置 > 自动检测

加完依赖，写完 YAML，什么都不用配，自动生效。

✨ 4. 官方配置格式兼容——零侵入迁移

这是最实用的特性。把spring-boot-starter-data-redis替换成multi-redis-spring-boot-starter后，现有配置不需要改任何内容。

# 现有项目配置（官方格式）spring:data:redis:host:localhostport:6379password:yourpassword

引入这个 Starter 后，不需要改任何配置。上述配置会自动识别为名为default的集群，Bean 命名为defaultRedisTemplate、defaultStringRedisTemplate。

Standalone 和 Cluster 两种官方格式都支持：

# 官方 Standalonespring:data:redis:host:localhostport:6379# 官方 Cluster（同样兼容）spring:data:redis:cluster:nodes:localhost:7001,localhost:7002,localhost:7003

当你需要新增 Redis 实例时，只需追加多集群配置，原有配置不动：

spring:data:redis:host:localhost# 现有配置不动 → defaultRedisTemplateport:6379clusters:user:# 新增第二个 Redis → userRedisTemplatehost:localhostport:6380

单 Redis 迁移到多 Redis，配置零改动，渐进式扩展。

✨ 5. YAML 序列化配置

在 Auto-register 模式下，可以直接在 YAML 中配置每个集群的序列化方式：

spring:data:redis:clusters:order:host:localhostport:6379serializer:key:string# string | json | java | byteArrayvalue:jsonhash-key:stringhash-value:json

序列化配置也无需写代码，YAML 里直接指定。

✨ 6. 读写分离与连接池

生产环境必备的读写分离和连接池能力，同样通过 YAML 配置：

spring:data:redis:clusters:cache:cluster:nodes:localhost:7001,localhost:7002,localhost:7003read-from:REPLICA_PREFERRED# 优先从副本节点读取lettuce:pool:max-active:16max-idle:8min-idle:2cluster:refresh:adaptive:true# 自适应拓扑刷新

生产环境的高可用读写分离，一行配置搞定。

🏛️ 架构设计

┌─────────────────────────────────────────────────────────┐ │ Spring Boot Application │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ multi-redis-spring-boot-starter │ │ │ │ │ │ │ │ ┌──────────────────────┐ ┌────────────────┐ │ │ │ │ │ MultiRedisAutoConfig │ │ ImportFilter │ │ │ │ │ │ (排除官方单实例配置) │ │ (条件装配) │ │ │ │ │ └──────────┬───────────┘ └────────────────┘ │ │ │ │ │ │ │ │ │ ┌──────────▼───────────────────────────────┐ │ │ │ │ │ MultiRedisRegistrar │ │ │ │ │ │ (ImportBeanDefinitionRegistrar) │ │ │ │ │ │ │ │ │ │ │ │ 自动检测 Redis 配置 │ │ │ │ │ │ 解析官方格式 / 多集群格式 │ │ │ │ │ │ 为每个 cluster 注册: │ │ │ │ │ │ - RedisConnectionFactory │ │ │ │ │ │ - RedisTemplate │ │ │ │ │ │ - StringRedisTemplate │ │ │ │ │ └──────────┬───────────────────────────────┘ │ │ │ └─────────────┼───────────────────────────────────┘ │ │ │ │ │ ┌─────────────▼───────────────────────────────────┐ │ │ │ Auto-register Beans (零代码，自动注册) │ │ │ │ RedisTemplateBuilder (进阶，编程控制) │ │ │ └─────────────┬───────────────────────────────────┘ │ └────────────────┼────────────────────────────────────────┘ │ ┌────────────┼────────────────┐ │ │ │ ┌───▼───┐ ┌────▼────┐ ┌───────▼──────┐ │Redis A│ │Redis B │ │Redis Cluster │ │:6379 │ │:6380 │ │:7001-:7003 │ └───────┘ └─────────┘ └──────────────┘

核心设计理念：

1. 零侵入：不修改 Spring Boot 原有行为，通过ImportBeanDefinitionRegistrar动态注册 Bean
2. 零配置：自动检测 Redis 配置，自动激活 Auto-register 模式，无需手动开启
3. 渐进式采用：官方配置格式完全兼容，从单 Redis 到多 Redis 无需改配置
4. 双模式互补：Auto-register 覆盖标准场景，Builder 模式应对进阶需求

📊 模块速查表

🎓 学习价值

对于初中级开发者

• ✅ 理解 Spring Boot Starter 的实现原理
• ✅ 学习ImportBeanDefinitionRegistrar动态注册 Bean 的机制
• ✅ 掌握多 Redis 场景的零代码配置方式

对于高级开发者

• ✅ 深入理解AutoConfigurationImportFilter条件装配
• ✅ 学习RedisTemplateBuilder的 Builder 模式设计
• ✅ 掌握 Lettuce 连接池与集群读写分离配置

对于架构师

• ✅ 自定义 Starter 的设计模式参考
• ✅ 官方配置兼容的零侵入迁移方案
• ✅ 多 Redis 集群的统一治理思路

🚦 快速开始

把spring-boot-starter-data-redis换成multi-redis-spring-boot-starter，然后 3 步搞定：

1. 替换依赖

<!-- 替换掉官方 starter --><dependency><groupId>org.hongxi</groupId><artifactId>multi-redis-spring-boot-starter</artifactId><version>1.0.4</version></dependency>

2. 写 YAML（已有配置不用改，自动兼容）

spring:data:redis:clusters:order:host:localhostport:6380user:host:localhostport:6381

3. 直接注入

@RestControllerpublicclassDemoController{privatefinalRedisTemplate<String,Object>orderRedisTemplate;privatefinalStringRedisTemplateuserStringRedisTemplate;publicDemoController(RedisTemplate<String,Object>orderRedisTemplate,StringRedisTemplateuserStringRedisTemplate){this.orderRedisTemplate=orderRedisTemplate;this.userStringRedisTemplate=userStringRedisTemplate;}@GetMapping("/demo")publicStringdemo(){orderRedisTemplate.opsForValue().set("order:001","hello");userStringRedisTemplate.opsForValue().set("user:001","world");return"done";}}

完事。没有@Configuration类，没有手动 Bean 定义。

💡 进阶：Builder 模式

当你需要编程控制（如条件化创建、自定义 Pipeline），可以注入RedisTemplateBuilder手动定义 Bean。YAML 配置的序列化器默认生效，也可以在代码中覆盖：

@ConfigurationpublicclassRedisConfig{@BeanpublicRedisTemplate<String,Object>orderRedisTemplate(RedisTemplateBuilderbuilder){returnbuilder.cluster("order").keySerializer(RedisSerializer.string()).valueSerializer(RedisSerializer.json()).hashKeySerializer(RedisSerializer.string()).hashValueSerializer(RedisSerializer.json()).build();}@BeanpublicStringRedisTemplateorderStringRedisTemplate(RedisTemplateBuilderbuilder){returnbuilder.stringTemplate("order");}}

RedisTemplateBuilder可以注入到任何 Spring 管理的 Bean 中——不仅是@Configuration类，也可以是@Service、@Component。

设置spring.data.redis.auto-register=false可强制使用 Builder 模式。

💡 最佳实践总结

1. 命名规范

集群名称建议使用业务含义，Bean 自动以{clusterName}为前缀：

2. 序列化策略

• 新项目：推荐key: string+value: json，可读性好，方便调试
• 迁移项目：保持value: java（官方默认），确保与现有数据兼容
• 跨语言场景：使用json序列化，其他语言可直接读取

3. 生产环境配置

spring:data:redis:clusters:cache:cluster:nodes:${REDIS_CLUSTER_NODES}# 环境变量注入read-from:REPLICA_PREFERRED# 读写分离lettuce:pool:max-active:16min-idle:4cluster:refresh:adaptive:true# 自适应拓扑刷新

🔗 相关链接

• 📦GitHub: javahongxi/multi-redis-spring-boot-starter
• 📦Maven Central: org.hongxi:multi-redis-spring-boot-starter
• 📖Spring Data Redis: Spring 官方文档
• 📖Lettuce: Lettuce 官方文档
• 📖Spring Boot: Spring Boot 官方文档

📝 结语

multi-redis-spring-boot-starter解决了一个很实际的问题：在 Spring Boot 中优雅地管理多个 Redis 连接。替换依赖，写 YAML，直接注入，完事。官方配置格式完全兼容，从单 Redis 到多 Redis 零改动迁移。

如果你正在：

• 🎯 为项目中多个 Redis 连接配置而头疼
• 🚀 寻找一个零侵入的多 Redis Starter 方案
• 🏗️ 需要从单 Redis 平滑迁移到多 Redis
• 📚 想学习自定义 Spring Boot Starter 的实现方式

Star ⭐ multi-redis-spring-boot-starter，让多 Redis 管理变得简单！

gitclone https://github.com/javahongxi/multi-redis-spring-boot-starter.git

© hongxi.org| 打造实用的 Spring Boot 开源组件