前言
GraphQL 是一种用于 API 的查询语言，它被 Facebook 在 2015 年开源并作为一个规范推广。比起 RESTful API，GraphQL 在数据层面上提供了更好的可控性和灵活性。为了构建一个高效、易于维护的 GraphQL API，对 schema 的设计至关重要。在本篇文章中，我们将探讨 GraphQL schema 的设计最佳实践，希望能给前端开发者提供有深度和学习以及指导意义的内容。
什么是 GraphQL schema？
GraphQL schema 是对于整个 GraphQL API 中可查询和可变更的数据类型的描述。它描述了可查询和可变更的数据类型以及它们之间的关系。GraphQL schema 定义了客户端可以执行什么样的操作，以及每个操作所需的参数和返回值。
例如，以下是一个简单的 GraphQL schema：
-- -------------------- ---- ------- ---- ----- - -------- ----- ---- - ---- ---- - --- --- ------ ------- ------- ------- - ---- ------ - --- --- ----- ------- ------ -------- -
上述 schema 描述了一个书籍查询的 API。客户端可以通过调用 book 这一查询操作，传递 id 参数并返回一个 Book 类型的对象。
GraphQL schema 的设计最佳实践
- 保持 schema 的可读性
GraphQL schema 应该尽可能保持可读性。Schema 中应该包含遵循相同规则的 Type 和 Field 命名，定义远古少女和 snake_case 在 GraphQL schema 中的排版。
-- -------------------- ---- ------- ---- ---- - --- --- ----- ------- ------ ------- - ---- ---- - --- --- ------ ------- ------------- ------- -
- 使用 interface 和 union 来避免重复
在某些情况下，可能需要定义多个类型，这些类型在其结构上具有相同的字段。在这种情况下，使用 interface 和 union 可以避免重复。interface 是具有公共字段的类型的约定接口，而 union 是两个或多个类型的集合，集合可以在查询中组合。
-- -------------------- ---- ------- --------- ---- - --- --- - ---- ---- ---------- ---- - --- --- ----- ------- ------ ------- - ---- ---- ---------- ---- - --- --- ------ ------- ----- ------- - ----- ------------ - ---- - ----
- 使用 inputs 组织输入参数
使用 inputs 可以方便地组织输入参数。inputs 可以作为参数在 Mutation 和 Query 中使用，以简化查询和变质 API 的复杂性。
-- -------------------- ---- ------- ----- --------- - ----- ------ ------ ------ - ---- -------- - ----------------- ------------ ---- - ---- ----- - ------------- ---- ------ ----- ------- -
- 使用 directive 为 particular Fields 和 Arguments 添加元数据
directive 是一种自定义机制，在 GraphQL schema 中为特定的 Type、Field 和 Argument 添加元数据。我们可以使用 @directive（代表 Directive 名称）通过定义细节规范化 Field 级别的行为。
type Book {
id: ID!
title: String!
author: Author!
image(size: Int @default(value: 200)): String!
}
directive @default(value: Int!) repeatable on ARGUMENT_DEFINITION上述示例中，@default 指示 GraphQL 的执行引擎将 int 型参数的默认值设置为 200。
- 使用 custom scalar 实现自定义类型
在 GraphQL schema 中，scalar 变量表示基本的数据类型，如 Int、String 和 Boolean。为了实现扩展和特定的数据类型，我们可以使用 custom scalar 实现自定义类型。这样一来，我们可以表示任意的数据类型并在查询中使用它们。
-- -------------------- ---- ------- ------ -------- ---- ---- - --- --- ------ ------- ----------- --------- - ---- -------- - ----------------- --------- ----- - --- -------- ------------------- ---- --- ------ -------- ------ ---- --- --------------------- ---- --- ------ ----
上述示例中，DateTime 和 Date 自定义 scalar 类型被创建表示时间戳和日期，它们在 GraphQL 中使用字符串格式。
结论
在 GraphQL API 的 schema 设计中，考虑到前端类开发常常需要查询数据并使用标准语言表达图形的特点，上述五种最佳实践为前端开发者提供了一些适用的操作指南与参考。这其中的多项技巧，在实际开发过程中的使用上，会更有方便性，同时也将带来更好的代码质量与灵活度，对工程方案优化有不错的帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6752acba8bd460d3ad97360b