Бізнесові автомати станів
API Workflow\V2\StateMachine, а також підтверджений запуск дочірнього
workflow (Workflow::startChild()) і DurableScope::reserveChild(), які він
використовує, є експериментальними. Вони постачаються як експериментальні з
Workflow 2.29.0, не підпадають під гарантії стабільності пакета й можуть
змінитися в мінорному релізі. Вони є поверхнею experimental за
рівнями стабільності. Решта API
збережених областей компенсації, який він використовує, стабільна з Workflow
2.33.0.
Приклади на цій сторінці — це приклади з вихідного коду репозиторію із синтетичними провайдерами. Вони не є кваліфікацією встановленого пакета чи реального провайдера. Ніщо на цій сторінці не означає:
- міграції виконання, що вже триває, на нову версію визначення, профілю, правила чи обробника;
- рекурсивних або спільних дочірніх автоматів;
- гарантій для будь-якого реального платіжного провайдера, перевізника чи складу;
- що функцію бізнесових автоматів станів завершено або що вона має стабільний реліз.
Цей посібник описує необов’язковий бізнесовий протокол переходів для вбудованих
Laravel workflow з Workflow\V2\Workflow. Його побудовано з наявних примітивів:
activity, дочірніх workflow, стійких очікувань, replay і компенсації
Saga. Наявні workflow і Workflow\States\StateMachine не
змінюються.
Коли його використовувати
Використовуйте протокол, коли бізнес-стани мають одне спільне значення, але спосіб їх досягнення відрізняється між інтеграціями:
- Спільні значення автомата. Один
MachineDefinitionоголошує значення станів, ідентичності переходів, обов’язковий інваріант та іменовані дочірні слоти. - Політики окремих інтеграцій. Кожен
PolicyProfileвибирає свої ребра, версії обробників та іменовані умови в межах цього визначення. Одна інтеграція може вимагати зовнішньої операції перед переходом; інша може вже надати докази й пропустити роботу. - Вкладені дочірні автомати. Order може розміщувати автомат Shipment, поки перебуває в оголошеному стані. Прив’язка зберігає початкову ідентичність дочірнього автомата під час повторних спроб, змін стану й перезапусків worker.
- Захищені бізнес-рішення. Новий бізнес-стан фіксується через межу, якою володіє застосунок і яка перевіряє очікуваний стан, ревізію та прийняте скасування.
- Збережена компенсація. Зобов’язання можуть існувати довше за запуск, який їх створив, завдяки збереженим областям компенсації.
Якщо достатньо одного workflow із saga, використовуйте безпосередньо Saga і Дочірні workflow.
Контракт переходу
Кожен обробник переходу реалізує ті самі чотири методи незалежно від автомата чи інтеграції:
interface TransitionStep
{
public function canTransition(TransitionContext $context): bool;
public function canExecute(TransitionContext $context): bool;
public function execute(TransitionContext $context): ExecutionReceipt;
public function compensate(TransitionContext $context, ExecutionReference $originalExecution): void;
}
canTransition()відповідає, чи ціль уже досягнуто. Це чиста проєкція записаної оцінки цілі.canExecute()відповідає, чи роботу дозволено. Це чиста проєкція записаної оцінки дозволу.execute()оркеструє записані activity або стійкі очікування й повертаєExecutionReceipt. Квитанція підтверджує роботу; вона не встановлює готовності до фіксації.compensate()отримує початковийExecutionReference. Повертайте керування лише після того, як потрібні ефекти або їхню відсутність перевірено. Невідома робота чи робота, що очікує, має чекати або явно завершуватися помилкою, але ніколи не повертатися успішно.
Розширте AssessedTransitionStep, щоб реалізувати дві охоронні умови
безпосередньо із записаного знімка. Виконавець відхиляє власну охоронну умову,
яка суперечить записаній оцінці.
Як виконавець виконує перехід
TransitionRunner::run() приймає workflow, закріплений профіль, початковий
ExecutionReference, подію, TransitionRuntime і закритий реєстр обробників.
Потім він:
- Вибирає єдине ребро для події та вихідного стану. Якщо кандидатів немає,
повертається
Unavailable; якщо їх кілька —Ambiguous. - Запитує записаний знімок
beforeі, якщо профіль має визначення, перевіряє його спільний інваріант. Невиконаний інваріант повертаєBlocked; невідомий —Unknown. - Перевіряє охоронну умову цілі. Якщо ціль досягнуто, робота пропускається,
але перехід усе одно проходить через захищену фіксацію; пропуск не переймає
володіння зовнішніми ефектами, які вже існують. Невідома ціль повертає
Unknown. - Повертає
Pending, коли ребро не оголошує роботи. Інакше перевіряє охоронну умову виконання й записує живий допуск. Відмова повертаєBlocked; невідома відповідь —Unknown. - Реєструє компенсацію початкового кроку в нативному Saga, а потім викликає
execute(). - Запитує свіжий знімок
afterі знову перевіряє інваріант та ціль. Застарілий вихідний стан чи ревізія повертаєConflict, невиконаний результат —Pending, а невідомий —Unknown. Досягнута ціль переходить до захищеної фіксації. - Фіксує через runtime, який повідомляє
Committed,ConflictабоCancellationRequested.
Значення TransitionStatus — це результати обробки, а не ваш каталог
бізнес-станів. Виконавець ніколи не повторює перехід повністю й ніколи сам не
компенсує заблокований перехід. Застосунок вирішує, чи чекати, повторювати,
звіряти або компенсувати. Результат не є дозволом закрити workflow, якому
належить перехід: тримайте його відкритим, поки залишаються пряма робота чи
зобов’язання компенсації.
ActivityTransitionRuntime реалізує TransitionRuntime за допомогою трьох
activity застосунку (знімок, допуск і фіксація) та необов’язкового
MachineDefinition. Він використовує звичайну історію activity і не додає
жодної команди worker чи події історії. У налаштованому прикладі Order/Shipment
кожен перехід проходить через той самий виклик виконавця:
return (new TransitionRunner())->run(
$this->workflow,
$this->profile,
$execution,
Catalogue::transition($this->profile, $key)->event,
new ActivityTransitionRuntime(
SnapshotActivity::class,
AdmissionActivity::class,
CommitActivity::class,
$this->profile->definition
),
$handlers
);
Три класи activity — це код застосунку, а не класи пакета.
Визначення, профілі та версії
MachineDefinition містить те, що спільне для всіх інтеграцій. Визначення
версії два з прикладу оголошує чотири стани, ідентичності переходів, правило
інваріанта та дочірній слот Shipment:
return new MachineDefinition(
$machine,
'2',
[
new MachineState('received', 'Business input accepted; completion has not been committed.'),
new MachineState('working', 'Original work admitted; business completion remains pending.'),
new MachineState('completed', 'The original execution has verified its required business outcome.'),
new MachineState('cancelled', 'Original compensation verified and business cancellation committed.'),
],
$machine === 'orders' ? ['begin', 'finish', 'cancel', 'reconcile'] : ['deliver'],
self::fact('model_consistent'),
$machine === 'orders' ? [
new ChildSlot('shipment', ['received', 'working'], 'shipments', '2', 'completed'),
] : []
);
PolicyProfile::forDefinition() приєднує до цього визначення ребра
TransitionDefinition та іменовані умови інтеграції. Профіль не може додати
неоголошений стан чи ідентичність переходу, а іменовані умови профілю не можуть
замінити спільний інваріант.
Версіонування підпорядковується таким правилам:
- Відбитки. Відбиток визначення охоплює значення станів, інваріант і оголошення слотів. Відбиток профілю охоплює метадані визначення й профілю, граф, структури умов, версії обробників і будь-які обмеження. Жоден із них не хешує реалізації PHP.
- Закріплені виконання.
ExecutionReferenceзакріплює область, бізнес-суб’єкт, ID виконання, відбиток політики, очікуваний вихідний стан і ревізію. Записуйте вибраний відбиток до початку роботи й передавайте його знову під час replay. Ніколи не обчислюйте його з найновішої конфігурації під час відновлення. - Лише нові виконання. Нова версія визначення чи профілю вибирається для нових виконань. Переписування призначення суб’єкта, що виконується, змінює його відбиток, і тоді початкове виконання відмовляє. API для міграції виконань, що вже тривають, немає.
- Збережені реалізації. Тримайте розгорнутими старі визначення, правила,
обробники та версії авторизації, поки їхні виконання або збережені
зобов’язання залишаються відновлюваними. Обробники надходять із закритого
реєстру тип/версія з ключем
TransitionDefinition::handlerKey(). Збережені дані не можуть вибрати клас PHP, а відсутній обробник спричиняє помилку до будь-якого вводу-виводу застосунку.
Загальні правила зміни коду workflow описано в розділі Керування версіями.
Правила, умови та записані факти
Конфігурація вибирає умови; реалізації правил залишаються довіреним кодом
застосунку. RuleRegistry, створений під час довіреного початкового
завантаження, зіставляє тип і версію правила з об’єктом ConditionRule.
RuleReference закріплює тип, версію та параметри, а
ConditionDefinition::rule(), all(), any() і not() поєднують ці листки.
Умова має щонайбільше 64 вузли.
Рішення мають три значення: Verdict::Satisfied, Verdict::Unsatisfied і
Verdict::Unknown. Для all() невиконаний дочірній вузол робить групу
невиконаною; інакше невідомий дочірній вузол робить її невідомою. Для any()
виконаний дочірній вузол робить групу виконаною; інакше невідомий дочірній
вузол робить її невідомою. Заперечення невідомого залишається невідомим.
Факти збираються лише в записаній activity знімка. AssessmentStore з
прикладу записує факти з посиланнями на докази й обчислює умови цілі та
дозволу профілю:
$facts = new RecordedFacts($id, $values, array_combine(array_keys($values), array_map(
static fn (string $name): string => 'recorded-fact:' . $id . ':' . $name,
array_keys($values)
)));
$registry = Catalogue::registry();
$target = $registry->evaluateCondition($profile->condition($transition->key . '.target'), $facts);
$permission = $registry->evaluateCondition($profile->condition($transition->key . '.permission'), $facts);
Якщо профіль має визначення, та сама activity обчислює
MachineDefinition::assess() і повертає MachineAssessment::fromEvaluation()
як machineAssessment знімка. Зберігайте повне пояснення
ConditionEvaluation::toArray() разом зі знімком. Відсутня оцінка, змінене
визначення чи змінена умова спричиняють відмову до початку роботи. Записана
оцінка — це доказ хоста, а не авторизація: захищена фіксація все одно має
перевірити живі повноваження, ревізію та скасування.
Детермінований replay
Протокол спирається на записану історію, тому звичайні обмеження workflow застосовуються суворо:
- Охоронні умови й правила не виконують вводу-виводу. Вони не читають базу даних, конфігурацію, провайдера чи контейнер.
- Живі читання відбуваються всередині activity знімка. Під час replay завершені activity повертають свої записані результати; правила не обчислюються повторно на живих даних.
- Знімок
afterмає використовувати інший ID знімка й щойно зібрані факти.SnapshotPhaseрозділяє доказиbefore,afterіcompensation, тож одна фаза не може підмінити іншу. execute()іcompensate()викликають activity. Обгортайте синхронний провайдер чи обробник застосунку в activity; прямий виклик із коду workflow може повторити його ефекти під час replay.- Допуск записує лише повноваження та дозвіл. Він не повинен виконувати прямий бізнес-ефект до реєстрації в Saga.
- Використовуйте
TransitionResult::toArray()на межах workflow та історії. Доменні об’єкти застосунку залишаються за вашими адаптерами кроку й runtime.
Захищені бізнес-фіксації
Activity фіксації є бізнес-повноваженням застосунку. Вона має:
- Прив’язати ID рішення до його області, суб’єкта, політики, переходу та вмісту. Точний дублікат повертає записаний результат; повторне використання ID для іншого вмісту спричиняє відмову.
- Повторно перевірити живі повноваження, очікуваний вихідний стан і ревізію, а також будь-яке прийняте скасування під авторитетним блокуванням застосунку.
- Атомарно записати бізнес-стан, рішення та будь-який намір публікації, якщо вони мають спільне сховище.
- Після втраченого підтвердження знайти або повторити саме це рішення замість повторення ефектів.
Вона повертає CommitResult зі статусом committed, conflict або
cancellation_requested. Останній статус означає, що прийняте скасування
запобігло цій фіксації. Він не означає, що компенсацію завершено чи що
бізнес-сутність скасовано. Розподілена транзакція між сховищем застосунку й
Durable Workflow не передбачається.
Дочірні автомати, прив’язані до станів батька
ChildSlot у визначенні батька називає слот, його стани розміщення, дочірній
автомат і версію визначення, а також потрібний бізнес-результат.
MachineDefinition::assertBinding() перевіряє прив’язку щодо цього
оголошення. Він не виконує пошуку, авторизації чи допуску.
BindingIdentity закріплює початкове виконання батька, namespace, екземпляр і
запуск батька, слот, покоління, стан розміщення, тип дочірнього workflow,
відбиток політики дочірнього автомата, потрібний результат, відбиток вхідних
даних і параметри дочірнього запуску. Покоління ідентифікує один вхід у стан.
Запити для старого покоління ніколи не перенаправляються до новішого
дочірнього автомата після того, як батько змінює стан або повторно входить у
нього.
Запуск дочірнього автомата й очікування на нього — окремі переходи:
- Запуск. Батько резервує та допускає дочірній автомат, записує точну
прив’язку і лише потім фіксує стан розміщення. Якщо прив’язку вже записано,
крок повторно використовує її замість нового запуску. Зі збереженими
областями
DurableScope::reserveChild()повертаєChildReservation, аChildReservation::start()використовує підтверджений нативний запуск дочірнього workflow. ПізнішеChildReservationStore::close()повертає або допущенийChildBinding, або остаточнийNeverAdmittedChild. - Очікування. Пізніший перехід спостерігає той самий допуск. Він не створює ні другого дочірнього автомата, ні другого власника компенсації.
Спільний крок прикладу показує обидва переходи:
if ($key === 'begin') {
$childScope = Ownership::childScope($execution);
$reservation = $this->scope->reserveChild(
$execution->executionId . '.shipment',
$childScope,
Ownership::binding(
$execution,
$this->initialization['rootRun'],
$this->initialization['integration'],
$this->initialization['version']
)
);
$existing = Workflow::activity(BoundaryActivity::class, 'binding', [
'reservation' => $reservation->toArray(),
]);
if ($existing === null) {
$reservation->start(
$execution->subject,
$this->initialization['rootRun'],
$execution->toArray(),
$childScope->toArray()
);
$existing = Workflow::activity(BoundaryActivity::class, 'record-start', [
'reservation' => $reservation->toArray(),
]);
}
$binding = ChildBinding::fromArray($existing);
$operations[] = 'child:' . $binding->admission->childRunId;
} elseif ($key === 'finish') {
$value = Workflow::activity(BoundaryActivity::class, 'active-binding', []);
$binding = ChildBinding::fromArray($value);
$outcome = StartedChildWorkflow::fromArray($binding->admission->toArray())->await();
Workflow::activity(BoundaryActivity::class, 'outcome', [
'binding' => $value,
'outcome' => $outcome,
]);
} elseif ($key !== 'deliver') {
throw new LogicException('A proof-only transition must not dispatch work.');
}
Без резервування Workflow::startChild() повертає квитанцію
StartedChildWorkflow, на яку пізніший крок може виконати await(). Батько
має перевірити бізнес-результат дочірнього workflow; технічного завершення
дочірнього workflow, прийнятого signal чи тайм-ауту недостатньо.
Workflow::startChild() доступний лише у вбудованому режимі; виконання через
протокол worker його відхиляє.
Компенсація та збережені області
Виконавець реєструє початковий крок у нативному Saga, перш ніж execute()
зможе призупинитися чи завершитися помилкою. Зворотний виклик захоплює
початкове виконання й крок, а не квитанцію. Під час компенсації виконавець
запитує свіжий знімок compensation і викликає compensate() з початковим
виконанням. Використовуйте типову послідовну компенсацію.
Локальний для запуску зворотний виклик Saga завершується разом зі своїм
запуском. Збережені області компенсації (Workflow\V2\Compensation)
зберігають кожне зобов’язання у стійкому журналі, тож його можна компенсувати
після закриття запуску, що його створив. Цей API і те, які його частини
стабільні, описано в посібнику з областей компенсації.
У прикладах кожен зовнішній ефект реєструється як
Obligation через DurableScope::execute() до його відправлення, а дочірню
область перевіряють до скасування попередніх ефектів батька. Потім власна
компенсація кроку перевіряє лише його початкові зобов’язання:
public function compensate(TransitionContext $context, ExecutionReference $originalExecution): void
{
Workflow::activity(RequestScopeActivity::class, $this->identity->toArray(), $this->principal);
// Scope callbacks registered within execute() run first. Check only this step's original subset:
// verifying the whole scope here would block earlier steps before their callbacks can run.
Workflow::activity(BoundaryActivity::class, 'verify-step', [
'execution' => $originalExecution->toArray(),
'key' => $context->transition->key,
]);
}
Бізнес-скасування — це окреме рішення. У прикладах суто доказовий перехід
фіксує cancelled лише після перевірки збереженої області. Технічне
скасування, запит на відновлення в черзі чи невдала компенсація його не
встановлюють. Поточний збережений граф має один рівень батько/дитина,
щонайбільше 16 дочірніх елементів і 256 зобов’язань на область. Пряме
володіння кореня й дочірнього елемента не переходить до наступників
continue-as-new чи redrive, а зняття утримання залишається явним.
Бюджети та явні результати
Довірена конфігурація може обмежити автомат:
DefinitionLimits(states,transitions,childSlots,ruleNodes) передається вMachineDefinitionякlimits:. Кожен прив’язаний профіль також перевіряє свої розгорнуті ребра вихідних станів і загальну кількість вузлів умов.ExecutionLimits(commands,historyEvents,historyBytes,groupDepth) приєднується черезPolicyProfile::withLimits()або аргументlimits:методуPolicyProfile::forDefinition(). Бюджет команд охоплює кожне стійке призупинення всерединіTransitionRunner, до 4096 команд і 64 рівнів груп. Значення історії — це пороги допуску, виміряні черезWorkflow::historyBudgetAtStep()перед кожною командою, а не абсолютні межі.
Обидва обмеження входять до своїх відбитків. Якщо їх не задано, попередні відбитки зберігаються; додавання чи зміна бюджету потребує явно вибраної версії для нових виконань.
Бюджет, вичерпаний під час виконання, повертає TransitionStatus::Blocked з
причиною state_machine_<dimension>_limit_exceeded. Недійсне визначення
спричиняє ResourceLimitExceeded із виміром, спостереженою кількістю та
лімітом до запуску будь-якого обробника. Жоден із цих результатів не означає,
що скасування вдалося чи що попередній зовнішній ефект не відбувся.
Workflow::compensate() виконується поза бюджетами прямої роботи.
Діагностика
TransitionResult::toArray()повертає виконання, статус, причину, оцінку та ключ переходу.ConditionEvaluation::toArray()зберігає відбиток структури, ID знімка, версії правил, причини, посилання на докази та відсутні факти.MachineAssessment::toArray()записує рішення щодо інваріанта, прив’язане до визначення та знімка.ResourceLimitExceededнадаєdimension,observedіlimit.ScopeRecovery::describe()повідомляє стан збереженої області, зокрема коли потрібен свіжий авторизований запит на скасування.
Виконувані приклади
Приклади містяться в репозиторії workflow і запускаються з його залежностями для розробки та тестовою базою даних. Вони використовують власні одноразові таблиці застосунку, а не міграції пакета.
| Приклад | Що він демонструє |
|---|---|
| Налаштовані Order і Shipment | Два профілі інтеграції, prepare та imported, з однаковими станами й одним спільним кроком. Підготовка розміщує Shipment у working; імпорт — у received. Суто доказове ребро reconcile пропускає роботу, коли докази вже є. Версія два додає спільні визначення для нових суб’єктів, тоді як версія один залишається закріпленою. Містить резервування дочірнього автомата, збережену компенсацію та фіналізацію скасування. |
| Order, Payment і Shipment із провайдером | Три автомати на тому самому протоколі із синтетичним журналом провайдера. Рецепти охоплюють оформлення замовлення спочатку з резервуванням і спочатку з оплатою, результати повернення коштів, авторизацію та списання після наявності товару чи доставки, фінансування банківським переказом, накладеним платежем (COD), авансом із доплатою залишку та підпискою, оренди Cart, грошові суми в мінімальних одиницях, часткову наявність товару, повернення, обміни, інциденти перевізника та відновлення після втрати worker. |
| Бізнес-рішення в SQL | Захищена фіксація, якою володіє застосунок, з SQL-огородженням (fencing) для скасування, конфліктів ревізій, відкликання повноважень, наміру публікації та втрачених підтверджень, а також нативна вкладена компенсація Order і Shipment. |
Запустіть тести налаштованого прикладу з репозиторію workflow:
vendor/bin/phpunit tests/Feature/V2/V2ConfiguredStateMachineExampleTest.php
Усі три приклади використовують синтетичних провайдерів або провайдерів у тій самій базі даних. Вони не кваліфікують реального перевізника, платіжного провайдера чи склад, оновлення встановленого пакета або міграцію виконань, що вже тривають. Реальна інтеграція має сама забезпечити ідемпотентність, огородження та звірку невизначених результатів.
Довідник бізнесових автоматів станів репозиторію рушія документує повний контракт, зокрема форми payload activity. Стан реалізації відстежується в durable-workflow/workflow#1069.