Spring Boot 整合 Redis听起来像是无数教程写过的话题但我实际带项目时发现大部分人卡住的点根本不在“代码不会写”而在“不知道整合前要想清楚什么、装好之后如何验证、以及序列化配置为什么这么关键”。这篇文章我想换个角度看这套“整合步骤”先帮你想清楚场景再把环境准备成一个能跑通的状态然后是最基础的键值写入接着专门拆解序列化这个重灾区最后把分布式锁和缓存注解这些常用扩展一并讲透。标题里提到的 Spring Boot 和 Redis 这两个关键词在下面的内容里会作为主线贯穿始终。我不打算讲特别悬的架构只讲一个后端工程师在真正干活时最需要掌握的整合过程。无论你是刚接触 Spring Boot 的初学者还是在公司接手了一个已经能跑但偶尔出诡异缓存问题的老项目这篇内容都可以当作战术参考直接用。1. 先问清楚你的项目到底为什么要接 Redis很多教程一上来就让你加依赖、写配置然后跑一个 “Hello World” 的 Set/Get告诉你整合完成了。但说实话这一步人人都能跟着抄真正值钱的判断是你知不知道这个 Redis 在你的系统里扮演什么角色。Spring Boot 项目里引入 Redis最常见的理由是这几类。第一类是缓存。查询热点数据时每次都打 MySQL 会带来不必要的 IO 压力。尤其像用户信息、商品详情、配置字典这种读多写少、允许短暂不一致的数据放在 Redis 里能明显降低数据库负载。注意我说的是“允许短暂不一致”。如果你的业务要求强一致比如余额、库存那要谨慎使用缓存或者在设计缓存更新机制时下更多功夫。第二类是会话共享。单体应用还好一旦服务做了多实例部署用户的登录 Session 默认存在各自的 JVM 里就会出现“明明在 A 机器登录了请求被负载均衡转发到 B 机器结果 Session 又失效了”的问题。把 Session 存到 Redis多实例之间就能共享同一份数据。Spring Session Data Redis 这个子项目就是专门干这个事的它的整合思路和普通缓存整合不太一样但底层的连接、序列化思想是通用的。第三类是高并发场景下的限流与分布式锁。比如秒杀防超卖、防重复提交、接口限流。这类功能依赖 Redis 的原子操作比如INCR、EXPIRE、SETNX。它们不是你给 Redis 发一条指令就完事而是需要你认真设计 key、过期时间、释放锁时的原子性。这个我会在后面的章节专门展开。搞清楚为什么要用其实决定了你后面怎么做。如果只是缓存大部分时候你只需要StringRedisTemplate根本不需要折腾自定义的RedisTemplateObject, Object。如果要用对象缓存那序列化配置才是关键。如果要用分布式锁你要考虑网络抖动、锁误删、续期这些危险场景。不同的目标复杂度完全不一样。所以我的建议是在动手前先接受一句话Redis 不是一个“存字符串的网盘”而是一个支持原子操作、带过期机制的高性能数据结构服务器。只有理解了它的数据结构、过期策略和线程模型整合 Spring Boot 时才不会只是“配置一把梭”。2. 环境准备从零装一个能跑通的 Redis这一步看似基础但“安装完 Redis 后不知道测没测通”是很多新手整合失败的起点。咱们分平台来看不追求多高深目标是打开命令行能 ping 通能读写。在 macOS 上最简单的办法是用 Homebrew。打开终端输入brew install redis安装完成之后后台启动可以用brew services start redis如果只是想临时跑一下不想注册成服务直接运行redis-server也能把进程拉起来。默认端口6379配置文件通常在/opt/homebrew/etc/redis.conf或者/usr/local/etc/redis.conf取决于具体安装路径。在 Windows 上这点我多说两句。Redis 官方其实没有原生支持 Windows网上看到的各种 Windows 安装包大多是开源社区维护的移植版本。如果你只是本地开发两个比较省心的路子用 Docker 跑 Redis 容器使用 WSL 后在 Ubuntu 里安装 Redis。如果是公司开发环境直接用 Windows 桌面版 Redis 工具类的软件也行但生产环境强烈不建议用非官方版本。这个坑我见过稳定性达不到要求出问题还不好排查。在 Linux 上Debian/Ubuntu 系直接sudo apt update sudo apt install redis-server sudo systemctl enable redis-server sudo systemctl start redis-serverCentOS/RHEL 上则可能是yum install redis装完检查一下服务状态。装好后不要急着回去写 Java。先做两个验证redis-cli ping如果返回PONG说明服务起来了。再设置一个 key读一下redis-cli set name ming redis-cli get name能读到ming恭喜环境没问题。生产环境通常还要设置密码。可以在配置文件里把requirepass打开也可以动态设置redis-cli config set requirepass yourpassword redis-cli -a yourpassword pingSpring Boot 那边连接时就需要在配置里配密码字段。提前设置密码可以避免后面项目上线时 Redis 裸奔。除了密码可视化工具我也强烈建议配一个。只看命令行在数据量小的时候还行等 key 多起来你需要一个能看 TTL、看内存占用、看 key 前缀的工具。比较主流的RedisInsight官方出品的桌面客户端界面现代功能全Another Redis Desktop Manager开源社区常用轻量各种在线版的 Redis 客户端适合临时连接。我个人的习惯是开发环境用 RedisInsight 看配置信息和慢日志快速验证代码里写入的 key 是否膨胀、是否存在乱码。这个东西在排查序列化问题时特别好用等会儿你会体会到。3. 工程骨架到首个键值写入最小集成路线环境通了接下来就给 Spring Boot 项目装上依赖。这里有一个常见的概念混淆很多人以为spring-boot-starter-data-redis是 Redis 客户端本身其实不是。它是对 Spring Data Redis 的自动配置封装底层默认集成的是 Lettuce是 Spring 封装好的一套连接池和模板抽象。创建一个项目最省事的方式是到 Spring Initializr 官网生成或者用 IDE 自带的新建项目向导。依赖列表里勾上Spring Web和Spring Data Redis。如果要用缓存注解加上Spring Cache Abstraction相关支持Spring Boot 的 spring-boot-starter-cache 可以单独引。如果用 Mavenpom.xml里的核心依赖是这样的dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependencySpring Boot 3.x 之后默认的 Redis 客户端是 Lettuce如果你想换成 Jedis需要额外引spring-boot-starter-data-redis里排除掉 Lettuce再单独引 Jedis。不过 Lettuce 在大多数场景下已经足够默认用就可以没必要折腾。接下来是application.yml配置。基础配置长这样spring: data: redis: host: 127.0.0.1 port: 6379 password: yourpassword database: 0 timeout: 3s lettuce: pool: max-active: 8 max-idle: 8 min-idle: 0注意Spring Boot 2.x 时代的配置前缀是spring.redis.*到了 Spring Boot 3.x 改成了spring.data.redis.*。这个差异不知道坑了多少人。如果你使用的版本是 3.0 及以上却按网上的老教程写spring.redis.host配置会被直接忽略然后本地回报错或者默认去连本机 6379。连接池参数需要解释一下。max-active是连接池最多能分配的连接数max-idle是空闲连接上限min-idle是保持的最小空闲连接数。在高并发场景max-active太小会出现等待获取连接的异常但也不是越大越好连接数太大会把 Redis 机器拖垮。配置写完之后我先不急着往业务代码里塞 Redis而是用CommandLineRunner做一个最简单的验证。写一个启动执行器Component public class RedisSmokeTestRunner implements CommandLineRunner { private final StringRedisTemplate stringRedisTemplate; public RedisSmokeTestRunner(StringRedisTemplate stringRedisTemplate) { this.stringRedisTemplate stringRedisTemplate; } Override public void run(String... args) { stringRedisTemplate.opsForValue().set(boot:smoke, ok); String value stringRedisTemplate.opsForValue().get(boot:smoke); System.out.println(redis smoke value value); } }启动项目控制台如果能打印出redis smoke value ok说明整个最小链路已经通了Spring Boot 启动 - 创建连接池 - 执行命令 - 拿到返回值。从这一步开始后面所有玩法都有了地基。有人会问为什么用StringRedisTemplate而不是直接注入RedisTemplate因为StringRedisTemplate默认使用字符串序列化器读写字符串类型最省心不会出现 key 带乱码前缀的问题。等你需要存对象再考虑自定义RedisTemplate或者 JSON 序列化方案。4. 序列化不匹配Spring Boot 整合 Redis 最容易踩的坑如果你把整合看着是一门手艺序列化就是这门手艺里最容易翻车的环节。典型场景是这样的项目启动后用RedisTemplate写入一个User对象然后到客户端里一看key 是一长串类似\xac\xed\x00\x05t\x00\x03xxx的二进制乱码Value 也完全不可读。这不是 Redis 坏了而是默认序列化器在用 JDK 原生序列化方式把对象和字符串都变成了二进制字节流。Spring Data Redis 里RedisTemplate默认会使用JdkSerializationRedisSerializer这个序列化器有两个问题生成的字节流混乱难读而且序列化后的 key 会带类型信息。更麻烦的是如果实体类结构变化旧数据还会反序列化失败。我们理想的方案是key 用 String 序列化保持可读性value 对简单的字符串也保持原始可读value 对复杂对象使用 JSON 序列化器。下面这个自定义配置在项目里非常常用Configuration public class RedisConfig { Bean public RedisTemplateString, Object redisTemplate(RedisConnectionFactory connectionFactory) { RedisTemplateString, Object template new RedisTemplate(); template.setConnectionFactory(connectionFactory); StringRedisSerializer stringSerializer new StringRedisSerializer(); GenericJackson2JsonRedisSerializer jacksonSerializer new GenericJackson2JsonRedisSerializer(); template.setKeySerializer(stringSerializer); template.setHashKeySerializer(stringSerializer); template.setValueSerializer(jacksonSerializer); template.setHashValueSerializer(jacksonSerializer); template.afterPropertiesSet(); return template; } }这样配置之后写入一个对象User user new User(); user.setId(1L); user.setName(张三); redisTemplate.opsForValue().set(user:1, user);客户端里看到的就是一个可读的 JSON 字符串调试体验完全不同。但这里还有一个容易忽视的细节GenericJackson2JsonRedisSerializer在反序列化时依赖落盘数据里保存的class类型元信息。或者说它会在 JSON 里自动加一个类型字段。这也意味着如果你的应用升级了实体类的包名或类名旧数据可能无法正常反序列化。考虑向前兼容时有些人会选择手动指定 ObjectMapper 的默认类型或改用别的方案比如只存 DTO而不是把所有实体类直接塞进 Redis。序列化配置也不只是影响RedisTemplate缓存注解如Cacheable同样会受它影响。当你开启 Spring Cache 并把缓存管理器指向 RedisCacheManager 时默认的RedisCacheManager会创建自己的序列化配置。想要统一序列化还可能需要自定义RedisCacheConfigurationBean public RedisCacheManager cacheManager(RedisConnectionFactory connectionFactory) { RedisCacheConfiguration config RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(30)) .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer())) .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer())) .disableCachingNullValues(); return RedisCacheManager.builder(connectionFactory) .cacheDefaults(config) .build(); }如果缓存和业务查询用的是不同的序列化配置可能出现一种很分裂的现象你用redisTemplate写进去的数据用Cacheable读不到反过来也成立。所以我的经验是在一套代码里尽量把RedisTemplate和RedisCacheManager的序列化策略统一。尤其注意 key 的序列化方式最好全部用StringRedisSerializer。排查序列化问题时最直观的方法就是打开可视化客户端看 key 的前缀是否长得像人话。如果是人话说明 key 序列化没问题如果是一串十六进制乱码第一反应应该是查看代码里的 key 序列化器而不是猜数据存放逻辑。5. 从熟练使用到扩展实践缓存注解与分布式锁把基本的读写跑通后大多数项目会进入第二阶段用 Spring 的缓存注解或者实现一个分布式锁。这两个都是高频需求值得单独拆开讲。5.1 缓存注解的三板斧开启缓存注解只需在主类上添加EnableCaching。然后就可以在 Service 层的方法上使用CacheableCacheable(value userCache, key #id) public User getUserById(Long id) { return userMapper.selectById(id); }第一次调用时方法体执行并触发 SQL 查询结果被写入 Redis第二次调用直接命中缓存方法的查询逻辑不再执行。这个设计很简单但有一个隐含条件你必须在RedisCacheManager里定义好缓存 key 前缀和 TTL。value字段相当于一个逻辑区域Redis 里实际 key 会变成类似userCache::1的样子。更新和失效分别用CachePut和CacheEvict。CachePut会在方法执行后更新缓存适合主键修改的场景CacheEvict清空缓存适合删除场景。这里有个设计经验修改数据时要么用CachePut主动更新要么用CacheEvict直接删缓存让下次查询重新加载。两者都行但没有统一策略的话容易出现缓存里还是旧值的脏读。同时要注意一个常见的缓存陷阱是穿透。如果查询方法返回nullCacheable默认不会缓存空值。一旦某个不存在的 key 被频繁查询请求会逐个打到数据库。RedisCacheConfiguration里disableCachingNullValues()就是设置是否允许缓存空值。允许缓存空值可以防穿透但要小心缓存的是空对象策略上最好给空值设置一个较短的 TTL。5.2 分布式锁从能跑到跑到完全正确分布式锁是另一个高频需求。最简单的实现方式是利用 Redis 的STRING类型和SETNX语义如果 key 不存在就设置返回成功如果存在就失败。代码层面RedisTemplate对应的操作是Boolean locked stringRedisTemplate.opsForValue() .setIfAbsent(lock:order: orderId, holder, Duration.ofSeconds(30));这里用setIfAbsent加Duration是重点它能保证“加锁”和“设置过期时间”是一个原子操作。早期很多人分两步写先setnx再expire结果第一步成功、第二步失败时锁永远不释放直接把系统锁死。这个坑是真实出现过的。在释放锁时最怕的是 A 线程加的锁被 B 线程给解了。假设业务执行时间超过了锁的过期时间锁自动过期后 B 线程拿到锁然后 A 线程执行完直接调用delete(key)把 B 的锁删掉了系统又会走进并发失控。所以释放锁需要先校验持有者身份再看删除是否成功。简单写法可能长这样String lockKey lock:order: orderId; String token UUID.randomUUID().toString(); Boolean locked stringRedisTemplate.opsForValue() .setIfAbsent(lockKey, token, Duration.ofSeconds(30)); if (Boolean.TRUE.equals(locked)) { try { // 业务逻辑 } finally { String current stringRedisTemplate.opsForValue().get(lockKey); if (token.equals(current)) { stringRedisTemplate.delete(lockKey); } } }不过上面这个释放锁的写法依然存在“获取值”和“删除 key”两步之间的间隙。更严谨的做法是用 Lua 脚本保证原子性。这部分的逻辑其实并不复杂但很多人不知道可以用DefaultRedisScript在 Java 里执行 Luaif redis.call(get, KEYS[1]) ARGV[1] then return redis.call(del, KEYS[1]) else return 0 end如果你的业务锁比较重直接使用 Redisson 会更稳妥。Redisson 提供了封装好的RLock支持看门狗自动续期和原子释放代码上接近本地锁体验RLock lock redissonClient.getLock(lock:order: orderId); lock.lock(30, TimeUnit.SECONDS); try { // 业务逻辑 } finally { if (lock.isHeldByCurrentThread()) { lock.unlock(); } }Redisson 的看门狗机制是很多团队选它的理由因为它解决了“业务没跑完但锁先过期”的问题。不过要注意Redisson 默认的续期是每 10 秒续一次加锁和释放的语义一定要配套否则也容易出现逻辑错误。分布式锁不是越高深越好核心目标是互斥、安全释放、可容忍轻微超时。如果你的系统允许用数据库唯一索引替代那不一定非要引入 Redis 锁。6. 从现象到根因常见异常排查清单整合做完后项目上到测试环境大概率会遇到一堆奇奇怪怪的问题。这里我列一个排查清单每一条基本都是我自己或团队成员真实踩过的。6.1 连接类问题第一类是连接失败。现象是启动时暴Connection refused或Unable to connect to Redis。排查顺序如下。先确认 Redis 进程是否存活用redis-cli ping验证。如果可以 ping 通再看 Spring Boot 配置里的 host、port、password 是否和实际一致。最常见的错误是配置中心写的是生产地址本地却连接测试环境或者是password没写而 Redis 又开启了requirepass直接 auth 失败。还有一种隐蔽的连接问题防火墙拦截。生产环境里 Redis 端口一般不应该暴露到公网但如果在内网环境要注意安全组是否放通了 6379 端口。这种问题最难受因为本地连没问题部署到服务器上就连不上第一反应往往是代码错了其实只是网络策略没通。6.2 序列化与类型转换异常第二类是反序列化失败。典型报错是ClassCastException或org.springframework.data.redis.serializer.SerializationException。出现这种问题时最有效的办法就是把缓存数据用可视化工具打开看里面是什么格式。如果你发现 key 是乱码大概率是默认 JDK 序列化器导致的。解决方式是自定义序列化参考我在第 4 章给出的配置。如果你发现 value 是 JSON但反序列化时包或类出现了变化那可能是旧数据仍然带着旧的类型信息。此时可以考虑清掉缓存或者写过期机制让旧数据自动失效而不是硬着头皮去反序列化。6.3 缓存一致性引发的问题第三类是缓存与数据库不一致。这类问题代码层面是看不出来的因为 Redis 返回的确实是你之前写入的值问题出在缓存更新策略上。举一个真实的例子一个商品详情接口先查缓存再查数据库数据更新的时候只更新数据库不删缓存。结果用户端看到的一直是旧数据。解决这个问题的关键不是“等缓存过期”而是要建立一套缓存失效规则。更新菜单的时候用CacheEvict把对应 key 删掉或者在写入数据库后把新数据同步更新到缓存。极端情况下可以考虑用延时双删的策略先删缓存、更新 DB、休眠一小段时间再删一次缓存。我不建议所有项目都上复杂的一致性方案。如果你的业务就是能接受缓存 30 秒过期那直接设置短 TTL 反而是最省心的方案。过度设计是比不设计更大的坑。6.4 性能相关慢查询与连接池耗尽第四类是性能问题。当系统压力一大连接池就可能被耗尽日志里会频繁出现Cannot get a connection。先不要急着增加max-active要看一下自己是否在循环里反复获取连接。比如一个循环里嵌套了几百次 Redis 操作每次都创建一个临时RedisTemplate调用那池子再大也不够用。正确的做法是批量操作聚合能用 Pipeline 就合并命令能批量设置就用opsForValue().multiSet()。另外开启 Redis 的慢日志也是一种手段直接把命令执行时间记录下来能快速定位是不是有大 key 或复杂命令拖慢了整体。排查问题的总体思路是先确认 Redis 本身是否正常再看配置是否生效最后才怀疑代码。不要一上来就断断续续改代码那样效率极低。7. 关于后续进阶的几点体会实际项目中Redis 整合的终点通常不是“能用了”而是“用得稳、跑得快、容易排查”。我个人的做法是在项目里保留一个统一的CacheKey类把业务缓存 key 的命名集中管理。比如user:{id}、order:{id}避免不同模块写出来的 key 风格完全不统一。key 的 TTL 也集中定义能定义成常量就不要散落在业务代码里。这样如果某天调大缓存过期时间只需要改一个地方不用整站搜set方法。另外如果有条件一定做好监控。Redis 的内存使用率、keyspace_hits和keyspace_misses这两个命中率指标比“代码能跑通”重要得多。命中率过低说明缓存设计基本失效命中率过高又可能是缓存长期不失效数据一致性风险在累积。找一个合适的命中率范围比单纯追求“用了 Redis”更有意义。还有一点很多人忽略Redis 持久化不是默认帮你把所有数据稳稳保住的。默认配置在内存充足、进程正常的情况下运行没问题但一旦服务器重启没有开启AOF或RDB就可能丢数据。缓存数据丢失无所谓如果是业务数据那就要评估下持久化策略了。生产上也不要为了性能关掉持久化除非你能百分百确认这个 Redis 实例只是个随时可重建的缓存。最后想说Spring Boot 整合 Redis 本身就是一条很成熟的路不存在太多神秘的东西。真正的门槛在于你要理解它的数据结构、缓存失效模型以及序列化方式然后把工具用到合适的位置上。先跑通最小链路再针对性解决序列化逐步加上缓存注解和锁机制这一套路径走下来你手里的项目会变得更能打。
Spring Boot 整合 Redis 实战：序列化、缓存注解与分布式锁
Spring Boot 整合 Redis听起来像是无数教程写过的话题但我实际带项目时发现大部分人卡住的点根本不在“代码不会写”而在“不知道整合前要想清楚什么、装好之后如何验证、以及序列化配置为什么这么关键”。这篇文章我想换个角度看这套“整合步骤”先帮你想清楚场景再把环境准备成一个能跑通的状态然后是最基础的键值写入接着专门拆解序列化这个重灾区最后把分布式锁和缓存注解这些常用扩展一并讲透。标题里提到的 Spring Boot 和 Redis 这两个关键词在下面的内容里会作为主线贯穿始终。我不打算讲特别悬的架构只讲一个后端工程师在真正干活时最需要掌握的整合过程。无论你是刚接触 Spring Boot 的初学者还是在公司接手了一个已经能跑但偶尔出诡异缓存问题的老项目这篇内容都可以当作战术参考直接用。1. 先问清楚你的项目到底为什么要接 Redis很多教程一上来就让你加依赖、写配置然后跑一个 “Hello World” 的 Set/Get告诉你整合完成了。但说实话这一步人人都能跟着抄真正值钱的判断是你知不知道这个 Redis 在你的系统里扮演什么角色。Spring Boot 项目里引入 Redis最常见的理由是这几类。第一类是缓存。查询热点数据时每次都打 MySQL 会带来不必要的 IO 压力。尤其像用户信息、商品详情、配置字典这种读多写少、允许短暂不一致的数据放在 Redis 里能明显降低数据库负载。注意我说的是“允许短暂不一致”。如果你的业务要求强一致比如余额、库存那要谨慎使用缓存或者在设计缓存更新机制时下更多功夫。第二类是会话共享。单体应用还好一旦服务做了多实例部署用户的登录 Session 默认存在各自的 JVM 里就会出现“明明在 A 机器登录了请求被负载均衡转发到 B 机器结果 Session 又失效了”的问题。把 Session 存到 Redis多实例之间就能共享同一份数据。Spring Session Data Redis 这个子项目就是专门干这个事的它的整合思路和普通缓存整合不太一样但底层的连接、序列化思想是通用的。第三类是高并发场景下的限流与分布式锁。比如秒杀防超卖、防重复提交、接口限流。这类功能依赖 Redis 的原子操作比如INCR、EXPIRE、SETNX。它们不是你给 Redis 发一条指令就完事而是需要你认真设计 key、过期时间、释放锁时的原子性。这个我会在后面的章节专门展开。搞清楚为什么要用其实决定了你后面怎么做。如果只是缓存大部分时候你只需要StringRedisTemplate根本不需要折腾自定义的RedisTemplateObject, Object。如果要用对象缓存那序列化配置才是关键。如果要用分布式锁你要考虑网络抖动、锁误删、续期这些危险场景。不同的目标复杂度完全不一样。所以我的建议是在动手前先接受一句话Redis 不是一个“存字符串的网盘”而是一个支持原子操作、带过期机制的高性能数据结构服务器。只有理解了它的数据结构、过期策略和线程模型整合 Spring Boot 时才不会只是“配置一把梭”。2. 环境准备从零装一个能跑通的 Redis这一步看似基础但“安装完 Redis 后不知道测没测通”是很多新手整合失败的起点。咱们分平台来看不追求多高深目标是打开命令行能 ping 通能读写。在 macOS 上最简单的办法是用 Homebrew。打开终端输入brew install redis安装完成之后后台启动可以用brew services start redis如果只是想临时跑一下不想注册成服务直接运行redis-server也能把进程拉起来。默认端口6379配置文件通常在/opt/homebrew/etc/redis.conf或者/usr/local/etc/redis.conf取决于具体安装路径。在 Windows 上这点我多说两句。Redis 官方其实没有原生支持 Windows网上看到的各种 Windows 安装包大多是开源社区维护的移植版本。如果你只是本地开发两个比较省心的路子用 Docker 跑 Redis 容器使用 WSL 后在 Ubuntu 里安装 Redis。如果是公司开发环境直接用 Windows 桌面版 Redis 工具类的软件也行但生产环境强烈不建议用非官方版本。这个坑我见过稳定性达不到要求出问题还不好排查。在 Linux 上Debian/Ubuntu 系直接sudo apt update sudo apt install redis-server sudo systemctl enable redis-server sudo systemctl start redis-serverCentOS/RHEL 上则可能是yum install redis装完检查一下服务状态。装好后不要急着回去写 Java。先做两个验证redis-cli ping如果返回PONG说明服务起来了。再设置一个 key读一下redis-cli set name ming redis-cli get name能读到ming恭喜环境没问题。生产环境通常还要设置密码。可以在配置文件里把requirepass打开也可以动态设置redis-cli config set requirepass yourpassword redis-cli -a yourpassword pingSpring Boot 那边连接时就需要在配置里配密码字段。提前设置密码可以避免后面项目上线时 Redis 裸奔。除了密码可视化工具我也强烈建议配一个。只看命令行在数据量小的时候还行等 key 多起来你需要一个能看 TTL、看内存占用、看 key 前缀的工具。比较主流的RedisInsight官方出品的桌面客户端界面现代功能全Another Redis Desktop Manager开源社区常用轻量各种在线版的 Redis 客户端适合临时连接。我个人的习惯是开发环境用 RedisInsight 看配置信息和慢日志快速验证代码里写入的 key 是否膨胀、是否存在乱码。这个东西在排查序列化问题时特别好用等会儿你会体会到。3. 工程骨架到首个键值写入最小集成路线环境通了接下来就给 Spring Boot 项目装上依赖。这里有一个常见的概念混淆很多人以为spring-boot-starter-data-redis是 Redis 客户端本身其实不是。它是对 Spring Data Redis 的自动配置封装底层默认集成的是 Lettuce是 Spring 封装好的一套连接池和模板抽象。创建一个项目最省事的方式是到 Spring Initializr 官网生成或者用 IDE 自带的新建项目向导。依赖列表里勾上Spring Web和Spring Data Redis。如果要用缓存注解加上Spring Cache Abstraction相关支持Spring Boot 的 spring-boot-starter-cache 可以单独引。如果用 Mavenpom.xml里的核心依赖是这样的dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependencySpring Boot 3.x 之后默认的 Redis 客户端是 Lettuce如果你想换成 Jedis需要额外引spring-boot-starter-data-redis里排除掉 Lettuce再单独引 Jedis。不过 Lettuce 在大多数场景下已经足够默认用就可以没必要折腾。接下来是application.yml配置。基础配置长这样spring: data: redis: host: 127.0.0.1 port: 6379 password: yourpassword database: 0 timeout: 3s lettuce: pool: max-active: 8 max-idle: 8 min-idle: 0注意Spring Boot 2.x 时代的配置前缀是spring.redis.*到了 Spring Boot 3.x 改成了spring.data.redis.*。这个差异不知道坑了多少人。如果你使用的版本是 3.0 及以上却按网上的老教程写spring.redis.host配置会被直接忽略然后本地回报错或者默认去连本机 6379。连接池参数需要解释一下。max-active是连接池最多能分配的连接数max-idle是空闲连接上限min-idle是保持的最小空闲连接数。在高并发场景max-active太小会出现等待获取连接的异常但也不是越大越好连接数太大会把 Redis 机器拖垮。配置写完之后我先不急着往业务代码里塞 Redis而是用CommandLineRunner做一个最简单的验证。写一个启动执行器Component public class RedisSmokeTestRunner implements CommandLineRunner { private final StringRedisTemplate stringRedisTemplate; public RedisSmokeTestRunner(StringRedisTemplate stringRedisTemplate) { this.stringRedisTemplate stringRedisTemplate; } Override public void run(String... args) { stringRedisTemplate.opsForValue().set(boot:smoke, ok); String value stringRedisTemplate.opsForValue().get(boot:smoke); System.out.println(redis smoke value value); } }启动项目控制台如果能打印出redis smoke value ok说明整个最小链路已经通了Spring Boot 启动 - 创建连接池 - 执行命令 - 拿到返回值。从这一步开始后面所有玩法都有了地基。有人会问为什么用StringRedisTemplate而不是直接注入RedisTemplate因为StringRedisTemplate默认使用字符串序列化器读写字符串类型最省心不会出现 key 带乱码前缀的问题。等你需要存对象再考虑自定义RedisTemplate或者 JSON 序列化方案。4. 序列化不匹配Spring Boot 整合 Redis 最容易踩的坑如果你把整合看着是一门手艺序列化就是这门手艺里最容易翻车的环节。典型场景是这样的项目启动后用RedisTemplate写入一个User对象然后到客户端里一看key 是一长串类似\xac\xed\x00\x05t\x00\x03xxx的二进制乱码Value 也完全不可读。这不是 Redis 坏了而是默认序列化器在用 JDK 原生序列化方式把对象和字符串都变成了二进制字节流。Spring Data Redis 里RedisTemplate默认会使用JdkSerializationRedisSerializer这个序列化器有两个问题生成的字节流混乱难读而且序列化后的 key 会带类型信息。更麻烦的是如果实体类结构变化旧数据还会反序列化失败。我们理想的方案是key 用 String 序列化保持可读性value 对简单的字符串也保持原始可读value 对复杂对象使用 JSON 序列化器。下面这个自定义配置在项目里非常常用Configuration public class RedisConfig { Bean public RedisTemplateString, Object redisTemplate(RedisConnectionFactory connectionFactory) { RedisTemplateString, Object template new RedisTemplate(); template.setConnectionFactory(connectionFactory); StringRedisSerializer stringSerializer new StringRedisSerializer(); GenericJackson2JsonRedisSerializer jacksonSerializer new GenericJackson2JsonRedisSerializer(); template.setKeySerializer(stringSerializer); template.setHashKeySerializer(stringSerializer); template.setValueSerializer(jacksonSerializer); template.setHashValueSerializer(jacksonSerializer); template.afterPropertiesSet(); return template; } }这样配置之后写入一个对象User user new User(); user.setId(1L); user.setName(张三); redisTemplate.opsForValue().set(user:1, user);客户端里看到的就是一个可读的 JSON 字符串调试体验完全不同。但这里还有一个容易忽视的细节GenericJackson2JsonRedisSerializer在反序列化时依赖落盘数据里保存的class类型元信息。或者说它会在 JSON 里自动加一个类型字段。这也意味着如果你的应用升级了实体类的包名或类名旧数据可能无法正常反序列化。考虑向前兼容时有些人会选择手动指定 ObjectMapper 的默认类型或改用别的方案比如只存 DTO而不是把所有实体类直接塞进 Redis。序列化配置也不只是影响RedisTemplate缓存注解如Cacheable同样会受它影响。当你开启 Spring Cache 并把缓存管理器指向 RedisCacheManager 时默认的RedisCacheManager会创建自己的序列化配置。想要统一序列化还可能需要自定义RedisCacheConfigurationBean public RedisCacheManager cacheManager(RedisConnectionFactory connectionFactory) { RedisCacheConfiguration config RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(30)) .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer())) .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer())) .disableCachingNullValues(); return RedisCacheManager.builder(connectionFactory) .cacheDefaults(config) .build(); }如果缓存和业务查询用的是不同的序列化配置可能出现一种很分裂的现象你用redisTemplate写进去的数据用Cacheable读不到反过来也成立。所以我的经验是在一套代码里尽量把RedisTemplate和RedisCacheManager的序列化策略统一。尤其注意 key 的序列化方式最好全部用StringRedisSerializer。排查序列化问题时最直观的方法就是打开可视化客户端看 key 的前缀是否长得像人话。如果是人话说明 key 序列化没问题如果是一串十六进制乱码第一反应应该是查看代码里的 key 序列化器而不是猜数据存放逻辑。5. 从熟练使用到扩展实践缓存注解与分布式锁把基本的读写跑通后大多数项目会进入第二阶段用 Spring 的缓存注解或者实现一个分布式锁。这两个都是高频需求值得单独拆开讲。5.1 缓存注解的三板斧开启缓存注解只需在主类上添加EnableCaching。然后就可以在 Service 层的方法上使用CacheableCacheable(value userCache, key #id) public User getUserById(Long id) { return userMapper.selectById(id); }第一次调用时方法体执行并触发 SQL 查询结果被写入 Redis第二次调用直接命中缓存方法的查询逻辑不再执行。这个设计很简单但有一个隐含条件你必须在RedisCacheManager里定义好缓存 key 前缀和 TTL。value字段相当于一个逻辑区域Redis 里实际 key 会变成类似userCache::1的样子。更新和失效分别用CachePut和CacheEvict。CachePut会在方法执行后更新缓存适合主键修改的场景CacheEvict清空缓存适合删除场景。这里有个设计经验修改数据时要么用CachePut主动更新要么用CacheEvict直接删缓存让下次查询重新加载。两者都行但没有统一策略的话容易出现缓存里还是旧值的脏读。同时要注意一个常见的缓存陷阱是穿透。如果查询方法返回nullCacheable默认不会缓存空值。一旦某个不存在的 key 被频繁查询请求会逐个打到数据库。RedisCacheConfiguration里disableCachingNullValues()就是设置是否允许缓存空值。允许缓存空值可以防穿透但要小心缓存的是空对象策略上最好给空值设置一个较短的 TTL。5.2 分布式锁从能跑到跑到完全正确分布式锁是另一个高频需求。最简单的实现方式是利用 Redis 的STRING类型和SETNX语义如果 key 不存在就设置返回成功如果存在就失败。代码层面RedisTemplate对应的操作是Boolean locked stringRedisTemplate.opsForValue() .setIfAbsent(lock:order: orderId, holder, Duration.ofSeconds(30));这里用setIfAbsent加Duration是重点它能保证“加锁”和“设置过期时间”是一个原子操作。早期很多人分两步写先setnx再expire结果第一步成功、第二步失败时锁永远不释放直接把系统锁死。这个坑是真实出现过的。在释放锁时最怕的是 A 线程加的锁被 B 线程给解了。假设业务执行时间超过了锁的过期时间锁自动过期后 B 线程拿到锁然后 A 线程执行完直接调用delete(key)把 B 的锁删掉了系统又会走进并发失控。所以释放锁需要先校验持有者身份再看删除是否成功。简单写法可能长这样String lockKey lock:order: orderId; String token UUID.randomUUID().toString(); Boolean locked stringRedisTemplate.opsForValue() .setIfAbsent(lockKey, token, Duration.ofSeconds(30)); if (Boolean.TRUE.equals(locked)) { try { // 业务逻辑 } finally { String current stringRedisTemplate.opsForValue().get(lockKey); if (token.equals(current)) { stringRedisTemplate.delete(lockKey); } } }不过上面这个释放锁的写法依然存在“获取值”和“删除 key”两步之间的间隙。更严谨的做法是用 Lua 脚本保证原子性。这部分的逻辑其实并不复杂但很多人不知道可以用DefaultRedisScript在 Java 里执行 Luaif redis.call(get, KEYS[1]) ARGV[1] then return redis.call(del, KEYS[1]) else return 0 end如果你的业务锁比较重直接使用 Redisson 会更稳妥。Redisson 提供了封装好的RLock支持看门狗自动续期和原子释放代码上接近本地锁体验RLock lock redissonClient.getLock(lock:order: orderId); lock.lock(30, TimeUnit.SECONDS); try { // 业务逻辑 } finally { if (lock.isHeldByCurrentThread()) { lock.unlock(); } }Redisson 的看门狗机制是很多团队选它的理由因为它解决了“业务没跑完但锁先过期”的问题。不过要注意Redisson 默认的续期是每 10 秒续一次加锁和释放的语义一定要配套否则也容易出现逻辑错误。分布式锁不是越高深越好核心目标是互斥、安全释放、可容忍轻微超时。如果你的系统允许用数据库唯一索引替代那不一定非要引入 Redis 锁。6. 从现象到根因常见异常排查清单整合做完后项目上到测试环境大概率会遇到一堆奇奇怪怪的问题。这里我列一个排查清单每一条基本都是我自己或团队成员真实踩过的。6.1 连接类问题第一类是连接失败。现象是启动时暴Connection refused或Unable to connect to Redis。排查顺序如下。先确认 Redis 进程是否存活用redis-cli ping验证。如果可以 ping 通再看 Spring Boot 配置里的 host、port、password 是否和实际一致。最常见的错误是配置中心写的是生产地址本地却连接测试环境或者是password没写而 Redis 又开启了requirepass直接 auth 失败。还有一种隐蔽的连接问题防火墙拦截。生产环境里 Redis 端口一般不应该暴露到公网但如果在内网环境要注意安全组是否放通了 6379 端口。这种问题最难受因为本地连没问题部署到服务器上就连不上第一反应往往是代码错了其实只是网络策略没通。6.2 序列化与类型转换异常第二类是反序列化失败。典型报错是ClassCastException或org.springframework.data.redis.serializer.SerializationException。出现这种问题时最有效的办法就是把缓存数据用可视化工具打开看里面是什么格式。如果你发现 key 是乱码大概率是默认 JDK 序列化器导致的。解决方式是自定义序列化参考我在第 4 章给出的配置。如果你发现 value 是 JSON但反序列化时包或类出现了变化那可能是旧数据仍然带着旧的类型信息。此时可以考虑清掉缓存或者写过期机制让旧数据自动失效而不是硬着头皮去反序列化。6.3 缓存一致性引发的问题第三类是缓存与数据库不一致。这类问题代码层面是看不出来的因为 Redis 返回的确实是你之前写入的值问题出在缓存更新策略上。举一个真实的例子一个商品详情接口先查缓存再查数据库数据更新的时候只更新数据库不删缓存。结果用户端看到的一直是旧数据。解决这个问题的关键不是“等缓存过期”而是要建立一套缓存失效规则。更新菜单的时候用CacheEvict把对应 key 删掉或者在写入数据库后把新数据同步更新到缓存。极端情况下可以考虑用延时双删的策略先删缓存、更新 DB、休眠一小段时间再删一次缓存。我不建议所有项目都上复杂的一致性方案。如果你的业务就是能接受缓存 30 秒过期那直接设置短 TTL 反而是最省心的方案。过度设计是比不设计更大的坑。6.4 性能相关慢查询与连接池耗尽第四类是性能问题。当系统压力一大连接池就可能被耗尽日志里会频繁出现Cannot get a connection。先不要急着增加max-active要看一下自己是否在循环里反复获取连接。比如一个循环里嵌套了几百次 Redis 操作每次都创建一个临时RedisTemplate调用那池子再大也不够用。正确的做法是批量操作聚合能用 Pipeline 就合并命令能批量设置就用opsForValue().multiSet()。另外开启 Redis 的慢日志也是一种手段直接把命令执行时间记录下来能快速定位是不是有大 key 或复杂命令拖慢了整体。排查问题的总体思路是先确认 Redis 本身是否正常再看配置是否生效最后才怀疑代码。不要一上来就断断续续改代码那样效率极低。7. 关于后续进阶的几点体会实际项目中Redis 整合的终点通常不是“能用了”而是“用得稳、跑得快、容易排查”。我个人的做法是在项目里保留一个统一的CacheKey类把业务缓存 key 的命名集中管理。比如user:{id}、order:{id}避免不同模块写出来的 key 风格完全不统一。key 的 TTL 也集中定义能定义成常量就不要散落在业务代码里。这样如果某天调大缓存过期时间只需要改一个地方不用整站搜set方法。另外如果有条件一定做好监控。Redis 的内存使用率、keyspace_hits和keyspace_misses这两个命中率指标比“代码能跑通”重要得多。命中率过低说明缓存设计基本失效命中率过高又可能是缓存长期不失效数据一致性风险在累积。找一个合适的命中率范围比单纯追求“用了 Redis”更有意义。还有一点很多人忽略Redis 持久化不是默认帮你把所有数据稳稳保住的。默认配置在内存充足、进程正常的情况下运行没问题但一旦服务器重启没有开启AOF或RDB就可能丢数据。缓存数据丢失无所谓如果是业务数据那就要评估下持久化策略了。生产上也不要为了性能关掉持久化除非你能百分百确认这个 Redis 实例只是个随时可重建的缓存。最后想说Spring Boot 整合 Redis 本身就是一条很成熟的路不存在太多神秘的东西。真正的门槛在于你要理解它的数据结构、缓存失效模型以及序列化方式然后把工具用到合适的位置上。先跑通最小链路再针对性解决序列化逐步加上缓存注解和锁机制这一套路径走下来你手里的项目会变得更能打。
