GraphQL Docs

Learn 栏目的结构

Learn 首页的标题是“Learn GraphQL”，导语说明先从基础入门，再学习如何设计更好的 API。页面中部用四个方框说明内容范围：Learn GraphQL（基础课程）、Tutorials（教程）、Best Practices（最佳实践）和 FAQ（常见问题）。顶部导航还有 Resource Hub、Community、Blog 和 AI 等入口。

基础课程：9 课

“Getting started with GraphQL”是一套类似教程的入门课程，页面称其讲解支撑所有 GraphQL API 的核心概念，并从基础查询讲到进阶功能。课程目录共 9 课，依次是：

1. Introduction（概述，介绍 GraphQL 如何借助强类型系统提供灵活、无版本号的 API）
2. Schemas and Types（用类型描述数据形状的 schema 语言）
3. Queries（如何构造查询，只请求需要的字段，并使用变量和片段）
4. Mutations（如何修改数据）
5. Subscriptions（如何通过订阅获取实时数据）
6. Validation（如何通过验证规则保证查询正确）
7. Execution（解析器如何驱动执行，以及服务器如何执行查询）
8. Response（响应的结构，包括数据与错误）
9. Introspection（用内省功能查询 schema 本身）

最佳实践：16 课加 4 课治理专题

Best Practices 部分的课程从 Introduction 开始，之后依次是 Thinking In Graphs（从 RESTful 端点转向基于图的思维）、Serving Over HTTP、File Uploads（把文件上传包装为变更）、Authorization（类型级与字段级的授权）、Pagination（不同的分页策略）、Schema Design（如何设计清晰、可演进的 schema）、Error Handling、Global Object Identification、Caching、Performance、Security、Federation、Robust Applications、Common GraphQL over HTTP Errors、Naming Conventions and Design Standards，共 16 课。

官网说明，这部分内容不应被当作定论，有些做法在具体项目中可以被其他方案替代。这一点在阅读时需要留意。

Schema 治理：以所有权模型为例

Schema Governance 下有 4 课：Schema Ownership and Governance Models、Governance Tooling、Schema Review 和 Schema Change Management。第一课比较了三种治理模式：集中式（centralized）、联邦式（federated）和混合式（hybrid），并说明如何根据组织结构，在中央管控力度与团队自主、迭代速度之间取舍。

页面对集中式模式的描述是：由单一团队控制整个 schema，其他团队提交变更，由中央团队审阅并批准；适合需要跨领域严格一致、受监管要求约束或偏好集中质量控制的场景，代价是所有变更都要经过一个团队，迭代较慢。联邦式模式则让各团队拥有称为 subgraph 的 schema 部分，独立部署，只需遵守共同标准；代价是需要更强的规范和工具来维持一致性。页面还给出了用注册表记录每个 subgraph 负责团队的示例代码。

阅读建议

如果只打算学习 GraphQL 的基本用法，从 Learn GraphQL 的 9 课开始即可；如果正在设计团队内的 API，则可以直接阅读 Best Practices 中的分页、Schema Design、Authorization 和 Schema Governance 等课程。