GraphiQL 与 introspection

GraphQL 自带 内省（introspection）：客户端可查询 Schema 元数据，驱动 GraphiQL、Apollo Studio、codegen。开发利器，生产需 谨慎暴露。

学习目标

• 使用 GraphiQL 编写、格式化、查看文档
• 执行内省查询理解类型系统
• 知道生产环境关闭或限制内省的原因

核心内容

GraphiQL 基本操作

Spring 启用 spring.graphql.graphiql.enabled=true 后访问 /graphiql：

1. 左侧写 Query，Ctrl+Enter 执行
2. Docs 面板浏览 Track、Lesson 类型
3. Variables 面板填 $slug 等

与 Postman 调 REST /tracks 类似，但响应形状 随 Query 变化。

内省查询示例

query IntrospectSchema {
  __schema {
    types {
      name
      kind
    }
  }
}

查单个类型字段：

query IntrospectTrack {
  __type(name: "Track") {
    fields {
      name
      type { name kind ofType { name } }
    }
  }
}

Apollo、GraphQL Code Generator 据此生成 TypeScript 类型，供 react-essentials / nextjs-essentials 使用。

其他工具

工具	用途
GraphiQL	浏览器 IDE（Spring 内置）
Apollo Sandbox	云端 Schema 协作
graphql-inspector	CI 中 Schema 破坏性变更检测
Altair / Insomnia	通用 API 客户端 GraphQL 模式

REST 侧等价物：OpenAPI Swagger UI（spring-boot-essentials 可开 springdoc）。

安全注意

内省暴露 全部类型与字段，攻击者可构造深度嵌套 Query。生产：

• 关闭 GraphiQL
• 禁用或鉴权后开放 __schema
• 与 gql-security 深度限制配合

CodeRoadMap 公开 文档站靠 REST，不依赖对外 GraphQL introspection。

练习

• 在 GraphiQL 用 Docs 拼出 track(slug: "...") { lessons { slug } }
• 运行 ，列出根 Query 字段