Schema 设计

无需版本号即可随时间设计和演进类型系统

版本控制

虽然没有什么能阻止 GraphQL 服务像其他 API 一样进行版本控制,但 GraphQL 通过提供持续演进 GraphQL schema 的工具,提出了避免版本控制的强烈主张。

为什么大多数 API 需要版本控制?当对 API 端点返回的数据控制有限时,任何更改都可能被视为破坏性更改,而破坏性更改需要新版本。如果为 API 添加新功能需要新版本,那么在“频繁发布并产生许多增量版本”与“API 的可理解性和可维护性”之间就会出现权衡。

相比之下,GraphQL 只返回显式请求的数据,因此可以通过新类型或现有类型上的新字段来添加新功能,而不会产生破坏性更改。这导致了一种常见的做法:始终避免破坏性更改并提供无版本的 API。

可空性 (Nullability)

大多数识别“null”的类型系统都会同时提供普通类型和该类型的可空版本,其中默认类型除非显式声明,否则不包含“null”。然而,在 GraphQL 类型系统中,每个字段默认都是可空的。这是因为在由数据库和其他服务支持的网络服务中,有很多事情可能会出错。数据库可能会宕机,异步操作可能会失败,可能会抛出异常。除了简单的系统故障,授权通常也是细粒度的,请求中的各个字段可能具有不同的授权规则。

通过将每个字段默认设置为可空,上述任何原因都可能导致仅该字段返回“null”,而不是使整个请求完全失败。相反,GraphQL 提供了类型的非空 (Non-null)变体,向客户端保证如果请求该字段,它绝不会返回“null”。相反,如果发生错误,之前的父字段将变为“null”。

在设计 GraphQL schema 时,务必记住所有可能出现的问题,以及对于失败的字段,“null”是否是一个合适的值。通常它是合适的,但偶尔也不是。在这些情况下,请使用非空类型来做出保证。

下一课

全局对象标识

使用全局唯一 ID 和 Node 接口来实现缓存、重新获取和高效的 schema 遍历。

前往下一课 教程