How to GraphQL:基于 TypeScript 与 GraphQL-Helix 实现实时 GraphQL Subscriptions 完整实战
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 规范中的一类操作,允许服务器在某个特定_事件_发生时主动向客户端推送数据。需要理解两个关键点:
- Subscriptions 本身只是 GraphQL 契约(contract)的一部分,它只声明“有哪些事件可以订阅”,并不决定数据如何通过网络传输;
- 要把事件真正实时送达客户端,必须选择一个支持推送的传输层(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());
代码要点:
- 声明 TypeScript 类型
PubSubChannels,后续所有事件都要在这里登记,它是事件类型的单一事实来源; - 用
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 有两个关键差异:
- 不直接返回数据:
subscribe返回一个AsyncIterator,GraphQL 服务器用它持续向客户端推送事件数据; - 双层解析器:订阅 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;
},
}
};
分步说明(对应代码中的编号注释):
- 鉴权:未登录不允许 upvote,直接抛出错误。这里依赖的
context.currentUser正是 8-authentication.md 中通过 JWT 解析并放入 context 的用户; - 防重复投票:用
findUnique按linkId_userId复合唯一键查询(对应 Prisma schema 中的@@unique([linkId, userId]))。若已存在该投票,抛出 “Already voted for link” 错误,保护那些“手抖双击”的用户; - 创建投票:确认不存在后,用
vote.create创建新Vote,并通过connect分别关联当前User与目标Link; - 发布事件:通过 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 推送,完成从数据库写入到客户端更新的闭环。
本章要点回顾
- 传输与契约分离:GraphQL Subscriptions 定义“可订阅的事件契约”,SSE 作为传输层负责把
AsyncIterator产出的数据帧推送到长连接客户端;SSE 无需新端口/新服务器,实现与扩展成本低于 WebSocket。 - 事件总线的三个位置:
src/pubsub.ts(PubSubChannels类型 +TypedPubSub单例)、src/context.ts(以pubSub: typeof pubSub注入每请求 context)、src/schema.ts(mutation 内publish、Subscription 内asyncIterator)。channel 字符串与 payload 类型在这三处保持一致,类型安全由PubSubChannels统一保证。 subscribe/resolve双层结构:subscribe返回AsyncIterator建立事件监听,resolve从 payload 中映射出字段返回值,这是订阅与 Query/Mutation resolver 的本质区别。- 功能闭环依赖前置章节:
vote的鉴权依赖 8-authentication.md 的 JWT 认证;数据库访问全部经由 Prisma Client;后续 10-filtering-pagination-and-sorting.md 会继续扩展feed查询,全部完成后见 11-summary.md 对整个 TypeScript & GraphQL-Helix 技术栈的总结。