GraphQL vs REST：API 设计范式对比

🎯 API 设计范式

API 是系统间通信的桥梁。选择合适的 API 设计范式直接影响开发效率、性能、可维护性。

📊

REST（Representational State Transfer）

资源导向，HTTP 标准，缓存友好

采用率83%

学习曲线平缓

🔗

GraphQL（Graph Query Language）

查询语言，精确获取数据，强类型

采用率38%

学习曲线陡峭

💡 独特观点

GraphQL 不是 REST 的替代品，而是补充。两者各有适用场景：REST 适合简单、缓存密集型应用，GraphQL 适合复杂、多数据源应用。

📊 REST 基础

REST（Representational State Transfer）是最流行的 API 设计范式。它基于 HTTP 标准，简单易懂。

1. REST 核心原则

资源导向

一切都是资源（用户、订单、商品），用 URL 标识

GET /users/123  # 获取用户 123
POST /orders   # 创建订单

统一接口

使用HTTP 方法表示操作（GET/POST/PUT/DELETE）

GET    /users     # 列表
POST   /users     # 创建
GET    /users/:id # 获取
PUT    /users/:id # 更新
DELETE /users/:id # 删除

无状态

每个请求独立，服务器不保存会话状态

# 每个请求都携带认证信息
GET /users/123
Authorization: Bearer <token>

# 服务器不保存会话

可缓存

响应必须明确是否可缓存（Cache-Control、ETag）

HTTP/1.1 200 OK
Cache-Control: max-age=3600
ETag: "abc123"

# 客户端可缓存 1 小时

2. REST API 设计最佳实践

✅ 应该做

使用名词表示资源（/users，非 /getUsers）
使用复数表示集合（/users，非 /user）
使用HTTP 状态码表示结果（200、404、500）
提供分页、过滤、排序（?page=2&limit=10）
使用版本控制（/api/v1/users）
返回JSON（默认），支持HATEOAS

❌ 不应该做

在 URL 中使用动词（/getUser）
混淆HTTP 方法语义（用 GET 修改数据）
返回2xx 表示错误
忽略状态码（所有响应都是 200）
过度嵌套资源（/users/1/posts/2/comments/3）
不提供文档（Swagger/OpenAPI）

📝 RESTful API 完整示例

## ✅ 好的 REST API 设计

# 用户资源
GET    /api/v1/users       # 获取用户列表（分页）
POST   /api/v1/users       # 创建用户
GET    /api/v1/users/:id   # 获取用户详情
PUT    /api/v1/users/:id   # 更新用户（全量）
PATCH  /api/v1/users/:id   # 更新用户（部分）
DELETE /api/v1/users/:id   # 删除用户

# 嵌套资源（适度）
GET /api/v1/users/:id/orders  # 获取用户的订单

# 过滤、排序、分页
GET /api/v1/users?role=admin&sort=-created_at&page=2&limit=10

# 响应示例（成功）
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": 123,
    "username": "alice",
    "email": "[email protected]",
    "created_at": "2024-01-01T08:00:00Z"
  },
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

# 响应示例（错误）
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "用户不存在",
    "details": { "user_id": 999 }
  }
}

📝 总结与展望

GraphQL 和 REST 是互补的 API 设计范式，而非替代关系。

🎯 核心要点

REST：资源导向、HTTP 标准、缓存友好、简单易懂
GraphQL：查询语言、精确获取、强类型、单一入口
核心差异：数据获取方式、类型系统、错误处理、缓存策略
REST 适用：简单 CRUD、缓存密集型、公开 API
GraphQL 适用：复杂查询、多数据源、移动端优化
REST 最佳实践：名词复数、HTTP 状态码、分页过滤、版本控制
GraphQL 最佳实践：类型设计、分页（cursor）、错误格式、性能优化
性能优化：REST（缓存、CDN）、GraphQL（DataLoader、批处理）
安全：REST（JWT、OAuth 2.0）、GraphQL（查询深度限制、复杂度分析）
迁移策略：并存、网关、逐步迁移

🚀 未来展望

API 设计领域正在快速演进，值得关注的方向：

gRPC：高性能 RPC 框架，适合微服务通信
Async API：异步 API 规范（WebSocket、Webhook）
tRPC：类型安全的 RPC（TypeScript 优先）
OpenAPI + GraphQL：融合两者优势（OpenAPI-to-GraphQL）
AI 生成 API：根据自然语言生成 API（GPT-4 + OpenAPI）