Перейти до основного вмісту
Версія: 2.0

Перехід на 2.0

Цей посібник описує основні зміни під час оновлення наявного застосунку Laravel з v1 до v2. Спочатку виберіть, чи Laravel і надалі керуватиме runtime, чи підключатиметься до Cloud або самостійно розгорнутого Server через PHP SDK, за допомогою посібника з упровадження в Laravel і переходу між runtime. Далі ця сторінка описує докладну процедуру переходу вбудованого пакета з v1 до v2.

Процедура оновлення​

Перед оновленням​

1. Складіть перелік усіх сховищ виконання v1

Стан виконання v1 може зберігатися поза базою даних workflow. Окрім рядків workflow та історії, завдання черги Laravel можуть бути готовими, відкладеними або зарезервованими в Redis, базі даних черги, SQS чи іншому бекенді черги. До зміни коду зафіксуйте:

  • з'єднання зі сховищем workflow та фактичні відповідності моделей і таблиць v1
  • усі з'єднання та назви черг, які використовують workflow й activity v1, включно з перевизначеннями для окремих workflow чи activity
  • базу даних, префікс ключів, регіон, обліковий запис та інші параметри маршрутизації бекенду черги, потрібні для відновлення тих самих черг
  • посилання на секрет у менеджері секретів і його незмінну версію для отримання точного APP_KEY, а також сховище кешу для блокувань унікальних завдань v1

Не копіюйте значення APP_KEY, облікові дані відновлення менеджера секретів, бази даних чи провайдера черги до цього переліку. Для зашифрованих завдань і серіалізованих аргументів workflow потрібен початковий ключ, але маніфест відновлення має містити лише посилання на нього в менеджері секретів і версію. Облікові дані для отримання ключа зберігайте окремо від резервних копій SQL і черг, з окремим контролем доступу.

Типові таблиці v1: workflows, workflow_logs, workflow_signals, workflow_timers, workflow_exceptions і workflow_relationships. Опублікований файл config/workflows.php може перевизначати stored_workflow_model, stored_workflow_log_model, stored_workflow_signal_model, stored_workflow_timer_model або stored_workflow_exception_model. Власна модель може також перевизначати Eloquent $table, а workflow_relationships_table окремо задає таблицю зв'язків. Створіть резервні копії таблиць і з'єднання зі сховищем, визначених цими налаштованими моделями, а не лише таблиць із типовими назвами.

2. Виберіть межу відкату й призупиніть роботу v1

Заблокуйте запуск нових workflow і надсилання signal на час створення узгодженого набору відновлення. Призупиніть планувальники й зупиніть усі worker, що споживають завдання з перелічених черг, після завершення поточного завдання. Наприклад:

# Horizon
php artisan horizon:pause

# Supervisor or systemd (use the names from your deployment)
sudo supervisorctl stop <your-worker-group>:*
sudo systemctl stop laravel-worker

Сам по собі php artisan queue:restart не призупиняє роботу, якщо Supervisor, systemd, Kubernetes чи інший менеджер процесів одразу запускає нового worker. Перш ніж фіксувати стан, переконайтеся, що жоден споживач не може зарезервувати наступне завдання.

Виберіть і зафіксуйте одну з цих політик:

  • Завершити роботу v1: заблокуйте нову роботу v1 і залиште worker v1 працювати, доки php artisan workflow:v1:list (якщо команда доступна) або еквівалентний запит до налаштованої таблиці збережених workflow не покаже відсутність незавершених workflow. Потім зупиніть worker і переконайтеся, що відповідні черги не містять готових, відкладених чи зарезервованих завдань v1. Для таких завершених workflow v1 достатньо відкату SQL.
  • Зберегти активну роботу v1: зупиніть worker між завданнями та зробіть узгоджений знімок SQL і кожного надійного бекенду черги. Знімок черги має містити готову, відкладену й зарезервовану роботу та відповідати тому самому моменту відновлення, що й SQL. Дочекайтеся завершення зарезервованого завдання, якщо бекенд не описує, як безпечно відновити його повідомлення та lease.
  • Прийняти втрату активної роботи: якщо бекенд не дає створити відновлюваний узгоджений знімок черги, зафіксуйте відповідні ID workflow і явно прийміть, що незавершені виконання, залежні від черги, неможливо відновити цим відкатом. Виключайте придатний рядок pending з цього переліку лише після перевірки шляху Watchdog нижче, а справжнє очікування лише signal лише після перевірки збереженого входу signal. Не вважайте інші рядки SQL відновлюваною роботою.

Очікування лише signal може правомірно не мати завдання в черзі, якщо зовнішній вхід signal залишається доступним після відкату. Повторні спроби activity й timer залежать від черги: рядок workflow_timers або рядок workflows зі станом очікування не відтворює втрачене відкладене завдання.

Підтримувана v1.0.77 також запускає типово ввімкнений Workflow\Watchdog із циклу worker черги. Watchdog може знайти workflow pending, чий updated_at старший за п'ять хвилин і чиї серіалізовані arguments наявні, та повторно направити його до записаних з'єднання й черги. Це обмежений шлях пробудження лише для pending, а не заміна резервної копії черги. Покладайтеся на нього лише після перевірки в тестовому середовищі: відновлений цикл worker v1 запускає Watchdog, Watchdog повторно направляє придатний застарілий рядок pending, а workflow просувається на очікуваній черзі. Цей шлях не відтворює повторні спроби activity чи завдання timer та не відновлює рядки waiting або running. Для них потрібне збережене завдання черги або справний зовнішній шлях signal, якщо workflow справді очікує signal.

3. Створіть резервну копію набору відновлення для відкату

Перед оновленням створіть повну резервну копію бази даних:

# MySQL/MariaDB
mysqldump -u root -p your_database > backup-v1-$(date +%Y%m%d-%H%M%S).sql

# PostgreSQL
pg_dump -U postgres your_database > backup-v1-$(date +%Y%m%d-%H%M%S).sql

# Laravel backup package (if installed)
php artisan backup:run --only-db

Потім збережіть стан черги відповідно до її бекенду:

  • Черга в базі даних: включіть таблиці черги та їхнє з'єднання до того самого узгодженого набору відновлення. Вони можуть бути поза базою даних workflow.
  • Черга Redis: використайте відновлюваний знімок чи резервну копію Redis із точною базою даних і префіксом черги та її готовими, відкладеними й зарезервованими ключами. Якщо ця база Redis містить потрібні блокування унікальних завдань, збережіть і їх. Бажано мати окрему базу чи екземпляр для черг, адже відновлення спільного знімка Redis може відкотити сторонні дані застосунку.
  • SQS чи інша керована черга: використовуйте відновлення повідомлень на момент часу, підтримуване провайдером, лише якщо воно узгоджено зберігає доступні, відкладені й активні повідомлення. SQS не надає довільного знімка черги для цієї процедури, тому завершіть роботу v1 або визнайте решту залежної від черги роботи v1 невідновлюваною. Єдині винятки для відновлення лише SQL: перевірений рядок pending, придатний для Watchdog, і перевірене очікування лише signal.

Зберігайте резервні копії SQL і черг, перелік без секретів і час відновлення разом. Маніфест відновлення може містити посилання на APP_KEY у менеджері секретів і його версію, але не сам ключ чи облікові дані для його отримання. Доступ до облікових даних менеджера секретів, бази даних, провайдера черги та відновлення резервних копій контролюйте окремо. Відновлення SQL і стану черги з різних моментів часу не є підтримуваним способом відкату активної роботи.

4. Спочатку перевірте в тестовому середовищі

Не оновлюйте production без перевірки в тестовому середовищі. Оновлення включає:

  • Зміни схеми бази даних: надійне ядро v2 додає нові таблиці, точну кількість визначає php artisan migrate, а майбутня об'єднана міграція може згрупувати файли
  • Зміни просторів імен, що потребують оновлення коду
  • Перезапуск worker черги з короткою перервою
  • Перевірку можливостей бекенду

Контрольний список перевірки:

  • Розгорніть код v2 у тестовому середовищі
  • Виконайте міграції тестової бази даних
  • Перезапустіть worker черги
  • Виконайте php artisan workflow:v2:doctor --strict
  • Запустіть новий workflow v2 і перевірте його завершення
  • Перевірте, що workflow v1, якщо вони є, також завершуються
  • Перевірте відображення workflow v1 і v2 у Waterline
  • Запустіть тести свого застосунку
  • Перевірте відсутність помилок у журналах

Переходьте до production лише після успішної перевірки в тестовому середовищі.

Кроки оновлення​

1. Оновіть залежність Composer

composer require durable-workflow/workflow:2.5.4

Підтримуваний пакет Composer для v1 і v2 має назву durable-workflow/workflow. Ця команда змінює обмеження версії на поточну зафіксовану публічну версію v2. Стара назва laravel-workflow/laravel-workflow є лише псевдонімом сумісності для графів залежностей, створених до перейменування пакета. Для нових вимог і відкату використовуйте підтримувану назву. Поточна публічна зафіксована версія належить стабільному пакету 2.0. Використовуйте durable-workflow/workflow:^2.0, якщо хочете, щоб Composer автоматично приймав сумісні оновлення 2.x.

2. Виконайте міграції бази даних

php artisan migrate

v2 додає таблиці надійного ядра, які забезпечують контракт функцій v2. Поточні міграції окремих функцій створюють:

  • Ядро: workflow_instances, workflow_runs, workflow_history_events, workflow_tasks, workflow_commands
  • Activity: activity_executions, activity_attempts
  • Функції: workflow_updates, workflow_signal_records, workflow_run_waits, workflow_run_timeline_entries, workflow_run_lineage_entries, workflow_schedules, workflow_schedule_history_events
  • Спостережуваність: workflow_run_summaries, workflow_failures, workflow_links, worker_compatibility_heartbeats
  • Timer: workflow_run_timers, workflow_run_timer_entries
  • Пошук / memo / повідомлення / дочірні workflow: workflow_search_attributes, workflow_memos, workflow_messages, workflow_child_calls
  • Каталог сервісів: workflow_service_endpoints, workflow_services, workflow_service_operations, workflow_service_calls

Майбутня об'єднана міграція може згрупувати їх у меншу кількість файлів без зміни надійного контракту. Підтримуваний спосіб визначити фактичний стан бази даних: виконати php artisan migrate:status після оновлення.

Типові таблиці v1 (workflows, workflow_logs, workflow_signals, workflow_timers, workflow_exceptions, workflow_relationships) зберігаються для завершення виконання на v1. Якщо налаштовані моделі v1 перевизначають таблиці чи з'єднання зі сховищем, саме ці таблиці є джерелом істини v1.

3. За потреби оновіть конфігурацію

Конфігурація v2 зворотно сумісна. Якщо ви опублікували config/workflow.php у v1, він продовжить працювати. Нові параметри v2:

  • durable_types: псевдоніми типів для незалежних від мови посилань на workflow
  • task_repair_policy: обробка застряглих завдань
  • backend_capability_check: сувора чи дозвільна перевірка
  • projection_rebuild: стратегії відновлення з історії
  • history_budget: обмеження кількості подій для continue-as-new

Вони мають практичні типові значення. Змінюйте їх лише за потреби іншої поведінки. Докладніше в розділі Конфігурація.

Типовий кодек payload змінено на avro. v1 типово використовувала PHP-специфічний Workflow\Serializers\Y::class. v2 типово використовує незалежний від мови кодек avro, щоб worker інших мов могли декодувати payload без спільного PHP runtime. avro є єдиним підтримуваним кодеком для нових workflow v2. Нові workflow v2 отримують payload_codec = "avro".

Якщо у вас є опублікований config/workflows.php із v1 зі значенням 'serializer' => Workflow\Serializers\Y::class, v2 продовжує читати його для діагностики міграції, але payload нових workflow v2 використовує Avro. Після оновлення виконайте php artisan workflow:v2:doctor: команда позначить застарілий кодек як питання завершення чи імпорту роботи v1.

Щоб явно прийняти типове значення v2, не задавайте serializer або зафіксуйте його:

// config/workflows.php — v2 default (language-neutral, compact binary)
'serializer' => 'avro',

Зберігайте застарілий кодек ('workflow-serializer-y' чи 'workflow-serializer-base64') лише для завершення workflow v1, що обмінюються власними значеннями PHP між сервером і worker лише на PHP. Застарілі назви класів (Workflow\Serializers\Y::class тощо) залишаються псевдонімами для декодування v1.

Власні класи серіалізаторів v1 не підтримуються у v2. Публічний реєстр v2 розпізнає лише avro. Застарілі декодери workflow-serializer-y і workflow-serializer-base64 обмежені внутрішнім шляхом імпорту та завершення v1. Їх не можна вибрати для нового виконання v2 чи payload SDK. Якщо у вас був власний серіалізатор, завершіть виконання v1 до оновлення або перекодуйте історичний payload в avro: власний клас не викликається. php artisan workflow:v2:doctor позначає інші значення workflows.serializer як борг міграції. Відсутність кодека нового виконання означає avro.

Власні підкласи моделей підтримуються лише зі збереженням контракту колонок і ключів пакета. Зафіксована матриця налаштувань є авторитетним джерелом: підкласи моделей екземпляра, виконання, завдання, події історії, проєкції, schedule, activity, помилки, зв'язку, повідомлення, memo, атрибута пошуку та дочірнього виклику v2 підтримуються зі збереженням назв таблиць, первинних і зовнішніх ключів пакета. Власні назви таблиць із власними назвами колонок зовнішніх ключів виходять за межі контракту. Waterline читає проєкції v2 через контракт Workflow\V2\Contracts\OperatorObservabilityRepository, тому сумісний зі схемою підклас не потребує зміни Waterline.

Змінні середовища:

v2 не додає нових обов'язкових змінних середовища. Наявні QUEUE_CONNECTION, CACHE_DRIVER і DB_CONNECTION продовжують працювати.

4. Перезапустіть worker черги

Worker черги потрібно перезапустити для завантаження коду v2:

# If using Laravel queue workers
php artisan queue:restart

# If using Supervisor
sudo supervisorctl restart <your-worker-group>:*

# If using systemd
sudo systemctl restart laravel-worker

# If using Horizon
php artisan horizon:terminate

Worker:

  1. Завершать поточне завдання
  2. Коректно завершать процес
  3. Перезапустяться із завантаженим кодом v2

Worker мають перезапуститися до обробки workflow v2. Workflow v1 можуть завершуватися зі старими чи новими worker завдяки сумісності finish-on-v1.

Після оновлення​

1. Перевірте можливості бекенду

php artisan workflow:v2:doctor --strict

Очікуваний результат:

✓ Database driver supports required features
✓ Queue driver supports required features
✓ Cache driver supports locks
✓ All backend capabilities present

Якщо перевірка не пройшла, дивіться передумови драйверів у розділі Вимоги до бекенду.

2. Перевірте успішний запуск workflow v2

Запустіть тестовий workflow через API v2:

use Workflow\V2\WorkflowStub;
use Workflow\V2\StartOptions;

$workflow = WorkflowStub::make(TestWorkflow::class, 'test-upgrade');
$result = $workflow->start(['test' => true], new StartOptions());
$runId = $result->runId();

WorkflowStub::start() повертає об'єкт StartResult. Отримайте ID виконання через runId() перед порівнянням із рядками бази даних. Спроба порівняти повернений об'єкт із колонкою як звичайний рядок непомітно дає неправильне порівняння.

Перевірте:

  • Workflow відображається у Waterline
  • У таблиці workflow_instances є рядок із відповідним instance_id ($workflow->id())
  • У таблиці workflow_runs є рядок із відповідним run_id ($result->runId())
  • Workflow завершується чи просувається як очікується

3. Перевірте workflow v1, якщо вони є

Якщо у вас є активні workflow v1:

php artisan workflow:v1:list

Перевірте їх подальше просування. Workflow v1 мають завершитися на рушії v1 без помилок.

4. Перевірте журнали на помилки

Стежте за помилками workflow в журналах застосунку:

tail -f storage/logs/laravel.log | grep -i workflow

Типові проблеми:

  • Помилки просторів імен: код досі використовує Workflow\Workflow замість Workflow\V2\Workflow
  • Помилки методів: класам workflow чи activity v2 ще потрібно перейменувати початковий метод на handle()
  • Помилки драйвера черги: драйвер sync у режимі черги не підтримується. У режимі poll (workflows.v2.task_dispatch_mode=poll) черга не використовується для доставлення завдань, тому sync прийнятний

5. Перевірте спостережуваність Waterline

Відкрийте Waterline (типово /waterline) і перевірте:

  • Workflow v1, якщо вони є, відображаються з початковими даними
  • Workflow v2 відображаються з повними відомостями про виконання, історію й activity
  • Waterline відображається без помилок

Процедура відкату​

Відкат потребує узгодженого набору відновлення. Саме лише відновлення бази даних SQL workflow не відновлює активне виконання v1, якщо стан черги Laravel зберігається в Redis, SQS, іншій базі даних чи зовнішньому бекенді.

Якщо оновлення production не вдалося, повертайтеся лише до політики й моменту відновлення, вибраних до оновлення:

1. Призупиніть вхідні запити застосунку, планувальники й worker черги

Використайте ту саму процедуру зупинки, що й перед оновленням. Переконайтеся, що жоден worker не може зарезервувати завдання, а жоден запит не може запустити workflow чи надіслати signal під час відновлення стану.

2. Перевірте набір відновлення

  • Набір відновлення лише SQL підтримується, якщо на вибраний момент не було незавершеного виконання v1, що залежить від збереженої роботи в черзі. Придатний застарілий рядок pending може використовувати перевірений шлях Watchdog v1.0.77, описаний вище, а справжнє очікування лише signal може використовувати перевірений зовнішній вхід signal. Не поширюйте ці винятки на інші стани.
  • Набір відновлення активної роботи має містити SQL і відновлюваний стан готових, відкладених та зарезервованих завдань черги з того самого моменту для повторних спроб, timer, activity та роботи waiting або running. Для очікування лише signal потрібен справний вхід signal, для timer потрібні їхні відкладені завдання.
  • Якщо жодна умова не виконується, зупиніться. Виправте поточну версію, вручну узгодьте зафіксовані workflow або дійте відповідно до заздалегідь задокументованого прийняття невідновлюваності цих виконань.

3. Відновіть резервну копію бази даних

# MySQL/MariaDB
mysql -u root -p your_database < backup-v1-YYYYMMDD-HHMMSS.sql

# PostgreSQL
psql -U postgres -d your_database < backup-v1-YYYYMMDD-HHMMSS.sql

Відновіть усі налаштовані власні таблиці моделей v1 та workflow_relationships_table, навіть якщо вони використовують інше з'єднання.

4. За потреби відновіть стан черги на вибраний момент

Не запускайте споживачів. Дотримуйтеся процедури відновлення провайдера черги та відновіть точні з'єднання, черги, префікси, готові, відкладені й зарезервовані завдання, збережені разом із SQL. Відновіть потрібні блокування унікальних завдань, якщо вони входили до набору відновлення. Порожня черга з тією самою назвою не може пробудити відновлені повторні спроби, timer чи роботу waiting/running. Порожньої доступної для запису черги достатньо лише для придатного рядка pending після перевірки запуску Watchdog v1.0.77 і повторного направлення ним цього рядка.

5. Поверніть попередню залежність Composer

composer require durable-workflow/workflow:^1.0 --with-all-dependencies

durable-workflow/workflow є підтримуваною назвою пакета для підтримуваних версій v1 і v2. laravel-workflow/laravel-workflow є лише застарілим псевдонімом, оголошеним підтримуваним пакетом для сумісності зі старими графами залежностей. Не використовуйте його у вимогах відкату.

Отримайте точний APP_KEY за зафіксованими посиланням і версією в менеджері секретів, використовуючи окремо контрольовані облікові дані відновлення. До запуску споживачів відновіть його разом зі з'єднанням зі сховищем workflow, з'єднаннями й назвами черг, префіксами Redis та налаштуваннями власних моделей. Зашифровані завдання й серіалізовані посилання на моделі залежать від відповідності цієї конфігурації збереженому моменту відновлення.

6. Перезапустіть worker черги й відновіть вхідні запити

# Use the start command for your worker system, for example:
sudo supervisorctl start <your-worker-group>:*
sudo systemctl start laravel-worker
php artisan horizon:continue

7. Перевірте можливість продовжити виконання v1

Видимість у Waterline підтверджує відновлення рядка, але не здатність worker продовжити виконання. Перед оголошенням успішного відкату виконайте цей список:

  • composer show durable-workflow/workflow показує потрібну версію v1, а worker завантажили цей код.
  • Фактичні налаштовані таблиці v1 і workflow_relationships_table наявні на очікуваних з'єднаннях зі сховищем.
  • Кожен незавершений рядок налаштованої таблиці збережених workflow (типово workflows) класифікований за наступним шляхом пробудження: готове/відкладене/зарезервоване завдання черги, збережене завдання timer або перевірений зовнішній вхід signal. Придатний рядок pending може натомість посилатися на перевірені докази повторного направлення Watchdog v1.0.77 нижче.
  • Перевірка провайдера черги підтверджує наявність кожного залежного від черги пробудження повторної спроби, timer, activity та workflow waiting або running на зафіксованих з'єднанні й черзі. Сам рядок timer у SQL не задовольняє цю перевірку, а Watchdog не заміняє ці завдання.
  • Якщо відновлений рядок pending не має збереженого завдання workflow, спостерігається постановка Watchdog у чергу циклом worker v1.0.77. Коли рядок досягає п'ятихвилинної межі застарілості, Watchdog ставить workflow на його записані з'єднання й чергу, а рядок просувається. Без цієї наскрізної перевірки вважайте рядок застряглим, навіть якщо Waterline його показує.
  • Жоден відновлений рядок повторної спроби, timer, waiting чи running не позбавлений потрібного виконуваного завдання черги або доступного зовнішнього шляху signal для справжнього очікування signal. Такий рядок вважайте застряглим. Докази Watchdog лише для pending не роблять його відновлюваним.
  • Відновлена повторна спроба чи timer просувається далі позначки до знімка, а контрольоване очікування signal може поставити й обробити пробудження signal.
  • Новий контрольний workflow v1 завершується, а журнали не містять помилок відсутніх завдань, дешифрування, таблиць моделей, з'єднань чи маршрутизації черг.

За типових таблиць цей запит дає початковий перелік. Для власної моделі збережених workflow замініть таблицю на визначену цією моделлю:

SELECT id, class, status
FROM workflows
WHERE status NOT IN ('completed', 'failed', 'cancelled');

Важливі зауваження щодо відкату:

  • Відкат відкидає всі workflow v2, запущені після оновлення: вони існують лише в таблицях v2
  • Відкат лише SQL відновлює записи workflow v1, але не повідомлення зовнішніх черг
  • Активне виконання v1 підтримується лише за відновлення SQL і надійного стану черги з одного узгодженого моменту або за збереження доступного входу для задокументованого очікування лише signal. Додатковий виняток для SQL: придатний застарілий рядок pending із перевіреним повторним направленням Watchdog v1.0.77. Він не охоплює повторні спроби, timer чи роботу waiting/running
  • Відтворення стану до оновлення може повторити зовнішні побічні ефекти. Перевірте ідемпотентність застосунку перед відновленням activity з черги
  • Якщо потрібно зберегти workflow v2, запущені під час оновлення, не відновлюйте базу даних, а виправте проблему в поточній версії

Зміни коду​

Розділи нижче описують зміни коду, потрібні для переходу від API v1 до API v2.

Зміна простору імен​

Усі класи v2 належать до Workflow\V2. Оновіть імпорти:

// v1
use Workflow\Workflow;
use Workflow\Activity;
use Workflow\WorkflowStub;

// v2
use Workflow\V2\Workflow;
use Workflow\V2\Activity;
use Workflow\V2\WorkflowStub;

Початковий метод​

Workflow й activity v2 використовують handle() як початковий метод. Під час переходу перейменуйте методи execute() із v1 на handle():

// v1
class MyWorkflow extends Workflow
{
    public function execute($input)
    {
        $result = yield ActivityStub::make(MyActivity::class, $input);
        return $result;
    }
}

// v2
use function Workflow\V2\activity;

class MyWorkflow extends Workflow
{
    public function handle($input)
    {
        return activity(MyActivity::class, $input);
    }
}

Не залишайте execute() початковим методом workflow чи activity v2: runtime відхиляє його.

Виклики activity​

v2 замінює ActivityStub::make() і yield прямими функціями-помічниками:

// v1
$result = yield ActivityStub::make(MyActivity::class, $arg1, $arg2);

// v2
use function Workflow\V2\activity;

$result = activity(MyActivity::class, $arg1, $arg2);

Activity тепер мають надійну ідентичність. Кожна запланована activity отримує рядок activity_executions зі сталим ID виконання, а кожна конкретна спроба отримує рядок activity_attempts із типізованою історією.

Ідентичність workflow​

v2 розділяє ідентичність на ID екземпляра й ID виконання:

  • id(): публічний ID екземпляра workflow, спільний для переходів continue-as-new
  • runId(): ID поточного виконання

У v1 це було одним поняттям.

Signal​

v2 використовує іменовані очікування signal замість методів зміни стану з атрибутом #[SignalMethod]:

// v1
#[SignalMethod]
public function approve()
{
    $this->approved = true;
}

// v2
use function Workflow\V2\await;

$approved = await('approve');

Іменовані signal підтримують await('name') для блокувального очікування в коді workflow та signal() / attemptSignal() для зовнішніх даних. Скасування й примусове завершення залишаються явними командами runtime й не моделюються як signal.

Query​

v2 використовує безпечні для replay методи query замість прямого читання властивостей workflow:

// v1
#[QueryMethod]
public function getStatus(): string
{
    return $this->status;
}

// v2
use function Workflow\V2\query;

// Queries are defined as named, replay-safe accessors

Timer і побічні ефекти​

Функції-помічники заміняють статичні методи v1:

// v1
yield Timer::make(60);
$value = yield SideEffect::make(fn() => random_int(1, 100));

// v2
use function Workflow\V2\timer;
use function Workflow\V2\sideEffect;

timer(60);
$value = sideEffect(fn() => random_int(1, 100));

Тайм-аути​

v2 додає тайм-аути рівня workflow через StartOptions:

use Workflow\V2\StartOptions;
use Workflow\V2\WorkflowStub;

$workflow = WorkflowStub::make(MyWorkflow::class, 'order-123');

$workflow->start(
    $orderId,
    StartOptions::rejectDuplicate()
        ->withExecutionTimeout(7200)   // 2 hours across all runs
        ->withRunTimeout(3600),        // 1 hour per run
);
  • Тайм-аут виконання охоплює весь екземпляр, включно з переходами continue-as-new.
  • Тайм-аут run діє для одного виконання та починається заново після continue-as-new.

Міграції бази даних​

v2 додає нові таблиці й колонки. Пакет автоматично завантажує свої міграції, тому після оновлення виконайте:

composer update durable-workflow/workflow
php artisan migrate

Версія 2.0.0 включає базові міграції таблиць для чистого встановлення. Звичайний шлях: дозволити Laravel автоматично завантажити міграції пакета та виконати php artisan migrate.

Якщо ви раніше опублікували міграції Durable Workflow у застосунку, виберіть одне джерело міграцій і підтримуйте його актуальним:

  • Автоматично завантажувані міграції пакета: видаліть старі опубліковані файли міграцій Durable Workflow із database/migrations і виконайте php artisan migrate.

  • Опубліковані міграції: опублікуйте поточний набір перед застосуванням:

    php artisan vendor:publish \
      --provider="Workflow\Providers\WorkflowServiceProvider" \
      --tag=migrations \
      --force

    php artisan migrate

Не залишайте застарілі опубліковані файли одночасно з використанням нових автоматично завантажуваних файлів пакета. Інакше застосунок може не отримати новіші таблиці v2 чи виправні міграції.

Якщо ви змінили файли міграцій, під час кожного оновлення порівнюйте свої копії з каталогом src/migrations пакета. Зберігайте назви таблиць, колонки, індекси та правила nullable/default сумісними зі схемою моделей пакета. Якщо власна інсталяція направляє таблиці workflow на нетипове з'єднання, опублікуйте міграції, задайте їхній $connection і далі переносіть кожну нову міграцію пакета в порядку часових позначок.

Для користувачів попередніх версій v2 колонка workflow_run_summaries.memo відновлюється ідемпотентно, якщо старіша опублікована міграція таблиці зведень створила workflow_run_summaries без цієї колонки. Чисті інсталяції вже створюють її в базовій міграції таблиці зведень.

Перевірка можливостей бекенду​

v2 перевіряє відповідність драйверів черги, бази даних і кешу своїм вимогам. Після оновлення виконайте команду doctor:

php artisan workflow:v2:doctor --strict

Конфігурація​

v2 додає кілька параметрів конфігурації. Розділ Конфігурація описує:

  • Псевдоніми надійних типів
  • Політику відновлення завдань
  • Перевірки можливостей бекенду
  • Відновлення проєкцій
  • Бюджети історії та приховування даних в експорті

Waterline​

Waterline, інтерфейс моніторингу, оновлено для v2:

  • Деталі виконання показують тривалості тайм-аутів і дедлайни
  • Відстеження спроб activity зі сталими ID
  • Оновлене відображення статусів workflow

Continue-as-new​

v2 додає бюджети історії, що можуть автоматично запускати continue-as-new після перевищення межі кількості подій. Метадані (memo, атрибути пошуку, тайм-аути) переносяться між виконаннями.

Наявні workflow​

Стратегія finish-on-v1​

Workflow, запущені на v1, продовжують виконання через шляхи сумісності v1. Нові workflow після оновлення використовують семантику v2. Мігрувати активні екземпляри workflow не потрібно.

Після оновлення до 2.0:

  1. Дані v1 зберігаються: типові таблиці workflows, workflow_logs, workflow_signals, workflow_timers, workflow_exceptions і workflow_relationships залишаються цілими, а налаштовані перевизначення моделей і таблиць v1 залишаються авторитетними
  2. Workflow v1 завершуються на рушії v1: активні workflow v1 продовжують виконання на рушії replay v1 до термінального стану
  3. Workflow v2 використовують рушій v2: усі workflow після оновлення використовують схему v2 (workflow_instances, workflow_runs, workflow_history_events тощо)
  4. Waterline показує обидві версії: інтерфейс моніторингу відображає workflow v1 і v2 поруч

Finish-on-v1 також залежить від бекенду черги Laravel. Зберігайте кожне з'єднання та чергу v1 до завершення їхніх workflow. Рядки бази даних зберігають історію й статус, але не відтворюють втрачені готові, відкладені чи зарезервовані завдання зовнішнього бекенду. Watchdog v1.0.77 може повторно направити придатний застарілий workflow pending із SQL, але цей обмежений шлях не відтворює повторні спроби, timer чи роботу waiting/running.

Відстеження завершення workflow v1​

Щоб побачити workflow v1, які залишаються активними після оновлення:

php artisan workflow:v1:list

Ця команда показує всі workflow v1, що ще не досягли термінального стану (completed, failed, cancelled). Відстежуйте нею завершення workflow v1.

Приклад результату:

+--------------------------------------+---------------------+-----------+------------+
| ID                                   | Class               | Status    | Created    |
+--------------------------------------+---------------------+-----------+------------+
| 01J1234567890ABCDEFGHIJK             | App\OrderWorkflow   | running   | 2 days ago |
| 01J9876543210ZYXWVUTSRQP             | App\InvoiceWorkflow | pending   | 1 day ago  |
+--------------------------------------+---------------------+-----------+------------+

Видимість у Waterline​

Після оновлення до 2.0 Waterline автоматично показує workflow з обох рушіїв:

  • Workflow v1 відображають початкові дані StoredWorkflow: клас, статус, журнали, signal, винятки
  • Workflow v2 відображають повні деталі v2: виконання, події історії, timer, activity, атрибути пошуку

Налаштування не потрібне. Waterline читає обидва набори таблиць і надає спільний перегляд.

Коли видаляти таблиці v1​

Коли всі workflow v1 завершилися, що підтверджує нуль активних workflow у workflow:v1:list, можна за бажанням видалити таблиці v1:

DROP TABLE IF EXISTS workflow_relationships;
DROP TABLE IF EXISTS workflow_exceptions;
DROP TABLE IF EXISTS workflow_timers;
DROP TABLE IF EXISTS workflow_signals;
DROP TABLE IF EXISTS workflow_logs;
DROP TABLE IF EXISTS workflows;

Важливо: не видаляйте ці таблиці, доки хоч один workflow v1 залишається активним. Це спричинить збій replay v1 і залишить workflow застряглими.

Навіщо finish-on-v1?​

Стратегія finish-on-v1 дозволяє оновлення без примусової міграції даних. v1 і v2 мають принципово різні моделі зберігання:

  • v1 зберігає стан workflow у денормалізованому рядку workflows із пов'язаними журналами, signal і timer
  • v2 зберігає стан workflow як історію подій із проєкціями (workflow_instances, workflow_runs, workflow_history_events)

Перетворення активних workflow v1 на історію v2 потребувало б відновлення послідовностей подій із журналів v1, що створює ризик втрати даних і неузгодженості replay. Finish-on-v1 дозволяє workflow v1 безпечно завершитися на початковому рушії, а новій роботі одразу перейти до v2.