تغییر ساختار پیام (Schema Evolution)

مشکل: یک تغییر کوچک، چهار سرویس خراب

در فروشگاه اینترنتی ما، رویداد OrderCreated را چهار سرویس می‌خوانند: گزارش، پیامک، انبار و حسابداری. هر سرویس تیم خودش و زمان انتشار خودش را دارد. پیام امروز این شکلی است:

{ "orderId": "o-1", "amount": 250000 }

فروشگاه می‌خواهد چند ارزی شود. تیم سفارش مبلغ را به یک شیء تبدیل می‌کند:

{ "orderId": "o-1", "amount": { "value": 250000, "currency": "IRR" } }

قدم به قدم چه اتفاقی می‌افتد؟

1. سرویس پیامک هنوز کد قدیم را دارد. در کد آن، مبلغ یک عدد است.
2. پیام جدید می‌رسد و مبلغ یک شیء است. تبدیل JSON با خطا شکست می‌خورد.
3. مصرف‌کننده دوباره تلاش می‌کند و باز شکست می‌خورد. در کافکا ترتیب مهم است، پس پیام‌های بعدی هم پشت همین پیام گیر می‌کنند.
4. مشکل برعکس هم هست. اگر سرویسی زودتر به کد جدید برود، پیام‌های قدیمی که هنوز در topic هستند را نمی‌فهمد.
5. همه با هم منتشر کنیم؟ هماهنگ کردن انتشار چهار تیم در یک لحظه عملاً ممکن نیست. پیام‌های قدیمی هم در صف می‌مانند.

ایده اصلی: پیام یک قرارداد است

یک API عمومی را تصور کن. نمی‌توانی یک روز نوع یک فیلد را عوض کنی و انتظار داشته باشی همه کلاینت‌ها همان روز درست کار کنند. پیام هم دقیقاً همین است. فقط سخت‌تر، چون:

• پیام می‌ماند. پیامی که امروز نوشته شده، ممکن است هفته بعد یا سال بعد دوباره خوانده شود.
• فرستنده گیرنده‌ها را نمی‌شناسد. شاید سرویسی که خبر نداری هم این پیام را می‌خواند.

پس قانون اصلی این است: کد قدیم و کد جدید باید مدتی کنار هم کار کنند.

دو جهت سازگاری

1. سازگاری رو به عقب (Backward). کد جدید، پیام قدیمی را می‌فهمد. لازم است چون پیام‌های قدیمی در صف یا topic هنوز هستند.
2. سازگاری رو به جلو (Forward). کد قدیمی، پیام جدید را می‌فهمد. لازم است چون همه مصرف‌کننده‌ها همزمان به‌روز نمی‌شوند.
3. سازگاری کامل (Full). هر دو با هم. امن‌ترین حالت برای رویدادهایی که چند تیم می‌خوانند.

کدام تغییر امن است؟

راه درست: گسترش، مهاجرت، جمع کردن

تغییر بزرگ را به سه قدم کوچک تقسیم می‌کنیم. هر قدم به تنهایی امن است.

1. گسترش. یک فیلد جدید با نام جدید اضافه کن. فیلد قدیم هم هنوز پر می‌شود.
2. مهاجرت. هر تیم هر وقت آماده بود، کدش را به خواندن فیلد جدید می‌برد.
3. جمع کردن. وقتی همه رفتند و پیام‌های قدیمی هم دیگر لازم نیستند، فیلد قدیم را حذف کن.

پیام در قدم اول:

{ "orderId": "o-1", "amount": 250000, "money": { "value": 250000, "currency": "IRR" } }

سمت فرستنده در C#:

public sealed record Money(decimal Value, string Currency);

public sealed record OrderCreated(
    string OrderId,
    [property: Obsolete("Use Money. Will be removed after all consumers move.")]
    decimal Amount,
    Money Money);

var message = new OrderCreated(order.Id, order.Total.Value, order.Total);

سمت گیرنده: خواننده بخشنده (Tolerant Reader)

فرستنده باید مراقب باشد. ولی گیرنده هم باید بخشنده باشد:

1. فقط فیلدهایی را بخوان که لازم داری. سرویس پیامک فقط شناسه سفارش و مبلغ را لازم دارد. فیلدهای دیگر را در کلاسش تعریف نکن.
2. فیلد ناشناخته را نادیده بگیر. کتابخانه System.Text.Json این کار را به طور پیش‌فرض انجام می‌دهد. این رفتار را خاموش نکن.
3. برای فیلد جدید، نبودن را قبول کن. پیام قدیمی فیلد جدید را ندارد. پس آن را nullable تعریف کن و یک راه جایگزین داشته باش.

// The SMS service reads only what it needs.
public sealed record OrderCreatedForSms(string OrderId, decimal? Amount, Money? Money)
{
    // Works with old messages (only Amount) and new ones (Money).
    public decimal Total => Money?.Value ?? Amount
        ?? throw new InvalidOperationException("Message has no amount.");
}

خواندن دوباره پیام‌های قدیمی (Replay)

یک سرویس جدید می‌خواهد همه سفارش‌های یک سال گذشته را از اول کافکا بخواند. پیام‌های یک سال، چند شکل مختلف دارند. دو راه داریم:

1. سرویس جدید همه شکل‌ها را بفهمد. برای چند نسخه ممکن است، ولی کد شلوغ می‌شود.
2. یک لایه تبدیل (Upcaster). قبل از رسیدن به کد اصلی، هر نسخه قدیمی را به نسخه جدید تبدیل کن. کد اصلی فقط یک شکل را می‌بیند.

برای این کار، هر پیام باید نسخه‌اش را همراه داشته باشد. مثلاً در Header پیام، یا با شناسه schema.

public sealed record OrderCreatedV2(string OrderId, Money Money);

public static class OrderCreatedUpcaster
{
    public static OrderCreatedV2 Upcast(int version, JsonElement json) => version switch
    {
        1 => new OrderCreatedV2(
                json.GetProperty("orderId").GetString()!,
                new Money(json.GetProperty("amount").GetDecimal(), "IRR")), // v1 was always IRR
        2 => json.Deserialize<OrderCreatedV2>(JsonSerializerOptions.Web)!, // camelCase names
        _ => throw new NotSupportedException($"Unknown OrderCreated version {version}.")
    };
}

جلوگیری قبل از Production با Schema Registry

قانون‌های بالا را آدم‌ها فراموش می‌کنند. یک ابزار می‌تواند آن‌ها را خودکار چک کند.

1. شکل پیام با یک زبان دقیق تعریف می‌شود. معمولاً Avro یا Protobuf، و گاهی JSON Schema.
2. هر نسخه جدید در Schema Registry ثبت می‌شود. فرستنده قبل از ارسال، schema را ثبت می‌کند.
3. قانون سازگاری چک می‌شود. اگر نسخه جدید با قانون (مثلاً Backward) نخواند، ثبت رد می‌شود. پس خطا در CI یا هنگام انتشار دیده می‌شود، نه در Production.
4. پیام فقط شناسه schema را همراه دارد. گیرنده با همین شناسه، شکل دقیق پیام را از Registry می‌گیرد.

دو نکته درباره قالب‌ها:

• در Protobuf، هر فیلد یک شماره دارد. شماره فیلد حذف‌شده را هیچ وقت دوباره استفاده نکن. آن را reserved کن.
• در Avro، فیلد جدید باید مقدار پیش‌فرض داشته باشد. وگرنه خواندن پیام قدیمی با schema جدید ممکن نیست.

اشتباه‌های رایج

چقدر سخت‌گیری لازم است؟