API 设计 / 系统课时

执行 Schema Composition 检查

执行 Schema Composition 检查

联邦 Schema 能单独启动,并不代表它能安全进入 supergraph。本课把组合检查放进本地与 CI 流程:先验证多个 subgraph 是否可组合,再识别字段所有权冲突,最后用变更检查拦截可能破坏现有操作的发布。

学习目标

  • 使用 Rover 在本地组合多个 subgraph Schema,并把失败转换成发布门禁。
  • 区分字段所有权冲突、类型不一致与联邦指令约束错误。
  • 使用 rover subgraph check 检查候选 Schema 对现有 supergraph 与客户端操作的影响。

先把“能启动”与“能组合”分开

每个 subgraph 只证明自己的 SDL 与 Resolver 能工作;Composition 检查的是这些 Schema 放在一起后,能否形成一个语义一致、可被 Router 规划的 supergraph。常见失败包括同一非共享字段被多个 subgraph 解析、同名字段类型不一致,以及 @key、@requires、@provides 等联邦约束无法同时满足。

Federation Schema 从修改到发布的组合门禁流程

用 Rover 做本地组合

先准备一个 supergraph.yaml,明确每个 subgraph 的路由地址和 Schema 来源。下面的配置使用本地 SDL 文件;federation_version: 2 表示使用 Federation 2 组合方式。生产流水线更适合固定到与 Router 兼容的确切 Federation 版本,避免组合器自动升级带来意外变化。

yaml
federation_version: 2
subgraphs:
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      file: ./products.graphql
  reviews:
    routing_url: http://localhost:4002/graphql
    schema:
      file: ./reviews.graphql

配置文件本身不产生控制台输出。验证时执行组合,并确认生成的 supergraph 文件非空:

bash
rover supergraph compose --config supergraph.yaml > supergraph.graphql \
  && test -s supergraph.graphql \
  && echo "composition ok"

预期输出

text
composition ok

如果组合失败,Rover 会返回非零退出码,此时不能把生成文件作为 Router 的新配置继续发布。CI 应直接以命令退出码作为门禁,而不是匹配某条可能随 Rover 版本改变的错误文案。

处理字段所有权冲突

最常见的误区是“两个服务都有这个字段,所以加上 @shareable 就行”。正确顺序是先判断业务所有权:如果 Product.price 只有 pricing subgraph 才能可靠计算,就应保留单一解析方;如果多个 subgraph 都能独立返回同一语义、同一一致性要求的值,才考虑共享。

另一个常见冲突是字段签名不一致,例如一个 subgraph 定义 price: Int!,另一个定义 price: Float。这类问题应统一 API 契约,而不是试图让 Router 同时接受两种字段类型。Composition 的价值就是把跨团队契约冲突提前到构建阶段。

把 Schema 变更检查放进 CI

本地 Composition 只能证明当前候选文件彼此能组合;它不知道目标 graph ref 中已经发布的 Schema,也不能仅凭本地文件判断现有客户端操作是否受影响。使用 GraphOS 时,可以在合并前运行 rover subgraph check,把候选 subgraph 与指定变体比较,并执行相应的 build、operation 等 Schema checks。

下面脚本依赖已配置的 APOLLO_KEY 与 APOLLO_GRAPH_REF,适合放进 CI:

bash
if rover subgraph check "$APOLLO_GRAPH_REF" \
  --name reviews \
  --schema ./reviews.graphql; then
  echo "schema check passed"
else
  echo "schema check failed"
  exit 1
fi

预期结果:检查通过时 Rover 会先输出本次检查详情,随后脚本输出:

text
schema check passed

发布门禁至少要同时满足“候选 Schema 可以完成 Composition”和“相对目标环境没有不可接受的破坏性变化”。前者解决 supergraph 的结构一致性,后者解决 Schema 演进安全性;任何一步失败,都应该先修复 Schema,而不是让冲突进入 Router 运行阶段。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

执行 Schema Composition 检查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通