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 数据源（Standalone 单实例或 Cluster 集群），想要接入多个 Redis，要么手写一堆 @Bean 配置，要么自己封装 Starter。

有没有一种方式，只需一行依赖 + YAML 配置，就能自动注册多个 RedisTemplate？

multi-redis-spring-boot-starter 就是为此而生的。

---

🎯 为什么需要这个 Starter？

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

Spring Boot 的 RedisAutoConfiguration 只创建一个 RedisConnectionFactory 和一个 RedisTemplate，支持 Standalone 单实例或 Cluster 集群模式，但只能配置一个数据源。当需要同时连接多个 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.0</version>
</dependency>

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

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

✨ 2. 双模式设计——代码控制 vs 零代码

Mode 1：Builder + @RedisCluster 注解（适合需要精细控制的场景）

// 方式 A：Builder 模式手动创建
@Bean
public RedisTemplate<String, Object> orderRedisTemplate(RedisTemplateBuilder builder) {
    return builder.cluster("order")
        .keySerializer(RedisSerializer.string())
        .valueSerializer(RedisSerializer.json())
        .build();
}

// 方式 B：@RedisCluster 注解直接注入（最简方式）
@Service
public class OrderService {

    @RedisCluster("order")
    private RedisTemplate<String, Object> orderRedisTemplate;

    @RedisCluster("order")
    private StringRedisTemplate orderStringRedisTemplate;
}

Mode 2：Auto-register 零代码模式（适合标准场景）

只需 YAML 配置，自动注册所有 Bean，无需写一行 Java 代码：

spring:
  data:
    redis:
      auto-register: true
      clusters:
        order:
          host: localhost
          port: 6379
        user:
          host: localhost
          port: 6380
        cache:
          cluster:
            nodes: localhost:7001,localhost:7002,localhost:7003

自动生成的 Bean：

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

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

✨ 3. 官方配置格式兼容——无缝迁移

这是最实用的特性。如果你现有的项目使用官方配置格式：

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

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

当你需要新增 Redis 实例时，只需追加配置：

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

这意味着：从单 Redis 迁移到多 Redis，配置零改动，渐进式扩展。

✨ 4. Standalone + Cluster 双模式

同一个 Starter，同时支持 Standalone 和 Redis Cluster：

spring:
  data:
    redis:
      auto-register: true
      clusters:
        order:                     # Standalone 模式
          host: localhost
          port: 6379
        cache:                     # Cluster 模式
          cluster:
            nodes: localhost:7001,localhost:7002,localhost:7003
          max-redirects: 3

这意味着：无论你的 Redis 部署方式是单机还是集群，都能统一管理。

✨ 5. 读写分离与连接池

支持 Lettuce 连接池配置和集群读写分离：

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

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

✨ 6. 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	二进制数据

---

🏛️ 架构设计

┌─────────────────────────────────────────────────────────┐
│              Spring Boot Application                     │
│                                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │   multi-redis-spring-boot-starter               │    │
│  │                                                 │    │
│  │  ┌──────────────────────┐  ┌────────────────┐  │    │
│  │  │ MultiRedisAutoConfig │  │ ImportFilter   │  │    │
│  │  │ (排除官方单实例配置)  │  │ (条件装配)     │  │    │
│  │  └──────────┬───────────┘  └────────────────┘  │    │
│  │             │                                    │    │
│  │  ┌──────────▼───────────────────────────────┐   │    │
│  │  │     MultiRedisRegistrar                  │   │    │
│  │  │  (ImportBeanDefinitionRegistrar)         │   │    │
│  │  │                                          │   │    │
│  │  │  解析 spring.data.redis.clusters.*       │   │    │
│  │  │  为每个 cluster 注册:                     │   │    │
│  │  │  - RedisConnectionFactory                │   │    │
│  │  │  - RedisTemplate                         │   │    │
│  │  │  - StringRedisTemplate                   │   │    │
│  │  └──────────┬───────────────────────────────┘   │    │
│  └─────────────┼───────────────────────────────────┘    │
│                │                                         │
│  ┌─────────────▼───────────────────────────────────┐    │
│  │  RedisTemplateBuilder + @RedisCluster (Mode 1)  │    │
│  │  Auto-register Beans           (Mode 2)         │    │
│  └─────────────┬───────────────────────────────────┘    │
└────────────────┼────────────────────────────────────────┘
                 │
    ┌────────────┼────────────────┐
    │            │                │
┌───▼───┐  ┌────▼────┐  ┌───────▼──────┐
│Redis A│  │Redis B  │  │Redis Cluster │
│:6379  │  │:6380    │  │:7001-:7003   │
└───────┘  └─────────┘  └──────────────┘

核心设计理念：

1. 零侵入：不修改 Spring Boot 原有行为，通过 ImportBeanDefinitionRegistrar 动态注册 Bean
2. 渐进式采用：官方配置格式完全兼容，新增 Redis 只需追加配置
3. 双模式互补：Builder 模式适合复杂定制，Auto-register 适合标准场景

---

📊 模块速查表

模块	说明
multi-redis-spring-boot-autoconfigure	核心自动配置模块，包含所有自动注册逻辑
multi-redis-spring-boot-starter	Starter 依赖聚合模块，引入即用
multi-redis-spring-boot-sample	示例项目，演示 4 个 Redis 目标的完整用法

---

🎓 学习价值

对于初中级开发者

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

对于高级开发者

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

对于架构师

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

---

🚦 快速开始

前置要求

• Java 17+
• Spring Boot 3.5.x
• Redis 实例（Standalone 或 Cluster）

3 步接入

1. 添加依赖

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

2. 配置 YAML

spring:
  data:
    redis:
      auto-register: true
      clusters:
        order:
          host: localhost
          port: 6379
        user:
          host: localhost
          port: 6380

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() {
        // 写入 order Redis
        orderRedisTemplate.opsForValue().set("order:001", "hello");
        String order = orderRedisTemplate.opsForValue().get("order:001");

        // 写入 user Redis
        userStringRedisTemplate.opsForValue().set("user:001", "world");
        String user = userStringRedisTemplate.opsForValue().get("user:001");

        return "order=" + order + ", user=" + user;
    }
}

---

💡 最佳实践

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 连接。从官方配置兼容到零代码自动注册，从 Builder 模式到读写分离，它覆盖了多 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 开源组件