GraphQL vs REST：API 设计终极对比与实战

GraphQL vs REST：API 设计终极对比与实战

GraphQL 和 REST 是两种主流的 API 设计风格。本文深入对比两者的优劣，帮助你在项目中做出正确选择。

📊 REST 快速回顾

# 获取用户
GET /api/users/1

# 获取用户的文章
GET /api/users/1/posts

# 创建文章
POST /api/posts
Body: { "title": "GraphQL vs REST", "authorId": 1 }

🚀 GraphQL 快速上手

# 查询
query {
  user(id: 1) {
    name
    email
    posts {
      title
      createdAt
    }
  }
}

# 修改
mutation {
  createPost(title: "GraphQL vs REST", authorId: 1) {
    id
    title
  }
}

🔄 核心区别

特性	REST	GraphQL
数据获取	多个端点，可能过度获取或获取不足	单个端点，精确获取所需数据
版本控制	通常需要版本号（/v1/, /v2/）	无需版本控制，按需添加字段
错误处理	HTTP 状态码	200 OK + 错误数组
缓存	利用 HTTP 缓存	需要客户端缓存
学习曲线	低	中等

✅ GraphQL 的优势

1. 避免过度获取（Over-fetching）

// REST：获取用户，但只需要 name
// 返回：{ "id": 1, "name": "John", "email": "...", "age": 25, ... }

// GraphQL：只获取 name
{ user(id: 1) { name } }
// 返回：{ "data": { "user": { "name": "John" } } }

2. 避免获取不足（Under-fetching）

// REST：需要 3 个请求
GET /api/user/1
GET /api/user/1/posts
GET /api/user/1/followers

// GraphQL：1 个请求
query {
  user(id: 1) {
    name
    posts { title }
    followers { name }
  }
}

3. 强类型 Schema

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

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

❌ GraphQL 的挑战

1. 缓存复杂：需要使用 Apollo Client 等专用客户端
2. N+1 问题：需要使用 DataLoader 批量加载
3. 文件上传：需要额外处理（如 multipart request）
4. 学习曲线：需要学习 Schema 定义、Resolver 等概念

🎯 如何选择？

选择 REST 的场景

• 简单的 CRUD API
• 需要利用 HTTP 缓存
• 团队对 REST 更熟悉
• 公开 API（第三方集成）

选择 GraphQL 的场景

• 复杂的数据关系（如社交网络）
• 移动端需要精确控制数据量
• 多个数据源聚合
• 实时应用（配合 Subscription）

总结：GraphQL 和 REST 各有优劣，没有绝对的好坏。根据项目需求、团队经验和应用场景选择合适的技术方案。

---

本文整理自 GraphQL 官方文档及 API 设计社区实践