Mesaj sözleşmeleri · Consumer

Queue, schema version, content kind ve canonical envelope header sözleşmesini tanımlayın.

Mesajın yalnız JSON olması onu doğru handler'a göndermek için yeterli değildir. Lily, fiziksel kuyrukla birlikte schema version ve content kind değerlerini kullanır. Bu sözleşme producer ile Consumer arasında açıkça paylaşılır.

Handler seçimi#

#[queue("orders.created", version = 1, content = "json")]

Bu marker, orders.created kuyruğuna gelen version 1, content json mesajını kabul eder. Version uygulama payload sözleşmesinin sürümüdür; framework paket sürümü değildir. Content kind body'nin tahmini türü değil, publisher'ın açık sözleşme değeridir. Framework JSON sniffing veya automatic upcasting yapmaz.

Canonical envelope header değerleri#

Header	Sözleşme	Amaç
`x-lily-event-id`	Non-nil, küçük harfli, hyphenated canonical UUID string	Olay kimliğini retry/redelivery boyunca korumak
`x-lily-schema-version`	`1`–`65535` canonical decimal string	Sürüm seçimi; `01` geçerli canonical değer değildir
`x-lily-content-kind`	1–64 byte, `[a-z0-9][a-z0-9._+-]*`	Exact içerik sözleşmesi
`x-retry-count`	Yoksa 0; varsa AMQP `LongInt`, 0–100	Framework retry sayısı

İlk üç header zorunludur. Rust dışı producer kullanıyorsanız canonical AMQP string representation'ını da koruyun: schema version'ı rastgele integer header tipi yapmak string parser'ını karşılamaz. AMQP content_type, örneğin application/json, yararlı bir property'dir ama x-lily-content-kind yerine geçmez.

Typed publisher encoding, MIME ve Lily header'larını birlikte üretir. publish_json, publish_text, publish_binary kendi built-in content token'larını kullanır. Uygulama decoder'ı için CustomPublishContent ile farklı, geçerli bir token seçin.

Uyumsuz mesajlara ne olur?#

Envelope önce sınırları ve canonical biçimi açısından doğrulanır. Queue'da o version yoksa QUEUE_SCHEMA_VERSION_UNSUPPORTED; version varsa ama content eşleşmiyorsa QUEUE_CONTENT_KIND_UNSUPPORTED permanent hatası oluşur. Bu seçim scope ve uygulama middleware'i açılmadan yapılır.

Sözleşme seçildikten sonra payload decode ayrıca başarısız olabilir. Örneğin header json dese bile bozuk JSON Json<T> tarafından permanent hata olarak reddedilir. Poison mesajların tamamını middleware'de yakalamayı beklemeyin; operational snapshot ve dead letter yolu farklı gözlem ihtiyaçlarını karşılar.

Kimlik, retry ve sürüm geçişi#

Aynı olayın yeniden gönderiminde event ID korunur. Broker redelivered işareti, framework RetryCount değeri ve uygulamanın business attempt kimliği ayrı kavramlardır. Hiçbiri tek başına tüm dış yan etkileri exactly-once yapmaz; veritabanı deduplication sınırı transactional inbox bölümündedir.

Yeni sürüme geçerken önce Consumer replica'larının hem eski hem yeni tuple'ı kabul etmesini sağlayın, sonra publisher'ı değiştirin. Bir physical queue'daki competing consumer'lar version'a göre ayrılmaz. Detaylar versioning ve rollout sayfasındadır.