GraphQL

GraphQL 是一种 API 查询语言——后端定义数据结构（Schema），前端按需查询所需字段。所有请求走单一端点（通常 POST /graphql），由客户端在查询语句中精确指定要哪些字段。

REST vs GraphQL 的数据形态

┏━━━━━━━━━━ REST API ━━━━━━━━━━━┓
┃                               ┃
┃  GET /api/user/1              ┃  → { id, name, email, avatar, bio, ... }
┃  GET /api/user/1/posts        ┃  → [{ id, title, content, ... }, ...]
┃  GET /api/user/1/followers    ┃  → [{ id, name, ... }, ...]
┃                               ┃
┃  3 个请求，每个可能返回多余字段 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛


┏━━━━━━━━━ GraphQL API ━━━━━━━━━┓
┃                               ┃
┃  POST /graphql                ┃    {
┃  query {                      ┃      user: {
┃    user(id: 1) {              ┃        name: "Alice",
┃      name                     ┃  →     posts: [{ title: "..." }],
┃      followers { name }       ┃        followers: [{ name: "..." }]
┃    }                          ┃      }
┃  }                            ┃    }
┃                               ┃
┃  1 个请求，只返回所需字段      ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

基础概念

基本流程

①  后端定义 Schema（SDL）
        │
②  后端实现 Resolver（每个字段如何取数据）
        │
③  codegen 读取 Schema → 生成前端 TS 类型
        │
④  前端写 Query / Mutation → 发到 /graphql 端点
        │
⑤  服务端执行对应 Resolver → 返回 JSON

详细步骤：

1. 后端定义 Schema —— 用 SDL 声明数据类型和操作接口（详见）
2. 后端实现 Resolver —— 为 Schema 中的每个字段编写数据获取逻辑（详见）
3. codegen 生成类型 —— 读取后端 Schema，为前端生成 TypeScript 类型（详见）
4. 前端写查询语句 —— 用 Query/Mutation 指定需要的字段（详见）

多服务合并：Federation 与 Schema Stitching

企业级 GraphQL 常有多个后端服务，需要把各自的 Schema 合并成一张大图：

争议与取舍

GraphQL 的核心优势是客户端灵活查询。但这个灵活性不是免费的，它带来了一系列成本：

GraphQL vs tRPC

都解决了 REST 的类型安全问题，但思路完全不同：

GraphQL vs REST