跳到主要内容

结构优化:GraphQL To Schema AST — Numio

使用 @graphql-codegen/schema-ast 解析 GraphQL SDL、构建 schema,再将其打印为一份规范化的 schema。类型扩展会合并到基础类型中,description 以块字符串形式输出。

将分散在多个文件中的 extend type 块合并为一个 schema.graphql,便于审阅或供工具使用。

GraphQL Schema

Schema AST

适用场景

  • 将分散在多个文件中的 extend type 块合并为一个 schema.graphql,便于审阅或供工具使用。
  • 在比较两个 schema 版本的差异前,将手写的 SDL 规范化为标准的打印格式。

使用方法

  1. 将一个或多个 SDL 片段(包括 extend type 块)粘贴到 GraphQL Schema 编辑器。
  2. 检查打印结果:扩展字段会被加到原类型中,description 变为 """ 块。
  3. 复制输出并保存为 .graphql 文件。

GraphQL schema

extend type Query {
  me: User
}

type Query {
  ping: String
}

type User {
  id: ID!
  "Display name"
  name: String @deprecated(reason: "Use fullName")
}

打印后的 schema(SDL)

type Query {
  me: User
  ping: String
}

type User {
  id: ID!

  """
  Display name
  """
  name: String @deprecated(reason: "Use fullName")
}

功能与限制

字段顺序可能变化:在本例中,extend type 块中的字段排在基础类型自身字段之前。

@deprecated(reason: ...) 等字段指令会保留在打印出的 SDL 中。

schema 在浏览器的 Web Worker 中构建和打印,然后用 Prettier 的 GraphQL 解析器格式化。

FAQ

会输出 JSON AST 吗?

不会。虽然名称如此,结果是打印出的 GraphQL SDL,而不是 JSON 形式的 DocumentNode。如需 JSON,请使用 introspection JSON 页面。

# 注释会怎样?

注释不属于 schema,打印 schema 时会被丢弃。如需保留文档说明,请使用 "description" 字符串。

能把 extend type 合并到基础类型中吗?

能。扩展会应用到基础类型上,因此输出中只有一个包含所有字段的 type Query。

规范与参考资料