GraphQL 是一种用于 API 的查询语言,它类型系统让 API 端点更加可靠,并支持客户端驱动的 API 端点设计。在 GraphQL 中,定义 schema 是一个非常重要的步骤,因为 schema 定义了 API 所包含的数据类型和数据结构,以及对这些数据类型的查询和变更操作。
在本文中,我们将会介绍如何通过一些技巧和最佳实践来优雅地定义 GraphQL Schema,并通过示例代码演示如何使用这些技巧来提高开发效率和代码的可读性和可维护性。
1. 分层设计
为了使 GraphQL Schema 易于理解和维护,我们建议将 schema 分层。我们可以将 schema 分为以下三个层次:
- 根级别 (Root-Level): 定义 Query 和 Mutation 类型,并指向其他模块。
- 模块级别 (Module-Level): 定义模块特定的类型、查询和变更操作。 它们可能有各自的小模块或者是动态加载的模块。
- 实现级别 (Implementation-Level): 定义类型的具体实现细节,例如数据库连接或 API 端点调用。
下面是一个简单的例子:
-- -------------------- ---- ------- ------ - ------------------ ------------- - ---- ---------- ------ ---------- ---- ----------------- ------ ---------- ---- ----------------- ----- --------- - --- ------------------- ----- -------- ------- - -------------------------- -------------------------- -- --- ----- ------------ - --- ------------------- ----- ----------- ------- - ----------------------------- ----------------------------- -- --- ------ ------- --- --------------- ------ ---------- --------- ------------- ---
2. 使用 GraphQL Tools
GraphQL Tools 是一个用于构建和管理 GraphQL Schema 的工具包。它可以帮助我们轻松地集成 schema,拆分 schema,组合 schema,重命名类型名称和字段名称,甚至还可以混合其他类似 REST API 的数据源。
以下是一个完整的示例代码:
-- -------------------- ---- ------- ------ - -------------------- - ---- ---------------- ------ ---------- ---- ----------------- ------ ---------- ---- ----------------- ----- -------- - - ---------------------- ---------------------- ---- ----- - --------------------------- --------------------------- - ---- -------- - ------------------------------ ------------------------------ - -- ----- --------- - - ------ - ----------------------------- ----------------------------- -- --------- - -------------------------------- -------------------------------- -- ---------------------------- ---------------------------- -- ------ ------- ---------------------- --------- ---------- ---
3. 好好设计类型
在 GraphQL Schema 中,类型是 schema 的核心组成部分。好的类型设计可以使 schema 更具可读性和可维护性。以下是一些类型设计的最佳实践:
- 使用简洁的名称 - 命名应清晰、简洁、有意义,最好使用名词,例如 User、Post 等。
- 使用单数形式 - 标量类型应使用单数形式,例如 String、Int、Boolean 等。
- 让类型明确 - 你的类型应该确保数据的类型和内部的结构明确和一致。
- 利用枚举类型 - 枚举类型可以帮助开发人员在特定的列表中定义所有值,并通过一致的方式对外部表示。
- 使用自定义标量 - 自定义标量可以使我们轻松定义新类型,并可以重用它们。例如,URL、Date、Currency 等。
以下是一个定义 User 类型的示例代码:
-- -------------------- ---- ------- ------ - ------------------ -------------- -------------- - ---- ---------- ----- -------- - --- ------------------- ----- ------- ------- -- -- -- --- - ----- --- ----------------------------- -- ---------- - ----- ------------- -- --------- - ----- ------------- -- ------ - ----- --- ----------------------------- -- --- --- ------ ------- ---------
4. 使用 Interfaces
GraphQL 支持类型系统的接口定义,这可以帮助我们定义共享特性的类型,并在不同类型之间共享这些特性。
以下是一个定义共享特性的 User 和 Admin 类型的示例代码:
-- -------------------- ---- ------- ------ - -------------------- - ---- ---------- ----- ------------- - --- ---------------------- ----- ------- ------- -- -- -- --- - ----- --------- -- ---------- - ----- ------------- -- --------- - ----- ------------- -- ------ - ----- ------------- -- --- --- ----- --------- - --- ------------------- ----- -------- ----------- ---------------- ------- -- -- -- --- - ----- --------- -- ---------- - ----- ------------- -- --------- - ----- ------------- -- ------ - ----- ------------- -- -------- - ----- -------------- -- --- ---
5. 多态类型 (Union Types)
多态类型是一种特殊的类型,可以帮助我们将多个类型组成统一的类型并对外暴露。在 GraphQL Schema 中,多态类型通常在查询的返回类型中使用。例如,在博客站点上,我们可能需要查询所有博客文章和所有用户,将它们合并为单个返回类型,如:阅读文章或者用户的 feed。
以下是一个定义 User 和 Post 联合类型的示例代码:
-- -------------------- ---- ------- ------ - ---------------- - ---- ---------- ------ -------- ---- ------------- ------ -------- ---- ------------- ----- ---------------- - --- ------------------ ----- --------------- ------ ---------- ---------- ------------ ------- -- - -- ------ ---------- ----- - ------ --------- - ---- -- ------ ---------- ----- - ------ --------- - ---- - ----- --- -------------- ------ ------ ------- - -- ---
结论
在本文中,我们介绍了如何通过分层设计、使用 GraphQL Tools、好好设计类型、使用接口和联合类型等技术来优雅地定义 GraphQL Schema。这些技巧不仅可以使您的 schema 更加清晰,易于理解和维护,而且也可以提高代码的可读性、可维护性和重用性。使用这些技巧,可以让您和您的团队在开发 GraphQL API 时更加高效和愉快。
来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/66faabb544713626014ec530