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 连接。

相关推荐
爱勇宝19 小时前
第 1 章：别把“需求文档”当成真正的需求
前端·后端·程序员
IT_陈寒1 天前
闭包陷阱让我加了两天班，JavaScript你真行
前端·人工智能·后端
易协同低代码1 天前
通达OA核心类库TD类深度解析
后端
Gopher_HBo1 天前
Go语言学习笔记(十八)Gin处理Session
后端
谭光志1 天前
工具塞满上下文窗口怎么办？深度拆解 AI Agent Tool Search 按需加载实现原理
前端·后端·ai编程
她说..1 天前
Java 默认值设置方式
java·开发语言·后端·springboot
foggyprojects1 天前
从0开始，一句话启动AI DataAgent
后端·数据分析·ai编程
郡杰1 天前
一些基础和问题解决
后端
陈随易1 天前
前端项目部署只要30秒
前端·后端·程序员
YIAN1 天前
从零手写文件读取 MCP 服务：一文吃透 Model Context Protocol 全链路通信原理
前端·后端·mcp
热门推荐
01GitHub 镜像站点022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03AI科技热点日报 | 2026年07月01日04【AI】2026 年具身智能模型和世界模型总结05AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路062026 年 AI 大模型 & AI 编程工具实战全总结072026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？082026 AI 编程工具选型横评：Cursor / Claude Code / Trae / Copilot 到底选谁（建议收藏·避坑版）092026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？102026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片