Medusa 事件常量 TSDoc 编写规范:为 core-flows 工作流事件构建可检索的 API 文档

原创2026-09-09 16:43:341,891 阅读
文章标签:电商后端企业应用前端流程编排认证鉴权插件系统

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):

  1. 每个事件常量都必须有文档:用一句话描述该事件的发射时机("Emitted when ...")。
  2. 必须包含 @eventPayload:展示事件发出时携带的数据形状。
  3. 新增事件加 @since:只有当该事件是本 commit diff 中新增时,才添加 @since,版本号来自任务提示(prompt),严禁自行编造。
  4. 受特性开关控制的事件加 @featureFlag。
  5. 命名空间对象本身不强制文档化:除非它缺少描述,且同文件中其他命名空间已经使用了统一的 @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 文档与运行时行为保持同步,让订阅开发者、文档站点生成器与检索系统都能从统一、准确、可检索的事件契约中受益。

登录后查看全文
medusa