GraphQL用法笔记 – Ahui's Blog

GraphQL语法结构

1. `operationName`

定义: operationName 是一个可选参数，用来标识 GraphQL 操作的名称，通常用来描述或标识一个特定的查询或操作。
作用:
- 当同一请求中包含多个查询或变更操作时，operationName 用于明确指定执行哪一个操作。
- 如果在请求中只包含一个查询或变更操作，operationName 是可选的。

示例:

query GetUser {
user(id: "1") {
  id
  name
}
}

如果你想给这个查询命名，operationName 可以是 GetUser，如下所示：

{
"operationName": "GetUser",
"query": "query GetUser { user(id: \"1\") { id name } }"
}

2. `variables`

定义: variables 是一个 JSON 对象，包含动态传递给 GraphQL 查询或变更操作的变量。
作用:
- 使用 variables 可以避免在查询中硬编码参数，使得查询更加灵活和可重用。
- 你可以通过变量动态传入查询的参数，避免每次修改查询字符串。

示例: GraphQL 查询可以通过变量接收参数：

query GetUser($id: ID!) {
user(id: $id) {
  id
  name
}
}

这里的 $id 是变量，在实际请求时可以通过 variables 提供这个参数：

{
"operationName": "GetUser",
"query": "query GetUser($id: ID!) { user(id: $id) { id name } }",
"variables": {
  "id": "1"
}
}

3. `query`

定义: query 包含实际的 GraphQL 查询或变更操作，是 GraphQL 请求的核心部分。
作用:
- query 是用来定义你想要的操作，比如查询数据、变更数据等。它包含查询的结构和字段，指定需要从服务器获取的数据。
- GraphQL 查询是一个字符串，包含查询类型、字段、参数等。

示例: 这是一个包含实际查询的 query：

{
"query": "query GetUser($id: ID!) { user(id: $id) { id name } }"
}

综合示例：

当你需要通过 GraphQL 查询获取某个用户的信息，并使用变量动态传递用户的 ID 时，完整的查询请求可能会像这样：

{
  "operationName": "GetUser",
  "query": "query GetUser($id: ID!) { user(id: $id) { id name } }",
  "variables": {
    "id": "1"
  }
}

operationName: GetUser 用来标识当前操作。
query: 实际的 GraphQL 查询字符串，包含查询类型、参数和需要返回的字段。
variables: 用来传递变量，这里通过 variables 将用户的 id 传递给查询。

总结：

operationName: 用来给查询或变更操作命名，便于在多个操作中指定执行哪个操作。
variables: 是传递给查询或变更操作的参数，可以动态调整查询的输入。
query: 是实际的 GraphQL 查询或变更操作，包含请求的结构和字段定义。

自省查询

方法 1: 使用 `__type` introspection query 查询类型信息

你可以使用 GraphQL 的 introspection 来查询 User 类型的所有字段。可以通过 __type introspection 查询来获取 User 类型的定义。以下是如何构造查询的示例：

{
  __type(name: "User") {
    name
    fields {
      name
      type {
        name
        kind
        ofType {
          name
          kind
        }
      }
    }
  }
}

解释：

__type(name: "User")：查询 GraphQL 类型为 User 的所有字段信息。
fields：列出该类型的所有字段名称及其类型。

这个查询将返回 User 类型的所有字段列表，包括每个字段的名称和字段类型。

方法 2: 使用工具查看 schema

如果你没有权限运行 introspection 查询，或者 introspection 功能在生产环境中被禁用，你也可以使用以下工具查看 schema 中的所有字段：

GraphQL Playground 或 GraphiQL：
- 在这些开发工具中，你可以在文档栏（Docs）中查找 User 类型的所有字段。
Apollo Studio：
- 如果你的 API 在 Apollo Server 上运行，可以使用 Apollo Studio 来检查 schema 中的所有字段。

方法 3: 通过 introspection 查询 schema 的所有类型

你还可以通过以下查询获取整个 schema 中所有类型的信息，然后找到 User 类型。

{
  __schema {
    types {
      name
      fields {
        name
      }
    }
  }
}

方法 4: 通过 IntrospectionQuery查询 schema 的所有类型

query IntrospectionQuery{__schema{queryType{name}mutationType{name}subscriptionType{name}types{...FullType}directives{name description locations args{...InputValue}}}}fragment FullType on __Type{kind name description fields(includeDeprecated:true){name description args{...InputValue}type{...TypeRef}isDeprecated deprecationReason}inputFields{...InputValue}interfaces{...TypeRef}enumValues(includeDeprecated:true){name description isDeprecated deprecationReason}possibleTypes{...TypeRef}}fragment InputValue on __InputValue{name description type{...TypeRef}defaultValue}fragment TypeRef on __Type{kind name ofType{kind name ofType{kind name ofType{kind name ofType{kind name ofType{kind name ofType{kind name ofType{kind name}}}}}}}}

常见查询

1. `query`：查询操作

定义: 用于获取数据，不会修改服务器端的数据状态，类似于 REST API 中的 GET 请求。
示例:
```
query {
session {
  id
  __typename
}
}
```
这个查询请求了 session 数据，并返回会话的 id 和类型信息。

2. `mutation`：变更操作

定义: 用于修改服务器端的数据，类似于 REST API 中的 POST、PUT、DELETE 请求。通常用于创建、更新或删除数据。
示例:
```
mutation {
createUser(input: { name: "John", email: "[email protected]" }) {
  id
  name
  email
}
}
```
这个 mutation 请求用于创建一个用户，并返回创建成功后的用户 id、name 和 email。

3. `subscription`：订阅操作

定义: 用于订阅服务端的数据变更，当数据发生变化时，服务器会自动将更新的数据推送到客户端。适用于实时数据更新，类似于 WebSockets。
示例:
```
subscription {
messageAdded {
  id
  content
  user {
    id
    name
  }
}
}
```
这个 subscription 请求订阅了新消息的添加，当有新消息时，服务器会推送消息的 id、content 以及发送者的 id 和 name。

GraphQL 中的三大操作类型总结：

query：
- 作用: 获取数据（读取操作）。
- 类似于: REST API 中的 GET 请求。
- 是否修改数据: 否。
mutation：
- 作用: 修改数据（创建、更新、删除操作）。
- 类似于: REST API 中的 POST、PUT、DELETE 请求。
- 是否修改数据: 是。
subscription：

作用: 实时订阅数据变化，当服务端数据变化时通知客户端。
- 类似于: WebSockets。
是否修改数据: 否，主要用于实时数据推送。

总结

query：用于查询和获取数据。
mutation：用于修改数据。
subscription：用于订阅实时数据更新。

GraphQL语法结构

1. operationName

2. variables

3. query