Lewati ke konten

Mesin Status

Lihat sebagai Markdown Edit di GitHub Dokumentasi di 2cc7b2b

Mesin status dan alur kerja menyelesaikan masalah yang berbeda.

Alur kerja menjawab, "pekerjaan apa yang dijalankan berikutnya?" Mesin status menjawab, "apa status benda ini, dan peristiwa apa yang valid dari sini?" Perbedaan itu penting ketika yang Anda bangun bukan sekadar rangkaian langkah, melainkan entitas berumur panjang yang bereaksi terhadap masukan dari luar seiring waktu, seperti sesi agen, utas obrolan, siklus peninjauan, tiket, atau alur persetujuan.

Contoh singkat

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

Mesin ini dimulai di awaiting_user, beralih ke planning saat pesan pengguna tiba, membiarkan tindakan yang diantrekan mengeluarkan planned, lalu menunggu di awaiting_review hingga persetujuan eksternal menyelesaikan sesi. Hal yang penting bukan sintaks kodenya sendiri. Yang penting adalah siklus hidupnya dinyatakan secara eksplisit, dapat diperiksa, dan digerakkan oleh peristiwa.

Cara kerja mesin

Saat instans mesin di-dispatch, Queuety menyimpan nama status saat ini, payload status publik, versi dan hash definisi, peristiwa masuk yang valid untuk status saat ini, serta linimasa peristiwa yang persisten.

Jika status yang dimasuki memiliki action(), Queuety mengantrekan job untuk memasuki status tersebut. Tindakan itu dapat sekadar memperbarui status publik dan membiarkan mesin menunggu peristiwa berikutnya, atau dapat mengeluarkan _event dan secara opsional _event_payload untuk langsung menjalankan transisi berikutnya. Jika status tidak memiliki tindakan dan bukan status terminal, mesin hanya menunggu peristiwa eksternal yang dikirim dengan Queuety::machine_event().

Memilih antara alur kerja dan mesin status

Gunakan alur kerja ketika proses pada dasarnya berorientasi pada langkah. Ambil data, tunggu untuk setiap pekerjaan, rangkum, lalu selesaikan. Model ini cocok ketika ada awal dan akhir yang jelas, dan pertanyaan utamanya adalah pekerjaan apa yang harus dijalankan berikutnya.

Gunakan mesin status ketika perilaku yang valid bergantung pada fase siklus hidup saat ini. Ini lebih cocok ketika peristiwa dapat tiba dalam urutan berbeda, ketika entitas dapat hidup dalam waktu lama, atau ketika Anda memerlukan pemeriksaan siklus hidup yang eksplisit dengan status seperti awaiting_user, planning, running_agents, awaiting_review, dan completed.

Cara keduanya bekerja bersama

Kedua primitif ini paling baik digunakan bersama, bukan saling bersaing. Tindakan status dapat men-dispatch alur kerja ketika transisi memerlukan eksekusi yang lebih berat, dan alur kerja dapat mengirimkan peristiwa kembali ke mesin saat pekerjaan selesai. Dalam praktiknya, mesin status mengatur siklus hidup, sementara alur kerja menjalankan proses yang mahal atau sangat terstruktur.

Bentuk builder

StateMachineBuilder sengaja dibuat tetap kecil. initial() dan state() mendefinisikan graf siklus hidup. action() mengaitkan pekerjaan yang diantrekan ke satu status. on() menyatakan peristiwa mana yang dapat memindahkan mesin ke status berikutnya. on_queue(), with_priority(), dan max_attempts() mengatur cara tindakan status dijalankan, sedangkan version() dan idempotency_key() melampirkan metadata dispatch persisten. dispatch() membuat instans mesin.

Tindakan status juga dapat menyediakan metode config() opsional dengan menggunakan kunci kebijakan sumber daya yang sama seperti yang digunakan langkah dan handler alur kerja. Dengan begitu, satu transisi status yang mahal dapat ditempatkan dalam grup konkurensi bersama atau diberi bobot biaya lebih tinggi ketika suatu tindakan menghabiskan anggaran lebih besar daripada langkah biasa.

Model sumber daya yang lebih luas dijelaskan di Manajemen Sumber Daya.

Kontrak

Tindakan saat memasuki status mengimplementasikan 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 adalah payload terstruktur dari definisi tindakan, dan kosong jika tindakan diberikan sebagai nama kelas biasa. Queuety membuat tindakan dengan new $class(), sehingga kelas tindakan memerlukan konstruktor tanpa argumen wajib.

Tindakan status juga dapat mendefinisikan metode config() opsional dengan concurrency_group, concurrency_limit, dan cost_units jika tindakan masuk yang diantrekan harus turut serta dalam penerimaan worker, anggaran antrean berbobot atau penyedia, serta kebijakan sumber daya lainnya.

Penjaga transisi mengimplementasikan Queuety\Contracts\StateGuard:

PHP
namespace Queuety\Contracts;

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

API inspeksi

Gunakan facade untuk memeriksa mesin yang sedang berjalan:

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

Mesin status tidak memiliki perintah WP-CLI: wp queuety workflow ... hanya mencakup alur kerja. Gunakan API PHP ini, misalnya melalui wp eval, untuk memeriksa mesin dari baris perintah.

API tersebut menampilkan nama status saat ini, status siklus hidup, status publik, peristiwa yang tersedia, metadata definisi, linimasa transisi lengkap, dan bundel jejak yang dinormalisasi untuk UI debugger. Baris daftar mesin menyertakan versi definisi, hash definisi, dan kunci idempotensi agar layar daftar dapat menampilkan versi sumber/runtime tanpa memuat setiap mesin secara terpisah. Bundel jejak mencakup status yang dikelompokkan, peristiwa mentah, job tindakan yang berkorelasi, log, referensi artefak, referensi potongan, masukan/keluaran handler, status sebelum/sesudah, konteks, waktu, dan kesalahan terstruktur.

Sesi agen

Mesin status sangat berguna untuk sistem agen yang perilakunya lebih menyerupai sesi daripada pipeline. Sesi yang bergerak melalui awaiting_user, planning, running_agents, awaiting_review, dan completed biasanya lebih mudah dipahami sebagai siklus hidup eksplisit daripada sebagai satu definisi alur kerja yang sangat panjang dengan banyak penantian dan jalur balik.

Lihat juga