GraphQL系列 - 第1讲 GraphQL语法入门

- 一、介绍GraphQL
- 二、GraphQL基本使用方法
- [三、Schema 定义语言 (SDL)](#三、Schema 定义语言 (SDL))
- - [3.1 类型定义](#3.1 类型定义)
  - [3.2 查询和变更](#3.2 查询和变更)
- 四、示例
- - [4.1 schema定义示例](#4.1 schema定义示例)
  - [4.2 查询示例](#4.2 查询示例)

一、介绍GraphQL

GraphQL 是一种用于 API 的查询语言以及一个用于执行查询的服务器端运行时。它由 Facebook 开发，并在 2015 年开源。GraphQL 的主要目的是提供一种更高效、灵活的数据查询方式，替代传统的 REST API。

基本功能

基本功能	描述
类型系统	使用强类型系统定义 API 的数据结构。
查询	客户端可以通过查询请求精确地获取所需的数据，减少数据传输量。
变更（Mutation）	支持变更操作，用于创建、更新或删除数据。
订阅（Subscription）	支持订阅功能，允许客户端订阅数据的变化，并在数据发生变化时接收实时更新。
解析器（Resolver）	服务器端的函数，用于处理查询和变更请求。每个字段都有一个解析器来获取相应的数据。

使用场景

使用场景	描述
复杂数据需求	当客户端需要从多个资源中获取数据时，通过单个请求获取所有所需数据。
前端开发	前端开发人员可以精确地查询所需数据，减少不必要的数据传输。
微服务架构	作为聚合层，统一多个微服务的数据接口，简化客户端的调用逻辑。
实时应用	通过订阅功能，适合需要实时数据更新的应用，如聊天应用、股票行情等。

使用者

使用者	描述
Facebook	GraphQL 的发明者，广泛使用 GraphQL。
GitHub	提供基于 GraphQL 的 API，允许开发者查询和操作 GitHub 数据。
Shopify	使用 GraphQL 提供其 API，帮助开发者构建电商应用。
Twitter	使用 GraphQL 优化其数据查询和传输。
Pinterest	通过 GraphQL 提供其 API，简化数据获取过程。

GraphQL 通过其灵活性和高效性，已经成为现代 Web 开发中不可或缺的一部分，广泛应用于各种复杂数据需求的场景。

二、GraphQL基本使用方法

GraphQL 是一种用于 API 的查询语言和一个用于执行查询的服务器端运行时，GraphQL 的基本使用方法如下：

定义 Schema：Schema 定义了 API 中的数据类型及其关系。
编写查询：客户端编写查询请求特定的数据。
执行查询：服务器执行查询并返回请求的数据。

三、Schema 定义语言 (SDL)

注：

详细语法说明参见：https://graphql.cn/learn/

GraphQL 的 Schema 定义语言 (SDL) 用于描述 API 的数据结构和操作。以下是一些常见的语法和示例：

3.1 类型定义

在 GraphQL 的 Schema 定义中，支持多种字段类型。以下是一些常见的字段类型及其说明。

1）对象类型

对象类型用于定义复杂的数据结构，可以包含多个字段，每个字段可以是任意类型（包括标量类型和其他对象类型）。

graphql 复制代码

type Person {
    id: ID!
    name: String!
    age: Int
    friends: [Person]
}

2）标量类型

Int：整数类型，表示有符号 32 位整数。
graphql 复制代码
```
type Example {
    age: Int
}
```
Float：浮点数类型，表示有符号双精度浮点数。
graphql 复制代码
```
type Example {
    price: Float
}
```
String：字符串类型，表示 UTF-8 字符序列。
graphql 复制代码
```
type Example {
    name: String
}
```
Boolean ：布尔类型，表示 true 或 false。
graphql 复制代码
```
type Example {
    isActive: Boolean
}
```
ID：唯一标识符类型，通常用作对象的唯一标识。
graphql 复制代码
```
type Example {
    id: ID
}
```

3）枚举类型

枚举类型用于定义一组可能的值。

graphql 复制代码

enum Role {
    ADMIN
    USER
    GUEST
}

4）输入类型

输入类型用于变更操作的输入参数。

graphql 复制代码

input PersonInput {
    name: String!
    age: Int
}

5）列表类型

列表类型表示一组相同类型的值。

graphql 复制代码

type Example {
    tags: [String]
}

6）非空类型

非空类型表示字段不能为空，在类型后面加 ! 表示。

graphql 复制代码

type Example {
    name: String!
}

7）接口类型

接口类型定义一组必须实现的字段。

graphql 复制代码

interface Character {
    id: ID!
    name: String!
}

8）联合类型

联合类型表示多个可能的类型。

graphql 复制代码

union SearchResult = Person | Post

这些字段类型可以组合使用，以定义复杂的数据结构和操作。

3.2 查询和变更

查询类型：定义读取数据的入口点。
graphql 复制代码
```
type Query {
    person(id: ID!): Person
    people: [Person]
}
```
变更类型：定义写入数据的入口点。
graphql 复制代码
```
type Mutation {
    addPerson(input: PersonInput!): Person
}
```

四、示例

4.1 schema定义示例

以下是一个完整的 Schema 示例：

graphql 复制代码

type Query {
    person(id: ID!): Person
    people: [Person]
}

type Mutation {
    addPerson(input: PersonInput!): Person
}

type Person {
    id: ID!
    name: String!
    age: Int
}

enum Role {
    ADMIN
    USER
    GUEST
}

input PersonInput {
    name: String!
    age: Int
}

这个示例定义了一个 Person 类型，一个 Role 枚举，一个 PersonInput 输入类型，以及查询和变更类型。

4.2 查询示例

查询单个 Person

graphql 复制代码

{
    person(id: "1") {
        id
        name
        age
    }
}

结果示例

json 复制代码

{
    "data": {
        "person": {
            "id": "1",
            "name": "John Doe",
            "age": 30
        }
    }
}

查询所有 People

graphql 复制代码

{
    people {
        id
        name
        age
    }
}

结果示例

json 复制代码

{
    "data": {
        "people": [
            {
                "id": "1",
                "name": "John Doe",
                "age": 30
            },
            {
                "id": "2",
                "name": "Jane Smith",
                "age": 25
            }
        ]
    }
}

添加一个新的 Person

graphql 复制代码

mutation {
    addPerson(input: { name: "Alice", age: 28 }) {
        id
        name
        age
    }
}

结果示例

json 复制代码

{
    "data": {
        "addPerson": {
            "id": "3",
            "name": "Alice",
            "age": 28
        }
    }
}

GraphQL系列 - 第1讲 GraphQL语法入门

目录

一、介绍GraphQL

二、GraphQL基本使用方法

三、Schema 定义语言 (SDL)

3.1 类型定义

1）对象类型

2）标量类型

3）枚举类型

4）输入类型

5）列表类型

6）非空类型

7）接口类型

8）联合类型

3.2 查询和变更

四、示例

4.1 schema定义示例

4.2 查询示例