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 等联邦约束无法同时满足。

用 Rover 做本地组合
先准备一个 supergraph.yaml,明确每个 subgraph 的路由地址和 Schema 来源。下面的配置使用本地 SDL 文件;federation_version: 2 表示使用 Federation 2 组合方式。生产流水线更适合固定到与 Router 兼容的确切 Federation 版本,避免组合器自动升级带来意外变化。
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 文件非空:
rover supergraph compose --config supergraph.yaml > supergraph.graphql \
&& test -s supergraph.graphql \
&& echo "composition ok"预期输出
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:
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 会先输出本次检查详情,随后脚本输出:
schema check passed发布门禁至少要同时满足“候选 Schema 可以完成 Composition”和“相对目标环境没有不可接受的破坏性变化”。前者解决 supergraph 的结构一致性,后者解决 Schema 演进安全性;任何一步失败,都应该先修复 Schema,而不是让冲突进入 Router 运行阶段。