GraphQL 是什么

GraphQL 是一种 API 查询语言与运行时规范：客户端用 单一 HTTP 端点 描述所需数据结构，服务端按 Schema 返回 JSON。它与 REST 互补，而非默认替代。

学习目标

• 理解 GraphQL 与 REST 的核心差异
• 知道单端点、强类型 Schema、按需取字段三个特征
• 明确 CodeRoadMap 主 API 仍是 REST（/tracks），GraphQL 为扩展阅读

核心内容

与 REST 对照

	REST（本站）	GraphQL
端点	多个 URL，如 /tracks、/tracks/{slug}/lessons	通常一个 /graphql
数据形状	服务端固定 DTO	客户端选字段
文档	OpenAPI / 约定	Schema SDL + 内省
缓存	HTTP 缓存友好	需客户端策略（Apollo 等）

本站 platform 调 Spring Boot：

GET /tracks              → 课程列表
GET /tracks/{slug}       → 单课 track 元数据
GET /tracks/{slug}/lessons/{lessonSlug} → 课时 Markdown

这是 spring-boot-essentials 中 @RestController 模式，不是 GraphQL。

GraphQL 请求长什么样

query {
  track(slug: "graphql-essentials") {
    title
    lessons {
      slug
      title
    }
  }
}

一次请求可嵌套取 track 与其 lessons；REST 等价往往需要多次 GET 或冗余字段。

何时值得学 GraphQL

• 多端（Web / App / 第三方）字段需求差异大
• BFF 层要聚合多个后端
• 团队已有 Schema-first 协作流程

CodeRoadMap 课程站点结构稳定、读多写少、SEO 依赖 Next.js RSC——REST 足够且更简单。本 track 帮你读懂业界方案，并在实验环境动手。

练习

• 用浏览器或 curl 访问本站 /tracks，记录 JSON 顶层字段
• 画一张对比图：同一「课程+课时列表」用 REST 几次请求 vs GraphQL 一次 query
• 阅读 后端路线图 中 API 设计节点

小结

GraphQL = 强类型、按需查询的 API 风格；本站生产路径仍是 REST /tracks。 下一课 Schema 与类型系统。