在 Apollo Kotlin 中的 GraphQL 文件类型

Apollo Kotlin 支持以下文件类型用于 GraphQL 定义：

• .json 用于 introspection schemas
• .graphqls 用于 SDL schemas
• .graphql 用于 operations (查询、mutations 和 subscriptions)

Schemas

A GraphQL schema 描述了一个 graph 的数据类型以及这些类型之间的关系。 Apollo Kotlin 支持通过 introspection 获得的 JSON schemas，以及传统的 SDL schemas。

introspection schemas (.json)

您可以通过特殊的 introspection 查询 来获取 GraphQL 服务器 的架构。 introspection 查询 （假定服务器启用了 introspection ）。像任何其他 GraphQL 服务器响应一样，返回的架构作为 JSON 格式提供，类似于以下内容：

1
{
2
  "data": {
3
    "__schema": {
4
      "queryType": {
5
        "name": "Query"
6
      },
7
      "mutationType": {
8
        "name": "Mutation"
9
      },
10
      "types": [...]
11
    }
12
  }
13
}

像 Apollo Sandbox 这样的工具可以自动 introspect GraphQL 服务器并将其架构以 JSON（或 SDL）格式下载。 Apollo Kotlin 也可以使用 downloadApolloSchema Gradle 任务下载 introspection 架构：

1
./gradlew :app:downloadApolloSchema \
2
  --endpoint "https://example.com/graphql" \
3
  --schema schema.json

JSON introspection schemas are verbose and difficult to read or modify. For simplicity, you should consider JSON schemas read-only and convert them to SDL schemas if you need to make changes.

SDL schemas (.graphqls)

SDL (Schema Definition Language) is the canonical language for defining GraphQL schemas as defined in the GraphQL spec. It's much cleaner and more expressive than JSON for understanding a schema's structure. It also supports directives, unlike the JSON representation (see this issue):

1
type schema {
2
  query: Query
3
  mutation: Mutation
4
}
5

6
type Query {
7
  field: String @deprecated
8
  ...
9
}

您不能使用 introspection 从 GraphQL 终端直接下载 SDL 模式。但是，如果您在 --schema 选项中指定 .graphqls 扩展名，Apollo Kotlin 可以自动将 introspection 模式转换为 SDL：

1
./gradlew :app:downloadApolloSchema \
2
  --endpoint "https://example.com/graphql" \
3
  --schema schema.graphqls

操作(.graphql)

GraphQL 操作会针对图执行以检索或修改数据。

在 Apollo Kotlin 中，操作文件使用 .graphql (不带 's') 扩展名。这些文件仅包含 可执行定义 (查询、突变、订阅和/或片段)：

1
query MyQuery {
2
  field1
3
  field2
4
  ...
5
}

Apollo Kotlin 将这些操作编译为类型安全的模型，您可以在运行时使用这些模型。