Medusa core-flows 工作流与步骤 TSDoc 编写规范:从 createWorkflow 到 createStep 的文档化实战指南

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

Medusa core-flows 工作流与步骤 TSDoc 编写规范:从 createWorkflow 到 createStep 的文档化实战指南

导读

在 Medusa 开源仓库中,packages/core/core-flows/ 承载了平台最核心的业务编排逻辑:所有面向 API 路由的业务操作(创建购物车、下订单、管理库存等)都以 Workflow(工作流) 与 Step(步骤) 的形式实现,并通过 createWorkflow(...) 与 createStep(...) 两个工厂函数定义。本文以仓库内 .claude/skills/writing-tsdocs/reference/workflows-steps.md 为骨架,系统讲解这些核心流程的 TSDoc 注释编写规范——包括工作流与步骤各自的注释结构、@example/@summary/@property hooks.*/@since/@featureFlag 等标签的用法、输入类型接口的文档化,以及哪些内容明确不应该写进 TSDoc。读完本文,你将能够在 Medusa 仓库中为任意 core-flows 工作流或步骤写出符合官方规范、可被生成器与 LLM 正确解析的高质量文档注释。

一、背景:core-flows 的文档对象与文件组织

Workflow 与 Step 文件统一存放在 packages/core/core-flows/src/ 目录下。以购物车(cart)域为例,源码结构清晰分成了两条并行的目录:

  • packages/core/core-flows/src/cart/workflows/:存放工作流定义文件,如 update-cart.ts、add-to-cart.ts、complete-cart.ts 等;
  • packages/core/core-flows/src/cart/steps/:存放步骤定义文件,如 validate-cart.ts、create-carts.ts、retrieve-cart.ts 等。

从源码看,这一组织方式与文档规范高度一致:工作流由 createWorkflow(...) 创建,步骤由 createStep(...) 创建。两个工厂函数的签名都定义在 packages/core/workflows-sdk/src/utils/composer/ 目录下:

  • create-workflow.ts 中的 createWorkflow 接受工作流名称(或配置对象)与一个 composer 构造函数,返回可被后续 .run() 执行的工作流对象;
  • create-step.ts 中的 createStep 接受步骤名称、invoke 函数与可选的 compensate(补偿)函数,返回可在工作流内调用的步骤函数。

编写 TSDoc 时,文档对象就是这两个文件中导出的 const 变量。理解底层工厂的调用语义(例如 StepResponse 第一参数是步骤输出、第二参数是传给补偿函数的数据),才能写出与真实行为吻合的注释。

二、工作流(Workflow)的 TSDoc 编写规范

2.1 必须覆盖的注释要素

文档规范要求,为导出的工作流 const 编写注释时必须包含以下要素:

  1. 描述段落:说明该工作流做什么、在什么场景下被使用;
  2. API 路由链接(如适用):链接到执行该工作流的 API 路由;
  3. @example:演示如何调用 .run();
  4. @summary:一行话总结工作流功能;
  5. @property hooks.*:为工作流暴露的每个 hook 写一条条目;
  6. @since:若该工作流是新增的,注明版本号(来自需求上下文);
  7. @featureFlag:若该工作流处于某个特性开关(feature flag)之后,注明开关名。

其中 @summary 与 @property hooks.* 的职责是互补的:@summary 提供最精简的一句话摘要,供索引与检索;@property hooks.* 则逐个说明 hook 的触发时机与可定制的行为,供开发者了解如何在自定义逻辑中挂接钩子。

2.2 工作流标准模板

规范给出了可直接套用的标准模板:

export const myWorkflowId = "my-workflow"
/**
 * This workflow [does X]. It's executed by the
 * [Some API Route](https://docs.medusajs.com/api/admin#resource_postresourceid).
 *
 * You can use this workflow within your own customizations or custom workflows,
 * allowing you to wrap custom logic around [the operation].
 *
 * @example
 * const { result } = await myWorkflow(container)
 *   .run({
 *     input: {
 *       id: "foo_123",
 *     },
 *   })
 *
 * @summary
 *
 * [One-line summary of what the workflow does.]
 *
 * @property hooks.myHook - This hook is called [when/before/after X]. You can
 * use it to [describe what customization is possible].
 */
export const myWorkflow = createWorkflow(myWorkflowId, (input) => {

要点拆解:

  • @example 中调用工作流的方式与 createWorkflow 源码 的返回语义完全一致:createWorkflow 返回的是 ReturnWorkflow 类型,并非立即执行,必须先以容器(container)调用一次得到可运行实例,再调用其 .run({ input }) 方法;.run() 返回的 result 即为工作流输出。
  • 描述段落中"you can use this workflow within your own customizations or custom workflows"这句标准表述,点明了 core-flows 工作流对外部定制者开放的两类使用方式:在自定义工作流中作为子流程调用,或在自定义逻辑中包裹原操作。
  • @property hooks.* 的条目应说明 hook 的触发时机(when/before/after)与可实现的定制点(customization)。

2.3 带 @featureFlag 与 @since 的工作流

对于新增且被特性开关保护的工作流,规范给出了精简写法。以"创建视图配置"工作流为例:

/**
 * This workflow creates a view configuration.
 *
 * @since 2.10.3
 * @featureFlag view_configurations
 *
 * @example
 * const { result } = await createViewConfigurationWorkflow(container)
 *   .run({ input: { ... } })
 *
 * @summary
 *
 * Create a view configuration.
 */
export const createViewConfigurationWorkflow = createWorkflow(...)

注意这里的两个约定:

  • @since 标注工作流首次引入的版本(2.10.3),便于文档使用者判断自己使用的 Medusa 版本是否包含该能力;
  • @featureFlag 标注特性开关名称(view_configurations),提醒使用者必须启用对应开关才能使用该工作流。

即便带有 @featureFlag/@since,功能描述与 @example 依然保留,保证文档的完整性。

2.4 用 @property hooks.* 逐个文档化工作流钩子

工作流通过 createHook 暴露钩子后,必须为每个 hooks.* 上的钩子写一条 @property 条目,说明其运行时机与用途。规范给出的示例:

 * @property hooks.validate - This hook is called before all operations. You can
 * use it to validate the input or perform any custom validation logic.
 *
 * @property hooks.setPricingContext - This hook is called after the cart is
 * retrieved. You can use it to pass custom pricing context to the workflow.

仓库中真实的钩子文档案例可以佐证这一写法。在 add-to-cart.ts 中,validate 钩子被描述为"在所有操作之前执行,可用来做任何自定义校验,抛错即可终止工作流",setPricingContext 钩子被描述为"在购物车检索之后、创建行项目之前执行,可返回自定义定价上下文";紧随其后还给出了一个自定义定价规则(如按 location_id 等于 sloc_123 过滤)如何使用该钩子向价格计算注入 location_id 上下文的 JSON 示例。这种"钩子条目 + 具体用例"的组合正是规范推荐的深度文档化方式。

三、步骤(Step)的 TSDoc 编写规范

3.1 必须覆盖的注释要素

为导出的步骤 const 编写注释时,规范要求包含:

  1. 功能描述:该步骤做什么,以及在什么条件下抛出错误/返回什么;
  2. @example:演示如何调用该步骤;
  3. @since:若为新增步骤,注明版本号;
  4. @featureFlag:若受特性开关保护,注明开关名。

此外,步骤的输入类型接口也必须逐属性编写描述——这是步骤文档与工作流文档的一个显著差异:步骤的输入 interface 本身就是公开 API 的一部分,直接影响使用者在自定义工作流中如何调用该步骤。

3.2 步骤标准模板

export const myStepId = "my-step"
/**
 * This step [does X]. If [condition], the step throws an error.
 *
 * @example
 * const data = myStep({
 *   id: "foo_123",
 * })
 */
export const myStep = createStep(
  myStepId,
  async (data: MyStepInput, { container }) => {

模板强调两点:

  • 描述段落中除了说明步骤做什么,还要显式声明抛出条件("If [condition], the step throws an error")。这与 createStep 源码 的语义吻合:invoke 函数执行时可以主动抛错,从而触发工作流的补偿逻辑。
  • @example 展示的是步骤作为普通函数被直接调用的形态——这反映了步骤的可复用性:步骤函数本身是 StepFunction,既能在工作流 composer 中被调用,也能在自定义代码中独立执行。

3.3 步骤输入类型的文档化与 {@link} 交叉引用

步骤的输入类型接口需要为每个属性编写描述:

/**
 * The input for the {@link validateCartStep}.
 */
export interface ValidateCartStepInput {
  /**
   * The cart to validate.
   */
  cart: CartWorkflowDTO | CartDTO
}

这里有两个核心约定:

  • 接口的 TSDoc 描述中使用 {@link stepName} 语法交叉引用相关步骤,例如上面的 {@link validateCartStep}。{@link} 会让文档生成器与 IDE 建立步骤与输入类型之间的双向跳转关系,大幅提升文档的可导航性;
  • 接口注释应说明该输入在流程中的语义("The cart to validate"),而非机械复述类型名。

3.4 带 @featureFlag 与 @since 的步骤

规范明确区分了两种情形:

  • 简单场景:当步骤只需标注开关与版本、无需完整描述时,使用最精简写法:
export const createViewConfigurationStepId = "create-view-configuration"
/**
 * @since 2.10.3
 * @featureFlag view_configurations
 */
export const createViewConfigurationStep = createStep(...)
  • 复杂或高频使用场景:即便带有 @featureFlag/@since,仍应补全完整描述与 @example,确保文档信息密度不因开关标注而缩水。

这一区分本质上是文档成本与收益的权衡:简单步骤保留一行标注即可,重要步骤则必须完整文档化。

3.5 真实步骤案例:update-cart 中的 prepareCartToUpdateStep

仓库中的 prepareCartToUpdateStep 是规范"描述 + 抛出条件"写法的真实范例:

/**
 * This step builds the cart update payload: it resolves the currency and region
 * from the (possibly new) region, reconciles the shipping address against the
 * region's countries, and applies customer and sales channel changes. It throws
 * an error if the shipping address country isn't within the region.
 */
export const prepareCartToUpdateStep = createStep(
  "prepare-cart-to-update",
  async (data: PrepareCartToUpdateStepInput) => {

这段注释完整遵循了步骤文档规范:第一句概括步骤职责(构建购物车更新载荷),随后展开具体行为(从新 region 解析货币与区域、将配送地址与区域国家列表对齐、应用客户与销售渠道变更),最后用 "It throws an error if..." 明确声明抛出条件。对照实现(update-cart.ts),当 shipping_address.country_code 不在 region 的 countries 列表中时,步骤确实抛出 MedusaError.Types.INVALID_DATA,注释与实现严格对应。

四、明确不写入 TSDoc 的内容(What NOT to Document)

规范对"哪些内容不需要文档"给出了三条边界,防止文档噪音:

  1. *Id 字符串常量:例如 export const addToCartWorkflowId = "add-to-cart",这类 ID 常量不需要任何 TSDoc。它们是内部标识符,文档化反而会分散注意力;
  2. 模块内部未导出的辅助函数:仅在模块内部使用、未从模块导出的 helper 函数不属于公开 API,无需 TSDoc;
  3. 补偿函数(compensation functions):即 createStep 的第三个参数。尽管它是步骤的重要组成(负责在错误发生时回滚操作),但规范将其视为内部实现细节,明确不写入 TSDoc。

从 createStep 源码 可以看到,补偿函数接收 invoke 函数通过 StepResponse 第二参数传入的数据,用于撤销已执行的操作;它确实是支撑工作流"分布式事务回滚"语义的关键机制,但文档层面刻意将其隐藏,只通过 invoke 函数的描述间接呈现。

这三点边界背后的原则是:TSDoc 只面向公开 API 与开发者需要知道的使用语义,内部实现细节一律交给源码本身。遵循该原则能显著降低文档维护成本,同时避免误导使用者依赖内部行为。

五、将规范落地到仓库的实践建议

结合上文规范与源码,在实际为 core-flows 编写 TSDoc 时可遵循以下清单自检:

  1. 定位文件:确认文档对象位于 packages/core/core-flows/src/<domain>/workflows/ 或 .../steps/ 下,且是从模块导出的 const;
  2. 区分对象类型:工作流文档必须含 API 路由链接、@summary 与全部 @property hooks.*;步骤文档必须含抛出条件描述与输入类型逐属性说明;
  3. 验证 @example 可运行性:工作流的 @example 应严格采用 await myWorkflow(container).run({ input: { ... } }) 形态;步骤的 @example 采用直接调用形态;
  4. 正确处理版本与开关:新增对象标注 @since,受开关保护的对象标注 @featureFlag,二者可共存;
  5. 交叉引用:步骤输入类型描述中优先使用 {@link stepName} 建立跳转关系;
  6. 遵守否定清单:*Id 常量、内部辅助函数、补偿函数一律不写 TSDoc。

按此清单产出的注释,既符合 Medusa 官方生成规范,也能被 IDE 提示、API 文档生成器、搜索引擎与 LLM 准确索引与引用——这正是本文所依托的 .claude/skills/writing-tsdocs/reference/workflows-steps.md 想达成的核心目标:让 core-flows 里数百个工作流与步骤,每一份公开文档都准确、一致、可执行。

登录后查看全文
medusa