★ FEATURED ARTICLE CMS后端前端【免费下载链接】webiny-jsOpen-source, self-hosted CMS platform on AWS serverless (Lambda, DynamoDB, S3). TypeScript framework with multi-tenancy, lifecycle hooks, GraphQL API, and AI-assisted development via MCP server. Built for developers at large organizations.项目地址https://gitcode.com/gh_mirrors/we/webiny-js点击查看免费下载本指南以仓库中技能目录 SKILL.md 所定义的api/event-publisher两个核心抽象DomainEvent与EventPublisher为主体结合webiny/api-core的真实源码、单元测试与十亿级场景下的事件驱动用例完整讲解 Webiny 框架如何以「事件对象自描述处理器抽象」的方式实现进程内领域事件分发。读完本文你将掌握DomainEvent的建模规则、EventPublisher的发布链路、处理器注册与解析机制并能直接在自己的业务域如 Tenant、User、Role 等中落地这一模式。一、概览Webiny 的领域事件发布抽象Webiny 是一个构建在 AWS ServerlessLambda、DynamoDB、S3之上的开源、自托管 CMS 平台其后端核心包webiny/api-core提供了一组与存储无关的领域特征feature。其中event-publisher是一个极简但设计精巧的进程内事件发布器它不依赖外部消息队列而是利用 Webiny 的依赖注入容器webiny/di将「一个领域事件」分发给「所有注册了该事件处理器抽象的实现」。根据 SKILL.md该目录共暴露2 个抽象抽象名称导入语句源码位置职责DomainEventimport { DomainEvent } from webiny/api/event-publishereventPublisher/index.ts所有领域事件的基类EventPublisherimport { EventPublisher } from webiny/api/event-publishereventPublisher/index.ts向已注册的处理器发布领域事件注意源码中的导出入口已标记为deprecated并注明「Import from webiny/api instead」即推荐统一从webiny/api导入见 api.ts 与 event-publisher.ts。按照技能目录给出的使用步骤使用该抽象时应当在下方的抽象清单中找到你需要的抽象务必阅读源码文件获取精确的接口与类型定义按导入语句引入import { Name } from importPath;结合webiny-use-case-pattern或webiny-event-handler-pattern技能实现具体用例与处理器。二、核心抽象一DomainEvent领域事件基类DomainEvent是所有领域事件的抽象基类定义于 abstractions.ts。它的职责有二承载事件数据与声明该事件应该由哪些处理器消费通过返回处理器抽象实现。import { Abstraction } from webiny/di; /** Base class for all domain events. */ export abstract class DomainEventTPayload void { public abstract readonly eventType: string; public readonly occurredAt: Date; public readonly payload: TPayload extends void ? undefined : TPayload; constructor(payload: TPayload); constructor(payload?: never) { this.occurredAt new Date(); if (payload undefined) { this.payload undefined as any; } else { this.payload payload; } } abstract getHandlerAbstraction(): AbstractionIEventHandlerany; }关键成员说明eventType必填抽象只读属性事件的字符串类型标识如tenant.beforeCreate、page.published。源码中普遍使用as const收窄为字面量类型见 events.ts。occurredAt自动生成在构造函数中自动记录new Date()表示事件发生时间无需手动传入。payload泛型约束事件携带的业务数据。当泛型参数TPayload为void时payload类型被推导为undefined否则为对应负载类型。构造函数通过payload undefined判断支持「无负载事件」与「带负载事件」两种形态。getHandlerAbstraction()必填抽象方法返回该事件对应的处理器抽象一个webiny/di的AbstractionIEventHandlerany。这是整个发布机制的关键——事件对象自己「知道」该找谁处理。事件处理器接口IEventHandler与DomainEvent配套的处理器接口同样定义在 abstractions.tsexport interface IEventHandlerTEvent extends DomainEventany DomainEventany { handle(event: TEvent): Promisevoid; }处理器只有一个异步方法handle(event)接收对应类型的事件并返回Promisevoid天然适配 Serverless 异步场景。三、核心抽象二EventPublisher事件发布器EventPublisher同时存在两种形态抽象DI 令牌与实现容器注册的具体类。3.1 抽象定义DI 令牌export interface IEventPublisher { publishTEvent extends DomainEventany(event: TEvent): Promisevoid; } /** Publish domain events to registered handlers. */ export const EventPublisher new AbstractionIEventPublisher(EventPublisher); export namespace EventPublisher { export type Interface IEventPublisher; }EventPublisher是webiny/di的AbstractionIEventPublisher实例字符串令牌名为EventPublisher。业务代码如 UseCase应依赖EventPublisher.Interface而非具体类保持面向抽象编程Webiny 代码规范之一prefer-provider-over-resolved-value。3.2 实现类发布核心逻辑实现位于 EventPublisher.ts整个发布过程仅 5 行核心逻辑export class EventPublisher implements Abstraction.Interface { constructor(private container: Container) {} async publishTEvent extends DomainEvent(event: TEvent): Promisevoid { // Get handler abstraction from the event itself const handlerAbstraction event.getHandlerAbstraction(); // Resolve ALL implementations of that abstraction const handlers this.container.resolveAll(handlerAbstraction); // Execute all handlers for (const handler of handlers) { await handler.handle(event); } } }发布调用链三步解析获取处理器抽象event.getHandlerAbstraction()从事件对象本身拿到它绑定的处理器抽象令牌解析全部实现container.resolveAll(handlerAbstraction)从 DI 容器解析出所有注册了该抽象的实现实例——这意味着一个事件可以被多个处理器同时消费一对多广播顺序执行for循环await handler.handle(event)处理器按注册顺序串行执行任一处理器抛出异常会向上传播、中断后续执行。值得注意的是这里的分发是进程内、同步完成的发布完成后所有处理器已执行完毕并非投递到消息队列异步消费。它承担的是「领域事件 → 挂载在 DI 容器上的观察者」的解耦职责适合同请求上下文内的横向扩展逻辑如发送通知、更新搜索索引、写审计日志。3.3 特性注册EventPublisherFeature为了让容器知道如何实例化EventPublisher需要注册对应的 featurefeature.tsexport const EventPublisherFeature createFeature({ name: EventPublisher, register(container: Container) { container.registerInstance(EventPublisherAbstraction, new EventPublisher(container)); } });该 feature 在ApiCoreFeature中与其他基础特性一起被注册ApiCoreFeature.ts。也就是说任何使用ApiCoreFeature的 Webiny 后端都自带EventPublisher无需额外安装——你只需关注「定义事件」与「注册处理器」。四、在业务域中使用事件发布以 Tenant 为例webiny/api-core自身就是该模式的第一批消费者。以创建租户Tenant为例完整链路为「事件定义 → 处理器抽象 → UseCase 发布 → 处理器实现注册」。4.1 定义领域事件在 CreateTenant/events.ts 中定义了创建租户的前置与后置事件export class TenantBeforeCreateEvent extends DomainEventTenantBeforeCreatePayload { eventType tenant.beforeCreate as const; getHandlerAbstraction() { return TenantBeforeCreateEventHandler; } } export class TenantAfterCreateEvent extends DomainEventTenantAfterCreatePayload { eventType tenant.afterCreate as const; getHandlerAbstraction() { return TenantAfterCreateEventHandler; } }负载类型为export interface TenantBeforeCreatePayload { tenant: Tenant; input: CreateTenantInput Recordstring, any; }4.2 声明处理器抽象处理器抽象在 CreateTenant/abstractions.ts 中通过createAbstraction声明并同时导出Interface与Event两个类型别名供处理器实现方与事件发布方分别引用/** Hook into tenant lifecycle before a tenant is created. */ export const TenantBeforeCreateEventHandler createAbstraction IEventHandlerDomainEventTenantBeforeCreatePayload (TenantBeforeCreateEventHandler); export namespace TenantBeforeCreateEventHandler { export type Interface IEventHandlerDomainEventTenantBeforeCreatePayload; export type Event DomainEventTenantBeforeCreatePayload; }4.3 在 UseCase 中发布事件CreateTenantUseCase.ts 将EventPublisher.Interface作为构造函数依赖注入在仓储写入前后分别发布事件await this.eventPublisher.publish(new TenantBeforeCreateEvent({ tenant, input: data })); // ... repository.create(tenant) ... await this.eventPublisher.publish( new TenantAfterCreateEvent({ tenant: createdTenant, input: data }) );这正是webiny-use-case-pattern中「用例负责编排领域逻辑」的体现前置事件可做校验/默认值注入后置事件可做通知、索引、审计等副作用。创建成功后返回Result.ok(createdTenant)。4.4 注册处理器实现消费方可位于同一 feature 或扩展包中通过createImplementation绑定处理器抽象与实现并注册进容器来自 EventPublisher.test.ts 的同类写法class SendNotificationHandler implements IEventHandlerPagePublishedEvent { async handle(event: PagePublishedEvent): Promisevoid { console.log(Sending notification for page: ${event.payload.title}); } } export const SendNotificationHandlerImpl createImplementation({ abstraction: PagePublishedHandler, implementation: SendNotificationHandler, dependencies: [] });注册进容器时使用container.register(Impl).inSingletonScope()。同一个事件抽象可以注册任意多个实现发布时会被resolveAll全部取到并依次执行。五、行为验证单元测试揭示的六条语义仓库为事件发布器编写了完整的单元测试EventPublisher.test.ts基于 vitest webiny/di的Container定义了PagePublished、UserRegistered、OrderPlaced三类事件及对应的通知、搜索索引、支付、库存等多组处理器。测试揭示出以下明确语义一对多广播PagePublishedEvent注册 3 个处理器后publish一次即全部执行expect(handlers).toHaveLength(3)各处理器handledEvents均为 1数据透传处理器收到的payload与发布时传入的事件数据完全一致pageId、title、publishedBy逐字段断言且eventType正确顺序执行连续发布两个事件单例处理器累计收到 2 条且handledEvents[0]为第一条保持发布顺序无处理器不报错没有任何处理器注册时publish正常 resolve 不抛错——事件发布是「尽力通知」语义无需强制至少一个消费者错误传播处理器throw new Error(Handler failed!)时publish的 Promise 被 rejectrejects.toThrow(Handler failed!)调用方必须自行决定容错策略动态注册先发布0 处理器再注册再发布第二次发布即命中新处理器——发布时的处理器集合以当前容器状态为准类型隔离不同类型事件互不干扰页面处理器只会收到page.published事件用户处理器只会收到user.registered事件。测试的 setup 方式也值得参考beforeEach中新建Container调用EventPublisherFeature.register(container)注册发布器再用container.resolve(EventPublisherAbstraction)取得实例——这与生产环境ApiCoreFeature的装配方式一致。六、导入路径与工程约定小结推荐导入import { DomainEvent, EventPublisher } from webiny/api;api.ts 集中导出旧导入路径已废弃webiny/api/event-publisherevent-publisher.ts 仅为兼容保留源码核心位置eventPublisher 目录abstractions.ts、EventPublisher.ts、feature.ts、index.ts真实业务参考CreateTenant 用例、CreateTenant 事件定义、CreateTenant 处理器抽象同类事件在仓库中的广泛应用tenancyCreate/Update/Delete/Install Tenant、securityCreate/Update/Delete ApiKey、Role、Team、usersCreate/Update/Delete User、systemInstallSystem、aiAi 特征事件等目录下均存在各自的events.ts全部复用同一DomainEvent基类可作为编写新领域事件的范式模板。七、总结何时使用与设计要点Webiny 的EventPublisher是一套零外部依赖、与 DI 容器深度集成的进程内事件总线其设计要点可归纳为事件自描述getHandlerAbstraction()让事件与处理器之间的绑定关系由事件自身声明发布器无需维护「事件类型 → 处理器」映射表容器即注册表resolveAll天然支持一个事件对应多个处理器新增消费者只需注册新的createImplementation发布端与既有处理器零改动类型安全泛型DomainEventTPayload与IEventHandlerTEvent让负载与处理器在编译期强约束时序可预期处理器串行执行、顺序确定适合校验、审计、通知等需要同请求上下文完成的工作对跨服务、跨进程的异步解耦如发邮件、同步 OpenSearch 索引Webiny 另有基于调度任务的webiny-event-handler-pattern体系配合使用。若你正在扩展 Webiny 的某个业务域参考CreateTenant的「事件 → 处理器抽象 → UseCase 发布 → 实现注册」四步法即可快速获得一套可测试、可扩展、与框架风格一致的领域事件机制。赞分享CMS后端前端【免费下载链接】webiny-jsOpen-source, self-hosted CMS platform on AWS serverless (Lambda, DynamoDB, S3). TypeScript framework with multi-tenancy, lifecycle hooks, GraphQL API, and AI-assisted development via MCP server. Built for developers at large organizations.项目地址https://gitcode.com/gh_mirrors/we/webiny-js点击查看免费下载相关推荐Webiny 领域事件发布器EventPublisher源码级解析基于 DI 抽象的事件驱动架构实战Webiny 领域事件发布器EventPublisher源码级解析基于 DI 抽象的事件驱动架构实战 导读 本文以 Webiny 开源仓库中的 eventCMS后端前端Webiny EventHandler 模式实战领域事件定义、发布与处理器实现指南Webiny EventHandler 模式实战领域事件定义、发布与处理器实现指南 本文是 Webiny 项目开源、自托管的 AWS ServerlessCMS后端前端spring-reading 源码实战深入解析 ApplicationEventPublisherAware 事件发布器注入机制spring reading 源码实战深入解析 ApplicationEventPublisherAware 事件发布器注入机制 本篇技术指南以 spring示例工程文档上一篇Mermaid Live Editor免费在线图表编辑器的终极效率革命下一篇Mermaid Live Editor代码驱动图表创作的完整高效解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
