GraphQL 概念

约 835 字大约 3 分钟

GraphQLAPI查询语言

2026-04-08

官网：https://graphql.org/

1. 什么是 GraphQL

GraphQL 是一种用于 API 的查询语言，由 Facebook 于 2012 年开发并于 2015 年开源。它提供了一种更高效、更灵活且更强大的 REST 替代方案，让客户端能够精确地描述它所需要的数据，仅此而已。

与 REST 不同，GraphQL 将 API 抽象为一个强类型的 Schema，客户端通过发送声明式的查询语句，一次请求即可获取多个资源的组合数据。

2. 为什么使用 GraphQL

传统 REST 架构下常见的痛点：

Over-fetching（过度获取）：接口返回了过多客户端不需要的字段
Under-fetching（获取不足）：一次请求不够，需要多次往返拉取关联数据（N+1 问题）
多端差异：Web、iOS、Android 需要的数据结构不同，后端需维护多套接口
版本演进困难：REST 往往需要通过 /v1/、/v2/ 管理接口版本

GraphQL 的解决思路：

按需取数：客户端声明需要的字段，服务端只返回对应数据
一次请求聚合多资源：通过关联字段一次取回嵌套的数据
强类型 Schema：所有字段、类型、可空性都有明确定义，开发工具可做静态校验和自动补全
无版本演进：通过废弃（@deprecated）而非版本号来演进字段

3. 核心概念

3.1 Schema 与类型系统

Schema 是 GraphQL 服务的契约，用 SDL（Schema Definition Language）描述：

type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String!
    author: User!
}

type Query {
    user(id: ID!): User
    posts: [Post!]!
}

type Mutation {
    createPost(title: String!, content: String!): Post!
}

常用类型：

标量类型（Scalar）：Int、Float、String、Boolean、ID
对象类型（Object）：如上述 User、Post
枚举（Enum）、接口（Interface）、联合（Union）、输入类型（Input）
修饰符：! 表示非空，[] 表示列表

3.2 三种操作类型

Query：读取数据
Mutation：写入数据
Subscription：基于 WebSocket 订阅实时数据变更

3.3 Resolver（解析函数）

Schema 定义了"有什么"，Resolver 定义了"怎么拿"。每个字段都对应一个 resolver 函数：

const resolvers = {
    Query: {
        user: (parent, args, context, info) => {
            return db.users.findById(args.id)
        },
    },
    User: {
        posts: (parent) => db.posts.findByUserId(parent.id),
    },
}

Resolver 参数说明：

参数	说明
`parent`	上一级 resolver 的返回值
`args`	查询时传入的参数
`context`	请求上下文，常用来存放用户信息、数据源实例等
`info`	查询执行信息（AST、字段选择集等）

4. GraphQL vs REST

维度	REST	GraphQL
端点	多个 URL	单一端点（通常 `/graphql`）
数据结构	服务端决定	客户端决定
过度获取	常见	天然避免
版本管理	URL 版本号	字段级 `@deprecated`
类型系统	需借助 OpenAPI 等额外描述	内建强类型 Schema
缓存	HTTP 层天然支持	需在客户端或 CDN 层专门处理
学习成本	低	中

5. 生态一览

服务端：Apollo Server、GraphQL Yoga、Mercurius（Fastify）、Nest.js 的 @nestjs/graphql
客户端：Apollo Client、urql、Relay、graphql-request
工具链：GraphiQL / Apollo Sandbox（调试）、GraphQL Code Generator（类型生成）、graphql-tools
规范扩展：Federation（微服务联邦）、Persisted Queries（持久化查询）、DataLoader（批量与缓存）