Novu 群发实战:使用 Topic 向订阅者组批量触发工作流通知

原创2026-09-09 21:58:271,885 阅读
文章标签:后端消息路由工作流自动化前端WebSocketMCP 服务微服务

Novu 群发实战:使用 Topic 向订阅者组批量触发工作流通知

Topic 是 Novu 提供的"订阅者分组"机制:先把一批订阅者按业务语义(如"项目 Alpha 的关注者""工程团队")归入一个带唯一 key 的 Topic,之后只需向这个 Topic 触发一次事件,所有成员就会各自收到通知。本文以 Novu 官方示例 topic-trigger-examples.md 为骨架,结合仓库内 Topic 控制器、事件触发解析与 e2e 测试源码,完整演示 Topic 的创建、订阅者添加、单 Topic 触发、多 Topic 触发及 cURL 调用,并解释 fan-out 与去重等底层行为,读完后你可以直接在自己的业务中实现"一次触发、全员通知"的群发方案。

Topic 是什么:为群发而生的订阅者分组

在日常业务中,很多通知并不是发给单个订阅者,而是发给"一群人":一个开源项目的 watcher、一个公司的全体员工、某个版本的灰度用户群。Novu 的 Topic 正是为这类场景设计的一等公民抽象——它是一个有名字、有唯一 key 的订阅者集合:

  • 创建 Topic:只需提供 key(唯一标识,用于后续触发)和 name(可读名称);
  • 添加订阅者:把 subscriberId 加入该 Topic;
  • 触发通知:向 to 传入 { type: "Topic", topicKey },Novu 会自动把消息扇出(fan out)给 Topic 内的每一个订阅者。

从仓库源码看,Novu 对 Topic 的 REST 支持分为两代实现。当前推荐使用的是 v2 接口,控制器定义在 topics.controller.ts,路由为 /topics(version 2),提供创建/查询/更新/删除 Topic 及订阅关系管理的完整 CRUD;早期 v1 实现则保留在 topics-v1.controller.ts。本文 SDK 示例走的是官方 @novu/api 客户端封装,最终都会落到这些 REST 接口上。

创建 Topic 并添加订阅者

官方示例首先演示了最基础的两步:创建 Topic,然后把订阅者加进去。

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY,
});

// Create a topic
await novu.topics.create({
  key: "project-alpha-watchers",
  name: "Project Alpha Watchers",
});

// Add subscribers to the topic
await novu.topics.subscriptions.create(
  { subscriptions: ["user-1", "user-2", "user-3"] },
  "project-alpha-watchers"
);

几个值得展开的细节

1. key 是触发时的寻址依据,name 只是展示名。 在 v2 控制器中,POST /v2/topics 对应的 UpsertTopicCommand 会携带 key、name、data 和 failIfExists 四个字段(见 topics.controller.ts)。其中 key 是触发阶段 topicKey 必须匹配的标识,name 仅用于在控制台/列表中人类可读,data 是可选的自定义元数据。

2. v2 的创建是"幂等 upsert"语义。 接口文档明确说明:POST /v2/topics 在 Topic 不存在时创建,已存在时则更新(见控制器上的 ApiOperation 描述,topics.controller.ts)。如果你希望"已存在则报错",可以追加查询参数 ?failIfExists=true,此时若 key 冲突会返回 409。该能力由 upsert-topic.usecase.ts 实现。

3. 添加订阅者的入参更灵活。 topics.subscriptions.create 的第一个参数既可以是字符串数组(如上例,直接传 subscriberId),也支持对象数组 { identifier, subscriberId, name? }。控制器在 mapSubscriptions 中对字符串形式做了归一化。响应体包含 data(成功创建的订阅)、meta(成功/失败计数)与 errors(失败明细);若所有订阅均失败,接口会返回 400(topics.controller.ts),因此建议对响应中的 meta.failed 做防御性处理。

4. 一个订阅者可以同时属于多个 Topic。 订阅关系是独立存储的,同一 subscriberId 加入多个 Topic 互不影响,这为下文"一个用户同时命中多个群组"的触发场景提供了数据基础。

触发到单个 Topic:一次触发,全员通知

创建好 Topic 并加入订阅者后,触发通知的方式与普通触发几乎一致,区别仅在 to 字段:

const result = await novu.trigger({
  workflowId: "project-update",
  to: {
    type: "Topic",
    topicKey: "project-alpha-watchers",
  },
  payload: {
    projectName: "Alpha",
    update: "New release v2.0 deployed",
  },
});

to 从"单个订阅者标识"换成了 { type: "Topic", topicKey },Novu 服务端会解析出该 Topic 下的全部订阅者,并为每个订阅者独立生成一份通知(各自拥有独立的 transaction 与消息记录)。

这一点在仓库的 e2e 测试中得到直接印证:trigger-event-topic.e2e.ts 中,先创建 Topic topic-key-trigger-event 并加入两名订阅者,再以 [{ type: TriggerRecipientsTypeEnum.Topic, topicKey: createdTopicDto.key }] 触发(L62),断言响应 status === "processed"、acknowledged === true 且 transactionId 存在。后续用例进一步按订阅者逐一查询,验证每个订阅者都生成了一条通知记录(L1169-L1176)——这就是"扇出到所有订阅成员"的服务端行为。

在服务端接收端,事件触发请求的 to 会进入 parse-event-request.usecase.ts 的 parseRecipients 流程(L572-L593)做合法性校验:单个 to 或 to 数组均会被验证,其中携带 topicKey 的对象是合法的接收者类型之一(L563),且该 topicKey 需匹配 SUBSCRIBER_ID_REGEX 约束。

触发到多个 Topic:一次请求,命中多群组

通知目标并不限定为单个 Topic。你可以在一次 trigger 中同时指定多个 Topic,甚至混合 Topic 与单个订阅者:

const result = await novu.trigger({
  workflowId: "company-announcement",
  to: [
    { type: "Topic", topicKey: "engineering-team" },
    { type: "Topic", topicKey: "product-team" },
  ],
  payload: {
    announcement: "Company all-hands at 3pm",
  },
});

混合接收者的真实验证

仓库 e2e 对"多个 Topic + 多个订阅者"组合进行了完整覆盖:trigger-event-topic.e2e.ts 构造了 to = [Topic1, Topic2, subscriberId, {subscriberId, firstName, lastName, email}] 的混合数组——两个 Topic 各含 2 名订阅者,另加 2 个直接订阅者,共 6 个去重后的接收者。断言最终消息总数为 12(L1144-L1149),即 6 个订阅者 × 工作流中的 2 个步骤,说明:

  • 多个 Topic 的成员会被合并展开;
  • Topic 成员与直接指定的订阅者可以共存于同一个 to 数组;
  • 服务端按"接收者 × 工作流步骤"正确生成消息,没有遗漏也没有多余。

另外,测试中还向 to 追加了一个不存在的 topic key 再触发(L1132),请求依然返回 status: "processed"、acknowledged: true,且消息总数不变——这说明不存在的 Topic 不会阻塞整个触发流程(建议仍以 meta/errors 或业务日志确认异常订阅)。

使用 cURL 直接调用 REST API

不依赖 SDK 时,可以直接调用 Novu 的 REST 接口。官方示例使用的是事件触发端点 /v1/events/trigger:

curl -X POST https://api.novu.co/v1/events/trigger \
  -H "Authorization: ApiKey $NOVU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-update",
    "to": {
      "type": "Topic",
      "topicKey": "project-alpha-watchers"
    },
    "payload": {
      "projectName": "Alpha",
      "update": "New release v2.0 deployed"
    }
  }'

要点说明:

  • 请求体中的 name 对应 SDK 里的 workflowId,即工作流的外部标识;
  • to 与 SDK 写法完全一致,可以是单个 { type: "Topic", topicKey } 对象,也可以是数组(多 Topic、或 Topic 与订阅者混合);
  • payload 会透传给工作流步骤模板中的变量;
  • Topic 的管理接口(创建、添加订阅者等)在 v2 路径下,如 POST /v2/topics、POST /v2/topics/:topicKey/subscriptions,对应 OpenAPI 定义见 create-a-topic.mdx;完整接口清单可参考 docs/api-reference/topics 目录下的各端点文档。

Important Notes:四条关键行为约定

原文档以四条注意事项收尾,它们直接决定了使用 Topic 的正确姿势,这里结合源码逐条展开:

  1. Topics 必须先创建,再触发。 topicKey 是触发时的寻址标识,服务端在触发解析阶段按 key 查找订阅关系。因此生产代码中请确保"创建 Topic + 添加订阅者"先于任何 trigger 执行,或在触发前对 Topic 是否存在做显式检查。

  2. 一个订阅者可以属于多个 Topic。 订阅关系按"Topic × 订阅者"独立存储,同一用户加入"工程团队"和"产品团队"两个 Topic 完全合法。这正是多 Topic 触发、以及按兴趣/角色分组发送通知的基础。

  3. Topic 触发会对所有订阅成员逐个扇出通知。 每个订阅者获得独立的消息实体与执行链路(如上面的 e2e 断言所示),因此一条 Topic 触发在活动流(Activity Feed)中会呈现为多条独立发送记录,便于按订阅者维度追踪送达状态。

  4. 同一触发请求中跨 Topic 的重复订阅者会被自动去重。 例如用户 A 同时属于 engineering-team 和 product-team,在一次 company-announcement 触发中,A 只会收到一份通知而不是两份。这一保证由服务端在展开接收者时统一去重,用户无需在业务侧处理"一人多群组"的重复投递问题。

进一步探索

掌握了 Topic 的创建、订阅与触发三板斧,你就可以把"逐个遍历订阅者触发"的循环逻辑,替换成一句 trigger + 一个 topicKey,让 Novu 替你完成群发扇出与跨群组去重。

登录后查看全文
novu