GraphQL 与 REST 双栈:共享 hydrate 对齐字段,信封差别硬拧

Hello,我是小兔大白糖。 前端同事说:「换协议别换意思。」——听起来合理,真摩擦却很少出在字段名拼写上,而在「同一实体两套拼装」和「信封形态不一样」。写成这篇,给要做 GraphQL / REST 双栈语义对齐调研 的初中级后端同学:不是某次迁移联调 runbook,而是业界向、可复述的 parity(字段对齐)心智模型。
说明:文中
FULL指「业务字段全量选取」的教学标签,不是某网关私有契约。hydrate/BuildXForAPI泛指「把领域数据装成对外 DTO」的共享组装层。示例 ids、字段名为脱敏示意。姊妹篇/blog/graphql_rest_perf_fair_compare/管性能对照是否公平;本文只管语义对齐与信封差——两件事别混谈。
估计阅读时间:10 分钟
目录
为什么现在要关心
双栈最贵的不是多写一个 handler,而是静默漂移:一边有值,另一边同路径空。
现场里「换协议不换意思」常被理解成「字段名对上就行」。评审一追问,暴露的往往是:
| 你以为对齐了 | 实际在漂 |
|---|---|
| 字段名一致 | 两套拼装:详情挂了税点,列表 accidentally 没挂 |
| 都返回了实体 | 一个 cache 前 attach,一个 cache 后 attach |
| 批量接口「差不多」 | 一边有序 null 槽,一边 compact 无序;全 miss 一边 200 全 null,一边 400 |
| 「GQL 多几个 dashboard 字段」 | 强迫 REST 合同外也塞,扩大破坏面 |
性能对比用不同 selection(选取)深度却宣称「GQL 更慢」,是另一类误伤——见姊妹篇。本文先把 parity 钉死:业务意思同源,信封可以不同。
问题空间:对齐的是菜,不是盘子
真实摩擦通常落在三层,不是「要不要统一成一种 JSON 形状」。
-
业务字段是否同源组装
同一实体,走共享 hydrate,还是 REST handler / GraphQL resolver 各自拼 DTO? -
信封(envelope)差异
批量顺序、缺失是null还是省略、批量上限、全 miss 是 200 还是 4xx——协议习惯不同,客户端要有约定。 -
协议多出来的字段
GraphQL 可按 selection 多拿可选字段;不代表 REST 合同必须同步膨胀。
把第 2、3 层硬拧成「两边 JSON 长得一模一样」,成本高、收益低,还容易破坏已有 REST 客户端。
心智模型:同一厨房,两套餐盘
菜必须同一锅炒;盘子可以圆可以方——别让后厨为方盘改菜谱。
| 类比 | 对应 | 硬规则一句话 |
|---|---|---|
| 菜 | 业务字段 / 领域值 | 同源 hydrate;FULL 下关键路径应对齐 |
| 盘子 | 信封:顺序、null 槽、compact、HTTP 状态 | 允许差;写进客户端适配约定 |
| 服务员 | 前端 / BFF 适配层 | 用 id map、过滤 null,不强迫后厨改菜 |
类比局限:厨房管的是组装同源;它解释不了 DataLoader 批处理、缓存冷热或网关序列化成本——那些归性能对照,不归 parity。
业界常见模式对比
已有双栈时,默认倾向:共享 hydrate + 信封对照表 + fixture 验收。
| 模式 | 做法 | 代价 | 适用 |
|---|---|---|---|
| A. 两套拼装 | REST handler / GQL resolver 各自拼 DTO | 最快分叉;字段必漂移 | 短期 PoC |
| B. 共享 hydrate | 核心组装函数两协议复用;协议层只做信封 | 要抽公共层、改调用点 | 生产双栈默认 |
| C. 以 GQL 为源生成 REST | schema / 工具链驱动 REST | 工具链重;遗留 REST 难吞 | 绿场 |
| D. BFF 只暴露一种 | 对外砍掉双栈 | 少对齐税;迁移成本一次性付清 | 能砍掉一种协议时 |
没有银弹:B 的副作用是多一层抽象、新人要先找「真正拼装点」;A 的副作用是几周后「同名字段不同意思」。选 B 时,把「谁负责信封」写进一页约定,比事后对 JSON 肉眼 diff 便宜。
三条硬规则
FULL 下业务字段对齐;信封差用适配消化;验收只比业务字段。
-
FULL selection 下业务字段应对齐
同一实体在两协议下,关键业务值同源。允许 GraphQL 多可选字段;不允许 REST 有值而 GraphQL 同路径空或缺。 -
信封差异用适配层消化,不靠改协议硬拧成一样
有序 + null 槽 vs 无序 compact、批量上限、全 miss 语义——写进客户端约定,而不是强行让 REST 返回 GraphQL 形状的数组。 -
验收用固定 fixture 对照 JSON
只比业务字段;声明规则:「GQL 可多、REST 不可单边有」。
可复述版:同事拷问时,先答「菜同源、盘可异、CI 比菜不比盘」。
信封差异清单
把差异列成一页表给前端,比强迫两边 JSON 同形更省破坏面。
| 差异 | GraphQL 常见 | REST 常见 | FE / 客户端适配 |
|---|---|---|---|
| 批量顺序 | 常按输入 id 顺序 | 常无序 | map by id |
| 缺失槽 | null 占位 | 常直接省略 | whereNotNull / 填默认 |
| 批量上限 | 校验常报 BAD_USER_INPUT 一类 | 400 / 同错码族 | 客户端 chunk |
| 全 miss | 常仍 200 + 全 null | 有的 API 直接 400 | 统一当空列表(产品约定) |
| 额外字段 | selection 可选多拿 | 合同外不加 | 不选即可 |
「常见」是业界习惯归纳,不是某厂商官方内幕;你们团队的具体状态码仍以公开合同为准。表的价值在于:先承认差,再约定谁消化——消化方通常是客户端或薄 BFF,不是改协议硬统一。
示意验收:fixture 怎么比
固定 ids,比 A/B 业务字段深度相等;missing 不要求 REST 出 null 槽。
教学示意(脱敏):
fixture ids = [A, missing, B]
GQL FULL → [objA, null, objB]
REST list → [{id:B,...},{id:A,...}] // 无序 compact 亦可
assert: 对 A/B 业务字段深度相等
assert: missing 不要求 REST 出 null 槽
forbid: REST.A.tax 有值而 GQL.A.tax 空/缺CI 里把这条写成「业务字段 parity」检查即可。信封形状、HTTP 状态差异走契约测试或客户端单测,别和业务字段深度相等揉成一个 assert——揉了之后,修信封会误伤「字段漂移」告警,或反过来。
反模式
下面几条会把「看起来对齐」写成线上静默漂移。
-
详情挂扩展块,列表 accidentally 不一致
税点、权限块、dashboard 摘要只挂在一条路径上。列表 / 详情 / by-keys 应用同一 attach 时机与同一 hydrate。 -
用不同 selection 深度做性能对比,却宣称协议更慢
那是 trim(裁剪载荷)故事,不是 parity。见姊妹篇公平对照。 -
为对齐强行让 REST 返回 null 槽数组
扩大破坏面:旧客户端、分页语义、空列表约定全可能炸。信封差留给适配层。 -
「字段名对齐了」但 attach 时机不同
一个走 cache 前组装,一个走 cache 后组装——同名字段,不同新鲜度,最难排。 -
把 GQL 可选字段强迫进 REST 合同
GraphQL 的 selection 优势被浪费,REST 载荷与兼容成本上升。规则是 GQL 可多,不是两边必须一样胖。
选型结论
- 双栈先抽共享 hydrate,再谈 resolver / handler 薄封装;别长期停在模式 A。
- 维护一页信封差异表给前端;不改协议硬统一 JSON 形状。
- CI 用 fixture 做业务字段 parity;声明「GQL 可多、REST 不可单边有」。
- 列表 / 详情 / by-keys 同一 attach 时机,避免 cache 前后分叉。
- 性能对比另开公平基准,不与 parity 混谈 →
/blog/graphql_rest_perf_fair_compare/。