概述
GraphQL 的灵活性使字段删除成为对既有查询的破坏。每次变更先做 schema 差异分类，能区分安全与破坏；弃用而非删除、跟踪用量、零用量后再移除，再以 CI 门控，可让 schema 持续演进而不伤害客户端。
关键步骤
- 每次变更运行 schema 差异并区分破坏与安全。
- 以弃用替代删除并跟踪字段用量。
- 仅在用量归零后移除弃用字段。
- 在 CI 中按分类门控 schema 检查。
验证
- 安全变更通过 CI，破坏性变更被拒。
- 字段删除前用量为零。
- 弃用字段有跟踪记录。
- 客户端查询未被打断。
决策点
破坏性变更只应在新大版本与迁移时间线下允许；用量遥测会漏掉低频客户端，删除前应结合消费方确认。
适用范围
本条目围绕「GraphQL Schema 治理工作流」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。
npx graphql-inspector diff old.graphql new.graphql
# breaking changes are flagged with a non-zero exit