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）：

@Configuration
public class RedisConfig {

    @Bean public LettuceConnectionFactory orderRedisConnectionFactory() { /* ... */ }
    @Bean public RedisTemplate<String, Object> orderRedisTemplate() { /* ... */ }
    @Bean public StringRedisTemplate orderStringRedisTemplate() { /* ... */ }

    @Bean public LettuceConnectionFactory userRedisConnectionFactory() { /* ... */ }
    @Bean public RedisTemplate<String, Object> userRedisTemplate() { /* ... */ }
    @Bean public StringRedisTemplate userStringRedisTemplate() { /* ... */ }

    // ... 再来两组就是 12 个 Bean
}

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

spring:
  data:
    redis:
      clusters:
        order:
          host: localhost
          port: 6380
        user:
          host: localhost
          port: 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 → orderRedisTemplate
          host: localhost
          port: 6380
        user:                      # Standalone → userRedisTemplate
          host: localhost
          port: 6381
        cache:                     # Redis Cluster → cacheRedisTemplate
          cluster:
            nodes: localhost:7001,localhost:7002,localhost:7003
        session:                   # Redis Cluster → sessionRedisTemplate
          cluster:
            nodes: localhost:7011,localhost:7012,localhost:7013

自动生成的 Bean：

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

直接按名称注入使用：

@Service
public class OrderService {

    private final RedisTemplate<String, Object> orderRedisTemplate;
    private final StringRedisTemplate userStringRedisTemplate;

    public OrderService(RedisTemplate<String, Object> orderRedisTemplate,
                        StringRedisTemplate userStringRedisTemplate) {
        this.orderRedisTemplate = orderRedisTemplate;
        this.userStringRedisTemplate = userStringRedisTemplate;
    }
}

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

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

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

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

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

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

场景	配置	激活模式
多集群格式	spring.data.redis.clusters.order.host=...	Auto-register
官方 Standalone	spring.data.redis.host=127.0.0.1	Auto-register
官方 Cluster	spring.data.redis.cluster.nodes=...	Auto-register
显式开启	spring.data.redis.auto-register: true	Auto-register
显式关闭	spring.data.redis.auto-register: false	Builder 模式

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

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

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

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

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

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

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

# 官方 Standalone
spring:
  data:
    redis:
      host: localhost
      port: 6379

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

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

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

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

✨ 5. YAML 序列化配置

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

spring:
  data:
    redis:
      clusters:
        order:
          host: localhost
          port: 6379
          serializer:
            key: string        # string | json | java | byteArray
            value: json
            hash-key: string
            hash-value: json

序列化类型	对应实现	适用场景
java	JdkSerializationRedisSerializer	官方默认，兼容性最好
json	GenericJackson2JsonRedisSerializer	可读性好，跨语言
string	StringRedisSerializer	纯文本场景
byteArray	ByteArrayRedisSerializer	二进制数据

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

✨ 6. 读写分离与连接池

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

spring:
  data:
    redis:
      clusters:
        cache:
          cluster:
            nodes: localhost:7001,localhost:7002,localhost:7003
            read-from: REPLICA_PREFERRED    # 优先从副本节点读取
          lettuce:
            pool:
              max-active: 16
              max-idle: 8
              min-idle: 2
            cluster:
              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 模式应对进阶需求

---

📊 模块速查表

模块	说明
multi-redis-spring-boot-autoconfigure	核心自动配置模块，包含自动检测、Bean 注册、官方格式兼容等全部逻辑
multi-redis-spring-boot-starter	Starter 依赖聚合模块，引入即用
multi-redis-spring-boot-sample	示例项目，演示多 Redis 场景的实际用法

---

🎓 学习价值

对于初中级开发者

• ✅ 理解 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: localhost
          port: 6380
        user:
          host: localhost
          port: 6381

3. 直接注入

@RestController
public class DemoController {

    private final RedisTemplate<String, Object> orderRedisTemplate;
    private final StringRedisTemplate userStringRedisTemplate;

    public DemoController(RedisTemplate<String, Object> orderRedisTemplate,
                          StringRedisTemplate userStringRedisTemplate) {
        this.orderRedisTemplate = orderRedisTemplate;
        this.userStringRedisTemplate = userStringRedisTemplate;
    }

    @GetMapping("/demo")
    public String demo() {
        orderRedisTemplate.opsForValue().set("order:001", "hello");
        userStringRedisTemplate.opsForValue().set("user:001", "world");
        return "done";
    }
}

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

---

💡 进阶：Builder 模式

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

@Configuration
public class RedisConfig {

    @Bean
    public RedisTemplate<String, Object> orderRedisTemplate(RedisTemplateBuilder builder) {
        return builder.cluster("order")
                .keySerializer(RedisSerializer.string())
                .valueSerializer(RedisSerializer.json())
                .hashKeySerializer(RedisSerializer.string())
                .hashValueSerializer(RedisSerializer.json())
                .build();
    }

    @Bean
    public StringRedisTemplate orderStringRedisTemplate(RedisTemplateBuilder builder) {
        return builder.stringTemplate("order");
    }
}

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

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

---

💡 最佳实践总结

1. 命名规范

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

集群名	生成的 Bean
order	orderRedisTemplate, orderStringRedisTemplate
cache	cacheRedisTemplate, cacheStringRedisTemplate
default	defaultRedisTemplate（官方格式兼容）

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: 16
              min-idle: 4
            cluster:
              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 管理变得简单！

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

---

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