中文
devexamples
← Workflows

阅读中文版本

GraphQL Schema Governance Workflow

Review schema changes for breaking impact, enforce deprecation instead of removal, track field usage, and gate the schema in CI.

intermediate~90 mingraphqlapigovernance

Objective

Keep a GraphQL schema evolving without breaking existing clients.

Environment

  • A GraphQL schema with a registry or check tool
  • Field usage telemetry

Steps

1. Run a schema diff on every

Run a schema diff on every change and classify breaking versus safe.

Expected state: Breaking changes are identified.

2. Deprecate fields instead of removing them,

Deprecate fields instead of removing them, and track usage.

Expected state: You know which deprecated fields are safe to remove.

3. Remove a deprecated field only

Remove a deprecated field only when usage is zero.

Expected state: Removal is data-driven.

4. Gate the schema check in CI

Gate the schema check in CI on the classification.

Expected state: Breaks cannot merge.

Decision points

Block all breaking changes?

  • Yes
  • Allow with a major version

Allow breaking changes only behind a new major version and a migration timeline.

Trust usage telemetry alone?

  • Yes
  • Combine with client survey

Telemetry misses off-peak clients; combine with consumer confirmation before removal.

Expected outcome

A schema that evolves additively and removes fields only when usage telemetry proves they are unused.

Verification

Confirm the CI check passes for safe changes and fails for breaking ones, and that removal only happens for zero-usage fields.

Cleanup

Update the schema registry and the deprecation tracking sheet.

Overview

Keep a GraphQL schema evolving without breaking existing clients. Confirm the CI check passes for safe changes and fails for breaking ones, and that removal only happens for zero-usage fields.

Steps

  1. Run a schema diff on every change and classify breaking versus safe. Expected state: Breaking changes are identified.
  2. Deprecate fields instead of removing them, and track usage. Expected state: You know which deprecated fields are safe to remove.
  3. Remove a deprecated field only when usage is zero. Expected state: Removal is data-driven.
  4. Gate the schema check in CI on the classification. Expected state: Breaks cannot merge.
npx graphql-inspector diff old.graphql new.graphql
# breaking changes are flagged with a non-zero exit

Verification

  • A schema that evolves additively and removes fields only when usage telemetry proves they are unused.

Decision points

  • Block all breaking changes? Options: Yes; Allow with a major version. Recommended: Allow breaking changes only behind a new major version and a migration timeline.
  • Trust usage telemetry alone? Options: Yes; Combine with client survey. Recommended: Telemetry misses off-peak clients; combine with consumer confirmation before removal.