Stāvokļu mašīnas

Skatīt kā Markdown Rediģēt vietnē GitHub Dokumentācija vietnē 2cc7b2b

Stāvokļu mašīnas un darbplūsmas risina atšķirīgus uzdevumus.

Darbplūsma atbild uz jautājumu: "Kāds darbs jāveic tālāk?" Stāvokļu mašīna atbild uz jautājumu: "Kādā stāvoklī atrodas šis objekts, un kādi notikumi šajā stāvoklī ir derīgi?" Šī atšķirība ir svarīga, ja veidojat nevis vienkāršu darbību secību, bet gan ilgstoši pastāvošu objektu, kas laika gaitā reaģē uz ārēju ievadi, piemēram, aģenta sesiju, tērzēšanas pavedienu, pārskatīšanas dzīves ciklu, pieteikumu vai apstiprināšanas plūsmu.

Īss piemērs

PHP

use Queuety\Enums\StateMachineStatus;
use Queuety\Queuety;

$machine_id = Queuety::machine( 'agent_session' )
    ->version( 'agent-session.v1' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'awaiting_review' )
    ->state( 'awaiting_review' )
    ->on( 'approve', 'completed', ReviewApprovedGuard::class )
    ->on( 'reject', 'awaiting_user' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

Queuety::machine_event(
    $machine_id,
    'user_message',
    [ 'message' => 'Find competitors for this product' ]
);

Queuety::machine_event(
    $machine_id,
    'approve',
    [ 'approved' => true, 'reviewer' => 'editor@example.com' ]
);

Šī mašīna sākas stāvoklī awaiting_user, pāriet stāvoklī planning, kad tiek saņemta lietotāja ziņa, ļauj rindā ievietotajai darbībai izdot planned un pēc tam gaida stāvoklī awaiting_review, līdz ārējs apstiprinājums pabeidz sesiju. Svarīga ir nevis pati koda sintakse, bet gan tas, ka dzīves cikls ir skaidri definēts, pārskatāms un notikumu vadīts.

Kā darbojas mašīna

Kad tiek nosūtīta mašīnas instance, Queuety saglabā pašreizējā stāvokļa nosaukumu, publiskā stāvokļa datus, definīcijas versiju un jaucējvērtību, pašreizējam stāvoklim derīgos ienākošos notikumus un noturīgu notikumu laika skalu.

Ja ievadītajam stāvoklim ir action(), Queuety ievieto rindā stāvokļa ievades uzdevumu. Šī darbība var vienkārši atjaunināt publisko stāvokli un likt mašīnai gaidīt nākamo notikumu, vai arī izdot _event un pēc izvēles _event_payload, lai uzreiz veiktu nākamo pāreju. Ja stāvoklim nav darbības un tas nav termināls, mašīna vienkārši gaida ārējos notikumus, kas nosūtīti ar Queuety::machine_event().

Kad izvēlēties darbplūsmu vai stāvokļu mašīnu

Izmantojiet darbplūsmu, ja izpilde pamatā sastāv no secīgiem soļiem. Iegūstiet datus, gaidiet katru uzdevumu, apkopojiet rezultātus, pabeidziet. Šis modelis ir piemērots, ja ir skaidrs sākums un beigas un galvenais jautājums ir, kāds darbs jāveic tālāk.

Izmantojiet stāvokļu mašīnu, ja derīgā darbība ir atkarīga no pašreizējā dzīves cikla posma. Tā ir piemērotāka, ja notikumi var pienākt dažādā secībā, objekts var pastāvēt ilgu laiku vai ir skaidri jāpārskata dzīves cikls ar tādiem stāvokļiem kā awaiting_user, planning, running_agents, awaiting_review un completed.

Kā abas pieejas sadarbojas

Abi pamatmehānismi vislabāk darbojas kopā. Stāvokļa darbība var nosūtīt darbplūsmu, ja pārejai nepieciešama apjomīgāka izpilde, savukārt darbplūsma pēc darba pabeigšanas var nosūtīt notikumu atpakaļ mašīnai. Praksē tā stāvokļu mašīna pārvalda dzīves ciklu, bet darbplūsmas veic sarežģītu vai strukturētu izpildi.

Veidotāja struktūra

StateMachineBuilder ir apzināti vienkāršs. initial() un state() definē dzīves cikla grafu. action() piesaista rindā ievietoto darbu vienam stāvoklim. on() nosaka, kuri notikumi var pārvietot mašīnu uz nākamo stāvokli. on_queue(), with_priority() un max_attempts() nosaka, kā tiek izpildītas stāvokļa darbības, savukārt version() un idempotency_key() pievieno noturīgus nosūtīšanas metadatus. dispatch() izveido mašīnas instanci.

Stāvokļa darbībām var būt arī neobligāta metode config(), kurā izmanto tās pašas resursu politikas atslēgas kā darbplūsmas soļos un apstrādātājos. Tas ļauj iekļaut dārgu stāvokļa pāreju koplietojamā vienlaicīguma grupā vai piešķirt lielāku izmaksu svaru darbībai, kas patērē vairāk budžeta nekā parasts solis.

Plašāks resursu modelis ir aprakstīts sadaļā Resursu pārvaldība.

Līgumi

Stāvokļa ievades darbības implementē Queuety\Contracts\StateAction:

PHP

namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}

$payload ir strukturēti dati no darbības definīcijas; ja darbība norādīta kā vienkāršs klases nosaukums, tie ir tukši. Queuety izveido darbības ar new $class(), tāpēc darbības klases konstruktoram nedrīkst būt obligātu argumentu.

Stāvokļa darbībām var būt arī neobligāta metode config() ar concurrency_group, concurrency_limit un cost_units, ja rindā ievietotajai ievades darbībai jāpiedalās darbinieku piekļuves kontrolē, svērtās rindas vai pakalpojumu sniedzēju budžetos un citās resursu politikās.

Pāreju nosacījumi implementē Queuety\Contracts\StateGuard:

PHP

namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}

Pārbaudes API

Izmantojiet fasādi, lai pārbaudītu darbojošās mašīnas:

PHP

$status   = Queuety::machine_status( $machine_id );
$machines = Queuety::list_machines();
$events   = Queuety::machine_timeline( $machine_id );
$trace    = Queuety::machine_trace( $machine_id );
$state    = Queuety::machine_state_at( $machine_id, $event_id );

Stāvokļu mašīnām nav WP-CLI komandu: wp queuety workflow ... aptver tikai darbplūsmas. Izmantojiet šīs PHP API, piemēram, ar wp eval palīdzību, lai pārbaudītu mašīnas komandrindā.

Šīs API nodrošina pašreizējā stāvokļa nosaukumu, dzīves cikla statusu, publisko stāvokli, pieejamos notikumus, definīcijas metadatus, pilnu pāreju laika skalu un normalizētu izsekojuma datu kopu atkļūdotāja saskarnēm. Mašīnu saraksta ierakstos ir definīcijas versija un jaucējvērtība, kā arī idempotences atslēga, lai saraksta ekrānos varētu parādīt pirmkoda un izpildlaika versiju, neielādējot katru mašīnu atsevišķi. Izsekojuma datu kopā ir grupēti stāvokļi, neapstrādāti notikumi, saistītie darbību uzdevumi, žurnāli, artefaktu un fragmentu atsauces, apstrādātāja ievade un izvade, stāvoklis pirms un pēc darbības, konteksts, laika mērījumi un strukturētas kļūdas.

Aģentu sesijas

Stāvokļu mašīnas ir īpaši noderīgas aģentu sistēmām, kas vairāk līdzinās sesijām, nevis konveijeriem. Sesiju, kas pāriet starp awaiting_user, planning, running_agents, awaiting_review un completed, parasti ir vieglāk izprast kā skaidri definētu dzīves ciklu, nevis kā vienu ļoti garu darbplūsmas definīciju ar daudzām gaidīšanām un atgriezeniskām pārejām.