Redisson 与 Spring Boot 3.4 整合指南

江湖人称小鱼哥2025-11-03 15:15

概述

本文档总结了在 Spring Boot 3.4.0 项目中整合 Redisson 3.23.2 的完整流程、注意事项和常见坑点。

项目环境

  • Spring Boot: 3.4.0
  • Java: 21
  • Redisson: 3.23.2
  • Sa-Token: 1.37.0（使用 Redis 存储 Token）

整合方案

方案选择

经过实践，推荐使用手动配置方式 ，而非依赖 redisson-spring-boot-starter 的自动配置。

为什么选择手动配置？

  1. 自动配置的坑点：

    • redisson-spring-boot-starter 的自动配置不支持 spring.redisson.config: | 内联 YAML 块标量
    • spring.redisson.file 属性在某些版本中可能无法正确读取配置文件
    • 默认配置会尝试连接 localhost:6379，导致连接失败

  2. 手动配置的优势：

    • 配置透明，便于理解和调试
    • 可以精确控制 Redisson 客户端的创建时机
    • 避免与 Spring Boot 自动配置的冲突

整合步骤

1. Maven 依赖配置

xml 复制代码 
<properties>
    <redisson.version>3.23.2</redisson.version>
</properties>

<dependencies>
    <!-- Redisson Spring Boot Starter -->
    <dependency>
        <groupId>org.redisson</groupId>
        <artifactId>redisson-spring-boot-starter</artifactId>
        <version>${redisson.version}</version>
    </dependency>

    <!-- Sa-Token Redis 支持（可选，如果使用 Sa-Token） -->
    <dependency>
        <groupId>cn.dev33</groupId>
        <artifactId>sa-token-redis-jackson</artifactId>
        <version>${sa-token.version}</version>
    </dependency>
</dependencies>

2. 创建 Redisson 配置文件

在 src/main/resources/ 目录下创建 redisson-dev.yml：

yaml 复制代码 
singleServerConfig:
  # Redis 服务器地址（格式：redis://host:port）
  address: redis://45.56.67.87:6379
  # 密码
  password: your_password
  # 数据库索引
  database: 0
  # 连接超时时间（毫秒）- 10秒
  connectTimeout: 10000
  # 命令等待超时时间（毫秒）- 3秒
  timeout: 3000
  # 连接池大小
  connectionPoolSize: 64
  # 最小空闲连接数
  connectionMinimumIdleSize: 1
  # 订阅连接池大小
  subscriptionConnectionPoolSize: 1
  # 重试次数
  retryAttempts: 3
  # 重试间隔（毫秒）
  retryInterval: 1500
  # 空闲连接超时（毫秒）- 10分钟
  idleConnectionTimeout: 600000
  # DNS监控间隔（毫秒）- 5秒
  dnsMonitoringInterval: 5000

# 线程池配置
threads: 4
nettyThreads: 4

注意事项：

  • address 必须包含 redis:// 协议前缀
  • YAML 块标量中不需要额外的双引号
  • 密码直接写值，不需要引号

3. 创建 RedisConfig 配置类

java 复制代码 
package com.agent.mall.config;

import org.redisson.Redisson;
import org.redisson.api.RedissonClient;
import org.redisson.config.Config;
import org.redisson.spring.cache.RedissonSpringCacheManager;
import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;

import java.io.IOException;

/**
 * Redis配置类（使用 Redisson）
 *
 * @author Claude Code
 * @date 2025-11-02
 */
@Configuration
@EnableCaching
public class RedisConfig {

    /**
     * 手动配置 RedissonClient Bean
     * 从 classpath:redisson-dev.yml 读取配置
     *
     * @return RedissonClient 实例
     * @throws IOException 如果配置文件读取失败
     */
    @Bean(destroyMethod = "shutdown")
    public RedissonClient redissonClient() throws IOException {
        // 从 classpath 读取 Redisson 配置文件
        Config config = Config.fromYAML(new ClassPathResource("redisson-dev.yml").getInputStream());
        return Redisson.create(config);
    }

    /**
     * 配置缓存管理器（使用 Redisson）
     *
     * @param redissonClient Redisson 客户端
     * @return CacheManager 实例
     */
    @Bean
    public CacheManager cacheManager(RedissonClient redissonClient) {
        // 使用 Redisson 的 Spring Cache 管理器
        return new RedissonSpringCacheManager(redissonClient);
    }
}

关键点：

  • @Bean(destroyMethod = "shutdown")：确保应用关闭时正确释放连接
  • 不使用 @ConditionalOnMissingBean：确保我们的配置优先生效
  • Config.fromYAML()：直接从文件加载配置

4. 不需要在 application-dev.yml 中配置

由于使用手动配置方式，不需要 在 application-dev.yml 中添加 Redisson 相关配置。

如果之前添加了以下配置，请删除：

yaml 复制代码 
# ❌ 删除这段配置
spring:
  redisson:
    file: classpath:redisson-dev.yml

或者

yaml 复制代码 
# ❌ 删除这段配置
spring:
  redisson:
    config: |
      singleServerConfig:
        address: redis://...

使用示例

基础使用

java 复制代码 
@Autowired
private RedissonClient redissonClient;

public void example() {
    // 使用 RBucket 存储简单键值对
    RBucket<String> bucket = redissonClient.getBucket("key");
    bucket.set("value", 10, TimeUnit.MINUTES);

    String value = bucket.get();
    bucket.delete();
}

替代 RedisTemplate

如果之前使用 RedisTemplate，可以改用 Redisson API：

RedisTemplate 方式：

java 复制代码 
@Autowired
private RedisTemplate<String, String> redisTemplate;

redisTemplate.opsForValue().set("key", "value", 10, TimeUnit.MINUTES);
String value = redisTemplate.opsForValue().get("key");
redisTemplate.delete("key");

Redisson 方式：

java 复制代码 
@Autowired
private RedissonClient redissonClient;

RBucket<String> bucket = redissonClient.getBucket("key");
bucket.set("value", 10, TimeUnit.MINUTES);
String value = bucket.get();
bucket.delete();

高级特性

Redisson 提供了许多高级特性：

java 复制代码 
// 分布式锁
RLock lock = redissonClient.getLock("myLock");
lock.lock();
try {
    // 业务逻辑
} finally {
    lock.unlock();
}

// 分布式限流器
RRateLimiter rateLimiter = redissonClient.getRateLimiter("myRateLimiter");
rateLimiter.trySetRate(RateType.OVERALL, 10, 1, RateIntervalUnit.SECONDS);
if (rateLimiter.tryAcquire()) {
    // 允许访问
}

// 布隆过滤器
RBloomFilter<String> bloomFilter = redissonClient.getBloomFilter("myFilter");
bloomFilter.tryInit(10000, 0.01);
bloomFilter.add("element");
boolean exists = bloomFilter.contains("element");

常见坑点和解决方案

1. 连接 localhost 而非配置的地址

症状：

复制代码 
Unable to connect to Redis server: localhost/127.0.0.1:6379

原因：

  • Redisson Starter 的自动配置未读取到配置文件
  • 使用了内联 YAML 配置但 Starter 不支持

解决方案：

  • 使用手动配置方式（如本文档所述）
  • 不在 application.yml 中配置 Redisson，完全通过 RedisConfig.java 配置

2. YAML 配置中的引号问题

错误示例：

yaml 复制代码 
address: "redis://47.56.78.87:6379"  # ❌ 多余的引号
password: "dfgg2h3b4bv57d3b"          # ❌ 多余的引号

正确示例：

yaml 复制代码 
address: redis://47.56.78.87:6379    # ✅ 不需要引号
password: dfgg2h3b4bv57d3b             # ✅ 不需要引号

说明 ：在 YAML 文件中，除非有特殊字符，否则不需要引号。redis:// 协议前缀是必须的。

3. 与 Spring Data Redis 冲突

症状：

  • 同时存在 RedisTemplate 和 RedissonClient 的配置
  • 启动时出现 Bean 冲突错误

解决方案：

  • 移除 spring-boot-starter-data-redis 依赖
  • 删除 application.yml 中的 spring.data.redis 配置
  • 统一使用 Redisson

4. Sa-Token 整合问题

配置要点：

  • Sa-Token 可以同时使用 Redisson
  • 依赖 sa-token-redis-jackson 即可
  • 不需要额外配置，Sa-Token 会自动使用 Spring 容器中的 RedissonClient

5. 配置文件未找到

症状：

复制代码 
FileNotFoundException: class path resource [redisson-dev.yml] cannot be opened

解决方案：

  • 确保配置文件在 src/main/resources/ 目录下
  • 检查文件名是否正确（注意大小写）
  • 确保配置文件被打包到 jar 中

6. 编码问题

注意：

  • 配置文件统一使用 UTF-8 编码
  • 避免使用 GBK/ANSI 编码

连接池参数优化建议

根据不同场景调整连接池参数：

低并发场景（推荐配置）

yaml 复制代码 
connectionPoolSize: 16              # 连接池大小
connectionMinimumIdleSize: 1        # 最小空闲连接
subscriptionConnectionPoolSize: 1   # 订阅连接

中等并发场景

yaml 复制代码 
connectionPoolSize: 64
connectionMinimumIdleSize: 10
subscriptionConnectionPoolSize: 5

高并发场景

yaml 复制代码 
connectionPoolSize: 128
connectionMinimumIdleSize: 32
subscriptionConnectionPoolSize: 10

完整配置示例

项目结构

复制代码 
src/main/
├── java/
│   └── com/agent/mall/
│       ├── config/
│       │   └── RedisConfig.java          # Redisson 配置类
│       └── controller/
│           └── WxOpenController.java     # 使用 Redisson 的示例
└── resources/
    ├── application.yml                    # 主配置
    ├── application-dev.yml                # 开发环境配置（无需 Redisson 配置）
    └── redisson-dev.yml                   # Redisson 配置文件

总结

使用 Redisson 与 Spring Boot 3.4 整合时，关键点：

  1. ✅ 手动配置优于自动配置：避免 Starter 自动配置的坑
  2. ✅ 独立配置文件：将 Redisson 配置放在独立的 YAML 文件中
  3. ✅ 不要双引号：YAML 配置中不需要额外的引号
  4. ✅ 协议前缀必须 ：地址必须包含 redis:// 前缀
  5. ✅ 避免混用：不要同时使用 RedisTemplate 和 Redisson，统一使用 Redisson

遵循本文档的配置方式，可以避免大部分常见问题，实现稳定可靠的 Redis 连接。

相关推荐
何中应7 小时前
Spring Boot解决循环依赖的几种办法
java·spring boot·后端
donotshow7 小时前
SpringBoot】Spring Boot 项目的打包配置
java·后端
鬼火儿7 小时前
Spring Boot 整合 ShedLock 处理定时任务重复
java·后端
王元_SmallA7 小时前
【Spring Boot】Spring Boot解决循环依赖
java·后端
苦学编程的谢8 小时前
Redis_1_初识Redis+浅谈分布式系统
数据库·redis·缓存
洛卡卡了8 小时前
一次上线事故，我干脆写了套灰度发布系统
后端·面试·架构
Java水解8 小时前
【Spring Boot】Spring 魔法世界：Bean 作用域与生命周期的奇妙之旅
spring boot·后端
JohnYan8 小时前
Bun技术评估 - 26 Abort
javascript·后端·bun
逛逛GitHub8 小时前
国产首个开源 AI 原生后端平台，这次是真起飞了。
后端·github
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03BongoCat - 跨平台键盘猫动画工具04《大数据技术原理与应用》实验报告三 熟悉HBase常用操作05Linux下V2Ray安装配置指南06NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南07jdk21下载、安装（Windows、Linux、macOS）08GitLab 零基础入门指南：从安装到项目管理全流程09安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）