GraphQL 的三大操作类型

GraphQL 通过三种核心操作类型提供强大的数据交互能力。理解这三种操作是掌握 GraphQL 开发的基础。

1. Query - 查询操作

Query 用于从服务器获取数据，是 GraphQL 中最常用的操作类型。

基本语法

1query GetUser($id: ID!) {
2  user(id: $id) {
3    id
4    name
5    email
6    posts {
7      title
8      publishedAt
9    }
10  }
11}

特点

• 精确获取：只请求需要的字段，避免过度获取
• 嵌套查询：一次请求获取关联数据
• 强类型：响应结构由 Schema 保证
• 可缓存：查询通常可被缓存

示例场景

1# 获取用户信息及其订单
2query GetUserWithOrders {
3  user(id: "123") {
4    name
5    email
6    orders {
7      id
8      total
9      items {
10        product {
11          name
12          price
13        }
14        quantity
15      }
16    }
17  }
18}

2. Mutation - 变更操作

Mutation 用于修改服务器端数据，包括创建、更新、删除操作。

基本语法

1mutation CreateUser($input: CreateUserInput!) {
2  createUser(input: $input) {
3    id
4    name
5    email
6  }
7}

特点

• 数据修改：创建、更新、删除资源
• 立即返回值：返回修改后的数据
• 串行执行：多个 mutation 按顺序执行
• 不可缓存：通常不被缓存

示例场景

1# 创建订单
2mutation CreateOrder($input: CreateOrderInput!) {
3  createOrder(input: $input) {
4    order {
5      id
6      status
7      total
8      items {
9        productId
10        quantity
11        price
12      }
13    }
14    errors {
15      field
16      message
17    }
18  }
19}
20
21# 更新用户信息
22mutation UpdateUser($id: ID!, $input: UpdateUserInput!) {
23  updateUser(id: $id, input: $input) {
24    user {
25      id
26      name
27      updatedAt
28    }
29  }
30}
31
32# 删除操作
33mutation DeleteProduct($id: ID!) {
34  deleteProduct(id: $id) {
35    success
36    message
37  }
38}

3. Subscription - 订阅操作

Subscription 用于建立持久连接，实时接收服务器推送的数据更新。

基本语法

1subscription OnCommentAdded($postId: ID!) {
2  commentAdded(postId: $postId) {
3    id
4    content
5    author {
6      name
7    }
8    createdAt
9  }
10}

特点

• 实时更新：服务器主动推送数据
• 持久连接：通常使用 WebSocket
• 事件驱动：响应特定事件
• 资源敏感：需要管理连接生命周期

示例场景

1# 实时聊天
2subscription OnNewMessage($chatId: ID!) {
3  newMessage(chatId: $chatId) {
4    id
5    content
6    sender {
7      id
8      name
9      avatar
10    }
11    timestamp
12  }
13}
14
15# 股票价格更新
16subscription OnStockPriceChange($symbol: String!) {
17  stockPriceChange(symbol: $symbol) {
18    symbol
19    price
20    change
21    changePercent
22    timestamp
23  }
24}
25
26# 通知订阅
27subscription OnNotification {
28  notification {
29    id
30    type
31    title
32    message
33    read
34    createdAt
35  }
36}

三种操作对比

最佳实践

Query 最佳实践

• 使用变量传递参数，避免硬编码
• 利用片段（Fragment）复用字段
• 只请求需要的字段
• 为复杂查询添加别名

Mutation 最佳实践

• 一个 mutation 只修改一个资源
• 返回修改后的完整对象
• 包含错误处理信息
• 使用 Input 类型组织参数

Subscription 最佳实践

• 控制订阅范围（使用过滤条件）
• 实现连接心跳检测
• 设置合理的超时时间
• 在客户端取消订阅时清理资源

在 API 网关中处理 GraphQL

API 网关可以：

• 查询深度限制：防止复杂查询
• 复杂度分析：基于字段计算查询成本
• 持久化查询：只允许预定义的查询
• 缓存策略：为查询配置缓存规则
• 订阅管理：管理 WebSocket 连接

1客户端
2  ↓
3API 网关
4  ├── 认证/授权
5  ├── 查询深度检查
6  ├── 复杂度分析
7  └── 缓存/限流
8  ↓
9GraphQL 服务器

理解这三种操作类型，将帮助您设计出高效、易用的 GraphQL API。