API 设计 / 系统课时
实施 Schema 兼容演进
实施 Schema 兼容演进
GraphQL 客户端只请求自己选择的字段,但 Schema 变化仍可能让旧查询在校验阶段直接失败。本篇建立“先新增、再迁移、后弃用、最后删除”的兼容演进流程,并用内省验证弃用状态,让服务端演进不再依赖所有客户端同时升级。
学习目标
- 区分兼容新增、危险变化与明确破坏性变化
- 使用
@deprecated完成字段迁移而不是原地改名 - 为旧字段删除设置可观测、可验证的退出条件
先判断变化属于哪一类
判断兼容性时要站在“已有查询是否仍能通过校验并保持原语义”的角度,而不是只看 Schema 是否能启动。
| 变化 | 兼容判断 | 说明 |
|---|---|---|
| 新增输出字段 | 通常兼容 | 旧查询不会自动请求新字段 |
| 新增可选参数或带默认值的参数 | 通常兼容 | 旧调用仍可省略 |
| 新增非空且无默认值的参数或输入字段 | 破坏性 | 旧调用缺少必填值 |
| 删除或重命名字段 | 破坏性 | 旧查询在校验阶段失败 |
| 修改字段或参数类型 | 通常破坏性 | 可能改变变量与响应契约 |
| 新增枚举值 | 语法上可新增,但有风险 | 生成代码或穷举分支可能没有兜底 |
输出字段新增为非空类型不会迫使旧客户端改查询,但服务端必须能对所有对象兑现非空承诺;如果历史数据尚未补齐,先声明为可空通常更稳妥。
用新增再弃用代替原地改名
假设要把 User.name 改成语义更明确的 displayName。不要直接重命名,因为所有仍请求 name 的客户端会立刻失败。先同时保留两者,并让两个 resolver 在迁移期返回一致的数据。
type User {
id: ID!
# 迁移期保留旧字段,让已发布客户端继续工作。
name: String! @deprecated(reason: "Use displayName")
# 新客户端改用语义更明确的字段。
displayName: String!
}这段 SDL 生效后,旧客户端仍可请求 name,新客户端则改用 displayName。@deprecated 只是向工具和开发者暴露迁移信号,不会阻止旧字段继续执行。
在开发或测试环境,可以通过内省确认弃用信息已经发布。部分生产环境会关闭内省,因此这里把它作为部署验证手段,而不是线上依赖。
# <PORT> 替换为开发或测试环境的 GraphQL 服务端口。
GRAPHQL_URL="http://localhost:<PORT>/graphql"
curl -sS "$GRAPHQL_URL" \
-H 'content-type: application/json' \
--data-binary '{"query":"{ __type(name: \"User\") { fields(includeDeprecated: true) { name isDeprecated deprecationReason } } }"}'预期输出
{
"data": {
"__type": {
"fields": [
{
"name": "id",
"isDeprecated": false,
"deprecationReason": null
},
{
"name": "name",
"isDeprecated": true,
"deprecationReason": "Use displayName"
},
{
"name": "displayName",
"isDeprecated": false,
"deprecationReason": null
}
]
}
}
}字段顺序可能因实现而不同,但 name.isDeprecated 应为 true,且弃用原因应与 Schema 一致。
把迁移做成可观测流程
兼容演进不是加一条 @deprecated 就结束。服务端应把字段迁移拆成可回退的阶段,并让每一步都有退出条件。

迁移时至少记录旧字段的实际调用量,最好能按客户端版本、应用名称或 persisted query 标识分组。只有“Schema 中标记了弃用”而没有使用数据时,服务端无法判断仍有多少真实消费者。
删除前再检查客户端发布节奏:移动端旧版本可能长期存活,离线应用也可能延迟升级。团队可以约定最短弃用窗口,但真正的删除门槛应是“仍受支持的客户端不再发送旧字段”,而不是单纯到达某个日期。
处理输入参数与其他危险边界
输入侧比输出侧更敏感。给已有字段新增 limit: Int! 这类无默认值的必填参数,会让所有旧查询立即失效;更安全的做法是先新增可选参数或给出默认值,再逐步迁移调用方。
还要警惕“SDL 看起来只是在增加内容”的变化。新增枚举值、给 union 增加可能类型,可能让使用生成代码并做穷举分支的客户端遇到未知值。对这类变化应在客户端约定未知值兜底,并在发布前执行 Schema diff 与代表性查询回归。
只要坚持增量新增、双轨迁移、可观测弃用和有证据的删除,GraphQL Schema 就可以独立于客户端发布节奏持续演进;真正需要破坏性修改时,也能把它安排到明确版本边界,而不是让旧客户端被动承担风险。