GraphQL Subscriptions 与消息推送（WebSocket、graphql-ws 与验证）

---

title: GraphQL Subscriptions 与消息推送（WebSocket、graphql-ws 与验证）

date: 2025-11-26

keywords:

• Subscriptions
• WebSocket
• graphql-ws
• 推送
• 可扩展

description: 通过WebSocket与graphql-ws实现GraphQL Subscriptions消息推送，提供服务端与客户端实现及可靠性验证方法。

categories:

• 文章资讯
• 技术教程

---

概述

GraphQL Subscriptions用于事件推送与实时更新。使用graphql-ws协议与WebSocket连接，可在订阅的字段发生变化时向客户端推送消息，并配合心跳与重连提升稳定性。

关键实践与参数

• 协议：graphql-ws（推荐）
• 心跳与重连：客户端定时ping/pong与指数退避重连
• 授权：连接参数携带令牌并在服务端校验
• 可扩展：多实例下通过消息队列或发布订阅广播事件

示例/配置/实现

// 服务端（Apollo + graphql-ws）
import { makeExecutableSchema } from '@graphql-tools/schema'
import { createServer } from 'http'
import { WebSocketServer } from 'ws'
import { useServer } from 'graphql-ws/lib/use/ws'
const typeDefs = `type Message { id: ID!, text: String! } type Query { _noop: Boolean } type Subscription { message: Message }`
const resolvers = { Subscription: { message: { subscribe: async function* () { while (true) { yield { message: { id: Date.now(), text: 'hi' } }; await new Promise(r => setTimeout(r, 1000)) } } } } }
const schema = makeExecutableSchema({ typeDefs, resolvers })
const server = createServer()
const wss = new WebSocketServer({ server })
useServer({ schema }, wss)
server.listen(4000)

// 客户端（graphql-ws）
import { createClient } from 'graphql-ws'
const client = createClient({ url: 'ws://localhost:4000' })
client.subscribe({ query: 'subscription { message { id text } }' }, { next: (data) => console.log(data) })

验证

• 连接稳定：心跳与重连策略在网络抖动下保持订阅
• 授权校验：无效令牌拒绝连接，可审计
• 可扩展广播：多实例下事件一致广播，无丢失
• 性能：订阅数与推送延迟在目标阈值内

注意事项

• 对热点订阅使用限速与分片
• 在浏览器与Node环境分别测试
• 与缓存与离线策略结合提升体验
• 记录订阅事件与错误用于告警