GraphQL系列 - 第1讲 GraphQL语法入门
目录
- 一、介绍GraphQL
- 二、GraphQL基本使用方法
- 三、Schema 定义语言 (SDL)
- 3.1 类型定义
- 1)对象类型
- 2)标量类型
- 3)枚举类型
- 4)输入类型
- 5)列表类型
- 6)非空类型
- 7)接口类型
- 8)联合类型
- 3.2 查询和变更
- 四、示例
- 4.1 schema定义示例
- 4.2 查询示例
一、介绍GraphQL
GraphQL 是一种用于 API 的查询语言以及一个用于执行查询的服务器端运行时。它由 Facebook 开发,并在 2015 年开源。GraphQL 的主要目的是提供一种更高效、灵活的数据查询方式,替代传统的 REST API。
基本功能
基本功能 | 描述 |
---|---|
类型系统 | 使用强类型系统定义 API 的数据结构。 |
查询 | 客户端可以通过查询请求精确地获取所需的数据,减少数据传输量。 |
变更(Mutation) | 支持变更操作,用于创建、更新或删除数据。 |
订阅(Subscription) | 支持订阅功能,允许客户端订阅数据的变化,并在数据发生变化时接收实时更新。 |
解析器(Resolver) | 服务器端的函数,用于处理查询和变更请求。每个字段都有一个解析器来获取相应的数据。 |
使用场景
使用场景 | 描述 |
---|---|
复杂数据需求 | 当客户端需要从多个资源中获取数据时,通过单个请求获取所有所需数据。 |
前端开发 | 前端开发人员可以精确地查询所需数据,减少不必要的数据传输。 |
微服务架构 | 作为聚合层,统一多个微服务的数据接口,简化客户端的调用逻辑。 |
实时应用 | 通过订阅功能,适合需要实时数据更新的应用,如聊天应用、股票行情等。 |
使用者
使用者 | 描述 |
---|---|
GraphQL 的发明者,广泛使用 GraphQL。 | |
GitHub | 提供基于 GraphQL 的 API,允许开发者查询和操作 GitHub 数据。 |
Shopify | 使用 GraphQL 提供其 API,帮助开发者构建电商应用。 |
使用 GraphQL 优化其数据查询和传输。 | |
通过 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)对象类型
对象类型用于定义复杂的数据结构,可以包含多个字段,每个字段可以是任意类型(包括标量类型和其他对象类型)。
type Person {
id: ID!
name: String!
age: Int
friends: [Person]
}
2)标量类型
-
Int:整数类型,表示有符号 32 位整数。
type Example { age: Int }
-
Float:浮点数类型,表示有符号双精度浮点数。
type Example { price: Float }
-
String:字符串类型,表示 UTF-8 字符序列。
type Example { name: String }
-
Boolean:布尔类型,表示
true
或false
。type Example { isActive: Boolean }
-
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 查询和变更
-
查询类型:定义读取数据的入口点。
type Query { person(id: ID!): Person people: [Person] }
-
变更类型:定义写入数据的入口点。
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 查询示例
-
查询单个 Person
{ person(id: "1") { id name age } }
结果示例
{ "data": { "person": { "id": "1", "name": "John Doe", "age": 30 } } }
-
查询所有 People
{ people { id name age } }
结果示例
{ "data": { "people": [ { "id": "1", "name": "John Doe", "age": 30 }, { "id": "2", "name": "Jane Smith", "age": 25 } ] } }
-
添加一个新的 Person
mutation { addPerson(input: { name: "Alice", age: 28 }) { id name age } }
结果示例
{ "data": { "addPerson": { "id": "3", "name": "Alice", "age": 28 } } }