API设计最佳实践：从REST到GraphQL的选择指南

昨天 7阅读

文章最后更新时间：2026年05月04日

一个好的API设计可以节省数月的开发时间和无数的维护成本。本文从实战角度出发，对比REST和GraphQL两种主流API风格，提供经过生产环境验证的设计规范和选择指南。

REST API设计规范

URL设计

# 正确
GET    /api/users          # 获取用户列表
GET    /api/users/123      # 获取特定用户
POST   /api/users          # 创建用户
PUT    /api/users/123      # 完整更新用户
PATCH  /api/users/123      # 部分更新用户
DELETE /api/users/123      # 删除用户

# 子资源
GET    /api/users/123/orders       # 用户的订单
GET    /api/users/123/orders/456   # 用户的特定订单

# 错误示范
GET /api/getUsers          # 不要在URL中使用动词
POST /api/createUser       # 同上
GET /api/users?id=123      # 资源ID应该在路径中

响应格式标准化

// 成功响应
{
  "success": true,
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com",
    "created_at": "2026-05-04T10:30:00Z"
  }
}

// 列表响应（含分页）
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 156,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

// 错误响应
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "邮箱格式不正确",
    "details": [
      {"field": "email", "reason": "格式不符合email规范"}
    ]
  }
}

HTTP状态码正确使用

200：成功（GET、PUT、PATCH）
201：创建成功（POST）
204：删除成功，无返回内容
400：客户端请求错误（参数错误）
401：未认证
403：无权限
404：资源不存在
409：资源冲突（重复创建等）
422：请求格式正确但语义错误
429：请求频率超限
500：服务器内部错误

GraphQL：另一种选择

什么时候用GraphQL？

GraphQL在以下场景中明显优于REST：

复杂的数据关系：前端需要在一个请求中获取用户信息、订单列表、订单详情、商品信息。REST需要多次请求，GraphQL一次完成。

移动端优化：移动网络带宽有限，GraphQL允许客户端精确指定需要的字段，避免过度获取（Over-fetching）。

快速迭代的前端：前端频繁变更数据需求时，GraphQL不需要后端修改API。

GraphQL Schema设计

type User {
  id: ID!
  name: String!
  email: String!
  orders(first: Int, after: String): OrderConnection!
  createdAt: DateTime!
}

type Order {
  id: ID!
  status: OrderStatus!
  totalAmount: Float!
  items: [OrderItem!]!
}

enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: PaginationInput): UserConnection!
}