API 设计 / 系统课时
实现 Subscription 实时更新
实现 Subscription 实时更新
Subscription 不只是“把 Query 放到 WebSocket 上”。本节搭建一个最小 graphql-ws 服务,用 Pub/Sub 产生事件、用连接参数建立用户上下文,并明确断线重连后哪些状态会恢复、哪些事件可能永久丢失。
学习目标
- 理解 Subscription 从建立订阅到逐事件执行 Resolver 的数据链路。
- 使用
graphql-ws、graphql-subscriptions与ws实现可运行的实时推送。 - 正确处理连接级认证上下文、自动重连、重新订阅与事件缺口边界。
先看清实时链路
一次 Subscription 先建立 WebSocket 连接并完成连接初始化,然后执行订阅操作。订阅字段的 subscribe 必须返回 AsyncIterable;之后 Pub/Sub 每产生一个事件,GraphQL 再按该事件执行字段解析并把新的执行结果发送给客户端。

连接参数属于当前 WebSocket 会话。服务端可以在 onConnect 中做认证,再由 context 为每个订阅操作生成 Resolver Context;连接断开后旧 Context 也随之失效,重连必须重新完成连接初始化和鉴权。
实现 Pub/Sub 服务端
示例需要 graphql、graphql-ws、graphql-subscriptions 与 ws。保存为 server.mjs。内存 Pub/Sub 每秒交替发布给 u1 和 u2,withFilter 根据连接上下文只把当前用户的事件交给订阅。
import {
GraphQLNonNull,
GraphQLObjectType,
GraphQLSchema,
GraphQLString,
} from "graphql";
import { PubSub, withFilter } from "graphql-subscriptions";
import { useServer } from "graphql-ws/use/ws";
import { WebSocketServer } from "ws";
const pubsub = new PubSub();
const TOPIC = "MESSAGE_ADDED";
const MessageType = new GraphQLObjectType({
name: "Message",
fields: {
userId: { type: new GraphQLNonNull(GraphQLString) },
text: { type: new GraphQLNonNull(GraphQLString) },
},
});
const QueryType = new GraphQLObjectType({
name: "Query",
fields: {
health: {
type: new GraphQLNonNull(GraphQLString),
resolve: () => "ok",
},
},
});
const SubscriptionType = new GraphQLObjectType({
name: "Subscription",
fields: {
messageAdded: {
type: new GraphQLNonNull(MessageType),
subscribe: withFilter(
() => pubsub.asyncIterableIterator(TOPIC),
(payload, _variables, context) =>
payload.messageAdded.userId === context.userId,
),
resolve: (payload) => payload.messageAdded,
},
},
});
const schema = new GraphQLSchema({
query: QueryType,
subscription: SubscriptionType,
});
const wsServer = new WebSocketServer({
port: 4000,
path: "/graphql",
});
const cleanup = useServer(
{
schema,
onConnect(ctx) {
const userId = ctx.connectionParams?.userId;
if (typeof userId !== "string" || userId.length === 0) return false;
},
context(ctx) {
return { userId: ctx.connectionParams.userId };
},
},
wsServer,
);
let seq = 0;
const timer = setInterval(() => {
seq += 1;
const userId = seq % 2 === 0 ? "u1" : "u2";
void pubsub.publish(TOPIC, {
messageAdded: { userId, text: `message-${seq}` },
});
}, 1000);
console.log("subscription server: ws://localhost:4000/graphql");
process.on("SIGINT", async () => {
clearInterval(timer);
await cleanup.dispose();
wsServer.close();
});预期输出:
subscription server: ws://localhost:4000/graphql默认 PubSub 基于单进程内存事件,只适合本地演示;多实例生产服务应替换为 Redis、NATS、Kafka 等可跨实例传播的事件系统,否则连接落在不同进程时无法收到同一主题的事件。
连接客户端并验证过滤
保存为 client.mjs 并在另一个终端运行。把 connectionParams 写成函数,意味着每次建立新连接时都可以读取当下有效的身份信息;这里固定返回 u1 便于验证过滤。
import WebSocket from "ws";
import { createClient } from "graphql-ws";
const client = createClient({
url: "ws://localhost:4000/graphql",
webSocketImpl: WebSocket,
connectionParams: async () => ({ userId: "u1" }),
retryAttempts: 5,
});
const unsubscribe = client.subscribe(
{
query: "subscription { messageAdded { userId text } }",
},
{
next: (result) => console.log(JSON.stringify(result)),
error: (error) => console.error(error),
complete: () => console.log("complete"),
},
);
process.on("SIGINT", async () => {
unsubscribe();
await client.dispose();
});预期输出:
{"data":{"messageAdded":{"userId":"u1","text":"message-<ID>"}}}
{"data":{"messageAdded":{"userId":"u1","text":"message-<ID>"}}}<ID> 是运行时递增的偶数编号,起始值取决于客户端何时连上;不会收到 u2 的事件。
处理断线重连边界
retryAttempts 只解决“重新建立连接”的问题。可重试断线后,客户端重新连接并再次建立活跃订阅;如果认证凭证会刷新,应让 connectionParams 在每次连接时读取最新凭证,而不是把旧 Token 固化在客户端初始化阶段。
更关键的是,重连不等于事件重放。客户端断线到重新订阅成功之间,内存 Pub/Sub 已发布的事件不会自动补发。对订单状态、审计事件等不能丢失的业务,应让事件携带递增序号或游标,并使用具备持久化与 replay 能力的消息系统;客户端重连后从最后确认位置恢复。对于“在线提示”这类只关心最新状态的场景,允许跳过断线窗口中的旧事件反而更简单。