API 设计 / 系统课时
检查 Schema 变更兼容性
检查 Schema 变更兼容性
这一节把 Schema 兼容性检查变成可执行门禁:先计算旧、新 Schema 的结构差异,再叠加真实操作的字段使用情况与弃用时间,只有满足退役策略的删除才能放行,其余破坏性变更直接让 CI 失败。
学习目标
- 用 Schema diff 识别删除字段、改类型等破坏性变化
- 把已知操作使用情况加入判断,避免删除仍在使用的字段
- 用
@deprecated与弃用时长建立可自动执行的下线策略
兼容性不能只看 diff
结构 diff 能回答“Schema 发生了什么变化”,却不能单独回答“现在是否可以发布”。例如删除字段在结构上一定是 breaking change,但如果该字段已经弃用足够长时间,并且操作注册表确认没有客户端继续使用,团队可以按既定策略允许它下线。
反过来,“没有观测到使用”也不等于安全。只有当使用数据覆盖范围明确、字段已正式弃用且满足最短等待期时,才应把删除从阻断项降级为允许项;未知使用情况应按不安全处理。
| 变更情况 | 已知使用 | 弃用策略 | 门禁结果 |
|---|---|---|---|
| 删除字段 | 是 | 任意 | 阻断 |
| 删除字段 | 否 | 已弃用且达到最短等待期 | 允许 |
| 删除字段 | 否或未知 | 未弃用、无日期或等待期不足 | 阻断 |
| 其他 breaking diff | 任意 | 默认不豁免 | 阻断 |

用 GraphQL.js 实现一个最小门禁
下面的脚本同时使用 findBreakingChanges、操作文档和弃用元数据。为了让示例独立可运行,旧 Schema、新 Schema、已知操作和弃用日期都放在同一文件中;生产环境通常把它们替换成仓库文件、Schema Registry 与操作注册表的输入。
// 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');
}执行门禁脚本:
node schema-compat.mjs预期输出:
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 演进可以持续进行,同时把误删仍在使用字段的风险挡在合并或发布之前。