Durum Makineleri

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: 2cc7b2b

Durum makineleri ve iş akışları farklı sorunları çözer.

İş akışı, "Sırada hangi işler çalışacak?" sorusunu yanıtlar. Durum makinesi ise "Bu şey hangi durumda ve buradan hangi olaylar geçerli?" sorusunu yanıtlar. Oluşturduğunuz şey yalnızca bir adım dizisi değil de zaman içinde dış girdilere tepki veren uzun ömürlü bir varlıksa (ör. bir aracı oturumu, sohbet dizisi, inceleme yaşam döngüsü, destek kaydı veya onay akışı), bu fark önem kazanır.

Hızlı örnek

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' ]
);

Bu makine awaiting_user durumunda başlar, kullanıcı mesajı geldiğinde planning durumuna geçer, sıraya alınan eylemin planned üretmesine izin verir ve harici bir onay oturumu tamamlayana kadar awaiting_review durumunda bekler. Önemli olan yalnızca kod söz dizimi değildir. Yaşam döngüsünün açık, incelenebilir ve olay odaklı olmasıdır.

Makine nasıl çalışır

Bir makine örneği gönderildiğinde Queuety; geçerli durum adını, genel durum yükünü, tanım sürümünü ve karmasını, geçerli duruma ait geçerli gelen olayları ve kalıcı bir olay zaman çizelgesini kaydeder.

Girilen durumda bir action() varsa Queuety, durum giriş işini kuyruğa ekler. Bu eylem yalnızca genel durumu güncelleyip makinenin sonraki olayı beklemesini sağlayabilir veya _event üretebilir ve sonraki geçişi hemen başlatmak için isteğe bağlı olarak _event_payload gönderebilir. Durumda bir eylem yoksa ve sonlandırıcı bir durum da değilse makine, Queuety::machine_event() ile gönderilen harici olayları bekler.

İş akışları ile durum makineleri arasında seçim

Çalıştırma temelde adım odaklıysa iş akışı kullanın. Verileri alın, her iş için bekleyin, sentezleyin ve tamamlayın. Başlangıcı ve bitişi net olan, temel sorusu sırada hangi işin yürütülmesi gerektiği olan durumlarda bu model uygundur.

Geçerli davranış mevcut yaşam döngüsü aşamasına bağlıysa durum makinesi kullanın. Olaylar farklı sıralarda gelebiliyorsa, varlık uzun süre yaşayabiliyorsa veya awaiting_user, planning, running_agents, awaiting_review ve completed gibi durumlarla yaşam döngüsünü açıkça incelemeniz gerekiyorsa bu yaklaşım daha uygundur.

İkisi birlikte nasıl çalışır

Bu iki temel yapı birbiriyle rekabet etmek yerine birlikte en iyi sonucu verir. Bir geçiş daha ağır bir yürütme gerektirdiğinde durum eylemi bir iş akışı gönderebilir; iş tamamlandığında iş akışı makineye bir olay iletebilir. Böylece uygulamada durum makinesi yaşam döngüsünü yönetirken iş akışları maliyetli veya yüksek düzeyde yapılandırılmış yürütmeyi gerçekleştirir.

Oluşturucu yapısı

StateMachineBuilder bilerek küçük tutulmuştur. initial() ve state() yaşam döngüsü grafiğini tanımlar. action(), sıraya alınmış işi tek bir duruma bağlar. on(), makineyi sonraki duruma taşıyabilecek olayları bildirir. on_queue(), with_priority() ve max_attempts() durum eylemlerinin nasıl yürütüleceğini denetler; version() ve idempotency_key() kalıcı gönderim meta verilerini ekler. dispatch() makine örneğini oluşturur.

Durum eylemleri, iş akışı adımları ve işleyicilerin kullandığı aynı kaynak politikası anahtarlarını kullanan isteğe bağlı bir config() yöntemi de sunabilir. Böylece maliyetli bir durum geçişini paylaşılan bir eşzamanlılık grubunda tutabilir veya eylem normal bir adımdan daha fazla bütçe tükettiğinde daha yüksek bir maliyet ağırlığı atayabilirsiniz.

Daha kapsamlı kaynak modeli Kaynak Yönetimi bölümünde açıklanmıştır.

Sözleşmeler

Durum giriş eylemleri Queuety\Contracts\StateAction arayüzünü uygular:

PHP

namespace Queuety\Contracts;

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

$payload, eylem tanımındaki yapılandırılmış yüktür; eylem düz sınıf adı olarak verilmişse boştur. Queuety, eylemleri new $class() ile oluşturur; bu nedenle eylem sınıfının zorunlu bağımsız değişkeni olmayan bir kurucusu olmalıdır.

Kuyruğa alınan giriş eyleminin çalışan kabulüne, ağırlıklı kuyruk veya sağlayıcı bütçelerine ve diğer kaynak politikalarına katılması gerektiğinde durum eylemleri; concurrency_group, concurrency_limit ve cost_units ile birlikte isteğe bağlı bir config() yöntemi de tanımlayabilir.

Geçiş korumaları Queuety\Contracts\StateGuard arayüzünü uygular:

PHP

namespace Queuety\Contracts;

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

İnceleme API'leri

Çalışan makineleri incelemek için facade'i kullanın:

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 );

Durum makinelerinin WP-CLI komutları yoktur: wp queuety workflow ... yalnızca iş akışlarını kapsar. Komut satırından makineleri incelemek için örneğin wp eval aracılığıyla bu PHP API'lerini kullanın.

Bu API'ler geçerli durum adını, yaşam döngüsü durumunu, genel durumu, kullanılabilir olayları, tanım meta verilerini, tüm geçiş zaman çizelgesini ve hata ayıklayıcı arayüzleri için normalleştirilmiş bir iz paketini sunar. Makine listesi satırlarında tanım sürümü, tanım karması ve idempotency anahtarı bulunur; böylece liste ekranları her makineyi ayrı ayrı yüklemeden kaynak/çalışma zamanı sürümünü gösterebilir. İz paketi; gruplandırılmış durumları, ham olayları, ilişkili eylem işlerini, günlükleri, yapıt başvurularını, parça başvurularını, işleyici girdisini/çıktısını, önceki/sonraki durumu, bağlamı, zamanlamaları ve yapılandırılmış hataları içerir.

Aracı oturumları

Durum makineleri, işlem hatlarından çok oturumlar gibi davranan aracı sistemleri için özellikle yararlıdır. awaiting_user, planning, running_agents, awaiting_review ve completed durumları arasında ilerleyen bir oturumu, çok sayıda bekleme ve geri dönüş içeren tek ve çok uzun bir iş akışı tanımı olarak değil, açık bir yaşam döngüsü olarak ele almak genellikle daha kolaydır.