Medusa 自定义工作流开发实战:从 createStep 到 createWorkflow 的完整指南

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

Medusa 自定义工作流开发实战:从 createStep 到 createWorkflow 的完整指南

导读

本文以 Medusa(当前仓库 GitHub_Trending/me/medusa)loyalty 插件中的工作流目录 packages/plugins/loyalty/src/workflows 及其配套文档 Custom Workflows README 为核心,系统讲解如何在 Medusa 中通过 createStep、createWorkflow、StepResponse、WorkflowResponse 构建和编排自定义工作流,并介绍 transform、useQueryGraphStep、runAsStep、hooks 等进阶组合手段。读完本文,你将掌握:在工作流文件中定义多步骤任务的完整写法、在 API Route / Scheduled Job / Subscriber 中执行工作流的调用方式,以及如何基于源码理解 Medusa 工作流引擎的底层编排与补偿机制。


一、工作流是什么

在 Medusa 中,工作流(Workflow) 是"一系列完成某项任务的查询(queries)与动作(actions)"的组合。它把多个业务步骤组织成一个可执行、可回滚、可复用的单元,是 Medusa 框架中处理复杂业务逻辑的标准抽象。

工作流文件是普通的 TypeScript 或 JavaScript 文件,约定存放于项目的 src/workflows 目录下,例如 loyalty 插件中:

  • packages/plugins/loyalty/src/workflows/gift-cards/workflows/create-gift-cards.ts
  • packages/plugins/loyalty/src/workflows/gift-cards/workflows/redeem-gift-card.ts
  • packages/plugins/loyalty/src/workflows/store-credit/workflows/credit-accounts.ts

插件通过 index.ts 统一导出各业务子目录(carts、gift-cards、store-credit)下的工作流,外部模块即可按需引用。

一个工作流由两类核心构件组成:

构件 用途 定义来源
createStep 定义一个最小执行单元(Step),可携带补偿函数 packages/core/workflows-sdk/src/utils/composer/create-step.ts
createWorkflow 将多个 Step 编排为一个可执行的工作流 packages/core/workflows-sdk/src/utils/composer/create-workflow.ts
StepResponse Step 的返回包装,携带输出与补偿数据 packages/core/workflows-sdk/src/utils/composer/helpers/step-response.ts
WorkflowResponse 工作流构造器函数的返回包装,声明最终输出 packages/core/workflows-sdk/src/utils/composer/helpers/workflow-response.ts

二、创建第一个自定义工作流

2.1 基础示例

在原文档 Custom Workflows README 中给出了最简化的"Hello World"工作流,我们完整继承并加以注解:

import {
  createStep,
  createWorkflow,
  WorkflowResponse,
  StepResponse,
} from "@medusajs/framework/workflows-sdk"

const step1 = createStep("step-1", async () => {
  return new StepResponse(`Hello from step one!`)
})

type WorkflowInput = {
  name: string
}

const step2 = createStep(
  "step-2",
  async ({ name }: WorkflowInput) => {
    return new StepResponse(`Hello ${name} from step two!`)
  }
)

type WorkflowOutput = {
  message1: string
  message2: string
}

const helloWorldWorkflow = createWorkflow(
  "hello-world",
  (input: WorkflowInput) => {
    const greeting1 = step1()
    const greeting2 = step2(input)

    return new WorkflowResponse({
      message1: greeting1,
      message2: greeting2
    })
  }
)

export default helloWorldWorkflow

要点拆解:

  • createStep("step-1", async () => {...}):第一个参数是步骤名称(在日志、追踪与补偿编排中作为唯一标识),第二个参数是调用函数(invoke function),返回 StepResponse。
  • createWorkflow("hello-world", (input) => {...}):第一个参数是工作流名称,第二个参数是构造器函数(composer function),它接收工作流输入 input,在其中"声明"步骤的调用顺序,最后必须返回 WorkflowResponse。
  • 注意:构造器函数内部不能直接操作或读取运行时数据,只能声明性地组合步骤;若需要对步骤输出做数据变换,必须使用 transform(见下文)。
  • 文件默认导出工作流对象,供 API Route、Scheduled Job、Subscriber 引用。

2.2 执行工作流

工作流定义后并不会立即执行,需要在其他资源(API Route、定时任务、订阅者)中显式触发。原文档给出了在 API Route 中执行的示例:

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework"
import myWorkflow from "../../../workflows/hello-world"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await myWorkflow(req.scope)
    .run({
      input: {
        name: req.query.name as string,
      },
    })

  res.send(result)
}

关键点:

  • myWorkflow(req.scope):传入请求级容器(req.scope),获得一个可执行的工作流实例;
  • .run({ input }):提交输入并运行,返回 { result, errors };result 即 WorkflowResponse 中声明的输出。
  • 同样的模式可用于 Scheduled Job(定时任务)与 Subscriber(事件订阅者)——只需把 req.scope 换成各自的容器引用。

三、深入 Step:调用函数、补偿函数与 StepResponse

3.1 调用函数(Invoke Function)与补偿函数(Compensate Function)

从源码 create-step.ts 可以看出,createStep 的完整签名是:

export function createStep<TInvokeInput, TInvokeResultOutput, TInvokeResultCompensateInput>(
  nameOrConfig: string | ({ name: string } & Omit<TransactionStepsDefinition, "next" | "uuid" | "action">),
  invokeFn: InvokeFn<TInvokeInput, TInvokeResultOutput, TInvokeResultCompensateInput>,
  compensateFn?: CompensateFn<TInvokeResultCompensateInput>
): StepFunction<TInvokeInput, TInvokeResultOutput>
  • invokeFn:步骤执行时调用的函数,接收 input 与 StepExecutionContext(内含 container 等),必须返回 StepResponse。
  • compensateFn(可选):当工作流后续步骤出错时执行的回滚函数,用于撤销本步骤的副作用(即分布式事务中的补偿机制)。若未提供补偿函数,源码中会通过 stepConfig.noCompensation = !compensateFn 标记该步骤不可补偿。

一个带补偿的实际例子来自 SDK 注释(create-step.ts 顶部示例):

export const createProductStep = createStep(
  "createProductStep",
  async function (input: CreateProductInput, { container }) {
    const productModuleService = container.resolve("product")
    const product = await productModuleService.createProducts(input)
    return new StepResponse(
      { product },
      { product_id: product.id } // 传给补偿函数的参数
    )
  },
  async function (input, { container }) {
    if (!input) return
    const productModuleService = container.resolve("product")
    await productModuleService.deleteProducts([input.product_id])
  }
)

3.2 StepResponse:输出与补偿数据

StepResponse 构造函数接受两个参数(见 step-response.ts):

  • output:步骤的输出,供后续步骤或工作流最终结果使用;
  • compensateInput(可选):传给补偿函数的参数。若省略,则补偿函数默认接收 output 本身。

此外 StepResponse 提供两个静态工具方法:

  • StepResponse.permanentFailure(message?):抛出 PermanentStepFailureError,表示步骤已永久失败、不再触发重试,适合"业务上不可重试"的错误场景;
  • StepResponse.skip():返回 SkipStepResponse,用于条件不满足时跳过该步骤(常与条件逻辑配合)。

3.3 从忠诚度插件看真实 Step

loyalty 插件中的 redeem-gift-card.ts 定义了一个真实的校验步骤:

export const validateGiftCardRedeemStep = createStep(
  "validate-gift-card-redeem",
  async function ({ giftCardStoreCreditAccount, giftCard }) {
    if (giftCard.status === GiftCardStatus.REDEEMED) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "Gift card is already redeemed"
      )
    }
    if (giftCardStoreCreditAccount) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "Gift card already has a store credit account"
      )
    }
  }
)

该 Step 仅做前置校验:礼品卡已兑换、或已关联店铺信用账户时直接抛出 MedusaError,从而阻止后续步骤执行——体现了"Step 即业务原子操作"的设计理念。


四、组合与变换:transform、查询与并行

4.1 transform:在工作流内部变换数据

由于工作流构造器函数是"声明式"的,无法直接读写运行时数据,Medusa 提供了 transform 函数来访问步骤的运行时输出并加工(源码见 transform.ts):

const storeCreditAccontCurrencies = transform(
  { giftCards },
  ({ giftCards }) => {
    return giftCards.map((giftCard) => ({
      currency_code: giftCard.currency_code,
    }))
  }
)

transform 的第一个参数传入一个对象,其属性是先前步骤的输出引用;第二个参数是变换函数,接收运行时已解析的值并返回新数据,返回值同样可作为后续步骤的输入。

4.2 useQueryGraphStep:在工作流中查询数据

loyalty 插件大量使用 useQueryGraphStep(来自 @medusajs/medusa/core-flows)在工作流内部发起查询,例如 redeem-gift-card.ts:

const giftCardQuery = useQueryGraphStep({
  entity: "gift_card",
  filters: { id: input.gift_card_id },
  fields: ["id", "code", "status", "value", "currency_code"],
  options: { throwIfKeyNotFound: true },
}).config({ name: "get-gift-card-query" })

const giftCard = transform({ giftCardQuery }, ({ giftCardQuery }) => {
  return giftCardQuery.data[0]
})
  • entity / filters / fields 分别指定查询实体、过滤条件与返回字段;
  • options.throwIfKeyNotFound: true 表示查不到记录时抛错;
  • .config({ name }) 允许为步骤指定别名;
  • 查询结果通过 transform 提取为普通对象后供后续步骤消费。

4.3 runAsStep:在工作流中嵌套执行另一个工作流

Medusa 允许一个工作流作为另一个工作流的"步骤"运行,即 runAsStep(实现在 create-workflow.ts 的 mainFlow.runAsStep)。它本质上会创建一个名为 ${name}-as-step 的包装 Step,并把内部工作流的 run 包装进 invoke 函数、把 cancel 包装进补偿函数——这样嵌套工作流同样可以参与外层的事务与补偿。

典型的组合示例(create-gift-cards.ts):

createLinksWorkflow.runAsStep({ input: linkToCreate })

creditAccountsWorkflow.runAsStep({
  input: creditAccountsInput,
})

const redeemedGiftCards = updateGiftCardsWorkflow.runAsStep({
  input: updateGiftCardsInput,
})

return new WorkflowResponse(redeemedGiftCards)

这段代码串起了"创建礼品卡 → 创建匿名店铺信用账户并建立关联 → 按礼品卡面额入账 → 标记礼品卡为已兑换"的完整业务流程,每一步都复用已有工作流,充分体现工作流的可组合性。

4.4 并行执行与条件分支

workflows-sdk 还提供两个常用组合工具(见 composer/index.ts 的导出):

  • parallelize(...steps):将多个步骤声明为并行执行;
  • when(input, condition):根据条件动态构造分支执行路径。

此外,每个 Step 返回的引用对象还暴露了 .if(input, condition) 方法,用于给该步骤附加条件判断(源码位于 create-step.ts 的 refRet.if)。合理使用这些 API 可显著提升复杂业务流程的表达能力。


五、Hooks:扩展既有核心工作流

除自建工作流外,Medusa 还允许开发者为既有工作流注册 Hook,从而在核心流程的特定节点注入自定义逻辑。

loyalty 插件在 hooks/after-order-created.ts 中演示了完整用法:

import { StepResponse } from "@medusajs/framework/workflows-sdk"
import { completeCartWorkflow } from "@medusajs/medusa/core-flows"
import { confirmCartCreditLinesWorkflow } from "../carts/workflows/confirm-cart-credit-lines"
import { cloneCartGiftCardsToOrderWorkflow } from "../orders/workflows/link-gift-cards-to-order"

;(completeCartWorkflow.hooks as any).orderCreated(
  async (data: { order_id: string; cart_id: string }, stepContext) => {
    const { container, ...sharedContext } = stepContext
    const { order_id, cart_id } = data

    const transaction = await cloneCartGiftCardsToOrderWorkflow.run({
      input: { order_id, cart_id },
      container,
      context: { ...sharedContext, preventReleaseEvents: true },
    })

    return new StepResponse(transaction.result, stepContext.transactionId)
  },
  async (transactionId, stepContext) => {
    if (!transactionId) return
    const { container, ...sharedContext } = stepContext
    await confirmCartCreditLinesWorkflow(container).cancel({
      transactionId,
      container,
      context: { ...sharedContext },
    })
  }
)

解读:

  • 通过 completeCartWorkflow.hooks.orderCreated(...) 挂载"订单创建完成"后的回调;
  • 回调函数签名与 Step 一致:第一参数为 Hook 负载数据,第二参数为 stepContext(含 container);
  • 回调返回 StepResponse,并同样提供补偿函数——当订单创建流程回滚时,自动取消购物车信用额度确认流程,保证数据一致性;
  • 这正是"工作流 + Hook + 补偿"三者协同的经典场景。

六、底层原理:工作流引擎如何编排

理解底层实现有助于排查问题与设计复杂流程。从源码看,编排核心位于 create-workflow.ts:

  1. 注册:createWorkflow 调用 WorkflowManager.register(name, undefined, handlers, options) 注册工作流;若已存在同名工作流则走 register 更新分支。
  2. 组合上下文:构造 CreateWorkflowComposerContext(包含 workflowId、flow、handlers 等),并将其挂在全局 SymbolMedusaWorkflowComposerContext 上,随后执行构造器函数,使每个 createStep 的调用都能拿到上下文(见 create-step.ts 中 global[SymbolMedusaWorkflowComposerContext] 的判断与报错 "createStep must be used inside a createWorkflow definition")。
  3. 构建执行图:每个 Step 通过 this.flow.addAction(stepName, stepConfig) 追加到事务定义中;stepConfig.uuid = ulid() 为每个步骤生成唯一 ID,stepConfig.noCompensation = !compensateFn 标记是否可补偿(详见 create-step.ts 的 applyStep)。
  4. 惰性执行:构造器函数内的所有代码(包括数据访问)并不会立即执行,而是在调用 .run() 时由工作流引擎统一调度;这也解释了为何必须用 transform 而非直接取值。
  5. 执行与补偿:.run() 按执行图依次执行步骤的 invoke 函数;任一步骤失败时,引擎逆序调用已完成步骤的补偿函数,实现"事务式"回滚。

理解了这一机制,就能明白 loyalty 插件中 redeemGiftCardWorkflow 为何能在一个编排中同时完成"查询礼品卡 → 校验 → 创建账户 → 入账 → 更新状态 → 返回账户详情"而无需手写任何事务代码。


七、在忠诚度业务中的实践总结

作为实践落点,梳理 loyalty 插件工作流目录中的真实资产,可作为你自建工作流的参考模板:

  • 礼品卡:gift-cards/workflows/create-gift-cards.ts(创建并自动建立店铺信用账户)、redeem-gift-card.ts(兑换并返回账户详情)、claim-gift-card.ts、update-gift-cards.ts、delete-gift-card.ts;
  • 店铺信用:store-credit/workflows/credit-accounts.ts、debit-accounts.ts、create-store-credit-accounts.ts、credit-store-credit-account.ts、claim-store-credit-account.ts;
  • 购物车:carts/workflows/add-gift-card-to-cart.ts、confirm-cart-credit-lines.ts、refresh-cart-gift-cards.ts、remove-gift-cart-from-cart.ts;
  • 订单:orders/workflows/link-gift-cards-to-order.ts、refund-credit-lines.ts;
  • Hooks:hooks/after-order-created.ts、hooks/after-order-credit-lines-created.ts、hooks/before-payment-collection-refresh.ts、hooks/complete-cart-before-payment-authorization.ts。

编写工作流的推荐步骤

  1. 在 src/workflows/<domain>/steps/ 下用 createStep 定义原子操作(含补偿函数);
  2. 在 src/workflows/<domain>/workflows/ 下用 createWorkflow 编排这些 Step,需要时用 transform 变换数据、用 useQueryGraphStep 查询、用 runAsStep 复用其他工作流;
  3. 用 WorkflowResponse 声明工作流输出;
  4. 在 API Route / Scheduled Job / Subscriber 中通过 workflow(container).run({ input }) 触发执行;
  5. 若需扩展核心流程,通过 someWorkflow.hooks.someHook(callback, compensateFn) 挂载 Hook。

八、常见问题与注意事项

  • "createStep must be used inside a createWorkflow definition":createStep 返回的函数只能在 createWorkflow 构造器函数内部调用,脱离组合上下文会抛出该错误(见 create-step.ts 中的校验)。
  • 不要直接操纵数据:构造器函数是声明式的,读写运行时数据必须使用 transform;否则数据访问不会按预期时机执行。
  • 异步步骤:可通过 createStep({ name, async: true }, ...) 声明异步步骤,引擎会将其标记为后台执行,避免阻塞整个事务(相关逻辑见 create-step.ts 的 wrapAsyncHandler)。
  • 补偿函数缺失:未提供补偿函数的步骤在出错时无法回滚,设计时请为有副作用的步骤(创建、扣款、状态变更等)补齐补偿逻辑。
  • StepResponse 的两个参数:第二个参数用于精确控制补偿函数拿到的数据;省略时补偿函数接收输出本身,业务上请确保输出中包含了补偿所需的最小信息(如刚创建的记录 ID)。

结语

从 createStep 的最小原子单元,到 createWorkflow 的声明式编排,再到 transform、useQueryGraphStep、runAsStep 与 Hooks 的组合拳,Medusa 的工作流体系让复杂业务可以被拆解、复用、组合,并天然具备补偿回滚能力。loyalty 插件 src/workflows 目录下的完整实现,以及 workflows-sdk 源码 中的底层机制,是理解这一体系的最佳参考。掌握本文的方法,你就能在自己的 Medusa 项目中构建出可靠、可维护的自定义工作流。

登录后查看全文
medusa