Medusa 事件常量 TSDoc 编写规范:为 core-flows 工作流事件构建可检索的 API 文档
Medusa 事件常量 TSDoc 编写规范:为 core-flows 工作流事件构建可检索的 API 文档
本文是 Medusa 开源仓库中 writing-tsdocs 技能体系的事件专项参考指南,围绕 .claude/skills/writing-tsdocs/reference/events.md 展开。它面向需要在 packages/core/utils/src/core-flows/events.ts 中维护事件常量文档的贡献者,讲解事件常量的 TSDoc 组织方式、@eventPayload、@since、@featureFlag 等自定义标签的用法与完整实战示例。读完本文,你将掌握为 Medusa 事件常量编写符合 TypeDoc 输出要求的规范注释,并理解这些注释如何与工作流中的 emitEventStep 发射逻辑形成对应关系。
事件常量在哪里:core-flows 事件中心
Medusa 的 core-flows(核心工作流)在工作流执行过程中会向外发射领域事件,例如购物车创建、订单下达、履约生成等。这些事件的事件名常量并不散落在各个工作流文件中,而是统一收敛在 packages/core/utils/src/core-flows/events.ts(全文约 1300 行),以"命名空间对象(namespace object)"的形式分组导出:
CartWorkflowEvents—— 购物车相关事件OrderWorkflowEvents/OrderEditWorkflowEvents—— 订单与订单编辑事件CustomerWorkflowEvents、UserWorkflowEvents、AuthWorkflowEvents—— 用户与认证事件ProductWorkflowEvents、ProductVariantWorkflowEvents、ProductCategoryWorkflowEvents等 —— 商品域事件SalesChannelWorkflowEvents、RegionWorkflowEvents、FulfillmentWorkflowEvents、ShippingOptionWorkflowEvents—— 渠道、区域、履约与配送事件PaymentEvents、InventoryItemWorkflowEvents、InventoryLevelWorkflowEvents、ReservationItemWorkflowEvents—— 支付与库存事件TranslationWorkflowEvents—— 翻译事件(特性开关控制)
每个命名空间都是 as const 导出的常量对象,其成员即事件常量,例如:
export const CartWorkflowEvents = {
CREATED: "cart.created",
UPDATED: "cart.updated",
} as const
事件常量本身是字符串字面量(如 "cart.created"),工作流通过 emitEventStep 步骤引用它们完成发射;而 TSDoc 注释则负责描述"事件在什么时机发出、载荷长什么样",二者共同构成事件的完整契约。
事件 TSDoc 的核心规则
为事件常量编写 TSDoc 时,需要遵守以下规则(源自 .claude/skills/writing-tsdocs/reference/events.md):
- 每个事件常量都必须有文档:用一句话描述该事件的发射时机("Emitted when ...")。
- 必须包含
@eventPayload:展示事件发出时携带的数据形状。 - 新增事件加
@since:只有当该事件是本 commit diff 中新增时,才添加@since,版本号来自任务提示(prompt),严禁自行编造。 - 受特性开关控制的事件加
@featureFlag。 - 命名空间对象本身不强制文档化:除非它缺少描述,且同文件中其他命名空间已经使用了统一的
@customNamespace+@category模式,才为它补上;不要给原本没有该模式的文件强行引入。
此外,整个 writing-tsdocs 技能还有两条总约束(见 .claude/skills/writing-tsdocs/SKILL.md):只给 export 导出的项写文档,绝不修改现有 TSDoc 与业务逻辑——写注释是"只增不改"的操作。
事件常量基础格式
事件常量的 TSDoc 块遵循固定的三段式结构:描述、@eventPayload、可选的版本与特性标签:
/**
* Emitted when [resource] is [action].
*
* @eventPayload
* ```ts
* {
* id, // The ID of the [resource]
* }
* ```
*/
CREATED: "resource.created",
落在真实源码中,CartWorkflowEvents 的第一个成员即完全对应此格式(见 events.ts):
export const CartWorkflowEvents = {
/**
* Emitted when a cart is created.
*
* @eventPayload
* ```ts
* {
* id, // The ID of the cart
* }
* ```
*/
CREATED: "cart.created",
} as const
事件名的措辞建议与事件字符串一一呼应:常量名 CREATED、事件名 "cart.created"、描述 "Emitted when a cart is created",三者在语义上保持一致,方便检索与理解。
@eventPayload:精确描述事件载荷
@eventPayload 是事件 TSDoc 中最具信息量的部分,它使用一个 TypeScript 代码块逐行列出事件发射时携带的属性,每个属性后面跟一个内联注释说明含义:
/**
* Emitted when the customer in the cart is transferred.
*
* @eventPayload
* ```ts
* {
* id, // The ID of the cart
* customer_id, // The ID of the customer
* }
* ```
*/
CUSTOMER_TRANSFERRED: "cart.customer_transferred",
当载荷中包含非字符串字段时,必须在行内注释中用括号标注其类型,例如 (boolean)、(number)、(array)、(object)、(Date);对于普通的字符串 ID,则省略类型标注。下面的 order.fulfillment_created 事件是一个典型的多字段、混合类型载荷:
/**
* Emitted when an order's fulfillment is created.
*
* @eventPayload
* ```ts
* {
* order_id, // The ID of the order
* fulfillment_id, // The ID of the fulfillment
* no_notification, // (boolean) Whether to notify the customer
* }
* ```
*/
FULFILLMENT_CREATED: "order.fulfillment_created",
在 events.ts 中,OrderWorkflowEvents.FULFILLMENT_CREATED 的注释与上述示例完全一致,可直接对照学习。
@since:标注新增事件的版本
当事件是当前提交中新增时,添加 @since 标签记录引入版本。版本号只能来自任务提示,不能自行猜测。放置顺序上,@since 应位于 @eventPayload 之前,让版本信息优先呈现:
/**
* Emitted when a translation is created.
*
* @since 2.14.0
*
* @eventPayload
* ```ts
* {
* id, // The ID of the translation
* }
* ```
*/
TRANSLATIONS_CREATED: "translations.created",
仓库中已有大量 @since 实例,覆盖了多个版本区间:cart.customer_transferred 标注 @since 2.8.0、shipping-option.created 标注 @since 2.12.4、translation.created 标注 @since 2.12.3、inventory-item.created 与 inventory-level.created 标注 @since 2.18.0、product-option-value.updated 标注 @since 2.20.0。当某个事件在后续版本发生载荷变化时,描述中也会补充迁移说明,例如 events.ts 中 auth.verification_requested 的注释详细说明了 v2.17.0 起的载荷字段变更(移除 actor_type、provider_identity_id,重命名 provider 为 code_provider,新增 entity_type),并提示旧订阅者必须更新。这种"版本演进说明"同样是高质量事件文档的一部分。
@featureFlag:标注特性开关控制的事件
有些事件只有在启用某个特性开关(feature flag)后才会发射,此时需要在 TSDoc 中追加 @featureFlag,并紧跟开关名称。它与 @since 组合使用时,@since 在前、@featureFlag 在后:
/**
* Emitted when a translation is created.
*
* @since 2.14.0
* @featureFlag translation
*
* @eventPayload
* ```ts
* {
* id, // The ID of the translation
* }
* ```
*/
TRANSLATIONS_CREATED: "translations.created",
仓库中的实际案例即 events.ts 的 TranslationWorkflowEvents:translation.created、translation.updated、translation.deleted 三个事件均同时携带 @since 2.12.3 与 @featureFlag translation。@featureFlag 与 @since、@eventPayload、@customNamespace 等均为 Medusa 在 www/utils/packages/typedoc-config/tsdoc.json 中注册的 TSDoc 自定义标签(该文件基于 typedoc/tsdoc.json 扩展,共定义了十余个项目专用标签),它们会被 TypeDoc 生成管线识别并在 API 文档中渲染。
命名空间对象的文档化
命名空间对象(如 CartWorkflowEvents 本身)默认不需要文档——文档的焦点是事件常量。唯一的例外是:当命名空间对象自身缺少描述、且同文件中的其他命名空间已经统一使用了 @customNamespace 与 @category 模式时,才为它补充:
/**
* @category Cart
* @customNamespace Cart
*/
export const CartWorkflowEvents = {
从源码看,这一模式已在 events.ts 中被一致使用:CartWorkflowEvents 标注 @category Cart,CustomerWorkflowEvents 标注 @category Customer,而多个商品子域命名空间共享 @category Product,多个配送子域共享 @category Fulfillment。@category 负责在文档站中归类,@customNamespace 则把事件常量归入自定义命名空间展示。遵循"仅在同文件已有该模式时才引入"的约束,可以保证整个文件风格的统一,避免某些命名空间被意外暴露为独立页面。
完整 Before / After 示例
把上述所有规则落在一个完整案例上,改造前后对比如下。
Before —— 无任何注释:
export const OrderWorkflowEvents = {
PLACED: "order.placed",
CANCELED: "order.canceled",
COMPLETED: "order.completed",
}
After —— 每个事件常量都补齐 TSDoc:
export const OrderWorkflowEvents = {
/**
* Emitted when an order is placed.
*
* @eventPayload
* ```ts
* {
* id, // The ID of the order
* }
* ```
*/
PLACED: "order.placed",
/**
* Emitted when an order is cancelled.
*
* @eventPayload
* ```ts
* {
* id, // The ID of the order
* }
* ```
*/
CANCELED: "order.canceled",
/**
* Emitted when an order is completed.
*
* @eventPayload
* ```ts
* {
* id, // The ID of the order
* }
* ```
*/
COMPLETED: "order.completed",
}
对照 events.ts 中的真实实现可以看到,OrderWorkflowEvents 除上述三事件外,还包含 UPDATED、ARCHIVED、FULFILLMENT_CREATED、FULFILLMENT_CANCELED、RETURN_REQUESTED、RETURN_RECEIVED、CLAIM_CREATED、EXCHANGE_CREATED、TRANSFER_REQUESTED 等事件,全部遵循同一注释模式。
从注释到运行时:事件如何被发射
事件文档并非纸上谈兵——事件常量会直接出现在工作流代码中。以购物车创建为例,packages/core/core-flows/src/cart/workflows/create-carts.ts 中 createCartsWorkflow 通过 parallelize 并行执行支付集合刷新与事件发射:
parallelize(
refreshPaymentCollectionForCartWorkflow.runAsStep({
input: {
cart: cart,
},
}),
emitEventStep({
eventName: CartWorkflowEvents.CREATED,
data: { id: cart.id },
})
)
这里 emitEventStep 的 eventName 直接引用 CartWorkflowEvents.CREATED,data 传入 { id: cart.id } —— 与 TSDoc 中 @eventPayload 声明的载荷形状严格一致。整个 core-flows 包内 emitEventStep 被大量工作流复用(如 generate-reset-password-token.ts、request-verification.ts、add-shipping-method-to-cart.ts 等),因此一份准确的 @eventPayload 注释,本质上就是对该步骤发射数据的契约声明,读者可以通过它准确判断订阅回调中能拿到哪些字段。
提交前的自检清单
结合 .claude/skills/writing-tsdocs/SKILL.md 中列出的常见错误,为事件常量补齐 TSDoc 后应逐项检查:
- [ ] 每个导出的事件常量都已有描述,且以 "Emitted when ..." 说明发射时机;
- [ ] 每个事件都包含
@eventPayload,载荷字段与emitEventStep的实际data一致; - [ ] 非字符串字段已在行内注释中用
(type)标注,字符串 ID 不标注; - [ ]
@since版本号仅使用任务提示提供的版本,未自行编造; - [ ] 受特性开关控制的事件已添加
@featureFlag; - [ ] 未给未导出的项、测试文件中的项添加文档;
- [ ] 未修改任何现有 TSDoc 与业务逻辑,只做"只增不改"的注释补充;
- [ ] 属性描述保持在 2 句话以内,不堆砌冗长解释。
遵循本指南维护 packages/core/utils/src/core-flows/events.ts,就能保证 Medusa 事件 API 文档与运行时行为保持同步,让订阅开发者、文档站点生成器与检索系统都能从统一、准确、可检索的事件契约中受益。