Redisson缓存报错missing @class？序列化配置与排查修复全指南

如果你在项目里用 Redisson 做分布式缓存，get()读取数据时突然抛出missing type id property '@class'，说明你写入缓存的数据格式和读取时使用的解析规则已经对不上了。这个报错我前阵子刚踩过，第一反应以为是get()方法用错了，后来才发现真正的病根不在读取动作本身，而在 Redis 里面存的那一串 JSON 和 Redisson 的序列化器配置上。这篇文章会把报错原因、排查路径、修复方案和需要避开的安全坑一次性讲透，适合正被 Redisson 序列化问题折磨的开发者，也适合还没遇到但想做分布式缓存的人提前排雷。

1. 报错现场与问题定性

1.1 报错日志到底在说什么

先看一个典型的报错日志，长下面这样：

org.springframework.data.redis.serializer.SerializationException: Could not read JSON: Missing type id property '@class' at [Source: (String)"{"name":"zhangsan","age":28}"; line: 1, column: 1] at com.fasterxml.jackson.databind.ObjectMapper.readValue(ObjectMapper.java:1234) at org.redisson.codec.JsonJacksonCodec.getValueDecoder(...) ... Caused by: com.fasterxml.jackson.databind.exc.MismatchedInputException: Missing type id property '@class'

从堆栈可以看到，异常发生在 Redisson 的JsonJacksonCodec里，实际是 Jackson 在反序列化时找不到@class这个字段。也就是说，Jackson 读取的 JSON 字符串里没有类型标识，但它又必须依赖这个标识才能把数据还原成 Java 对象。

这里要明确一个概念：这个异常的名字虽然带着Missing type id，但它和Redis 中 key 不存在是两回事。Redis 只是负责存字符串，Redisson 拿到字符串之后要用 Jackson 把 JSON 解析成目标类型。如果解析失败，就会在get()这一步抛异常，而且通常会包装成SerializationException或RedisSystemException，很多同学一看到这个包装类就跑去查 Redis 连接，偏离了方向。

1.2 这类问题最容易出现在什么场景

踩到这个坑的人，往往不是第一次写缓存代码，而是已经跑了一段时间才爆出来。根据我接触到的案例，高频场景集中在三类。

第一类是同一个服务升级了序列化配置。比如有人在RedissonClient初始化时自定义了ObjectMapper，为了精简字段或统一时间格式，却没有启用 Jackson 的默认类型机制，结果旧数据是带@class的，新配置读不了。

第二类是多个服务共用一个 Redis，写入端和读取端用的不是同一套 Codec。服务 A 用 Redisson 默认的JsonJacksonCodec写缓存，自动带上@class；服务 B 为了性能，自己包装了一个不开启默认类型的ObjectMapper去读，两边一碰就报错。

第三类是缓存里的数据可能不是 Redisson 写的。比如订单服务用 Spring 的RedisTemplate写了一份 JSON，或者用了别的序列化框架，数据格式和 Redisson 期望的完全不一样。这种情况更隐蔽，因为单看某一个服务都正常，只有跨服务读数据时才暴露。

2. 追根溯源：Redis 里的数据为什么带 @class

2.1 Redisson 默认序列化链路

Redisson 默认使用的编解码器是JsonJacksonCodec，它的实现核心是 Jackson 的ObjectMapper。在 Redisson 的默认配置里，这个ObjectMapper会开启 Jackson 的默认类型机制（default typing），序列化对象时会额外写入一个类型标识字段，这个字段名就是@class。

所以，如果你从来没做过任何特殊配置，直接用redissonClient.getBucket("user:" + id)往 Redis 里写一个 POJO，实际看到的存储内容会是这种带@class的 JSON：

{ "@class": "com.example.cache.dto.UserDTO", "name": "zhangsan", "age": 28 }

这一点很多人不知道，因为平时直接用工具看 Redis 里存的是字符串，不会太在意字段细节。可一旦读取端的配置和写入端不一致，@class就会成为第一个矛盾爆发点。

2.2 @class 字段是干什么用的

用一个生活中的例子来理解@class：它相当于快递箱里的物品清单。快递员不需要打开箱子就知道里面是人名还是鞋盒，因为有清单写在箱子上。Jackson 也一样，当它看到@class这个字段时，就知道要去加载哪个 Java 类，然后把后面的属性填充进去。

为什么需要这个清单？因为 Java 的类型系统在反序列化时存在“多态性”。比如你有一个接口类型CacheDTO，实际存放的是UserDTO；又比如你的字段类型是Object，实际塞进去一个List。如果不告诉 Jackson 具体的类名，它面对“一个 JSON 对象到底该变成哪个类”这个问题时根本无法决策。

更关键的是，Redisson 默认开启的NON_FINAL策略，意味着只要目标类型不是final修饰的类，就会在 JSON 里附加@class。这也是为什么普通 POJO 也会被写上@class的原因。

2.3 为什么 get() 会突然踩雷

很多人的第一反应是“昨天还好好的，今天怎么突然报错了”。在这个现象背后，真正变化的不一定是代码，而是 Redis 里的存量数据。

举例来说，某套系统分为登录服务和用户服务，登录服务写入用户缓存时一直用的是默认 Redisson 配置，Redis 里全是带@class的 JSON。后来用户服务为了接入一个第三方的序列化工具，在自定义ObjectMapper时没有考虑默认类型，上线后所有从 Redis 读数据的接口开始报missing type id property '@class'。

还有一种很常见的情况：缓存 key 没变，但数据被另一个调度任务用StringRedisTemplate覆盖写了普通 JSON。等到业务代码去get()时，Jackson 看到的是一个不带类型信息的 JSON，自然就炸了。

所以，不要只盯着get()方法本身。出现这个异常时，先确认 Redis 里的真实数据长什么样，再去看代码配置。

3. 先看数据再动手：两个排查命令

3.1 用 redis-cli 查看缓存的真实内容

遇到这个报错，第一件事不是改代码，而是直接看一下 Redis 里到底存的什么。命令很简单：

redis-cli GET user:10086

如果返回的是这种格式：

{"@class":"com.example.cache.dto.UserDTO","name":"zhangsan","age":28}

说明数据本身是带@class的，问题大概率出在读取端的配置，也就是你的 Jackson 或者 Redisson Codec 没有按默认类型解析。

如果返回的是这种不带@class的普通 JSON：

{"name":"zhangsan","age":28}

说明数据在写入端就没带类型信息，可能是写入时用了别的序列化方式。这时候要顺着写入链路去查，只改读取端是治标不治本。

3.2 快速判断是哪一类序列化器写入的

可以用一个更直观的小技巧：把 Redis 返回的内容开头几个字节贴出来对比。

• 如果是{"@class":"com.xxx...开头，说明是 Jackson default typing 写入的，对应 Redisson 默认JsonJacksonCodec或者 Spring 的GenericJackson2JsonRedisSerializer。
• 如果是\xAC\xED\x00\x05这类二进制开头，说明是 JDK 原生序列化写入的，对应JdkSerializationRedisSerializer。
• 如果是普通 JSON 但没有@class，说明写入端用的是自定义的 Jackson，并且没有开启默认类型机制，或者干脆用的是StringRedisTemplate存字符串。

这一步不需要什么高级工具，直接把redis-cli GET的输出贴到 IDE 或终端里就能判断。很多时候问题就藏在“你以为写的是对象，实际存的是字符串”这种低级差异里。

4. 修复方案：从统一配置到数据清理

4.1 方案A：恢复默认序列化规则，让 @class 正常写入和读取

如果确定 Redis 里的数据是带@class的，而读取端是自定义配置导致解析失败，修复思路就是让读取端的 Jackson 开启 default typing，恢复 Redisson 默认的行为逻辑。

对应初始化RedissonClient的配置代码大致如下：

@Configuration public class RedissonConfig { @Bean public RedissonClient redissonClient() { Config config = new Config(); config.useSingleServer() .setAddress("redis://127.0.0.1:6379"); ObjectMapper mapper = new ObjectMapper(); mapper.activateDefaultTyping( mapper.getPolymorphicTypeValidator(), ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY ); config.setCodec(new JsonJacksonCodec(mapper)); return Redisson.create(config); } }

这里的关键是activateDefaultTyping这个方法。它有三个参数：第一个是多态类型校验器，第二个是DefaultTyping.NON_FINAL，表示只有非 final 类才写入类型信息；第三个是JsonTypeInfo.As.PROPERTY，表示类型信息以属性形式放在 JSON 里，属性名默认就是@class。

需要注意，如果你的项目用的是 Jackson 2.10 之前的旧版本，需要用enableDefaultTyping这个方法，因为activateDefaultTyping是在新版中才引入的。如果版本太老，强行照抄会直接编译报错。

4.2 方案B：多服务共用同一份 Codec 配置

如果问题出在多个服务之间配置不一致，最稳妥的做法就是把序列化配置放在一个公共模块里，所有服务都引用同一个配置类。

我见过的一个典型教训是：服务 A 和服务 B 都是微服务，各自初始化了RedissonClient。服务 A 用默认配置，服务 B 为了给字段加脱敏逻辑，自定义了ObjectMapper，但忘了开 default typing。结果服务 A 写入的缓存，服务 B 一读就报missing type id property '@class'。两边互相排查了很久，最后才发现在RedissonConfig这里差了配置。

解决起来也不复杂：把ObjectMapper的创建逻辑抽到一个公共的CacheCodecProvider里，所有服务都通过这个Provider获取 Codec。这样既能保证默认类型配置一致，也能统一序列化规则，以后加了新服务也不会再出现类似问题。

4.3 方案C：清理历史脏数据与灰度切换

改完代码后，如果 Redis 里已经躺着大量不带@class的旧数据，那你必须处理历史数据，否则存量 key 仍然会报错。

最直接的方式是清理相关缓存，让业务重新写入。删除可以使用redis-cli的 scan 方式，避免在生产环境直接执行keys这种危险命令：

redis-cli --scan --pattern "user:*" | xargs redis-cli DEL

如果不想停机清缓存，可以考虑做一个兼容逻辑：读取失败后，尝试用旧格式反序列化一次，成功后重新写入一个新格式的缓存。这样能实现平滑迁移，但代码复杂度会高一些，适合缓存数据量大、不能随便清的场景。

需要注意的是，清理缓存和切换配置要配合进行。先保证写入端已经恢复成带@class的默认格式，再清理旧数据，然后再读取，顺序反了会出现“清了但马上又写入错误格式”的情况。

4.4 方案D：换用其他序列化方案

如果项目对 JSON 可读性要求不高，或者业务对象多态场景太复杂，可以考虑换掉默认的 JSON 序列化器。Redisson 支持多种编码器，比如Kryo5Codec、FstCodec，还有带类型信息的TypedJsonJacksonCodec。

TypedJsonJacksonCodec是个有意思的选择，它也需要额外的 class 信息，但是使用方式和默认的JsonJacksonCodec不一样，它要求你在get()的时候明确指定目标类型。如果缓存 key 对应的类型是固定的，用这种方式可以绕过一部分@class问题。

不过要注意，换序列化方案不是零成本的。第一，新方案写入的数据，旧数据不一定能读；第二，跨语言访问 Redis 时，JSON 有天然的可读性优势，换了二进制序列化会丧失这个优势；第三，引入新依赖还要考虑版本兼容和稳定性。所以，除非你对 JSON 格式有明确的性能或者兼容性需求，不然我建议还是优先修配置，不要动底层的序列化方案。

5. 深入原理：Jackson default typing 详解

5.1 为什么 Object、接口和父类场景必须带类型信息

missing type id property '@class'这个异常，本质上并不是 Redisson 的 bug，而是 Jackson 多态类型解析的正常报错。理解它需要知道 Jackson 在反序列化时怎么决定“要把 JSON 变成哪个 Java 类”。

如果字段声明类型是具体的UserDTO，那 Jackson 不需要@class也知道要创建UserDTO实例。但如果字段类型是Object、接口、抽象类或者父类，情况就不同了。JSON 本身只是{"name":"zhangsan","age":28}，没有任何信息告诉 Jackson 它到底是UserDTO还是AdminDTO，甚至可能是OrderDTO。这时候只有依赖类型标识，Jackson 才能反射出正确的类并完成填充。

所以，DefaultTyping.NON_FINAL这么设计是有道理的：对于final类，不可能有子类，多态解析不必要；对于非 final 类，存储时记录类型，读取时才能准确还原。

5.2 Jackson 是如何解析 @class 的

当 Jackson 的 ObjectMapper 开启了 default typing 后，序列化一个 POJO 的过程可以简单拆成两步：

1. 根据当前运行时对象的具体类型，生成类型标识。默认情况下，类型标识就是类的全限定名，属性名固定为@class。
2. 把对象的其他字段继续按正常流程序列化，拼接到@class后面。

反序列化时则反过来：先读取@class的值，通过反射得到对应的 Java 类，然后按该类的字段结构去解析剩余 JSON 内容。如果 JSON 里没有@class，而目标类型又不是具体类，Jackson 就直接抛出MismatchedInputException，报错信息就是我们看到的missing type id property '@class'。

这里有一个很容易忽略的点：如果你定义了一个类，字段类型是Object，那么即使你往里面放的是一个具体对象，序列化时也会带上@class。相反，如果字段类型本身就是具体类，即使没有开启 default typing，Jackson 也可能不需要类型信息。也就是说，报不报这个错，和你字段声明类型有直接关系。

5.3 全局开启 Default Typing 的安全风险与白名单

网上很多帖子会告诉你“在 ObjectMapper 里加一行 enableDefaultTyping 就好了”，这句话本身不算错，但放在生产环境要非常谨慎。全局开启 default typing 是历史上许多反序列化漏洞的根源。

攻击者一旦能控制 JSON 内容，而你的反序列化器又允许任意类名，就可能通过构造恶意的@class指向危险类，进而触发任意代码执行。这也是为什么 Jackson 和 Fastjson 都出过大规模安全事件的原因。

在 Jackson 2.10 之后的版本，推荐做法是使用BasicPolymorphicTypeValidator来限制允许反序列化的类型白名单：

ObjectMapper mapper = new ObjectMapper(); BasicPolymorphicTypeValidator validator = BasicPolymorphicTypeValidator.builder() .allowIfSubType("com.example.cache.dto.") .allowIfSubType("java.util.") .build(); mapper.activateDefaultTyping(validator, ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY);

这样即使 JSON 里被塞了恶意类名，也会因为不在白名单里而被拒绝。不要把整个项目的 entity 包全放进去，只放真正需要做多态解析的包，缩小攻击面。

6. 完整修复示例：从报错到上线

6.1 问题项目背景（虚构演示）

假设有一个订单缓存服务，业务代码里通过 Redisson 获取订单对象：

RBucket<OrderDTO> bucket = redissonClient.getBucket("order:" + orderId); OrderDTO order = bucket.get();

某天上线一个新功能时，有同事在基础设施配置里给JsonJacksonCodec传了一个自定义ObjectMapper，目的是统一日期格式。但这个ObjectMapper没有开启 default typing。上线后，凡是命中旧订单缓存的接口都在get()时报missing type id property '@class'，而新写入的订单因为还带了@class，反而不受影响。

这个现象非常具有迷惑性：看起来像是“有的订单能读，有的不能读”，很多人会怀疑是数据问题，实际上只是旧数据格式和新读取配置不匹配。

6.2 修复后的配置代码

正确的做法是，在自定义ObjectMapper时保留 default typing，同时满足日期格式的需求：

ObjectMapper mapper = new ObjectMapper(); mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")); BasicPolymorphicTypeValidator validator = BasicPolymorphicTypeValidator.builder() .allowIfSubType("com.example.cache.dto.") .build(); mapper.activateDefaultTyping( validator, ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY ); Config config = new Config(); config.useSingleServer().setAddress("redis://127.0.0.1:6379"); config.setCodec(new JsonJacksonCodec(mapper)); RedissonClient client = Redisson.create(config);

改完配置后，新写入的缓存会正常带@class，读取端也能正确识别。对于存量旧数据，按照 4.3 里说的方案，先清理或迁移，再灰度放量。

6.3 上线前要检查的一致性清单

在准备发上线之前，建议按这个清单过一遍，能省掉很多线上故障：

• 所有服务是否引用了同一个 Codec 配置，而不是各自实现ObjectMapper。
• ObjectMapper是否启用了 default typing，并且配置了类型白名单。
• 项目使用的 Jackson 版本是 2.10 之前还是之后，使用的是enableDefaultTyping还是activateDefaultTyping。
• Redis 中是否还留有旧格式数据，如需保留，是否已经做了兼容或清理方案。
• 测试环境是否验证过“写入一次，再读取一次”的完整流程。
• 是否把OrderDTO等业务 DTO 的包路径加入了白名单。

这份清单不是摆设。我见过不少项目，改完配置后只测了新写入的数据，忽略了线上旧缓存，结果一上线立刻被打回原形。序列化问题最麻烦的地方就在于“配置错了但当时不报错，等数据积累到一定量才统一爆掉”。

7. 线上问题排查速查表

7.1 六步定位法

如果不小心在生产环境遇到类似报错，按照下面的顺序排查，一般能在半小时内定位到根因。

第一步，拿完整日志堆栈。重点看异常是哪个 Codec 抛出来的，判断是不是JsonJacksonCodec。

第二步，用redis-cli GET key查看真实数据，确认有没有@class。

第三步，找写入端代码。搜索所有往该 key 写入数据的服务，确认它们的RedissonClient初始化方式。

第四步，找读取端代码。确认读取时用的RedissonClient是不是同一个配置，有没有自定义ObjectMapper。

第五步，对比新旧数据。如果 Redis 里同时存在带@class和不带@class的数据，说明写入端中途改过配置，或者有多个写入源。

第六步，根据结果选方案。数据普遍没带@class就改写入端；数据带了但读不了就改读取端；两边都有问题就统一配置后清理存量。

7.2 常见报错对照表

8. 踩过这次坑后的个人经验

序列化报错往往是分布式系统里最“玄学”的问题之一，因为它不像连接超时那样能被监控直接抓到，也不像空指针那样能看到具体字段。它的问题真正出现在数据格式和代码配置的缝隙里，两边各自运行都很正常，结合在一起就炸了。

我现在的习惯是，涉及缓存序列化的配置，全部放到公共基础设施模块里，所有服务禁止私自 new 出来一个新的ObjectMapper覆盖 Codec。另外，每次改完序列化配置，我都会在测试环境做一次“写入对象 -> 手动 GET 原始 JSON -> 重新读取对象”的完整回归，确保数据格式真的符合预期。

最后再分享一个小技巧：如果你实在改不动历史数据，又急着恢复业务，可以临时在读取端加一个兜底逻辑，先按新格式解析，失败后改用旧格式尝试。这个方案不优雅，但能先把线上稳住，再慢慢清理数据。记住，序列化配置最重要的是“写和读必须站在同一边”，只要能保证这一点，@class的恩怨自然就化解了。