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

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 形状」。

  1. 业务字段是否同源组装
    同一实体,走共享 hydrate,还是 REST handler / GraphQL resolver 各自拼 DTO?

  2. 信封(envelope)差异
    批量顺序、缺失是 null 还是省略、批量上限、全 miss 是 200 还是 4xx——协议习惯不同,客户端要有约定。

  3. 协议多出来的字段
    GraphQL 可按 selection 多拿可选字段;不代表 REST 合同必须同步膨胀。

把第 2、3 层硬拧成「两边 JSON 长得一模一样」,成本高、收益低,还容易破坏已有 REST 客户端。


心智模型:同一厨房,两套餐盘

菜必须同一锅炒;盘子可以圆可以方——别让后厨为方盘改菜谱。

共享 hydrate 厨房输出到 GraphQL 与 REST 两套信封餐盘
共享 hydrate 厨房输出到 GraphQL 与 REST 两套信封餐盘 · 点击查看 SVG 原图
类比对应硬规则一句话
菜业务字段 / 领域值同源 hydrate;FULL 下关键路径应对齐
盘子信封:顺序、null 槽、compact、HTTP 状态允许差;写进客户端适配约定
服务员前端 / BFF 适配层用 id map、过滤 null,不强迫后厨改菜

类比局限:厨房管的是组装同源;它解释不了 DataLoader 批处理、缓存冷热或网关序列化成本——那些归性能对照,不归 parity。


业界常见模式对比

已有双栈时,默认倾向:共享 hydrate + 信封对照表 + fixture 验收。

模式做法代价适用
A. 两套拼装REST handler / GQL resolver 各自拼 DTO最快分叉;字段必漂移短期 PoC
B. 共享 hydrate核心组装函数两协议复用;协议层只做信封要抽公共层、改调用点生产双栈默认
C. 以 GQL 为源生成 RESTschema / 工具链驱动 REST工具链重;遗留 REST 难吞绿场
D. BFF 只暴露一种对外砍掉双栈少对齐税;迁移成本一次性付清能砍掉一种协议时

没有银弹:B 的副作用是多一层抽象、新人要先找「真正拼装点」;A 的副作用是几周后「同名字段不同意思」。选 B 时,把「谁负责信封」写进一页约定,比事后对 JSON 肉眼 diff 便宜。


三条硬规则

FULL 下业务字段对齐;信封差用适配消化;验收只比业务字段。

  1. FULL selection 下业务字段应对齐
    同一实体在两协议下,关键业务值同源。允许 GraphQL 多可选字段;不允许 REST 有值而 GraphQL 同路径空或缺。

  2. 信封差异用适配层消化,不靠改协议硬拧成一样
    有序 + null 槽 vs 无序 compact、批量上限、全 miss 语义——写进客户端约定,而不是强行让 REST 返回 GraphQL 形状的数组。

  3. 验收用固定 fixture 对照 JSON
    只比业务字段;声明规则:「GQL 可多、REST 不可单边有」。

可复述版:同事拷问时,先答「菜同源、盘可异、CI 比菜不比盘」。


信封差异清单

把差异列成一页表给前端,比强迫两边 JSON 同形更省破坏面。

GraphQL 有序 null 槽与 REST compact 无序列表对比
GraphQL 有序 null 槽与 REST compact 无序列表对比 · 点击查看 SVG 原图
差异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 槽。

Parity 验收:业务字段对齐,允许 GQL 多字段,禁止 REST 单边有值
Parity 验收:业务字段对齐,允许 GQL 多字段,禁止 REST 单边有值 · 点击查看 SVG 原图

教学示意(脱敏):

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——揉了之后,修信封会误伤「字段漂移」告警,或反过来。


反模式

下面几条会把「看起来对齐」写成线上静默漂移。

  1. 详情挂扩展块,列表 accidentally 不一致
    税点、权限块、dashboard 摘要只挂在一条路径上。列表 / 详情 / by-keys 应用同一 attach 时机与同一 hydrate。

  2. 用不同 selection 深度做性能对比,却宣称协议更慢
    那是 trim(裁剪载荷)故事,不是 parity。见姊妹篇公平对照。

  3. 为对齐强行让 REST 返回 null 槽数组
    扩大破坏面:旧客户端、分页语义、空列表约定全可能炸。信封差留给适配层。

  4. 「字段名对齐了」但 attach 时机不同
    一个走 cache 前组装,一个走 cache 后组装——同名字段,不同新鲜度,最难排。

  5. 把 GQL 可选字段强迫进 REST 合同
    GraphQL 的 selection 优势被浪费,REST 载荷与兼容成本上升。规则是 GQL 可多,不是两边必须一样胖。


选型结论

  1. 双栈先抽共享 hydrate,再谈 resolver / handler 薄封装;别长期停在模式 A。
  2. 维护一页信封差异表给前端;不改协议硬统一 JSON 形状。
  3. CI 用 fixture 做业务字段 parity;声明「GQL 可多、REST 不可单边有」。
  4. 列表 / 详情 / by-keys 同一 attach 时机,避免 cache 前后分叉。
  5. 性能对比另开公平基准,不与 parity 混谈 → /blog/graphql_rest_perf_fair_compare/。