设计第一个 GraphQL 架构的实用指南

构建模式是设计图的关键部分，模式是使用 GraphQL 的主要优势之一。它定义了客户端如何从 GraphQL API 检索数据，使得根据特定业务、产品或项目需求灵活地塑造和发展数据成为可能。如果对 GraphQL 还不熟悉，可能会想知道如何构建灵活且可演化的模式。

本文将回顾在设计 GraphQL 模式时需牢记的一些原则。在开始之前，需要了解以下几点：

理解 GraphQL 的基本概念。如果不太清楚，可以参考相关的 GraphQL 介绍博客文章。
了解架构及其定义语言 (SDL)。如有必要，可查阅架构基础知识文档进行复习。

熟悉这些主题后，将为深入探讨模式设计及其所需的基础知识做好准备。

理解领域和用户需求

在进行架构设计时，深入了解领域至关重要。应熟悉应用程序的用户界面及目标受众的行为。

例如，如果为教育平台构建 API，了解典型用户（如学生）的需求和行为非常重要。他们希望访问哪些信息？希望修改哪些内容？用户、团队及其所需的数据是什么？这些数据将如何在 UI 中呈现？

通过反思这些问题，可以确保对业务领域有透彻理解。这将帮助充分利用 GraphQL 的灵活性，从而设计出高效且实用的模式。当领域知识与专业技能相结合时，可以完全自定义架构以满足特定需求。如果尚未达到“专业领域”水平，首先应问自己上述问题。

绘制应用程序图表

首先，什么是图表？GraphQL 的独特之处在于它改变了数据的视角，使其不仅仅是二维表格，而是看作对象及其间关系的集合。

这些对象称为节点，连接的关系称为边。用手绘制或借助插图软件来描绘这个结构，就会形成一个图表。那么在实际应用中，这种图表会是什么样子？

以教育平台的主页为例，页面将展示课程及其标题、作者和缩略图。

通过此示例，可以建立每门课程展示的信息与所需 API 数据之间的直接联系。

这可以转换为如下图示：

通过这个图表，可以直观地看出数据及其之间的关系，从而反映在架构中。

type Query {
  "获取主页课程数组"
  tracksForHome: [Track!]!
}
"A track 是一组模块，讲授特定主题"
type Track {
  id: ID!
  "课程标题"
  title: String!
  "主要作者"
  author: Author!
  "显示在课程卡或详情页的缩略图"
  thumbnail: String
  "课程完成的大致时长，单位为分钟"
  length: Int
  "该课程包含的模块数量"
  modulesCount: Int
}
"课程的作者"
type Author {
  id: ID!
  "作者的姓名"
  name: String!
  "作者的头像链接"
  photo: String
}

绘制应用程序图表非常有助于建立应用程序 UI 与用户与数据交互之间的联系。这两者在设计模式时至关重要，应该体现在数据结构中。

关键在于，架构应反映图表。因此，在构建模式之前绘制图表是一种良好的习惯。尤其在构建初始模式时，尝试为日常使用的现有应用程序绘制图表，将有助于培养“图表思维”，即将数据视作图表。

针对特定用例的设计

前端开发人员可以通过不同的用户界面访问架构，例如移动设备、桌面、智能电视，甚至智能手表。对于每种前端客户端，数据的展示方式可能会有所不同。这可能会导致尝试创建通用类型和字段的冲动，但这样真的最佳吗？

在软件开发中，通常希望代码尽可能简洁，而大家也都熟知 DRY 原则（不要重复自己）。然而，在设计模式时，应优先考虑客户的具体用例，无论这些用例多么特定。这并不意味着要放弃通用字段和类型，而是可以同时兼顾通用性和具体性。

那么，应该考虑哪些具体行为和用例呢？答案源于对领域和用户的深入了解。同时，要记住，随着应用程序的发展，客户的具体用例也会随时间变化。起初可能是一个网络应用程序，但最终可能扩展到移动客户端。随着应用的演变，架构也应随之调整。因此，采取以用例和行为为中心的思维方式将是一个明智的选择。

命名要具体

命名是一个挑战，但它在软件开发中至关重要，包括模式设计。在为模式创建类型时，常常容易使用最直接的名称，这可能导致后续的混乱和重大调整。

以前面提到的教育平台为例。如果需要包含课程和课程的评论，可能会倾向于创建一个名为 Review 的类型。但可以考虑更具体的命名。使用 CourseReview 和 LessonReview 作为类型名，而非简单的 Review，可以使代码更加清晰且易于理解。这种做法还允许根据特定用例和用户行为进行更加精确的构建。