Medusa core-flows 工作流与步骤 TSDoc 编写规范:从 createWorkflow 到 createStep 的文档化实战指南
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 编写注释时必须包含以下要素:
- 描述段落:说明该工作流做什么、在什么场景下被使用;
- API 路由链接(如适用):链接到执行该工作流的 API 路由;
@example:演示如何调用.run();@summary:一行话总结工作流功能;@property hooks.*:为工作流暴露的每个 hook 写一条条目;@since:若该工作流是新增的,注明版本号(来自需求上下文);@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 编写注释时,规范要求包含:
- 功能描述:该步骤做什么,以及在什么条件下抛出错误/返回什么;
@example:演示如何调用该步骤;@since:若为新增步骤,注明版本号;@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)
规范对"哪些内容不需要文档"给出了三条边界,防止文档噪音:
*Id字符串常量:例如export const addToCartWorkflowId = "add-to-cart",这类 ID 常量不需要任何 TSDoc。它们是内部标识符,文档化反而会分散注意力;- 模块内部未导出的辅助函数:仅在模块内部使用、未从模块导出的 helper 函数不属于公开 API,无需 TSDoc;
- 补偿函数(compensation functions):即
createStep的第三个参数。尽管它是步骤的重要组成(负责在错误发生时回滚操作),但规范将其视为内部实现细节,明确不写入 TSDoc。
从 createStep 源码 可以看到,补偿函数接收 invoke 函数通过 StepResponse 第二参数传入的数据,用于撤销已执行的操作;它确实是支撑工作流"分布式事务回滚"语义的关键机制,但文档层面刻意将其隐藏,只通过 invoke 函数的描述间接呈现。
这三点边界背后的原则是:TSDoc 只面向公开 API 与开发者需要知道的使用语义,内部实现细节一律交给源码本身。遵循该原则能显著降低文档维护成本,同时避免误导使用者依赖内部行为。
五、将规范落地到仓库的实践建议
结合上文规范与源码,在实际为 core-flows 编写 TSDoc 时可遵循以下清单自检:
- 定位文件:确认文档对象位于
packages/core/core-flows/src/<domain>/workflows/或.../steps/下,且是从模块导出的const; - 区分对象类型:工作流文档必须含 API 路由链接、
@summary与全部@property hooks.*;步骤文档必须含抛出条件描述与输入类型逐属性说明; - 验证
@example可运行性:工作流的@example应严格采用await myWorkflow(container).run({ input: { ... } })形态;步骤的@example采用直接调用形态; - 正确处理版本与开关:新增对象标注
@since,受开关保护的对象标注@featureFlag,二者可共存; - 交叉引用:步骤输入类型描述中优先使用
{@link stepName}建立跳转关系; - 遵守否定清单:
*Id常量、内部辅助函数、补偿函数一律不写 TSDoc。
按此清单产出的注释,既符合 Medusa 官方生成规范,也能被 IDE 提示、API 文档生成器、搜索引擎与 LLM 准确索引与引用——这正是本文所依托的 .claude/skills/writing-tsdocs/reference/workflows-steps.md 想达成的核心目标:让 core-flows 里数百个工作流与步骤,每一份公开文档都准确、一致、可执行。