Spring Boot 集成 Redis 这个话题只要是做后端的基本都绕不开。缓存加速、分布式锁、Session 共享、接口限流随便拎出来一个场景都能跟 Redis 扯上关系。我自己在项目里从最早的 Spring Boot 2.x 配 Jedis到后来切到 Lettuce再到现在 Spring Boot 3.x 默认集成中间踩过不少坑也积累了一些实战经验。这篇文章我不会只讲“怎么引入依赖、怎么写配置”这种表面功夫而是把 Redis 从安装部署、工具选择、Spring Boot 集成、序列化坑点、典型场景实战到问题排查完整过一遍。无论你是刚开始接触 Spring Boot 的新手还是已经用了 Redis 但经常遇到乱码、连接超时、缓存穿透这类问题的老手这篇文章都能给你一些可以参考的实操方案。1. 整体设计与思路拆解1.1 Redis 在 Spring Boot 项目中到底扮演什么角色很多初学者以为 Redis 就是一个缓存数据库其实它在实际项目里的作用远比“缓存”两个字要广得多。我接触过的 Spring Boot 项目里Redis 最常见的用途包括热点数据缓存用户信息、商品详情、配置项这类读多写少的数据放到 Redis 里能把数据库查询压力降一个量级。分布式锁多实例部署时用 Redis 的 SETNX 实现跨进程互斥解决库存扣减、订单创建这类并发问题。分布式 Session 存储多实例部署时把 Session 存到 Redis保证用户登录状态不丢。接口幂等与限流用 INCR EXPIRE 做滑动窗口计数用 SETNX 做防重标记。消息队列轻量版Redis 的 List 结构配合 BRPOP 可以做一个简单的异步任务队列适合中小型项目。理解这些用途之后再回头配置 Spring Boot 和 Redis思路就会清晰很多核心就是处理两个问题——连接管理和数据序列化。连接管不好高并发下连接池直接被打满序列化搞不明白缓存里全是乱码查数据的时候反序列化又报错。1.2 Spring Boot 版本选型2.x 还是 3.x这个问题在技术群里讨论频率特别高尤其是热词里既有 Spring Boot 2.3.x、2.6.x也有 Spring Boot 3说明很多人还处于迁移或者选型阶段。我的建议很直接新项目优先选 Spring Boot 3.x。它要求 Java 17 以上性能和安全都有提升Spring Data Redis 3.x 也一起更新配置模型更清爽。老项目如果还在 Java 8老老实实用 Spring Boot 2.6.x 或 2.7.x不要强行升 3.x否则依赖冲突会折磨到怀疑人生。Spring Boot 2.0 到 2.2 这种太老的版本就不要再用了很多 Redis 连接池参数、响应式支持都不够完善。关于客户端选择Spring Boot 2.x 默认用 LettuceSpring Boot 3.x 继续默认 Lettuce。Jedis 虽然老牌但在并发场景下性能和可靠性都不如 Lettuce而且 Lettuce 天然支持响应式。所以我的结论是不用纠结直接用默认的 Lettuce 就行。1.3 一个清晰的项目全景图先给大家一个整体的项目结构参考后面所有实操内容都围绕这个图展开基础层Redis 服务器单机、主从或集群 可视化工具 连接池配置。集成层Spring Boot 项目引入spring-boot-starter-data-redis配置 Lettuce 连接工厂和 RedisTemplate。增强层配置 RedisCacheManager缓存注解、封装分布式锁工具类、定义 Key 统一前缀规则。应用层缓存服务、Token 存储、接口限流、异步队列等具体业务场景。这样拆完之后每一层都有独立的关注点。比如基础层要解决“Redis 装哪、怎么连”集成层要解决“代码里怎么操作”增强层要解决“序列化规范和并发安全”。下面我按照这个顺序逐一展开。2. 环境准备Redis 安装、启动与可视化工具2.1 开发环境里最快跑通 Redis 的方式热词里出现了大量“Redis 下载”“Windows 安装 Redis”“macOS 安装 Redis”“docker安装redis主从”说明环境安装是很多人的第一道坎。我这里按平台给出最简单且稳定的方案。Windows 下安装 Redis 的经典方式是去 Redis 官方 Windows 移植版或者 GitHub 仓库下载 zip 包解压后直接运行redis-server.exe启动服务再开一个窗口运行redis-cli.exe ping能返回 PONG 就说明 OK。不过 Windows 下的 Redis 版本更新偏慢生产环境不推荐用 Windows 跑 Redis开发调试完全够用。macOS 下推荐用 Homebrew两条命令搞定brew tap redis-stack/redis-stack brew install redis-stack然后前台启动用redis-server后台启动用brew services start redis配置文件默认在/usr/local/etc/redis.conf。Linux 服务器上我习惯用编译安装或者包管理器安装。CentOS 用 yumUbuntu 用 apt。生产环境我会倾向 Docker 部署一条命令就能拉起单机版docker run -d --name redis \ -p 6379:6379 \ -v /data/redis:/data \ redis:7.2-alpine \ redis-server --appendonly yes --requirepass yourpassword注意--appendonly yes是开启 AOF 持久化数据安全很重要。--requirepass用于设置访问密码。开发环境可以不设密但只要你把 Redis 端口暴露到服务器外网就一定要加密否则 Redis 会被扫描器攻击轻则数据被清空重则被写入恶意数据。热词里有一条很具体的报错docker search redis request returned 500 internal server error ... dockerdesktoplinuxengine。这个问题我在 Windows Docker Desktop 上也碰到过本质是 Docker Desktop 内部的 Linux 引擎与 Docker Registry 通信异常。处理办法分三步先重启 Docker Desktop如果还不行就用docker search换一个 registry 或者直接跳过 search 用docker pull redis拉取镜像最后再看 Docker Desktop 的 WSL 内核版本是否需要更新。等这一步解决之后后面的docker run就顺畅了。2.2 可视化工具选择Redis Desktop Manager 还是 Another Redis Desktop Manager热词里“Redis Desktop Manager”“Another Redis Desktop Manager”“redis可视化工具”反复出现。我个人的结论是Another Redis Desktop Manager简称 ARDM更推荐。它是开源免费的相比老牌 Redis Desktop Manager 去掉了商业授权限制功能一点不落后支持连接管理、命令窗口、数据浏览、Key 过期监控还支持暗黑模式。Redis Desktop Manager 公司版虽然功能强但免费版很多高级功能被锁定没必要折腾。IDE 插件也是一个选项比如 IntelliJ IDEA 的 Redis 插件适合不想额外开软件的同学但功能比较简单。连接可视化工具的配置很简单填主机地址、端口默认 6379、密码如果有测试连接通过即可。有几个小技巧值得记住生产环境的 Redis 端口不要暴露公网用 SSH 隧道连接可视化工具连接成功后不要随便在生产环境执行 FLUSHALL 或者 KEYS *前者是清库后者在大 Key 下会阻塞 Redis。2.3 Redis 配置里必须知道的几个参数不管哪个平台安装以下几个配置项都是重点bind监听的 IP 地址。默认 127.0.0.1 只允许本机访问改成0.0.0.0意味着所有网卡可访问安全性急剧下降。protected-mode保护模式默认开启在没有认证密码时只允许本机访问。requirepass设置访问密码。热词里专门有一条“windows设置redis密码”说明很多人有加密需求。在 Windows 上设置密码的方式是在 redis.windows.conf 里找到requirepass行取消注释并改成自己的密码然后重启 redis-server 时指定配置文件。maxmemoryRedis 能占用的最大内存。不设的话默认 64 位系统不限制容易出现内存打满的问题。maxmemory-policy内存淘汰策略。一般用allkeys-lru或volatile-lru推荐 volatile-lru避免把没有设置过期时间的 Key 也淘汰掉。这些参数不一定每个开发环境都要调但生产部署必须关注。后面在排查“内存增长”“Key 丢失”的时候这些配置往往是根源。3. Spring Boot 集成 Redis 的核心细节与实操要点3.1 引入依赖两种方式都列出来Spring Boot 集成 Redis 的起步操作很简单在pom.xml加入依赖。我给两个版本示例。Spring Boot 3.xdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependencySpring Boot 2.6.xdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency依赖坐标其实一样版本由 Spring Boot 父级依赖统一管理不需要手动写版本号。如果你还要用连接池需要额外引入 Commons Pool 2dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency不加这个依赖即使配置里写了连接池参数Lettuce 也不会真正启用连接池而是用默认的无池化连接模式。这一点容易忽略会导致高并发下连接数异常增长。3.2 YAML 配置常见参数和解释热词里有“spring boot 集成 web socket yml 配置”说明大家很关心 YML 配置的细节。Redis 这块的配置我直接给一份带注释的完整示例按 Spring Boot 2.6 和 3.x 通用的格式来写spring: data: redis: host: 127.0.0.1 port: 6379 password: 123456 database: 0 timeout: 5s lettuce: pool: max-active: 16 max-idle: 8 min-idle: 0 max-wait: 3000ms几个容易踩坑的地方Spring Boot 2.x 早期版本的配置前缀是spring.redisSpring Boot 3.x 改成了spring.data.redis。新老配置混用是常见报错原因3.x 里写spring.redis.host不会报错但配置不生效连接的时候还是走默认 127.0.0.1。database选项表示使用哪个逻辑库Redis 默认有 16 个 db0-15默认走 0 号库。多业务隔离时可以用不同 database但生产环境通常不推荐集群模式下database只能为 0。timeout是连接超时时间不是读写超时。真正的读写超时控制可以在连接工厂层面配置后面我会提到。max-active和max-wait要结合业务并发量设置。设太大会浪费资源设太小高并发下会抛Cannot get Jedis connection或者 Lettuce 的连接等待异常。如果是 Spring Boot 3.xLettuce 的配置模型还能用spring.data.redis.lettuce.pool这套参数但注意版本升级后部分参数语义有调整。比如max-pool-size之类的命名变化建议查阅对应的版本文档不要照抄老配置。3.3 RedisTemplate别直接用默认 BeanSpring Boot 自动配置会提供一个 RedisTemplate 和 StringRedisTemplate但默认的 RedisTemplate 用的是 JdkSerializationRedisSerializer。这个序列化方式有几个问题可读性差缓存的 Key 和 Value 在 Redis 里是一堆二进制乱码跨语言兼容性差如果别的服务也要读这份数据基本没法读反序列化时还容易抛 ClassCastException。我习惯的做法是自定义一个 RedisTemplate BeanKey 用 StringRedisSerializerValue 用 GenericJackson2JsonRedisSerializer。这样 Key 在 Redis 里清晰可读Value 自动存成 JSON调试和排查都方便。Configuration public class RedisConfig { Bean public RedisTemplateString, Object redisTemplate( RedisConnectionFactory connectionFactory) { RedisTemplateString, Object template new RedisTemplate(); template.setConnectionFactory(connectionFactory); // Key 使用 String 序列化 StringRedisSerializer keySerializer new StringRedisSerializer(); // Value 使用 JSON 序列化 GenericJackson2JsonRedisSerializer valueSerializer new GenericJackson2JsonRedisSerializer(); template.setKeySerializer(keySerializer); template.setHashKeySerializer(keySerializer); template.setValueSerializer(valueSerializer); template.setHashValueSerializer(valueSerializer); template.afterPropertiesSet(); return template; } }注意这里的GenericJackson2JsonRedisSerializer会在序列化时写入class信息这样反序列化才能恢复成原来的 Java 对象类型。代价是 JSON 体积会略大Redis 内存占用略高。如果你确定所有缓存对象都放到一个固定的 DTO 类型可以用Jackson2JsonRedisSerializerMyDTO精确指定泛型JSON 更干净反序列化更可靠。热点词里有“redis序列化”这条说明被乱码困扰的人不少。我再补一个判断方法用 Redis 可视化工具打开一个 Key如果看到的是以\xAC\xED\x00\x05t开头的二进制乱码那基本可以确定是默认序列化器在作祟。换成 String JSON 之后看到的就应该是直接可读的字符串。3.4 用 RedisTemplate 操作五大基本数据类型Redis 的核心是数据结构和命令Spring Boot 的 RedisTemplate 只是把命令封装成了 Java API。常用的操作对象有五类String 字符串对应opsForValue()。最典型的就是缓存一个对象的 JSON 字符串、计数器、验证码。Hash 哈希对应opsForHash()。适合存对象字段比如用户信息的一部分字段单独更新。List 列表对应opsForList()。可以用作消息队列左推右取、右推左取。Set 集合对应opsForSet()。适合标签、好友关系、去重。ZSet 有序集合对应opsForZSet()。适合排行榜、延时队列、滑动窗口计数。给大家一段覆盖常见操作的示例代码Service public class RedisDemoService { private final RedisTemplateString, Object redisTemplate; public RedisDemoService(RedisTemplateString, Object redisTemplate) { this.redisTemplate redisTemplate; } /** 字符串缓存 */ public void cacheString(String key, String value, long timeout, TimeUnit unit) { redisTemplate.opsForValue().set(key, value, timeout, unit); } /** 带超时的对象缓存 */ public void cacheObject(String key, Object value, long timeout, TimeUnit unit) { redisTemplate.opsForValue().set(key, value, timeout, unit); } /** Hash 操作 */ public void hashPut(String key, String field, Object value) { redisTemplate.opsForHash().put(key, field, value); } /** 左侧推入队列 */ public void lpush(String queueName, Object message) { redisTemplate.opsForList().leftPush(queueName, message); } /** 右侧阻塞弹出队列 */ public Object rpop(String queueName, long timeout, TimeUnit unit) { return redisTemplate.opsForList().rightPop(queueName, timeout, unit); } /** 分布式锁的最简实现 */ public boolean tryLock(String lockKey, String requestId, long expireSeconds) { return redisTemplate.opsForValue() .setIfAbsent(lockKey, requestId, expireSeconds, TimeUnit.SECONDS); } /** 释放分布式锁 */ public boolean releaseLock(String lockKey, String requestId) { String value (String) redisTemplate.opsForValue().get(lockKey); if (requestId.equals(value)) { return redisTemplate.delete(lockKey); } return false; } }setIfAbsent就是 Redis 的 SETNX 命令设置了过期时间天然适合做分布式锁。这个小工具类的写法只是教学示例生产级别的锁还要处理 Lua 脚本保证“判断和删除”的原子性这些问题我在后面场景实战里详细讲。3.5 缓存注解Cacheable、CachePut、CacheEvict 的使用用 RedisTemplate 操作缓存是显式控制而 Spring 的缓存注解则是声明式控制代码更简单。要启用注解缓存首要条件是配置一个缓存管理器我这里用 RedisCacheManager 并且定制了 Key 和 Value 的序列化方式Bean public RedisCacheManager cacheManager(RedisConnectionFactory factory) { RedisCacheConfiguration config RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(30)) .serializeKeysWith(RedisSerializationContext.SerializationPair .fromSerializer(new StringRedisSerializer())) .serializeValuesWith(RedisSerializationContext.SerializationPair .fromSerializer(new GenericJackson2JsonRedisSerializer())) .disableCachingNullValues(); return RedisCacheManager.builder(factory) .cacheDefaults(config) .build(); }然后就可以在 Service 层直接用注解Cacheable(value userCache, key #userId) public User getUserById(Long userId) { // 查数据库或调用远程服务 return userMapper.selectById(userId); } CachePut(value userCache, key #user.id) public User updateUser(User user) { userMapper.updateById(user); return user; } CacheEvict(value userCache, key #userId) public void deleteUser(Long userId) { userMapper.deleteById(userId); }这套注解的使用逻辑值得展开说一下Cacheable先查缓存命中则直接返回未命中则执行方法并将结果写入缓存。适合读多写少的查询场景。CachePut每次都会执行方法并把返回值更新到缓存。适合更新场景能保证缓存内容不过期太久。CacheEvict方法执行后删除指定缓存。适合删除场景。CacheEvict(allEntries true)一次清空该缓存区域下的所有 Key适合全量变更场景。需要提醒的是缓存注解是代理生效机制在同一个类里调用同一个类的带缓存注解方法代理不生效缓存不会命中。比如outterMethod()里调用this.innerCacheMethod()注解是无效的。解决办法是把缓存方法拆到另一个 Bean 中或者自己注入代理对象。4. 典型场景实战缓存治理、分布式锁、WebSocket 与接口设计4.1 缓存治理穿透、击穿、雪崩的应对套路热词里有“redis缓存治理”和“redis缓存”两条缓存治理确实是生产里最考验功力的环节。要讲清楚这个问题先定义三个常见问题缓存穿透查询一个根本不存在的数据缓存和数据库都没有请求直接打到数据库。恶意攻击者可以用大量不存在的 Key 打垮数据库。缓存击穿某个热点 Key 过期瞬间大量请求同时打到数据库。缓存雪崩大量 Key 同时过期或者 Redis 服务直接宕机导致数据库压力骤升。针对穿透最常用的是布隆过滤器或者缓存空值。缓存空值的实现很直接查询数据库结果为空时往 Redis 写一个空对象并设置较短过期时间比如 60 秒后续同样的查询直接返回空数据库压力就被挡掉了。注意空值 Key 的过期时间不能太长否则大量穷举 Key 会让 Redis 内存涨得很快。针对击穿手段是加互斥锁。热点 Key 过期后不是所有请求都直接去查库而是先用 Redis 的分布式锁锁住让一个线程去查库并重建缓存其他线程短暂等待后直接读新缓存。这里有一个细节锁的过期时间不能太短否则锁提前失效其他线程还是会一起打到数据库。针对雪崩一是设置过期时间时加随机扰动让 Key 的过期时间分布错开二是做多级缓存比如本地 Caffeine Redis 双缓存Redis 挂了本地还有兜底三是给 Redis 集群做高可用从主从复制到哨兵再到 Cluster根据业务量选择。我这里放一个最简单的缓存防击穿示例用redisTemplate实现互斥重建public User getUserWithLock(Long userId) { String key user: userId; User user (User) redisTemplate.opsForValue().get(key); if (user ! null) { return user; } // 尝试获取分布式锁 String lockKey lock:user: userId; String requestId UUID.randomUUID().toString(); boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, requestId, 10, TimeUnit.SECONDS); if (locked) { try { // 二次检查缓存因为可能已经有线程重建过缓存 user (User) redisTemplate.opsForValue().get(key); if (user ! null) { return user; } user userMapper.selectById(userId); redisTemplate.opsForValue().set(key, user, 30, TimeUnit.MINUTES); return user; } finally { // 释放锁需要校验请求ID if (requestId.equals(redisTemplate.opsForValue().get(lockKey))) { redisTemplate.delete(lockKey); } } } else { // 未拿到锁短暂休眠后重试 Thread.sleep(50); return getUserWithLock(userId); } }这个写法里最重要的一个点是“二次检查缓存”英文叫 double-check。如果不做二次检查两个并发线程都会认为缓存没命中第一个线程重建缓存后第二个线程拿到锁还会再次查库重建互斥锁就失去意义了。4.2 分布式锁从手写 SETNX 到 Redisson 的演进热词里有“redis分布式锁”和“redis incr不准”这两个其实都指向并发场景下的原子性问题。手写 SETNX 方案有两个经典坑第一是锁的续期问题。我设置锁过期时间 10 秒但业务逻辑执行了 15 秒锁已经自动释放了别的线程又能获得锁并发安全被破坏。第二是主从切换问题在主从或哨兵架构下锁在主节点写入但还没有同步到从节点时主节点挂了从节点升级为主节点锁就丢失了。所以生产环境我强烈建议用 Redisson 分布式锁它是基于 Redis 的成熟实现内置看门狗机制自动续期还支持红锁解决主从切换场景。Autowired private RedissonClient redissonClient; public void businessWithLock() { RLock lock redissonClient.getLock(biz:lock:order:create); boolean isLocked false; try { // 尝试加锁最多等待3秒锁自动释放时间30秒 isLocked lock.tryLock(3, 30, TimeUnit.SECONDS); if (isLocked) { // 执行业务逻辑 doBiz(); } } catch (InterruptedException e) { Thread.currentThread().interrupt(); } finally { if (isLocked lock.isHeldByCurrentThread()) { lock.unlock(); } } }Redisson 集成方式也很简单依赖上加入redisson-spring-boot-starter配置文件中加入spring: data: redis: host: 127.0.0.1 port: 6379 redisson: config: | singleServerConfig: address: redis://127.0.0.1:6379 connectionPoolSize: 16 connectionMinimumIdleSize: 4这里我采用redisson-spring-boot-starter它会自动读取 Spring 的 Redis 配置并创建 RedissonClient。注意 Redisson 的配置格式比较严格redis://前缀不能省略否则会报连接地址非法。热词里“redis incr不准”很少被人注意但它反映了一个真实问题用 INCR 做计数器时如果并发量巨大Redis 单线程模型下的计数其实是准确的只是在集群模式下多个节点各自计数汇总时才不准。所以不要把计数逻辑拆到多个 Redis 节点上计数必须打到一个固定的 Key 上。另一个情况是用 INCR 之后没有设置合理的过期时间导致 Key 长期残留这个不是“不准”而是统计口径的问题。4.3 Spring Boot 集成 WebSocket 时 Redis 的作用热词里出现了“spring boot 集成 web socket yml 配置”看起来有点跳跃但在真实项目里两者经常一起出现。WebSocket 在分布式部署下有个经典问题用户 A 连着节点 1用户 B 连着节点 2A 发消息时节点 1 不知道该怎么转发给 B 所连的节点 2。解决方案之一就是用 Redis 的发布订阅Pub/Sub做消息中转。节点 1 收到 WebSocket 消息后把消息 publish 到 Redis 频道chat:room:1001所有订阅了该频道的节点都能收到再各自判断连接的用户并推送。实现方式很简单先定义一个消息监听器Component public class RedisMessageListener implements MessageListener { Autowired private WebSocketMessageSender sender; Override public void onMessage(Message message, byte[] pattern) { String channel new String(message.getChannel()); String payload new String(message.getBody()); sender.sendToClients(channel, payload); } }然后在配置类里注册监听容器Configuration public class RedisPubSubConfig { Bean public RedisMessageListenerContainer container( RedisConnectionFactory connectionFactory, RedisMessageListener listener) { RedisMessageListenerContainer container new RedisMessageListenerContainer(); container.setConnectionFactory(connectionFactory); container.addMessageListener(listener, new PatternTopic(chat:room:*)); return container; } }发送消息的代码redisTemplate.convertAndSend(chat:room: roomId, messageBody);这个场景在实际项目中很实用而且和 YML 配置关系不大主要靠 Java 配置类。唯一需要注意的就是 Redis 过期消息的可靠性Pub/Sub 是实时推送的订阅者不在线就会丢失消息如果对可靠性要求高要改用 Stream 或者持久化队列。4.4 对外接口设计时 Redis 的辅助价值热词里有一条很有意思的问题“spring boot对外提供的接口(给第三方)应该放在哪里是单独的服务还是放在对应的服务里”。这个问题和 Redis 看似无关但跟接口架构有关联。我的经验是对外 API 优先单独建一个服务模块通过统一网关暴露。这样做的好处是隔离第三方流量、安全策略、限流和监控可以在网关层统一处理。在这个架构里Redis 的用处非常直接接口凭据存储第三方应用的 AppKey、AppSecret 放在 Redis 里鉴权时快取快查。接口访问令牌生成 Token 存 Redis设置有效期做到一次签发多次使用。调用频率限制用 INCR EXPIRE 实现每个 AppKey 每分钟调用次数的计数。幂等标记用 SETNX 存请求唯一编号防止第三方重试导致重复重复提交。灰度路由把白名单用户或已开放的新接口路径存到 Redis动态控制对外行为。如果把这些逻辑放在独立服务里Redis 正好承担大部分共享状态不会让各个内部服务各自维护一份不一致的状态。5. 常见问题与排查技巧实录5.1 高频问题速查表我把项目里遇到的、以及热词里互相呼应的高频问题整理成一个速查表大家可以直接对照排查。现象常见原因处理方式RedisTemplate 操作报连接超时Redis 服务未启动防火墙拦截host 配置错误先用 redis-cli ping 验证服务再检查 YML 配置连接失败且无错误日志Spring Boot 3 用了新配置前缀 spring.data.redis老配置没生效检查配置项层级是否正确缓存 Key 出现二进制乱码使用了默认 JdkSerializationRedisSerializer自定义 RedisTemplateKey 用 StringRedisSerializer缓存 Value 反序列化报错GenericJackson 序列化后类型变化或缺少无参构造DTO 提供无参构造函数或指定具体的 Jackson 序列化器高并发下获取连接超时连接池太小或业务操作耗时太长调大 max-active优化业务代码避免大 Value 操作List 队列消费重复弹出后处理失败没有重新入队引入处理失败重试机制或用 Stream 实现消费者组Redis 内存增长过快大量缓存 Key 未设置过期时间检查缓存注解 TTL检查redis-cli --bigkeys大 Key缓存和数据库数据不一致更新数据库后没有清理缓存或写双份规范使用 CachePut 和 CacheEvict先更新库再清缓存Docker search redis 返回 500Docker Desktop 引擎异常或 registry 通信问题重启 Docker Desktop或直接用 docker pull redis集群模式下 INCR 计数不准计数 Key 分散到不同节点Key 加 hash tag确保同一逻辑 Key 落到同一槽位5.2 三个值得单独说透的排查案例案例一Redis 连接被拒但 YML 看着没问题。有一个同事调试了半天最后发现是 Redis 服务绑定在 127.0.0.1而 Spring Boot 部署在 Docker 容器里容器内访问宿主机的 127.0.0.1 自然是拒绝的。解决方法是让宿主机 Redis 监听0.0.0.0或者容器内配置访问宿主机网关地址比如 Windows 上用host.docker.internalLinux 上用容器网关 IP。这个坑在本地开发环境里特别常见特别是用 Docker Desktop 跑应用时。案例二缓存穿透引发数据库偶发卡顿。查出原因是某些查询不存在的 Key 每次都查库因为缓存注解默认不缓存空值。处理方式是在RedisCacheConfiguration里暂时不要用disableCachingNullValues()或者手动维护一个“空值缓存”逻辑。业务能容忍的情况下缓存空值 短过期是性价比最高的方案。案例三Redis 慢查询导致接口变慢。排查时发现一个 List 操作每次都是LRANGE key 0 -1取全量数据数据量大之后单次操作耗时几十毫秒并发上来直接把 Redis 拖垮。处理方式是把大数据拆成分页读取或改用 Hash/Set 结构替代。这个案例教会我一个习惯上线前用redis-cli的 monitor 模式或者慢日志命令检查一下有没有 O(N) 级别的大 Key 操作。5.3 实操心得Redis 键设计、监控与日志规范键设计这件事越早定规范越省心。我推荐统一的 Key 模式业务名:模块名:业务ID:字段名比如用户缓存键就是biz:user:1024:profile订单锁就是biz:order:lock:20250101001。好处是可视化工具里一眼能看出 Key 归属排查问题时能快速按前缀过滤也不容易发生 Redis Key 冲突。监控方面Spring Boot 官方提供了 Actuator 的 Redis HealthIndicator但是颗粒度太粗。我建议在项目里至少做这几个指标的记录Redis 操作耗时、连接数、Key 的数量变化、缓存命中率。可以通过 AOP 拦截 RedisTemplate 方法统计耗时和异常。这个增量投入很值得生产环境 Redis 出问题的时候这些数据能帮你快速定位是网络问题、数据问题还是代码问题。日志方面值得注意不要把大 Value 直接打印到日志里也不要在日志里打印敏感数据。排查问题时可以先打印 Key再通过可视化工具或者redis-cli get查看具体值。另外 Redis 本身的运行日志可以在 redis.conf 里配置loglevel和logfile遇到异常时先翻 Redis 日志很多时候比翻应用栈更有用。6. 我对 Spring Boot 集成 Redis 的一些实在建议说到最后分享几条我踩过坑之后形成的习惯。第一前缀配置和序列化方案必须在项目第一天就定好半路改序列化方式会牵扯到线上缓存数据的兼容问题非常痛苦。第二宁可业务代码多写几行也不要把 Redis 操作散落得到处都是建议统一封装在一个 RedisService 或者基于 AOP 的缓存工具类里后续加监控、加埋点都方便。第三Redis 的价值在缓存之外分布式锁、幂等、限流、消息这些场景的开发建议花点时间把 Redisson 和 Spring Data Redis Stream 用熟练它们比手写原生命令更可靠。再补一个小技巧开发调试时用redis-cli --scan --pattern biz:user:*可以快速列出某个业务前缀下的所有 Key比连接可视化工具更轻量。做全量基线检查时用redis-cli --bigkeys能找出大 Key这是排查内存膨胀的第一工具。Spring Boot 集成 Redis 本质上就是一个“连接配置 序列化策略 场景封装”的组合拳。把这三个层面的细节吃透后续不管遇到缓存穿透、分布式锁失效还是数据不一致你都能快速找到根因而不是病急乱投医。希望这篇长文能帮大家少走点弯路。