Spring Boot Redis序列化配置：原理、方案与避坑实践

1. 为什么说Redis序列化配置是缓存坑的开始

用Spring Boot操作Redis，业务跑了几天，打开Redis Desktop Manager一看，key全是\u4E2D\u6587这种转义字符，value是一坨看不懂的二进制，当场心态就崩了。如果遇到这种情况，多半是没做Redis序列化配置，或者还在用Spring Data Redis默认的JDK序列化策略。我写这篇是想把Redis序列化配置的原理、主流方案、完整代码和踩坑经验一次说清楚，适合正在做缓存、分布式锁、接口幂等的Java开发者，也适合准备面试时想把Redis原理捋明白的朋友。

1.1 Redis存的是字节，不是Java对象

Redis是一个基于内存的key-value存储，value支持String、List、Hash、Set、ZSet这些数据类型，但无论哪一种，底层最终都是字节数组。Java程序里的对象在JVM内存中是对象引用，想把它塞进Redis，必须先序列化成字节序列；下次用的时候，再从Redis取出字节，反序列化回Java对象。这个过程对很多初学者来说是透明的，因为Spring Data Redis把细节封装好了，你只管redisTemplate.opsForValue().set("user:1", user)。但封装不代表不犯错，如果序列化器选错，数据存进去容易，取出来就会出问题。

Spring Data Redis里负责序列化的组件叫RedisSerializer，它定义了serialize和deserialize两个方法，分别处理对象到字节、字节到对象的转换。RedisTemplate默认使用的序列化器是JdkSerializationRedisSerializer，这是Spring的历史选择，目的是让普通的Java对象直接实现Serializable就能存取。问题是，这个默认方案在真实业务里并不好用，甚至会让一个看起来很简单的缓存功能变成排查噩梦。

1.2 默认JDK序列化的两大硬伤

第一是“人看不懂”。JDK序列化输出的是Java特有的二进制格式，不是UTF-8字符串。你往Redis里存一个user:1的key，它底层的字节可能是\xAC\xED\x00\x05t\x00\x06user:1，用redis-cli或Redis Desktop Manager看，自然就是乱码。key乱码还能忍，value乱码更难受：你想确认缓存里到底有没有值、过期时间还剩多少，结果只能看到一堆十六进制。

第二是“跨语言没法用”。JDK序列化格式只有Java能反序列化，如果你的系统里有Python、Go、Node.js，它们拿到这段字节完全没有办法。现在很多项目已经不是单语言单体应用了，网关、报表、数据处理服务可能各用一个技术栈，缓存数据作为中间交换结果，必须让多方都能读懂。一旦用JDK序列化，等于把Redis锁死在Java生态里，后续要接其他语言只能重做。

除了这两点，JDK序列化还有“体积大”的问题。它会写入类名、继承关系、对象结构描述等大量元信息，同样一个对象，序列化出来的体积可能是JSON的3到5倍。Redis是内存数据库，数据量大了以后，这部分白白浪费的内存和网络带宽都算你的成本。

1.3 不配置序列化，迟早会遇到这些诡异现象

我在实际项目里见过的典型“诡异现象”至少有这么几种。

• 明明存的是user:1这个key，换一个客户端用同样的key去SET，结果RedisTemplate查不到。
• get出来的对象直接强转User，结果抛java.lang.ClassCastException，因为反序列化出来的是LinkedHashMap。
• 同一个缓存数据，用RedisTemplate写入，用StringRedisTemplate读取，读到null；反过来也一样。
• 分布式锁的key在监控页面里完全不可读，出问题时想手工删除都费劲。

这些问题的根源都不是Redis本身，而是序列化器不一致。序列化器不一致意味着同一个逻辑key，经过不同序列化算法后变成不同的字节，Redis底层认为它们是两个完全不同的key。你看着代码里都是同一个字符串，实际存储时早就分道扬镳了。

1.4 序列化配置到底要解决什么问题

说白了，配置Redis序列化就是要解决四个问题：可读性、正确性、兼容性、性能。可读性是指key和value尽量用肉眼能看懂的字符串或JSON；正确性是指对象序列化后还能还原本来的类型，而不是变成一个Map；兼容性是指不同语言和不同版本的服务都能处理这份数据；性能则是指序列化体积和速度不要成为瓶颈。

这四个目标不是每一项都要做到极致，因为它们之间有取舍。团队协作项目里，可读性和正确性往往比极致性能更重要，因为出问题的时候，人能看懂才是第一生产力。所以接下来的方案对比，我不会只看性能数字，而是结合真实使用场景来聊。

2. 主流Redis序列化方案对比：看清默认值和推荐值

2.1 四位常驻选手逐个过一遍

先看看最常碰到的几个序列化器。

JdkSerializationRedisSerializer：Spring的默认选择，底层用Java原生序列化，要求对象实现Serializable。前面说过，它的问题是可读性差、跨语言差、体积大。但它也不是一无是处，对象不用额外配置，无脑序列化就能用，适合临时调试或数据无所谓的场景。

StringRedisSerializer：用UTF-8编码把字符串转成字节，专治key乱码。它只支持String类型，如果value想存任意对象，它无能为力。在RedisTemplate配置里，它通常只承担key、hash key的序列化工作。

Jackson2JsonRedisSerializer：用Jackson把对象转成JSON字符串，然后按UTF-8存进去。相比JDK序列化，JSON可读性好、体积小、跨语言友好。缺点是需要指定目标类型，或者配合ObjectMapper启用类型信息，否则反序列化时不知道要还原成哪个类。

GenericJackson2JsonRedisSerializer：可以看成Jackson2JsonRedisSerializer的增强版，它会在JSON里额外写入一个@class字段，记录原始类型的全限定名。这样反序列化时可以自动恢复成原来的类型，省去很多手动指定的麻烦。代价是JSON里多几个字符，增加一点点存储和带宽，但换来的是“无脑对象存储”。

FastJsonRedisSerializer：国内早期用得比较多，性能和JSON处理都不差，但FastJson公开过不少反序列化漏洞，安全要求高的场景建议谨慎。新项目我更推荐直接用Jackson系列，避免额外依赖。

2.2 一张表看清差异

这张表里最关键的判断点是“类型还原”。如果包一层对象，用了不带类型信息的Jackson序列化器，读出来的对象只会是LinkedHashMap。这不是Jackson的bug，而是JSON本身没有类型信息，反序列化目标类型只能靠你指定或者额外写入。

2.3 为什么String+JSON组合成了大众选择

大多数团队最终选择的组合是：key用StringRedisSerializer，value用GenericJackson2JsonRedisSerializer。原因很直白。

key用String，是因为key本身就是一个标识字符串，没必要序列化成二进制。可读性直接拉满，运维排查、手动删key、看监控都很方便。value用GenericJackson，是因为业务对象五花八门，用JSON存既保留了跨语言能力，又能在读取时自动还原类型。Hash结构里，field同样建议用String序列化器，否则field也会变成乱码。

这个组合在可读性和正确性之间取得了很好的平衡。它不像JDK序列化那样黑盒，也不像CBOR、ProtoStuff那样需要引入额外schema，更不用像Kryo那样维护类型注册表。Redis里看到的就是你能理解的JSON，心里有底。

2.4 别迷信“最快”：Kryo和ProtoStuff的代价

我在评估序列化方案时，经常看到有人把Kryo的性能数据放在最前面，然后建议替换所有JSON序列化。我不能说Kryo不好，但它的高性能是有前提的。Kryo需要注册类，或者依赖完整类路径，类结构一变更，老数据反序列化很可能直接失败。ProtoStuff也有类似问题，它的schema绑定和版本兼容要自己处理。团队里如果没有专人维护，这类性能优化很容易变成线上事故根源。

我的建议是：绝大多数业务系统，先考虑可维护性。String+JSON已经能覆盖90%以上的缓存和访问场景。只有当你真的遇到网络带宽或Redis内存吃紧、序列化耗时成为热点时，再考虑Kryo或ProtoStuff。到那一步时，需要配套做版本管理和兼容性测试。

3. 动手实战：Spring Boot中配置好RedisTemplate

3.1 准备依赖和基础连接参数

既然要配置，先保证环境里能跑起来。使用Maven的话，在pom.xml里引入Spring Data Redis依赖。

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-pool2</artifactId> </dependency>

连接池依赖不是必须的，但高并发下建议加上，避免频繁创建连接。application.yml里给出Redis连接参数，我习惯把连接池上限、超时时间都显式写出来，方便后续调优。

spring: data: redis: host: 127.0.0.1 port: 6379 password: timeout: 3000ms lettuce: pool: max-active: 16 max-idle: 8 min-idle: 2

这里只负责连接工厂，不负责序列化。很多新手会在yml里找serializer配置项，实际上Spring Boot并没有提供一个外部化配置来直接替换序列化器，需要自己定义RedisTemplate的Bean。

3.2 配置类的核心思路

RedisTemplate默认的两个序列化器都是JDK，所以我们要做的是通过setKeySerializer、setValueSerializer、setHashKeySerializer、setHashValueSerializer这四个方法分别替换。不要只改key和value，hash key和hash value也一定要改，否则你用opsForHash()存字段时照样乱码。

我建议配置成一个Spring管理的@Bean，让整个项目注入的是同一个模板，而不是业务代码里到处new RedisTemplate()。手动new出来的模板没有连接工厂，也不受容器管理，很容易造成序列化器不一致的问题。

3.3 完整配置类代码

一个简单且稳妥的版本是这样：

@Configuration public class RedisConfig { @Bean public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) { RedisTemplate<String, Object> template = new RedisTemplate<>(); template.setConnectionFactory(factory); StringRedisSerializer stringRedisSerializer = new StringRedisSerializer(); GenericJackson2JsonRedisSerializer jsonRedisSerializer = new GenericJackson2JsonRedisSerializer(); // key、hash key 使用字符串序列化器 template.setKeySerializer(stringRedisSerializer); template.setHashKeySerializer(stringRedisSerializer); // value、hash value 使用 JSON 序列化器 template.setValueSerializer(jsonRedisSerializer); template.setHashValueSerializer(jsonRedisSerializer); // 确保设置生效 template.afterPropertiesSet(); return template; } }

这里说几个容易被忽略的点。

afterPropertiesSet()是在模板属性设置完成后做校验和初始化，Spring容器在Bean初始化的时候也会调用，但这里手动调用一次更稳妥，避免在Bean正式发布前序列化器还没生效。GenericJackson2JsonRedisSerializer内部已经配置了配套的ObjectMapper，默认会启用类型信息，所以不用再自己new一个ObjectMapper。

如果你的项目里用了LocalDateTime、LocalDate这类Java时间类型，GenericJackson2JsonRedisSerializer虽然能处理一部分，但在某些Spring Boot版本里还是需要额外注册JavaTimeModule。这种情况下，我会选择自定义ObjectMapper的Jackson2JsonRedisSerializer版本。

3.4 想要更精细控制，可以自定义ObjectMapper

如果不想用Generic版本，或者项目里有自定义类型转换的需求，可以用下面这种方式：

ObjectMapper objectMapper = new ObjectMapper(); objectMapper.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY); objectMapper.activateDefaultTyping( LaissezFaireSubTypeValidator.instance, ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY ); Jackson2JsonRedisSerializer<Object> jackson2JsonRedisSerializer = new Jackson2JsonRedisSerializer<>(objectMapper, Object.class);

这段代码在Spring Boot 2.x环境下很常见，注意activateDefaultTyping用来把类型信息写入JSON，避免反序列化变成LinkedHashMap。在Spring Boot 3.x里，Jackson2JsonRedisSerializer的构造方法有些变化，不同版本参数不一致，所以更推荐直接用Generic版本，把版本的坑交给Spring去填。

3.5 写个接口验证配置有没有生效

配置完之后，不要只靠“代码没报错”来判断，一定要实际往Redis里写一条数据再读出来，用客户端看一下。

@RestController @RequestMapping("/redis") public class RedisTestController { private final RedisTemplate<String, Object> redisTemplate; public RedisTestController(RedisTemplate<String, Object> redisTemplate) { this.redisTemplate = redisTemplate; } @GetMapping("/set") public String set() { User user = new User(1L, "张三", 28); redisTemplate.opsForValue().set("user:1", user); return "saved"; } @GetMapping("/get") public Object get() { return redisTemplate.opsForValue().get("user:1"); } }

调用/redis/set之后，用redis-cli执行：

keys *

如果配置正确，你会看到user:1这个key本身是明文。再用get user:1查看value，会看到类似下面这样的一段JSON：

{"@class":"com.example.User","id":1,"name":"张三","age":28}

@class字段说明类型信息生效了。如果不是这样，key变成二进制或者value变成乱码，回到配置类检查哪里漏配了。

3.6 什么时候直接用StringRedisTemplate就好

如果你的缓存内容只有字符串，比如短信验证码、Token、分布式锁的value，那么直接用StringRedisTemplate最合适。它的key和value都默认使用StringRedisSerializer，省去配置，也不会有类型还原问题。RedisTemplate<String, Object>和StringRedisTemplate不能随意混用，哪怕泛型看起来很接近，因为RedisTemplate的value序列化器是JSON，StringRedisTemplate的是String，读写规则完全不一样。

项目里最好统一一种用法。要么全部用自定义的RedisTemplate，要么全部用StringRedisTemplate，最怕一半代码用这个、一半用那个，缓存数据被两套字节规则隔开，互相看不到，排查起来非常痛苦。

4. 这些序列化坑我都踩过：问题排查与避坑

4.1 乱码、强转异常、局部覆盖

先看一个典型的线上事故。同事在代码里用RedisTemplate保存了一个User对象，第二天另一个服务读取后强转User，结果报ClassCastException，一看日志，反序列化出来的是LinkedHashMap。为什么会这样？因为他的value序列化器用的是不带类型信息的Jackson2JsonRedisSerializer，JSON本身只保存字段，不保存类名，读取时Jackson不知道目标类，只能默认转成Map。

解决方案有两个方向：一是改用GenericJackson2JsonRedisSerializer，让类型信息写入@class字段；二是在读取时指定类型，比如objectMapper.readValue(json, User.class)。前者更省心，后者更适合需要严格控制输出格式的场景。

还有一个常见的局部乱码问题：只配置了keySerializer和valueSerializer，忘了hashKeySerializer和hashValueSerializer。结果opsForHash().put("hashKey", "field1", value)后，hashKey整体是字符串，但field显示乱码。排查这类问题有一个快捷方法：先在Redis Desktop Manager里看key是否可读，再看field是否可读，再确认value类型，就能快速定位是哪个序列化器失效。

4.2 RedisTemplate和StringRedisTemplate混用：数据“消失”事件

有次项目里出现“缓存写了却读不到”的诡异情况。A服务用StringRedisTemplate写入token:10086，B服务用RedisTemplate读取，结果永远是null。两个服务里的key肉眼看着都是token:10086，但Redis底层存的是两组不同字节。StringRedisTemplate把key按UTF-8编码，RedisTemplate默认按JDK二进制编码，两边根本对不上。

这种情况不需要怀疑Redis故障，先检查两边用的序列化器是否一致。我踩过之后，给自己定了一个规矩：项目里所有Redis操作入口统一放在一个RedisService里，由它决定使用哪个Template，业务层不允许自己选择。这样即使后续要调整序列化方案，也只需要改一处。

4.3 分布式锁锁不住？先检查序列化器

分布式锁通常用SET key value NX EX实现。如果两个服务持有的RedisTemplate序列化器不同，一个把锁key按String存，一个按JDK存，那么它们实际上在争夺两个完全不同的锁，效果就是“锁了个寂寞”。这类问题很容易被忽略，因为业务日志里看不到异常，只会在高并发时偶发出现重复执行。

另外，锁的value也建议使用足够随机的字符串，比如UUID。释放锁时需要先比较value再删除，必须用Lua脚本保证原子性。这些虽然不完全是序列化配置的范畴，但都和“key用什么编码进Redis”强相关。锁场景下，我的建议是单独封装一个锁工具，内部强制使用固定序列化器。

4.4 缓存穿透、缓存空值与序列化的关系

缓存穿透的常用手段之一是缓存空值，比如数据库里查不到用户，就在Redis里存一个null或空对象。很多序列化器遇到null时要么返回空数组，要么报错。Spring Cache里的@Cacheable如果方法返回null，默认不会写入缓存，需要开启cacheNullValues属性。手动操作RedisTemplate时，如果要缓存null，最好在业务层统一包装成一个空对象，不要直接塞null。

我见过一个项目，把空值处理不当，导致缓存里出现了大量无法反序列化的数据，最后只能清空缓存重建。这里的关键不是序列化器本身，而是团队在缓存空值上的策略要统一。要么放一个约定好的空对象，要么设置极短的过期时间，千万不要用一种“今天能用、明天看着就怪”的方式。

4.5 升级缓存格式，老的二进制数据怎么办

如果项目之前用了JDK序列化，现在想切换到JSON序列化，最怕的就是老数据还没过期，新代码读取时报错。JDK二进制数据按JSON解析，必然反序列化失败。切换前一定要考虑存量数据。

我常用的办法有三种。第一，低峰期直接清空相关缓存key，简单粗暴但有效；第二，做一个兼容读取，反序列化时先尝试JSON，失败后走旧逻辑；第三，给key加版本号，比如user:v2:1，新数据用新格式，旧数据自然淘汰。加版本号这个方式看起来略费存储，但能让新旧逻辑共存很长一段时间，适合不能立刻清缓存的大型系统。

4.6 问题速查表

这张表我平时会贴在项目文档里，新同学接过Redis相关需求时，先看表再动手，能少踩很多坑。

5. 再进一步：序列化性能优化和自定义方案

5.1 大Value先压缩再存

有些缓存value虽然不多，但单个对象特别大，比如商品详情、报表结果，JSON字符串可能达到几十KB甚至几百KB。这种情况下Redis内存和网络带宽的消耗都会很突出。一个比较实用的优化思路是：先序列化成JSON，再判断长度，超过阈值就做gzip压缩，然后存进Redis。

压缩带来的代价是CPU占用和调试不便，所以不是所有数据都要压缩。数据只有几百字节时，压缩反而增加开销。一般我用4KB作为阈值，超过再压缩。压缩后的二进制在Redis客户端里不可读，排查时需要解压才能看，所以在value里加一个标记字段，比如{"compress":"gzip","data":"..."}，或者自定义一个RedisSerializer来收口压缩逻辑。

5.2 实现自定义RedisSerializer的通用套路

如果项目里确实需要定制序列化，可以自己实现RedisSerializer<T>。核心只需要两个方法：

public class GzipJsonRedisSerializer implements RedisSerializer<Object> { private final GenericJackson2JsonRedisSerializer delegate = new GenericJackson2JsonRedisSerializer(); @Override public byte[] serialize(Object value) throws SerializationException { if (value == null) { return new byte[0]; } byte[] jsonBytes = delegate.serialize(value); if (jsonBytes.length > 4096) { return compressWithFlag(jsonBytes); } return jsonBytes; } @Override public Object deserialize(byte[] bytes) throws SerializationException { if (bytes == null || bytes.length == 0) { return null; } return delegate.deserialize(decompressIfNeeded(bytes)); } }

注意空值处理，null要返回空数组，否则序列化器可能被框架认为异常。压缩标记可以用第一个字节表示，也可以用魔数。自定义Serializer看起来不复杂，但它影响的是所有Redis读写路径，上线前一定要做充值的接口测试和兼容性验证。

5.3 到底该选哪种序列化方案：我的决策建议

结合我自己的项目经验，给出一个比较务实的选型建议。

• 初创或中小型项目：直接用String + GenericJackson2JsonRedisSerializer，省事、可读、类型还原没问题。
• 业务中只有字符串数据：比如验证码、Token、幂等键，用StringRedisTemplate就够了，不搞复杂配置。
• 高吞吐、超大数据量：再去考虑Kryo、ProtoStuff，同时要有专门的人维护类型注册和版本兼容，不是复制一段代码就完了。
• 多语言异构系统：优先用JSON或Protobuf，不要碰JDK二进制。
• 安全敏感项目：不要使用老版本的FastJson，Jackson也要升级到当前稳定版本，避免反序列化漏洞。

我参与过不少Redis问题排查，最后基本都能查到序列化配置上。我的习惯是序列化方案统一在配置层收口，所有注入的RedisTemplate只允许由Spring容器管理，业务代码不要自己new。还有一个很接地气的技巧：配置完成后写一个单元测试，往Redis里放一个对象再读出来，断言类型和关键字段一致，这一个测试能挡住80%的序列化坑。配置完之后记得用Redis Desktop Manager亲眼看一眼，key明确、value可读，心里才踏实。