GraphQL 核心概念与 REST 对比

REST 的问题

过度获取（Over-fetching）

假设你在构建一个移动端用户列表页面，只需要显示用户名和头像。但 REST API 的 GET /users 返回了每个用户的所有信息：

{
  "id": "u1",
  "name": "Alice",
  "email": "alice@example.com",
  "phone": "+86-138-0000-0001",
  "address": { "city": "Beijing", "street": "..." },
  "preferences": { "theme": "dark", "language": "zh" },
  "createdAt": "2023-01-01T00:00:00Z",
  "lastLogin": "2024-01-15T10:30:00Z"
  // ...还有更多字段
}

你只用了 name 和头像 URL，却传输了十几个字段的数据。在 3G 网络下，这会显著增加加载时间。

欠获取（Under-fetching）与 N+1 问题

另一个常见问题是需要多次请求才能获取所需数据。例如显示用户列表，每个用户下面还需要显示该用户最新的3篇文章：

# 第1个请求：获取用户列表
GET /users
# 返回10个用户

# 第2-11个请求：为每个用户获取文章（N+1 问题！）
GET /users/u1/posts?limit=3
GET /users/u2/posts?limit=3
...
GET /users/u10/posts?limit=3
# 共需要 11 次 HTTP 请求

GraphQL 的诞生

Facebook 的解决方案（2012）

2012 年，Facebook 的 iOS 应用移动团队在构建 News Feed 时遇到了严重的性能问题。他们的 REST API 是为桌面 Web 设计的，无法满足移动端的精确数据需求。工程师 Lee Byron、Nick Schrock 和 Dan Schafer 开始设计一种新的查询语言——GraphQL（Graph Query Language）。

核心思想：让客户端（而不是服务器）决定需要哪些数据。

用 GraphQL 解决同样问题

# 只请求需要的字段：用户名 + 最新3篇文章标题
query UserListWithPosts {
  users {
    id
    name
    avatar
    posts(limit: 3) {
      id
      title
    }
  }
}

一次请求，精确获取所需数据，没有多余字段，也没有额外的 N+1 请求。

GraphQL vs REST vs gRPC

特性	REST	GraphQL	gRPC
端点数量	多个端点（/users, /posts...）	单一端点（/graphql）	方法调用（protobuf）
数据获取	固定响应结构	客户端精确声明	固定 proto 定义
类型系统	需要 OpenAPI 等额外工具	内置强类型 Schema	protobuf 强类型
实时支持	需要 SSE/WebSocket 扩展	内置 Subscription	内置 streaming
缓存	HTTP 缓存天然支持	需要额外工具（APQ）	应用层缓存
适用场景	简单 CRUD，公开 API	复杂数据图，移动端	内部微服务，高性能

核心概念

安装 Apollo Server

# 创建新项目
mkdir graphql-demo && cd graphql-demo
npm init -y

# 安装依赖
npm install @apollo/server graphql

# TypeScript 项目（推荐）
npm install -D typescript @types/node ts-node
npx tsc --init

第一个 Apollo Server

// src/index.ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';

// 1. Schema 定义
const typeDefs = `#graphql
  type Book {
    id: ID!
    title: String!
    author: String!
    year: Int
  }

  type Query {
    books: [Book!]!
    book(id: ID!): Book
  }
`;

// 2. 模拟数据
const books = [
  { id: '1', title: 'The Pragmatic Programmer', author: 'Hunt & Thomas', year: 1999 },
  { id: '2', title: 'Clean Code', author: 'Robert C. Martin', year: 2008 },
];

// 3. Resolvers
const resolvers = {
  Query: {
    books: () => books,
    book: (_: unknown, { id }: { id: string }) =>
      books.find(b => b.id === id),
  },
};

// 4. 启动服务器
const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});
console.log(`Server ready at: ${url}`);

本章小结