步骤上下文

每个 step.do 回调都会收到一个上下文对象（WorkflowStepContext）作为第一个参数。该上下文为步骤代码提供关于步骤本身、当前重试次数以及该步骤已解析配置的运行时信息。

WorkflowStepContext

type WorkflowStepContext = {
	step: {
		name: string;
		count: number;
	};
	attempt: number;
	config: WorkflowStepConfig;
};

属性

属性	类型	描述
`step.name`	`string`	你传递给 `step.do` 的名称。
`step.count`	`number`	在当前 Workflow 运行中，使用此名称调用 `step.do` 的次数。给定名称的首次调用从 `1` 开始。
`attempt`	`number`	当前尝试次数（从 1 开始）。首次尝试为 `1`，第一次重试为 `2`，依此类推。
`config`	`WorkflowStepConfig`	该步骤已解析的重试和超时配置，包括运行时应用的任何默认值。

如果步骤配置的 retries.delay 是函数，动态延迟不会暴露在 ctx.config.retries.delay 上。延迟函数会收到包含当前步骤上下文和导致重试的错误的对象。

访问上下文

向 step.do 回调传递参数以接收上下文对象：

await step.do("my-step", async (ctx) => {
	console.log(ctx.step.name); // "my-step"
	console.log(ctx.step.count); // 1
	console.log(ctx.attempt); // 首次尝试为 1，第一次重试为 2，依此类推
	console.log(ctx.config); // { retries: { limit: 5, ... }, timeout: "10 minutes" }
});

传递自定义 WorkflowStepConfig 时也可使用上下文：

await step.do(
	"call an API",
	{
		retries: {
			limit: 10,
			delay: "10 seconds",
			backoff: "exponential",
		},
		timeout: "30 minutes",
	},
	async (ctx) => {
		console.log(ctx.config.retries.limit); // 10
		console.log(ctx.config.timeout); // "30 minutes"
	},
);

要配置延迟函数，请参阅设置动态重试延迟。

示例

根据重试次数调整行为

使用 ctx.attempt 在重试时改变步骤行为。例如，在重试一定次数后使用备用端点：

await step.do(
	"fetch data",
	{ retries: { limit: 5, delay: "5 seconds", backoff: "linear" } },
	async (ctx) => {
		const url =
			ctx.attempt <= 3
				? "https://api.example.com/primary"
				: "https://api.example.com/fallback";

		const response = await fetch(url);
		if (!response.ok) {
			throw new Error(`Request failed with status ${response.status}`);
		}
		return await response.json();
	},
);

记录步骤元数据以便可观测

使用 ctx.step 为日志添加结构化元数据：

await step.do("process-order", async (ctx) => {
	console.log(
		JSON.stringify({
			step: ctx.step.name,
			stepCount: ctx.step.count,
			attempt: ctx.attempt,
			retryLimit: ctx.config.retries?.limit,
		}),
	);

	// 你的步骤逻辑
});