GraphQL 规范 — 2025年9月版：模式坐标、OneOf 输入和可执行文档描述

关键更新

GraphQL 基金会发布了 2025 年 9 月版的 GraphQL 规范——自 2021 年 10 月以来的首次完整规范版本——正式增加了模式坐标（模式元素的规范、机器可读和人类可读地址）、OneOf 输入对象（互斥输入形状）、将描述附加到可执行文档（查询/变更/订阅）的能力、完整的 Unicode 语法支持，以及关于弃用和执行语义的一些澄清。（graphql.org）

重要性

这些是面向开发者的语言变更，而非编辑细节。模式坐标为工具提供了一个稳定的字段/类型标识符，便于在差异中进行可靠的代码生成、确定性的代码检查、精确的自动 PR 评论以及更好的模式注册。OneOf 输入对象让 API 设计者能够在模式本身中建模互斥输入，减少临时验证的样板代码，并改善生成的客户端类型。操作描述（现在是文档 AST 的一部分）意味着 IDE、网关、CI 检查和 LLM 驱动的工具可以原生地使用操作级文档，而不必依赖脆弱的注释约定。澄清的弃用和执行规则使得在生产环境中进行滚动更改和可观察性变得更加可预测。实现者（代码生成器、网关和工具）需要采用规范更新，以充分展现这些好处，但这些变化应该会实质性提高生产 GraphQL 部署的工具可靠性和自动化。（graphql.org）

来源

• 来源