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

一、介绍GraphQL

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

基本功能

使用场景

使用者

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

二、GraphQL基本使用方法

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

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

三、Schema 定义语言 (SDL)

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

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

3.1 类型定义

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

1）对象类型

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

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

2）标量类型

1. Int：整数类型，表示有符号 32 位整数。

   type Example {
       age: Int
   }
   

2. Float：浮点数类型，表示有符号双精度浮点数。

   type Example {
       price: Float
   }
   

3. String：字符串类型，表示 UTF-8 字符序列。

   type Example {
       name: String
   }
   

4. Boolean：布尔类型，表示 true 或 false。

   type Example {
       isActive: Boolean
   }
   

5. ID：唯一标识符类型，通常用作对象的唯一标识。

   type Example {
       id: ID
   }
   

3）枚举类型

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

enum Role {
    ADMIN
    USER
    GUEST
}

4）输入类型

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

input PersonInput {
    name: String!
    age: Int
}

5）列表类型

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

type Example {
    tags: [String]
}

6）非空类型

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

type Example {
    name: String!
}

7）接口类型

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

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

8）联合类型

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

union SearchResult = Person | Post

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

3.2 查询和变更

1. 查询类型：定义读取数据的入口点。

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

2. 变更类型：定义写入数据的入口点。

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

四、示例

4.1 schema定义示例

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

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 查询示例

1. 查询单个 Person

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

   结果示例

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

2. 查询所有 People

   {
       people {
           id
           name
           age
       }
   }
   

   结果示例

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

3. 添加一个新的 Person

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

   结果示例

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