← 返回文章列表
所属专题:架构之道

JSON 向后兼容、RPC 调用与 Redis 缓存失效全解析

by李奕锦年份:2026字数:800阅读时长:2 分钟

这条链路上没有一行业务逻辑是错的——问题在于同一条数据在“缓存命中”与“缓存未命中”两条路径里被拼成了两个版本。

TL;DR · 核心结论

  • 1新增字段属于增量扩展,对旧客户端天然向后兼容;只有改类型、重命名或删字段才是破坏性变更,必须同步客户端。
  • 2RPC 调用本质是网络 IO,必须配置合理的超时与降级 / 熔断策略,防止上游卡顿拖垮本服务线程池。
  • 3缓存只应决定"字段从哪来",不应决定"字段有没有":命中与未命中的组装链路必须收敛到同一个方法。

架构之道 · 字段新增与缓存契约

2
新增通用属性
1
RPC 依赖
2
组装路径
0
破坏性变更

排序接口要新增两个通用属性:状态标识码 statusCode 与配置类型 configType。它们不存本地库,由上游基础数据微服务统一维护,因此这次改动需要跨服务取数,牵出 JSON 序列化与 RPC 两条链路。

需求背景

需求背景

statusCode 表示数据项状态(ACTIVE / PENDING / DISABLED),configType 表示业务配置类型(TYPE_A / TYPE_B),两者都由上游基础数据微服务维护,不在本服务本地库,只能跨服务获取。

向后兼容

新增字段本来就是向后兼容的

服务端把响应对象(VO)序列化成 JSON 再返回给客户端(Web、iOS、Android、小程序)。客户端反序列化时会忽略未定义的未知字段,所以新增字段对旧客户端天然兼容,不需要强制升级。

// 变更前
{ "id": 1, "name": "示例项" }
// 变更后:旧客户端自动忽略未知字段
{ "id": 1, "name": "示例项", "statusCode": "ACTIVE", "configType": "TYPE_A" }

只有修改已有字段的类型、重命名字段或删除字段,才是破坏性变更,必须和客户端同步。

RPC 调用

跨服务取数:RPC 做了什么

新字段通过 RPC 框架(如 Dubbo、gRPC)跨服务获取。本地写一行调用,体验像本地函数,底层却完成了参数序列化、网络传输、对端反序列化并执行、结果序列化回传、本地反序列化五步。

List<BaseItem> list = iBaseDataMicroService.queryAllList();
多路径陷阱

多路径组装一致性

为了提速,组装通常分两条路径:命中缓存时直接取名称,未命中时穿透查询多语言服务并回写缓存。若只在未命中分支补充新字段,命中分支遗漏,Jackson 就会把缺失字段序列化成 null,表现为“时有时无”的随机 Bug。

// 反面:只在未命中分支补字段
if (cachedName != null) {
    vo.setDisplayName(cachedName);          // 命中:新字段缺失
} else {
    vo.setDisplayName(rpc.getDisplayName());
    vo.setStatusCode(rpc.getStatusCode());  // 未命中:字段齐全
    vo.setConfigType(rpc.getConfigType());
}

// 正面:分支只决定数据来源,组装收敛到一处
String name = cachedName != null ? cachedName : rpc.getDisplayName();
return assembleVo(rpc, name);
陷阱解剖
未命中路径
补齐了 statusCode 与 configType,首个请求正常
命中路径
只取缓存名称,遗漏新字段赋值,Jackson 序列化为 null
线上表现
缓存生成后字段突然变 null,Bug 随机出现,难以排查
比对式失效

缓存为何只存多语言

不同字段的变更频率与查询成本不同:多语言译名涉及跨服务字典表查询,开销大、频率高但内容稳定,适合缓存;基础属性随 RPC 主列表直接返回,无需二次查询,不必占用 Redis。失效采用“比对式校验”:只比对记录条数与主键 ID 集合是否与最新列表一致,不比对译名文本,也未配置 TTL。

演进与接入

演进与接入

补救办法有两种:给缓存加 TTL,到期自动重建;或在数据变更时用消息队列(Kafka / RocketMQ)发事件,主动清除对应 Key。对前端而言,本次升级零破坏性变更:statusCode 按契约映射为 UI 状态,configType 用于逻辑判断或透传下游。

本文属于 无魔法工程流派 的第 9 篇肉身实战。

阅读时长:2 分钟


文档信息

版权声明:自由转载-非商用-非衍生-保持署名(CC BY-NC-ND 3.0)

原文链接:https://yijinlee.com/articles/article-70

作者:李奕锦

商业用途或修改衍生请联系授权。


李奕锦
李奕锦

全栈工程师,业余马拉松选手。

TL;DR

  • 新增字段属于增量扩展,对旧客户端天然向后兼容;只有改类型、重命名或删字段才是破坏性变更,必须同步客户端。
  • RPC 调用本质是网络 IO,必须配置合理的超时与降级 / 熔断策略,防止上游卡顿拖垮本服务线程池。
  • 缓存只应决定"字段从哪来",不应决定"字段有没有":命中与未命中的组装链路必须收敛到同一个方法。
Tags:JavaRPCDubboJacksonRedis缓存一致性JSON 序列化接口契约后端相关

参考文章:相关链接

权威引文 · 官方文档 · 站内深度文

  1. 权威引文MDN · JSON

    语言无关的文本数据交换格式,是"新增字段向后兼容"的事实基础。

  2. RPC 跨服务调用的序列化、网络传输、超时与熔断治理机制。

  3. Java 对象字段缺失时默认序列化为 null,对应缓存命中分支漏赋值时的表现。

  4. 按语言维度 Hash 分桶缓存译名,是"比对式失效"策略的存储载体。

  5. 同属服务端契约与运行时陷阱的架构层复盘。

  6. 同样强调以类型收窄与迁移定稿守住前后端接口契约。

该专题下的阅读路径

系统设计原则 → 工程化实践 → 技术选型与重构

常见问题 FAQ

Q1. 接口只是多返回两个字段,为什么不用强制客户端升级?
新增字段属于增量扩展,是典型的向后兼容变更。客户端反序列化时会默认忽略未定义的未知字段,原有业务逻辑不受影响。只有修改已有字段的数据类型、重命名字段或删除字段,才属于破坏性变更(Breaking Change),必须拉上客户端严格同步。
Q2. 新增字段明明在 RPC 里查到了,为什么缓存命中后却变成 null?
Redis 里通常只缓存变动极少的多语言译名,新字段仍来自实时 RPC。如果只在"缓存未命中"分支补充了 statusCode 与 configType 的赋值,而"缓存命中"分支遗漏了,Jackson 就会把缺失字段序列化成 null。本质是"部分字段走缓存、部分字段走实时 RPC"的拼装模式在两条路径上逻辑不对等。
Q3. 为什么只缓存多语言译名,不把所有字段都塞进 Redis?
不同字段的变更频率与查询成本差异很大。多语言译名涉及跨服务的字典表查询,网络开销大、调用频率高但内容相对稳定,适合缓存;而 statusCode、configType 等基础属性随 RPC 主列表查询直接返回,无需跨服务二次查询,没必要增加 Redis 的存储负担。
Q4. Redis 里的条数和 ID 都没变,为什么运营改了译名却不刷新?
该接口采用"比对式失效":只校验 Redis 记录条数与主键 ID 集合是否与最新列表一致,不比对译名文本内容,且未配置 TTL。若运营只修改了某个特定项的中文译名,而总数与 ID 集合均未增减,缓存就不会自动刷新。标准解法是加上 TTL,或通过 MQ 在数据变更时主动清除对应 Key。

发表评论

分享你的想法和反馈

支持 Markdown 格式

0/5000