API 设计 / 系统课时

实现 Subscription 实时更新

实现 Subscription 实时更新

Subscription 不只是“把 Query 放到 WebSocket 上”。本节搭建一个最小 graphql-ws 服务,用 Pub/Sub 产生事件、用连接参数建立用户上下文,并明确断线重连后哪些状态会恢复、哪些事件可能永久丢失。

学习目标

  • 理解 Subscription 从建立订阅到逐事件执行 Resolver 的数据链路。
  • 使用 graphql-ws、graphql-subscriptions 与 ws 实现可运行的实时推送。
  • 正确处理连接级认证上下文、自动重连、重新订阅与事件缺口边界。

先看清实时链路

一次 Subscription 先建立 WebSocket 连接并完成连接初始化,然后执行订阅操作。订阅字段的 subscribe 必须返回 AsyncIterable;之后 Pub/Sub 每产生一个事件,GraphQL 再按该事件执行字段解析并把新的执行结果发送给客户端。

GraphQL Subscription 从连接初始化到事件推送与重连

连接参数属于当前 WebSocket 会话。服务端可以在 onConnect 中做认证,再由 context 为每个订阅操作生成 Resolver Context;连接断开后旧 Context 也随之失效,重连必须重新完成连接初始化和鉴权。

实现 Pub/Sub 服务端

示例需要 graphql、graphql-ws、graphql-subscriptions 与 ws。保存为 server.mjs。内存 Pub/Sub 每秒交替发布给 u1 和 u2,withFilter 根据连接上下文只把当前用户的事件交给订阅。

js
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();
});

预期输出:

text
subscription server: ws://localhost:4000/graphql

默认 PubSub 基于单进程内存事件,只适合本地演示;多实例生产服务应替换为 Redis、NATS、Kafka 等可跨实例传播的事件系统,否则连接落在不同进程时无法收到同一主题的事件。

连接客户端并验证过滤

保存为 client.mjs 并在另一个终端运行。把 connectionParams 写成函数,意味着每次建立新连接时都可以读取当下有效的身份信息;这里固定返回 u1 便于验证过滤。

js
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();
});

预期输出:

text
{"data":{"messageAdded":{"userId":"u1","text":"message-<ID>"}}}
{"data":{"messageAdded":{"userId":"u1","text":"message-<ID>"}}}

<ID> 是运行时递增的偶数编号,起始值取决于客户端何时连上;不会收到 u2 的事件。

处理断线重连边界

retryAttempts 只解决“重新建立连接”的问题。可重试断线后,客户端重新连接并再次建立活跃订阅;如果认证凭证会刷新,应让 connectionParams 在每次连接时读取最新凭证,而不是把旧 Token 固化在客户端初始化阶段。

更关键的是,重连不等于事件重放。客户端断线到重新订阅成功之间,内存 Pub/Sub 已发布的事件不会自动补发。对订单状态、审计事件等不能丢失的业务,应让事件携带递增序号或游标,并使用具备持久化与 replay 能力的消息系统;客户端重连后从最后确认位置恢复。对于“在线提示”这类只关心最新状态的场景,允许跳过断线窗口中的旧事件反而更简单。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现 Subscription 实时更新

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通