Medusa 自定义工作流开发实战:从 createStep 到 createWorkflow 的完整指南
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.tspackages/plugins/loyalty/src/workflows/gift-cards/workflows/redeem-gift-card.tspackages/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:
- 注册:
createWorkflow调用WorkflowManager.register(name, undefined, handlers, options)注册工作流;若已存在同名工作流则走register更新分支。 - 组合上下文:构造
CreateWorkflowComposerContext(包含workflowId、flow、handlers等),并将其挂在全局SymbolMedusaWorkflowComposerContext上,随后执行构造器函数,使每个createStep的调用都能拿到上下文(见 create-step.ts 中global[SymbolMedusaWorkflowComposerContext]的判断与报错"createStep must be used inside a createWorkflow definition")。 - 构建执行图:每个 Step 通过
this.flow.addAction(stepName, stepConfig)追加到事务定义中;stepConfig.uuid = ulid()为每个步骤生成唯一 ID,stepConfig.noCompensation = !compensateFn标记是否可补偿(详见 create-step.ts 的applyStep)。 - 惰性执行:构造器函数内的所有代码(包括数据访问)并不会立即执行,而是在调用
.run()时由工作流引擎统一调度;这也解释了为何必须用transform而非直接取值。 - 执行与补偿:
.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。
编写工作流的推荐步骤
- 在
src/workflows/<domain>/steps/下用createStep定义原子操作(含补偿函数); - 在
src/workflows/<domain>/workflows/下用createWorkflow编排这些 Step,需要时用transform变换数据、用useQueryGraphStep查询、用runAsStep复用其他工作流; - 用
WorkflowResponse声明工作流输出; - 在 API Route / Scheduled Job / Subscriber 中通过
workflow(container).run({ input })触发执行; - 若需扩展核心流程,通过
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 项目中构建出可靠、可维护的自定义工作流。