GraphQL 概览

这一课你将能做到

1. 用一句话说清楚 GraphQL 是什么、和 REST 的本质区别
2. 解释「用图思考（Thinking in Graphs）」并把本站业务（课时、用户、进度）画成一张图
3. 发出第一个 GraphQL 查询，并读懂返回的 JSON

为什么要学

用 REST 做「课时详情页」这种聚合页面时，你通常会经历这样的对话：前端说「我还需要讲师名字和课时数」，后端说「那我再加两个接口」，或者干脆在一个接口里塞一堆不一定用得上的字段。前者叫多次往返（under-fetching），后者叫过度获取（over-fetching）。

GraphQL 是 Meta（Facebook）2012 年内部发明、2015 年开源的一种查询语言 + 运行时。它的核心思想只有一条：客户端精确描述自己要什么数据，服务器一次返回不多不少。接口长什么样由一份强类型的 Schema 决定，前后端都照它开发，文档自动生成，不用再维护一份永远过时的接口 Wiki。

人话总结：REST 是「菜单上有什么你吃什么」，GraphQL 是「你点菜，厨房照单出」。

先建立图像

REST 风格取「课时 + 作者 + 我的进度」要三个请求：

GET /api/lessons/101            → 课时基本信息
GET /api/lessons/101/author     → 作者信息
GET /api/users/me/progress?lessonId=101 → 我的进度

GraphQL 风格，一个请求、按图遍历：

query {
  lesson(slug: "gqlrm-intro") {   # 从一个节点出发
    title                          # 只要标题
    author { name }                # 顺着边走到作者节点，只要名字
    myProgress { status percent }  # 再走到我的进度节点
  }
}

返回结构和查询形状一一对应：

{
  "data": {
    "lesson": {
      "title": "GraphQL 概览",
      "author": { "name": "教研组" },
      "myProgress": { "status": "IN_PROGRESS", "percent": 40 }
    }
  }
}

把业务画成图（节点 = 类型，边 = 字段）：

Track ──has many──> Lesson ──belongs to──> Author(User)
  │                    │
  │                    └──has many──> Submission
  │                                       │
User ──has many──> Progress <─────────────┘

跟着做

步骤 1：用 curl 发第一个查询

任何 GraphQL 服务都是一个 HTTP 端点（通常是 POST /graphql），请求体是 JSON：

curl -s http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ lesson(slug: \"gqlrm-intro\") { title durationMinutes } }"}'

响应永远是 { "data": ... } 或 { "errors": [...] }（或两者都有）。

步骤 2：用 GraphiQL / Apollo Sandbox 探索

打开 http://localhost:8080/graphiql（大多数服务端库自带这个 IDE）。左侧写查询，Ctrl+Enter 执行，右侧出结果。点「Docs」能看到整张 Schema 的可点击文档——这就是「自文档化」的实际含义。

步骤 3：体会「要什么给什么」