How to GraphQL:基于 TypeScript 与 GraphQL-Helix 实现实时 GraphQL Subscriptions 完整实战

原创2026-09-24 10:18:291,826 阅读

How to GraphQL:基于 TypeScript 与 GraphQL-Helix 实现实时 GraphQL Subscriptions 完整实战

本文基于 How to GraphQL 的 TypeScript & GraphQL-Helix 后端教程,讲解如何在一个 Fastify + Prisma 的 GraphQL 服务中落地实时能力:通过 graphql-subscriptions 的 PubSub 与 SSE(Server-Sent Events)传输实现 newLink 与 newVote 两个订阅,并配套实现数据库层的投票功能(Vote 模型、vote mutation 与关系解析器)。读完后,你将掌握 Subscription 的 subscribe/resolve 双层解析器结构、事件通道(channel)的类型安全建模,以及“mutation 发布事件 → 订阅端实时推送”的完整调用链。

该教程属于本仓库 content/backend/typescript-helix 系列的第 9 章,前置内容(Fastify 服务、Prisma 数据库、JWT 认证)分别见 3-graphql-server.md 与 8-authentication.md;本章之后的过滤/分页/排序见 10-filtering-pagination-and-sorting.md。

目标:为 HackerNews API 增加两个实时订阅

本章为教程中的 Hacker News 克隆 API 增加实时功能,最终暴露两个订阅:

  • 当一个新的 Link 元素被创建时,向所有已订阅的客户端推送实时更新;
  • 当一个已存在的 Link 元素被**点赞(upvote)**时,向客户端推送实时更新。

从源码结构看,这两个订阅分别对应教程项目(hackernews-node-ts)中的 post mutation 与 vote mutation,事件发布点都落在 src/schema.ts 的 resolver 内。

什么是 GraphQL Subscriptions:一个基于事件的实时契约

Subscriptions 是 GraphQL 规范中的一类操作,允许服务器在某个特定_事件_发生时主动向客户端推送数据。需要理解两个关键点:

  1. Subscriptions 本身只是 GraphQL 契约(contract)的一部分,它只声明“有哪些事件可以订阅”,并不决定数据如何通过网络传输;
  2. 要把事件真正实时送达客户端,必须选择一个支持推送的传输层(transport)。本教程选择 SSE(Server-Sent Events):它是简单 HTTP 的扩展,天然支持流式与实时能力,不需要特殊的端口配置或额外搭建 WebSocket 服务器,实现与横向扩展都比 WebSocket 更简单。

SSE 的机制是把一次普通 HTTP 请求“升级”为一个长连接(long-living request),在其上持续发出多个数据帧,这与 GraphQL Subscriptions 的语义正好契合。

概念辨析:Subscriptions 不是“请求—响应循环”(那是 Query/Mutation 的模型),也不是绑定在某一种传输上的技术——它是实时的 GraphQL 契约,可以用 SSE、WebSockets 等多种实时传输实现。这正是本章 frontmatter 中知识检测题的正确答案所在。

搭建类型安全的 PubSub 实例并注入 Context

安装依赖

订阅的事件层使用 graphql-subscriptions 库中一个简单的 PubSub 实现,覆盖三类数据变更事件:新建(created)、更新(updated)、删除(deleted)。

Pub/Sub(发布/订阅) 是一种消息模式:代码中一部分组件负责 publish 事件/消息,另一部分组件订阅这些事件并在发生时被通知。本教程正是用这一技巧,为基于 mutation 发布事件的 GraphQL Subscriptions 构建底层通道。

执行安装命令:

npm install graphql-subscriptions typed-graphql-subscriptions

其中 graphql-subscriptions 提供 PubSub 实例,typed-graphql-subscriptions 则为发出的事件提供 TypeScript 类型约束,让 channel 名称与 payload 结构在编译期就受到检查。

创建 src/pubsub.ts

新建 src/pubsub.ts,初始版本如下:

import { PubSub } from "graphql-subscriptions";
import { TypedPubSub } from "typed-graphql-subscriptions";

// 1
export type PubSubChannels = {};

// 2
export const pubSub = new TypedPubSub<PubSubChannels>(new PubSub());

代码要点:

  1. 声明 TypeScript 类型 PubSubChannels,后续所有事件都要在这里登记,它是事件类型的单一事实来源;
  2. 用 TypedPubSub 包装一个 PubSub 实例,得到一个“完全类型化”的 Pub/Sub 单例。

注入 GraphQL context

与之前把 PrismaClient 存入 prisma 变量一样,PubSub 实例也要进入执行上下文,才能被所有 resolver 访问。在 src/context.ts 中加入 pubSub:

import { PrismaClient, User } from "@prisma/client";
import { FastifyRequest } from "fastify";
import { authenticateUser } from "./auth";
import { pubSub } from "./pubsub";

const prisma = new PrismaClient();

export type GraphQLContext = {
  prisma: PrismaClient;
  currentUser: User | null;
  pubSub: typeof pubSub;
};

export async function contextFactory(
  request: FastifyRequest
): Promise<GraphQLContext> {
  return {
    prisma,
    currentUser: await authenticateUser(prisma, request),
    pubSub,
  };
}

注意 GraphQLContext 类型中新增的 pubSub: typeof pubSub:typeof pubSub 直接复用 TypedPubSub<PubSubChannels> 的类型,因此每个 resolver 里 context.pubSub 的 publish/asyncIterator 调用都会按 PubSubChannels 检查 channel 名与 payload 形状。从 contextFactory 的签名(接收 FastifyRequest)可以推断,context 在每次请求时构建,而 pubSub 与 prisma 是模块级单例,保证发布与订阅发生在同一个事件总线上。

实现第一个订阅:newLink

与 Query、Mutation 一样,实现 Subscription 的第一步是扩展 GraphQL schema(SDL 优先的模式)。在 src/schema.graphql 中新增 Subscription 类型:

type Subscription {
  newLink: Link
}

订阅解析器的特殊结构

Subscription 的 resolver 与 Query/Mutation 的 resolver 有两个关键差异:

  1. 不直接返回数据:subscribe 返回一个 AsyncIterator,GraphQL 服务器用它持续向客户端推送事件数据;
  2. 双层解析器:订阅 resolver 被包裹在一个对象中,必须提供 subscribe 字段(返回 AsyncIterator),另需提供 resolve 字段,用于从 AsyncIterator 发出的事件 payload 中取出要返回给客户端的数据。

AsyncIterator 是 JavaScript 内建类型,允许以异步方式迭代逐步更新的值。Iterator 机制本身让语言层面可以自定义循环行为,AsyncIterator 则把“值可能异步到达”纳入其中,是订阅推送的底层载体。

声明事件通道

先在 src/pubsub.ts 中把事件登记进 PubSubChannels,事件名为 newLink,payload 是创建出的 Link 对象:

import { Link } from "@prisma/client";
import { PubSub } from "graphql-subscriptions";
import { TypedPubSub } from "typed-graphql-subscriptions";

export type PubSubChannels = {
  newLink: [{ createdLink: Link }];
};

export const pubSub = new TypedPubSub<PubSubChannels>(new PubSub());

可以看到,PubSubChannels["newLink"][0] 就是 publish 与订阅 resolve 共用的 payload 类型 [{ createdLink: Link }],这保证了发布端与订阅端结构一致。

实现订阅 resolver

在 src/schema.ts 中实现 newLink 的 subscribe/resolve:

import { PubSubChannels } from "./pubsub";

const resolvers = {
  Query: { /* ... */ },
  Mutation: { /* ... */ },
  Subscription: {
    newLink: {
      subscribe: (parent: unknown, args: {}, context: GraphQLContext) => {
        return context.pubSub.asyncIterator("newLink");
      },
      resolve: (payload: PubSubChannels["newLink"][0]) => {
        return payload.createdLink;
      },
    },
  },
};

执行流程拆解:

  • subscribe 通过 context.pubSub.asyncIterator("newLink") 创建一个监听 newLink 事件的 AsyncIterable。当客户端发起该订阅时,这个 iterable 被创建、监听器激活,订阅进入“等待事件”状态;
  • 每当有值在该事件上发出,resolve 就会以事件 payload 为参数被调用(其结构与 PubSubChannels 中的声明一致),这里直接返回 payload.createdLink 作为 newLink: Link 字段的数据。

在 mutation resolver 中触发事件

最后一步是让代码真正发布 newLink 事件。在 src/schema.ts 的 post mutation 中,于返回 newLink 之前调用 pubSub.publish():

const resolvers = {
  Mutation: {
    post: async (parent: unknown, args: { url: string; description: string }, context: GraphQLContext) => {
      if (context.currentUser === null) {
        throw new Error("Unauthenticated!");
      }

      const newLink = await context.prisma.link.create({
        data: {
          url: args.url,
          description: args.description,
          postedBy: { connect: { id: context.currentUser.id } },
        },
      });

      context.pubSub.publish("newLink", { createdLink: newLink });

      return newLink;
    },
  }
}

注意 publish 的第一个参数 "newLink" 与 subscribe 中 asyncIterator("newLink") 使用同一字符串——这就是事件通道的匹配键;第二个参数 { createdLink: newLink } 则是订阅端 resolve 收到的 payload。至此,完整的实时链路为:客户端发起 subscription → subscribe 建立 AsyncIterator 监听 → 某次 post mutation 执行 publish → resolve 提取 createdLink → 通过 SSE 推送给所有活跃订阅。

用 GraphiQL 验证订阅

代码就绪后,可以用 GraphiQL 验证实时 API。方法是同时打开两个 GraphiQL 实例(两个浏览器窗口):一个建立订阅连接,另一个发送触发事件的 mutation。

第一步:若服务器还在运行旧代码,先用 CTRL+C 停止,再重新 npm run start。

第二步:两个窗口都打开教程项目的 GraphQL 服务端点 http://localhost:3000/graphql(服务端口与 GraphiQL 配置见教程项目 src/index.ts,与 3-graphql-server.md 中的配置一致)。

第三步:在其中一个 GraphiQL 发送如下订阅:

subscription {
  newLink {
    id
    url
    description
    postedBy {
      id
      name
      email
    }
  }
}

与 Query/Mutation 不同,这次你不会立刻看到结果,而是看到一个持续转动的加载指示器,表示连接在等待事件发生——这是订阅操作的正常表现。

第四步:在另一个 GraphiQL 发送 post mutation 触发订阅(注意:必须已认证,认证方式见 8-authentication.md 中的 JWT 流程):

mutation {
  post(url: "www.graphqlweekly.com", description: "Just testing this new real-time thing") {
    id
  }
}

随后回到运行订阅的那个窗口,应当看到 newLink 的实时数据被推送出来(左窗口为订阅、右窗口为 mutation)。

注意:如果加载指示器一直不停,可能是因为 SSE 连接在标签页进入 idle 状态时被断开。请确保两个标签页都处于活动(active)状态再测试。

增加投票功能:Vote 模型与 vote mutation

第二个订阅 newVote 依赖一个尚未存在的投票功能,因此本章后半部分先补齐数据层与 GraphQL 层的投票实现。

扩展 Prisma 数据模型

打开 prisma/schema.prisma,为 Link 与 User 各增加到 Vote 的一对多关系,并新增 Vote 模型:

model Link {
  id          Int      @id @default(autoincrement())
  createdAt   DateTime @default(now())
  description String
  url         String
  postedBy    User?     @relation(fields: [postedById], references: [id])
  postedById  Int?
  votes       Vote[]
}

model User {
  id       Int    @id @default(autoincrement())
  name     String
  email    String @unique
  password String
  links    Link[]
  votes    Vote[]
}

model Vote {
  id     Int  @id @default(autoincrement())
  link   Link @relation(fields: [linkId], references: [id])
  linkId Int
  user   User @relation(fields: [userId], references: [id])
  userId Int

  @@unique([linkId, userId])
}

要点:

  • Vote 与 User、Link 均为一对多关系(一个用户可投多票,一条链接可被投多票);
  • @@unique([linkId, userId]) 复合唯一约束在数据库层面保证“同一用户对同一链接只能投一票”,这是后面 resolver 中“防重复投票”检查能使用 findUnique 的依据。

执行迁移:

npx prisma migrate dev --name "add-vote-model"

该命令会在 prisma/migrations 中生成新的迁移记录并更新数据库,同时重新生成 Prisma Client,使 vote 模型的 CRUD 查询可用。

扩展 GraphQL schema

遵循 schema-driven 开发流程,先在 src/schema.graphql 中暴露 vote mutation:

type Mutation {
  post(url: String!, description: String!): Link!
  signup(email: String!, password: String!, name: String!): AuthPayload
  login(email: String!, password: String!): AuthPayload
  vote(linkId: ID!): Vote
}

再定义被引用的 Vote 类型:

type Vote {
  id: ID!
  link: Link!
  user: User!
}

由于应该能从 Link 查询到它的所有 votes,Link 类型也要增加 votes 字段:

type Link {
  id: ID!
  description: String!
  url: String!
  postedBy: User
  votes: [Vote!]!
}

实现 vote mutation resolver

在 src/schema.ts 中添加 vote resolver:

const resolvers = {
  Mutation: {
    vote: async (
      parent: unknown,
      args: { linkId: string },
      context: GraphQLContext
    ) => {
      // 1
      if (!context.currentUser) {
        throw new Error("You must login in order to use upvote!");
      }

      const userId = context.currentUser.id;

      // 2
      const vote = await context.prisma.vote.findUnique({
        where: {
          linkId_userId: {
            linkId: Number(args.linkId),
            userId: userId,
          },
        },
      });

      if (vote !== null) {
        throw new Error(`Already voted for link: ${args.linkId}`);
      }

      // 3
      const newVote = await context.prisma.vote.create({
        data: {
          user: { connect: { id: userId } },
          link: { connect: { id: Number(args.linkId) } },
        },
      });

      // 4
      context.pubSub.publish("newVote", { createdVote: newVote });

      return newVote;
    },
  }
};

分步说明(对应代码中的编号注释):

  1. 鉴权:未登录不允许 upvote,直接抛出错误。这里依赖的 context.currentUser 正是 8-authentication.md 中通过 JWT 解析并放入 context 的用户;
  2. 防重复投票:用 findUnique 按 linkId_userId 复合唯一键查询(对应 Prisma schema 中的 @@unique([linkId, userId]))。若已存在该投票,抛出 “Already voted for link” 错误,保护那些“手抖双击”的用户;
  3. 创建投票:确认不存在后,用 vote.create 创建新 Vote,并通过 connect 分别关联当前 User 与目标 Link;
  4. 发布事件:通过 PubSub 发布名为 newVote 的新事件,payload 为 { createdVote: newVote }。

注册 newVote 事件通道

与 newLink 相同,把新事件加入类型化 PubSub。更新 src/pubsub.ts:

import { Link, Vote } from "@prisma/client";
import { PubSub } from "graphql-subscriptions";
import { TypedPubSub } from "typed-graphql-subscriptions";

export type PubSubChannels = {
  newLink: [{ createdLink: Link }];
  newVote: [{ createdVote: Vote }];
};

export const pubSub = new TypedPubSub<PubSubChannels>(new PubSub());

补齐关系字段的 resolver

GraphQL schema 中新增的关系需要在 resolver 中落实:Link.votes、Vote.user、Vote.link。

先为 Link.votes 增加 resolver:

const resolvers = {
  // ... other resolvers ...
  Link: {
    // ... other resolvers ...
    votes: (parent: Link, args: {}, context: GraphQLContext) =>
      context.prisma.link.findUnique({ where: { id: parent.id } }).votes(),
  }
}

再为 Vote 类型的两个关系字段增加 resolver:

const resolvers = {
  // ... other resolvers ...
  Vote: {
    link: (parent: User, args: {}, context: GraphQLContext) =>
      context.prisma.vote.findUnique({ where: { id: parent.id } }).link(),
    user: (parent: User, args: {}, context: GraphQLContext) =>
      context.prisma.vote.findUnique({ where: { id: parent.id } }).user(),
  },
}

至此,GraphQL API 正式接受 vote mutation。

实现并测试 newVote 订阅

最后一个任务:添加在有新 Vote 创建时触发的订阅,方法与 newLink 完全类比。

第一步,在 src/schema.graphql 的 Subscription 类型中新增字段:

type Subscription {
  newLink: Link
  newVote: Vote
}

第二步,在 src/schema.ts 中添加订阅 resolver:

export const resolvers = {
  // ... other resolvers ...
  Subscription: {
    // ... other resolvers ...
    newVote: {
      subscribe: (parent: unknown, args: {}, context: GraphQLContext) => {
        return context.pubSub.asyncIterator("newVote");
      },
      resolve: (payload: PubSubChannels["newVote"][0]) => {
        return payload.createdVote;
      },
    },
  },
}

第三步,重启服务器(CTRL+C 停止后执行 npm run start),然后用以下订阅验证:

subscription {
  newVote {
    id
    link {
      url
      description
    }
    user {
      name
      email
    }
  }
}

若不确定如何手工构造触发操作,可发送示例 vote mutation(把 __LINK_ID__ 替换为数据库中真实 Link 的 id,并确保已认证):

mutation {
  vote(linkId: "__LINK_ID__") {
    link {
      url
      description
    }
    user {
      name
      email
    }
  }
}

mutation 返回 Vote 数据的同时,订阅窗口会实时收到同一条 newVote 推送,完成从数据库写入到客户端更新的闭环。

本章要点回顾

  1. 传输与契约分离:GraphQL Subscriptions 定义“可订阅的事件契约”,SSE 作为传输层负责把 AsyncIterator 产出的数据帧推送到长连接客户端;SSE 无需新端口/新服务器,实现与扩展成本低于 WebSocket。
  2. 事件总线的三个位置:src/pubsub.ts(PubSubChannels 类型 + TypedPubSub 单例)、src/context.ts(以 pubSub: typeof pubSub 注入每请求 context)、src/schema.ts(mutation 内 publish、Subscription 内 asyncIterator)。channel 字符串与 payload 类型在这三处保持一致,类型安全由 PubSubChannels 统一保证。
  3. subscribe/resolve 双层结构:subscribe 返回 AsyncIterator 建立事件监听,resolve 从 payload 中映射出字段返回值,这是订阅与 Query/Mutation resolver 的本质区别。
  4. 功能闭环依赖前置章节:vote 的鉴权依赖 8-authentication.md 的 JWT 认证;数据库访问全部经由 Prisma Client;后续 10-filtering-pagination-and-sorting.md 会继续扩展 feed 查询,全部完成后见 11-summary.md 对整个 TypeScript & GraphQL-Helix 技术栈的总结。
登录后查看全文
howtographql