API 设计 / 系统课时

检查 Schema 变更兼容性

检查 Schema 变更兼容性

这一节把 Schema 兼容性检查变成可执行门禁:先计算旧、新 Schema 的结构差异,再叠加真实操作的字段使用情况与弃用时间,只有满足退役策略的删除才能放行,其余破坏性变更直接让 CI 失败。

学习目标

  • 用 Schema diff 识别删除字段、改类型等破坏性变化
  • 把已知操作使用情况加入判断,避免删除仍在使用的字段
  • 用 @deprecated 与弃用时长建立可自动执行的下线策略

兼容性不能只看 diff

结构 diff 能回答“Schema 发生了什么变化”,却不能单独回答“现在是否可以发布”。例如删除字段在结构上一定是 breaking change,但如果该字段已经弃用足够长时间,并且操作注册表确认没有客户端继续使用,团队可以按既定策略允许它下线。

反过来,“没有观测到使用”也不等于安全。只有当使用数据覆盖范围明确、字段已正式弃用且满足最短等待期时,才应把删除从阻断项降级为允许项;未知使用情况应按不安全处理。

变更情况 已知使用 弃用策略 门禁结果
删除字段 是 任意 阻断
删除字段 否 已弃用且达到最短等待期 允许
删除字段 否或未知 未弃用、无日期或等待期不足 阻断
其他 breaking diff 任意 默认不豁免 阻断

GraphQL Schema 兼容性门禁流程

用 GraphQL.js 实现一个最小门禁

下面的脚本同时使用 findBreakingChanges、操作文档和弃用元数据。为了让示例独立可运行,旧 Schema、新 Schema、已知操作和弃用日期都放在同一文件中;生产环境通常把它们替换成仓库文件、Schema Registry 与操作注册表的输入。

js
// schema-compat.mjs
import {
  TypeInfo,
  buildSchema,
  findBreakingChanges,
  isInterfaceType,
  isObjectType,
  parse,
  visit,
  visitWithTypeInfo,
} from 'graphql';

const oldSDL = `
  type Query {
    product(id: ID!): Product!
    legacyProduct(id: ID!): Product
      @deprecated(reason: "Use product")
  }

  type Product {
    id: ID!
    name: String!
  }
`;

const newSDL = `
  type Query {
    product(id: ID!): Product!
  }

  type Product {
    id: ID!
    name: String!
  }
`;

const knownOperations = `
  query ProductPage($id: ID!) {
    product(id: $id) {
      id
      name
    }
  }
`;

const deprecatedSince = {
  'Query.legacyProduct': '2026-06-01',
};

const minDeprecationDays = 30;
const oldSchema = buildSchema(oldSDL);
const newSchema = buildSchema(newSDL);

function collectUsedFields(schema, source) {
  const used = new Set();
  const typeInfo = new TypeInfo(schema);

  visit(
    parse(source),
    visitWithTypeInfo(typeInfo, {
      Field(node) {
        const parent = typeInfo.getParentType();
        if (parent) used.add(`${parent.name}.${node.name.value}`);
      },
    }),
  );
  return used;
}

function collectRemovedFields(before, after) {
  const removed = [];

  for (const type of Object.values(before.getTypeMap())) {
    if (type.name.startsWith('__')) continue;
    if (!isObjectType(type) && !isInterfaceType(type)) continue;

    const nextType = after.getType(type.name);
    if (!nextType || (!isObjectType(nextType) && !isInterfaceType(nextType))) {
      continue;
    }

    const nextFields = nextType.getFields();
    for (const field of Object.values(type.getFields())) {
      if (!nextFields[field.name]) {
        removed.push({
          coordinate: `${type.name}.${field.name}`,
          deprecationReason: field.deprecationReason,
        });
      }
    }
  }

  return removed;
}

function ageInDays(dateText) {
  return Math.floor(
    (Date.now() - new Date(`${dateText}T00:00:00Z`).getTime()) / 86_400_000,
  );
}

const usedFields = collectUsedFields(oldSchema, knownOperations);
const breakingChanges = findBreakingChanges(oldSchema, newSchema);
const removedFields = collectRemovedFields(oldSchema, newSchema);
const violations = [];
const allowedRemovals = [];

for (const change of breakingChanges) {
  if (change.type !== 'FIELD_REMOVED') {
    violations.push(`breaking diff: ${change.description}`);
  }
}

for (const field of removedFields) {
  const used = usedFields.has(field.coordinate);
  const since = deprecatedSince[field.coordinate];
  const oldEnough =
    Boolean(field.deprecationReason) &&
    Boolean(since) &&
    ageInDays(since) >= minDeprecationDays;

  if (used || !oldEnough) {
    violations.push(
      `${field.coordinate}: used=${used}, deprecatedLongEnough=${oldEnough}`,
    );
  } else {
    allowedRemovals.push(field.coordinate);
  }
}

console.log(`Structural breaking changes: ${breakingChanges.length}`);
console.log(`Known used fields: ${[...usedFields].sort().join(', ')}`);
console.log(`Allowed removals: ${allowedRemovals.join(', ') || '(none)'}`);

if (violations.length > 0) {
  for (const violation of violations) console.error(`BLOCK: ${violation}`);
  process.exitCode = 1;
} else {
  console.log('Schema compatibility check passed');
}

执行门禁脚本:

bash
node schema-compat.mjs

预期输出:

text
Structural breaking changes: 1
Known used fields: Product.id, Product.name, Query.product
Allowed removals: Query.legacyProduct
Schema compatibility check passed

示例中 legacyProduct 在结构 diff 里仍属于 breaking change,但已知操作没有引用它,同时旧 Schema 带有 @deprecated,并且 deprecatedSince 已超过 30 天,因此策略允许删除。实际运行日期不同不会改变这组示例在 2026-07-01 之后的结论。

让使用数据真正可信

knownOperations 在真实系统中不应靠人工手抄。更可靠的来源是持久化查询清单、客户端操作注册表或服务器端经过采样与去重的 operation registry。门禁需要明确数据覆盖窗口和客户端版本范围,否则“未发现使用”只能说明“观测不到”,不能证明字段可安全删除。

如果存在移动端、桌面端等长发布周期客户端,弃用窗口通常要覆盖其升级周期。仅凭最近几天的流量就删除字段,容易让暂时离线或低频客户端在恢复后直接失败。

把弃用策略变成可审计规则

字段准备下线时,应先添加 @deprecated(reason: "..."),再记录机器可读的 deprecatedSince。到期后 CI 同时检查三件事:字段没有已知使用、弃用元数据存在、等待期达到阈值。任何一项缺失都阻断删除。

最终目标不是追求“零 breaking diff”,而是让每一次破坏性变化都有证据、等待期和自动化判定。这样 Schema 演进可以持续进行,同时把误删仍在使用字段的风险挡在合并或发布之前。

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

目录与阅读设置

阅读设置

17

记录一个想法

检查 Schema 变更兼容性

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

登录哪都通