GraphQL 详细说明和使用指南

作者：光头佬 😎日期：2026-04-04

GraphQL 是一种用于 API 的查询语言，也是满足你数据查询需求的运行时。由 Facebook 开发维护（现 Meta），目前由 GraphQL 基金会管理。

核心特点：

• 强类型：API 有完整的类型系统在运行前就能发现错误
• 按需获取：客户端精确指定需要哪些字段，避免过度获取
• 一次性获取多接口数据：告别 REST 的多次请求
• 自省：客户端可以查询 API 本身获取Schema 信息
• 类型安全：前后端共享同一套类型定义

1. Schema（模式）

GraphQL Schema 是 API 的类型系统，定义了所有可用的类型和字段。

typeQuery{  hero(episode: Episode): Characterhumans:[Human]droids:[Droid]}

2. Query（查询）

用于读取/获取数据，是 GraphQL 最常用的操作。

query{  hero {    name    friends {      name}}}

3. Mutation（变更）

用于创建/更新/删除数据，类似 REST 的 POST/PUT/DELETE。

mutation{  createReview(review:$review) {    stars    commentary}}

4. Subscription（订阅）

用于实时数据推送，建立持久连接。

subscription{  onCommentAdded(postId:"123"){    content    author}}

字段查询

# 查询单个字段query{  hero {    name}}# 返回：{ "hero": { "name": "R2-D2" } }

参数传递

query{  human(id:"1000"){    name    height(unit: FOOT)}}

别名

query{empireHero: hero(episode: EMPIRE){    name}jediHero: hero(episode: JEDI){    name}}

片段

fragment NameParts on Character {  name  birthDate}query{  hero {...NameParts    friends {...NameParts}}}

变量

query HeroNameAndFriends($episode: Episode = JEDI){  hero(episode:$episode) {    name    friends {      name}}}# 变量：{"episode": "EMPIRE"}

指令

query Hero($withFriends: Boolean!){  hero {    name    friends @include(if:$withFriends) {      name}}}

标量类型

• Int：32位整数
• Float：浮点数
• String：字符串
• Boolean：布尔值
• ID：唯一标识符（序列化字符串）

对象类型

type Human {id: ID!name: String!friends:[Character]appearsIn:[Episode]!}

接口

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

联合类型

union SearchResult = Human | Droid | Starship

输入类型

input ReviewInput {stars: Int!commentary: String}

客户端库

服务端框架

开发工具

使用 Apollo Server 创建 API

// 1. 定义 Schemaconst typeDefs = gql`typeQuery{hello: Stringusers:[User]}type User {id: ID!name: String!email: String}`;// 2. 实现 Resolverconst resolvers = {Query: {hello: () =>'Hello World!',users: () => db.users,  },};// 3. 启动服务const server = newApolloServer({ typeDefs, resolvers });await server.start();server.listen();

GraphQL 请求示例

# 通过 curl 请求curl -X POST https://api.example.com/graphql \  -H "Content-Type: application/json" \  -d '{    "query": "query { hello }"  }'

GraphQL 为 API 设计提供了全新的范式：让客户端精确控制所需数据，减少网络请求，提升开发效率。虽然学习曲线比 REST 略高，但收益显著。

适用场景：

• 移动端 API（省流量）
• 多端复用同一 API（Web/iOS/Android）
• 复杂关联数据查询
• 快速迭代的前后端分离项目

不适用场景：

• 简单 CRUD 操作
• 文件上传/下载
• 已有成熟的 REST API

光头佬，没斑秃 😎