Schema 与类型

GraphQL Schema 是 API 的契约：定义有哪些类型、哪些字段可读（Query）、可写（Mutation）。常用 SDL（Schema Definition Language）描述。

学习目标

• 编写 Object、Scalar、List、Non-null 类型
• 理解 Query 根类型与字段签名
• 能将 REST 资源映射为 GraphQL 类型（概念练习）

核心内容

SDL 基础

type Track {
  slug: String!
  title: String!
  level: String
  lessons: [Lesson!]!
}

type Lesson {
  slug: String!
  title: String!
  duration: Int
  contentMd: String
}

type Query {
  tracks: [Track!]!
  track(slug: String!): Track
}

• ! 表示非空；[Lesson!]! 表示非空列表，元素也非空
• 标量：String、Int、Float、Boolean、ID；复杂结构用自定义 Object

与 REST 资源对照

REST GET /tracks/{slug} 返回的 JSON 可建模为 Track；嵌套 lessons 在 REST 里可能是第二次请求或 ?include=lessons。Schema 把 关系显式化，便于 react-essentials / nextjs-essentials 前端生成类型（codegen）。

输入类型预览

Mutation 常用 Input（下一课详述）：

input CreateTrackInput {
  slug: String!
  title: String!
  level: String
}

注意：CodeRoadMap 生产库表 cf_track、cf_lesson 在 MySQL；GraphQL Schema 是 API 视图，不替代 mongodb-essentials 或 SQL 建模，只是另一种暴露层。

Schema 即文档

团队以 schema.graphqls 为单一真相源；Spring for GraphQL 启动时加载（见 gql-spring）。

练习

• 为 Track 增加 description、estimatedWeeks 字段
• 写出 Query 根上 lesson(trackSlug: String!, lessonSlug: String!): Lesson 签名
• 对照 schema.sql 中 cf_track 列，标出哪些适合放进 GraphQL 类型