站点架构说明：graphql.org 新站点架构

Index

目标： 这是着陆页，是我们快速吸引注意力并解释 GraphQL 是什么以及为什么你应该关注它的机会。

时间安排： 9 月 12 日（周一）上线

这个页面实际上是 GraphQL 的营销页面，应该是 "Introducing GraphQL" 会议演讲的可视化、可滚动版本，并且应该富含视觉隐喻和插图，利用留白来突出各个要点。

在首屏区域，本页应简明地解释 GraphQL 是什么，并用一个简单（可编辑）的查询/响应示例加以说明。在向下滚动之前，你应该理解以下内容：

• GraphQL 解决与 REST 相同的问题。
• GraphQL 是一种用于 API 的查询语言（而不是数据库）。
• GraphQL 由客户端应用（例如 iOS 应用）发送。
• GraphQL 由 Web 服务执行，返回结果通常为 JSON。
• GraphQL 服务通过类型系统提供数据的完整描述。
• 使用 GraphQL 可以很容易为数据构建强大的工具。

在首屏下方，我们应该逐一介绍概念，每个概念都附带视觉隐喻和要点：

1. GraphQL 客户端以客户端开发者思考数据的方式来描述他们需要什么。

• 如果你熟悉 JSON，GraphQL 很容易学习和理解。
• GraphQL 只发送你要求的内容，不多也不少，使你的应用更快、更稳定。
• 很容易预测任何查询结果的形状。

2. GraphQL 查询可以在单个网络请求中访问许多"资源"。

• 查询不仅可以访问一个对象的属性，还可以访问许多相关对象的属性。
• 查询可以同时访问多个不相关的对象。
• 与 REST 相比，GraphQL 用更少的网络活动收集应用所需的所有数据，使你的应用更快。

3. GraphQL 服务通过强类型系统描述其能力。

• GraphQL 服务提供数据的完整描述。
• 每个 { } 对应一个特定类型的对象，每个类型都描述了可用的字段。
• GraphQL 只执行有意义的查询，并提供有用的错误提示。
• 工具和 IDE 可以通过类型自动补全让编辑查询变得容易。
  • GraphiQL 是一个你可以使用的免费工具。
• 类型系统定义了描述信息，使文档易于保持最新。
• 每个查询都保证其响应的形状和类型。

4. GraphQL 可以通过片段（fragments）进行组合。

• 片段描述某个类型中需要查询的一部分内容。
• 片段通常与使用数据的视图代码放在一起使用。
• 片段组合在一起构成完整的查询。

5. GraphQL 使向后兼容的 API 变得容易。

• 服务器不需要关心任何特定客户端的诉求，只需要关注完整的能力集合。客户端负责它们接收到的数据。
• 因为 GraphQL 只发送你要求的内容，所以可以通过在类型上添加新字段来引入新能力，而不会影响现有查询。
• 旧能力可以标记为"已弃用（deprecated）"，且不会影响现有查询。
• 使用 GraphQL 时无需为 API 进行版本管理，这使服务器端代码更清晰。

6. GraphQL 查询由服务器端的简单函数响应。

• 与 REST 一样，GraphQL 并不以任何数据库技术为后端。
• 每个类型上的每个字段都由一个用于检索该数据的函数表示。
• GraphQL 会调用你的函数，并以最佳并发方式执行查询。
• 使用现有数据模型编写 GraphQL API 很容易。

最后，会有一组链接用于了解更多信息（进入 Learn）和快速开始（在 Code 中），以及一个使用 GraphQL 的公司的 logo 墙。

Learn

目标： 一次介绍一个 GraphQL 概念，涵盖主要概念和最佳实践。

时间安排： 9 月 12 日前完成基础主要概念，9 月 30 日前完成高级主要概念，最佳实践在 Q3/Q4 期间陆续准备。

如果说"GraphQL 规范"是为构建 GraphQL 服务器的特定受众设计的，那么这一部分代表的是"GraphQL 之书"，面向所有希望使用 GraphQL 的人。它应该涵盖 GraphQL 核心概念，以及最佳实践和更多主题，并且内容应从入门概念延伸到高级概念。

这个部分的着陆页应该从一个信息更丰富的 GraphQL 介绍开始，解释你为什么可能使用它，并简要介绍其组成部分。这篇介绍页的要点如下：

• GraphQL 是一种查询语言。
• GraphQL 服务器描述类型系统，称为"schema"。
• 客户端可以访问 GraphQL 服务器的类型系统，以了解哪些能力是可用的。
• 客户端向服务器发送查询，通常收到 JSON 响应。
• GraphQL 服务器会验证并执行 GraphQL 查询。

然后是各章节的目录（这是一个初步的列表，欢迎重新排序和补充）：

• 介绍 GraphQL（即本页）
• 核心概念：
  • 请求：
    • 基础（查询与变更、字段、参数、别名、注释）
    • 变量
    • 片段
    • 值
    • 指令（skip 和 include）
  • 类型系统：
    • 基础（Schema、对象和字段）
    • 标量与枚举
    • 列表与 NonNull（提及错误处理）
    • 接口与联合类型
  • GraphQL 如何工作：
    • 验证
    • 执行与错误处理
    • 内省
• 最佳实践：
  • 服务器：
    • 通过 HTTP 提供服务
    • 认证与授权
    • 变更（Mutations）
    • 列表分页
    • Schema 变更与版本管理
    • 查询性能（批处理与缓存）
    • 安全与速率限制
    • Schema 设计指南
  • 客户端：
    • 使用变量
    • 将片段放在相关位置（Co-locating Fragments）
    • 缓存结果
    • 持久化查询（Persisted Queries）
    • 生成模型
    • 从 REST 迁移

Code

目标： 介绍开源 GraphQL 工具，并为每种工具提供快速入门指南。

时间安排： 9 月 12 日前至少描述 3 个服务器，其余在 9 月 30 日前完成。

这个页面全部是为了解决"好吧，我被说服了！现在该怎么办？"这个问题。它应该先非常快速地重新介绍你期望看到的 GraphQL 软件元素，并提供一条快速路径来让某些东西运行起来。

1. 服务器（Servers）

解释 GraphQL 服务器的用途，说明有许多用不同语言和环境编写的服务器，graphql-js 是 Facebook 运营的参考实现。

每个服务器应包含以下内容：

• Logo
• 项目名称
• 语言/环境
• 网站链接
• 入门指南（例如 npm install + 代码示例）

2. 客户端（Clients）

解释 GraphQL 客户端的用途，说明直接使用 curl/XHR/fetch 也是可以的，并且客户端可以通过智能缓存和与 UI 框架的集成提供更多价值。

每个客户端应包含与服务器类似的一组信息。

3. 服务（Services）

托管的 GraphQL 即服务（GraphQL-as-a-service）可以在这里进行自我推介。

4. 工具（Tools）

GraphQL 社区使用的常见工具，例如 GraphiQL。

Community

目标： 为寻找 GraphQL 问题解答、了解会议和聚会信息以及与社区建立联系提供集中入口。

时间安排： 9 月 12 日前完成简单版本，后续持续演进。

这个页面应该提供可用资源和社区动态的高层级视图。它应该鼓励提交 pull request，以便让社区持续更新它。

• 外部链接：
  • Stack Overflow 话题
  • Slack/Discord 频道
  • 热门博客
  • Twitter 动态
• 与 GraphQL 相关的即将举行的聚会或会议演讲日历（鼓励社区编辑）
• GraphQL 相关视频的网格展示（会议演讲等）

Blog

目标： GraphQL 核心团队的博客，为在其他地方发布的热门文章提供放大传播。

虽然任何长期有效的内容通常应该放在"Learn"部分的章节中，但 Blog 为 GraphQL 核心团队成员或偶尔受邀的贡献者提供了讨论实验、有趣应用或宣传放大诸如 GraphQL 规范新版本、参考实现、即将举行的活动或有趣文章链接等内容的场所。

任务：生成 RSS 源（或许还有邮件订阅？）

长期目标：统计文章发布频率，设定适当的频率目标。

Spec

链接到 GraphQL 规范。