GraphQL 是一种用于构建 API 的查询语言和运行时环境，具有强大的类型系统和基于类型的查询语言。在 GraphQL 中，Schema 是 API 的核心，它定义了应用中的所有可用类型和字段、查询、突变等操作。因此，在设计 GraphQL Schema 时，必须遵循一些原则以确保 Schema 的可扩展性、易维护性和易用性。本文将介绍 GraphQL Schema 设计的十大原则。
1. 明确与简单的命名
在 GraphQL Schema 设计中，命名是一项重要的工作。我们应该使用明确而简单的名称来描述每个类型和字段，确保它们易于理解和识别。除此之外，还应该尽量避免缩写或缩写词，这可能会导致混淆或错误的理解。
举个例子，假设我们有一个 User 类型，它有一个 fullName 字段，我们可以将其命名为：
type User {
fullName: String
}但更好的做法是：
type User {
name: String
}更为简洁明了。
2. 使用复数名词
GraphQL Schema 设计中的常见问题之一是类型、字段、枚举等名词的单复数问题。为了规范起见，我们应该尽可能使用复数名词来表示集合类型和字段。
比如，如果我们有一个类型叫做 Book，它应该以复数形式 BookList 表示它的集合类型：
type BookList {
books: [Book!]!
totalCount: Int!
}使用 BookList 作为 Book 集合类型的名称更易于理解，而且更加准确地表示它所代表的集合。
3. 定义清晰的字段类型
在 GraphQL Schema 中，字段类型是非常重要的。我们需要设计清晰、一致和明确的字段类型，以便 API 用户能够正确地理解每个字段的含义和用途。
一般来说，字段的类型应该遵循以下准则：
- 基本标量类型应该使用 GraphQL 内置的标量类型。
- 用于日期和时间的字段应该以字符串形式表示，以便更易于与客户端交互。
- 枚举类型应该使用单词和短语的小写和下划线组合表示，有助于更好地表示枚举实例的含义。
- 集合类型应该使用列表类型表示
例如，一个表示日期时间戳的字段可以这样定义：
scalar DateTime
type Post {
createdAt: DateTime!
}4. 使用参数来限制查询结果
在 GraphQL 中，参数是调用查询、突变和字段解析器时传递的首选方法。我们应该使用参数来限制返回的数据，以便 API 用户只获得他们需要的信息。
type Query {
posts(limit: Int!): [Post!]!
}在示例中，我们在查询中添加了一个名为 limit 的参数，这个参数用于限制返回的 Post 数量。
5. 将空值看作合法值
GraphQL 将空值视为合法值，这使得返回值与查询的类型更加接近。因此，我们应该让我们的类型和字段用途更清晰，能够容忍和清晰处理空值并将其直接返回给客户端。
因此，我们应该将返回类型定义为：
type User {
name: String
age: Int
}6. 使用界面和联合类型
界面和联合类型是 GraphQL Schema 中的两个有用的概念，它们可以帮助我们处理复杂的类型结构和数据源。
对于具有公共字段的类型，我们应该使用界面类型。例如，如果我们有一个 Book 和 Magazine 类型，它们都具有标题、作者和发布日期等字段，我们可以使用一个名为 Publication 的界面类型，包含该公共字段：
-- -------------------- ---- ------- --------- ----------- - ------ ------- ------- ------- ------------ -------- - ---- ---- ---------- ----------- - ------ ------- ------- ------- ------------ -------- ---------- ---- - ---- -------- ---------- ----------- - ------ ------- ------- ------- ------------ -------- ------------ ---- -
对于表示两个或多个类型之间相互关系的场景，我们应该使用联合类型。例如，如果我们有一个名为 SearchResult 的类型，它可以表示来自书籍、博客和文章的结果，我们可以使用类似于以下的代码：
-- -------------------- ---- ------- ---- ---- - ------ ------- ----- ------- ----- ------- - ---- ---- ---------- ---- - ------ -------- - ---- ------------- - -------- ---------------- - ----- ------------ - ---- - ----
7. 设计可重用的类型
随着应用程序的发展，我们可能会发现许多类型用于不同的查询或突变。因此，为了减少工作量，我们应该创建可重用的类型，并在不同的字段和参数中重复使用它们。
定义可重用类型的常用方法是使用标量或枚举类型。例如，如果我们要表示状态，我们可以定义一个名为 Status 的枚举类型，并在所有类型和字段中重复使用：
-- -------------------- ---- ------- ---- ------ - ------ -------- ------- - ---- ---- - ----- ------- ------- ------- - ---- ---- - ------ ------- ------- ------- - ---- ----- - --------------------- --------- -------- -
8. 设计易扩展的类型
在设计 GraphQL Schema 时，我们应该考虑到类型的可扩展性。我们应该要求每个类型都遵循开放式关闭原则，只有在需要时才对其进行修改。
一个好的做法是通过使用用户定义的标量类型来扩展 GraphQL Schema。例如，假设我们要添加一个 URL 类型字段：
scalar Url
type Link {
title: String!
url: Url!
}在这个示例中，我们定义了一个名为 Url 的标量类型，它表示 URL 字符串。通过这种方式，我们可以为 GraphQL Schema 添加自己的数据类型，并轻松扩展它。
9. 使用文档和注释
为了使 GraphQL Schema 更易于理解和维护，我们应该使用文档和注释来标注每个类型和字段。这使得其他人可以很容易地理解我们的文章并且开发。
例如，我们可以使用文档注释来描述一个类型或字段的用途：
-- -------------------- ---- ------- ---- ---- - --- ------ --- --- --- --- --- --- --------- ------- --- ------ --- ------ ------- -
注释是可重要的，可以帮助他人理解我们的 Schema。
10. 不要暴露敏感信息
在 GraphQL Schema 中，我们需要特别注意不要在查询或字段中暴露敏感信息，例如用户的密码。在设计 Schema 时，我们应该遵循安全性规则，将敏感信息限制在后端，而不是通过 API 暴露。
例如，如果我们要通过 API 更改用户密码，我们应该定义一个突变，该突变验证当前用户并通过加盐和散列算法安全地存储密码。我们不应该暴露任何明文密码或转换后的密码到前端。
type Mutation {
changePassword(currentPassword: String!, newPassword: String!): Boolean!
}结论
GraphQL Schema 设计是一项重要的工作，它需要考虑反应现实的特征和使用用例需求。在设计期间，我们应该遵循明确、简单、清晰的名称，使用参数来限制查询结果，使用界面和联合类型表示复杂类型，定义可重用和易扩展的类型，使用文档和注释来帮助开发人员，以及保护用户的隐私和安全。希望这些原则可以帮助您构建更好的 GraphQL Schema！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/670100580bef792019b01690