Создайте свой первый Workflow

npm create cloudflare@latest workflows-starter -- --template "cloudflare/workflows-starter"

1. Откройте терминал и выполните create cloudflare (C3), CLI-инструмент для создания проекта Worker:

   npmyarnpnpm

   npm create cloudflare@latest -- my-workflow

   Для настройки выберите следующие параметры:

   • Для С чего вы хотите начать?, выберите Hello World example.
   • Для Какой шаблон вы хотите использовать?, выберите Worker only.
   • Для Какой язык вы хотите использовать?, выберите TypeScript.
   • Для Хотите использовать git для контроля версий?, выберите Yes.
   • Для Хотите развернуть приложение?, выберите No (мы внесём некоторые изменения перед развёртыванием).

2. Перейдите в каталог нового проекта:

   cd my-workflow

   Какие файлы создал C3?

   В каталоге проекта C3 сгенерирует следующее:

   • wrangler.jsonc: Ваш конфигурационный файл Wrangler.
   • src/index.ts: минимальный Worker, написанный на TypeScript.
   • package.json: Минимальный файл конфигурации зависимостей Node.
   • tsconfig.json: конфигурация TypeScript.

1. Создайте новый файл src/workflow.ts:

   src/workflow.ts

   import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";
   import type { WorkflowEvent } from "cloudflare:workers";
   
   type Params = { name?: string };
   type IPResponse = { result: { ipv4_cidrs: string[] } };
   
   export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
   	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
   		const data = await step.do("fetch data", async () => {
   			const response = await fetch(
   				"https://api.cloudflare.com/client/v4/ips",
   			);
   			return await response.json<IPResponse>();
   		});
   
   		await step.sleep("pause", "20 seconds");
   
   		const result = await step.do(
   			"process data",
   			{ retries: { limit: 3, delay: "5 seconds", backoff: "linear" } },
   			async () => {
   				return {
   					name: event.payload.name ?? "World",
   					ipCount: data.result.ipv4_cidrs.length,
   				};
   			},
   		);
   
   		return result;
   	}
   }

   Workflow расширяет WorkflowEntrypoint и реализует run метод. Этот код также передаёт наш Params тип как параметр типа чтобы события, запускающие наш Workflow, были типизированы.

   step объект является основой Workflows API. Он предоставляет методы для определения устойчивых шагов в вашем Workflow:

   • step.do(name, callback) : выполняет код и сохраняет результат. Если выполнение Workflow прерывается или запускается повторно, он возобновляется с последнего успешно выполненного шага, а не повторяет уже проделанную работу. Функция обратного вызова возвращает сериализуемые данные, включая ReadableStream<Uint8Array> для больших бинарных данных в Workflows на JavaScript.
   • step.sleep(name, duration) : приостанавливает Workflow на заданное время (например, "10 seconds", "1 hour").

   Если вы возвращаете поток, возвращайте новый, разблокированный ReadableStream<Uint8Array>. Потоки BYOB и читатели BYOB не поддерживаются.

   Можно передать конфигурация повторных попыток к step.do() чтобы настроить обработку сбоев. См. полный API шага с требованиями к потокам, ограничениями и дополнительными методами, такими как sleepUntil и waitForEvent.

   Решая, стоит ли разбивать код на отдельные шаги, задайте себе вопрос: «Хочу ли я, чтобы весь этот код выполнялся снова, если откажет только одна его часть?» Отдельные шаги отлично подходят для таких операций, как вызов внешних API, обращение к базам данных или чтение файлов из хранилища: если последующий шаг завершится ошибкой, ваш Workflow сможет повторить попытку с этого места, используя уже полученные данные, не повторяя лишние вызовы API или запросы к базе данных.

   Дополнительные рекомендации по определению логики Workflow см. в Правила Workflows.

1. Откройте wrangler.jsonc, который является вашим конфигурационный файл Wrangler для вашего проекта Workers и вашего Workflow, а затем добавьте workflows конфигурация:

   {
   	"$schema": "node_modules/wrangler/config-schema.json",
   	"name": "my-workflow",
   	"main": "src/index.ts",
   	// Set this to today's date
   	"compatibility_date": "2026-08-28",
   	"observability": {
   		"enabled": true
   	},
   	"workflows": [
   		{
   			"name": "my-workflow",
   			"binding": "MY_WORKFLOW",
   			"class_name": "MyWorkflow"
   		}
   	]
   }

   "$schema" = "node_modules/wrangler/config-schema.json"
   name = "my-workflow"
   main = "src/index.ts"
   # Set this to today's date
   compatibility_date = "2026-08-28"
   
   [observability]
   enabled = true
   
   [[workflows]]
   name = "my-workflow"
   binding = "MY_WORKFLOW"
   class_name = "MyWorkflow"

   class_name должно совпадать с вашим экспортированным классом, а binding это имя переменной, которую вы используете для доступа к Workflow в своём коде (например, env.MY_WORKFLOW).

   Если вы хотите, чтобы один и тот же Workflow запускался автоматически с определённой периодичностью, добавьте schedules в определение Workflow:

   {
     "$schema": "node_modules/wrangler/config-schema.json",
     "name": "my-workflow",
     "main": "src/index.ts",
     // Set this to today's date
     "compatibility_date": "2026-08-28",
     "workflows": [
       {
         "name": "my-workflow",
         "binding": "MY_WORKFLOW",
         "class_name": "MyWorkflow",
         "schedules": ["0 * * * *"]
       }
     ]
   }

   "$schema" = "node_modules/wrangler/config-schema.json"
   name = "my-workflow"
   main = "src/index.ts"
   # Set this to today's date
   compatibility_date = "2026-08-28"
   
   [[workflows]]
   name = "my-workflow"
   binding = "MY_WORKFLOW"
   class_name = "MyWorkflow"
   schedules = [ "0 * * * *" ]

   Каждое совпадающее cron-выражение автоматически создаёт новый экземпляр Workflow, поэтому вам не нужен верхнеуровневый triggers.crons и отдельный scheduled обработчик для периодических запусков, специфичных для Workflow.

   Запланированные экземпляры включают соответствующее cron-выражение и время запланированного запуска в event.schedule.

   При настройке расписаний Workflow используйте последнюю версию Wrangler. Если локальная схема Wrangler не распознаёт schedules ещё, обновите Wrangler перед развёртыванием.

   Вы также можете получить доступ к привязки (например, KV, R2, или D1) через this.env внутри вашего Workflow. Подробнее о привязках в Workers см. Привязки (env).

2. Теперь сгенерируйте типы для своих привязок:

   npx wrangler types

   Это создаёт worker-configuration.d.ts файл с Env тип, который включает ваш MY_WORKFLOW привязку.

1. Замените src/index.ts с обработчик fetch для запуска и проверки состояния экземпляров Workflow:

   src/index.ts

   export { MyWorkflow } from "./workflow";
   
   export default {
   	async fetch(request: Request, env: Env): Promise<Response> {
   		const url = new URL(request.url);
   		const instanceId = url.searchParams.get("instanceId");
   
   		if (instanceId) {
   			const instance = await env.MY_WORKFLOW.get(instanceId);
   			return Response.json(await instance.status());
   		}
   
   		const instance = await env.MY_WORKFLOW.create();
   		return Response.json({ instanceId: instance.id });
   	},
   } satisfies ExportedHandler<Env>;

1. Запустите локальный сервер разработки:

   npx wrangler dev

2. Чтобы запустить экземпляр Workflow, откройте новое окно терминала и выполните:

   curl http://localhost:8787

   Одна instanceId будет сгенерирован автоматически:

   { "instanceId": "abc-123-def" }

3. Проверьте статус с помощью возвращенного instanceId:

   curl "http://localhost:8787?instanceId=abc-123-def"

   Workflow последовательно пройдёт свои шаги. Примерно через 20 секунд (это длительность паузы) он завершится.

1. Разверните свой Workflow:

   npx wrangler deploy

   Протестируйте в продакшене, используя те же команды curl, но с адресом развёрнутого URL. Также вы можете запуск экземпляра workflow в продакшене через Workers, Wrangler или Cloudflare dashboard.

   После развёртывания вы также можете просматривать экземпляры Workflow с помощью CLI:

   npx wrangler workflows instances describe my-workflow latest

   Вывод instances describe показывает:

   • Статус (success, failure, running) каждого шага
   • Любое состояние, переданное шагом. При потоковом выводе CLI показывает предварительный просмотр или сводку вместо полного содержимого.
   • Любой sleep состояние, включая время, когда Workflow снова активируется
   • Повторы, связанные с каждым шагом
   • Ошибки, включая сообщения исключений