رجیستری طرح و تکامل داده ها

چرا من نیاز به یک رجیستری طرح

• تکامل قابل پیش بینی: قوانین سازگاری و چک کردن شکستن خودکار.
• تکرارپذیری و شفافیت: تاریخچه نسخه ها، چه کسی/چه زمانی/چرا تغییر کرده است.
• استاندارد سازی: نام یکنواخت، فرمت های خطا، زمینه های ردیابی، برچسب های PII.
• ادغام با CI/CD: مسدود کردن تغییرات شکستن قبل از تولید.

رجیستری پروتکل اول و سازگاری قرارداد را پیوند می دهد و تغییرات را سریع و ایمن انجام می دهد.

فرمت ها و برنامه های کاربردی

JSON Schema: بارهای REST/HTTP، اسناد، تنظیمات.
آورو: اتوبوس رویداد (کافکا/پولسار)، جمع و جور/تکامل از طریق ID درست.
Protobuf: gRPC/RPC، باینری کارآمد، برچسب های سخت.
GraphQL SDL: نوع و طرح دستورالعمل، تکامل از طریق «مستهلک».
SQL DDL به عنوان یک مصنوع: ما دیدگاه های توافق شده (به عنوان مثال، فروشگاه های خارجی) را با احتیاط ثابت می کنیم.

یک رجیستری تنها می تواند چندین نوع مصنوعات را در یک زمان ذخیره کند، اما با سیاست های سازگاری جداگانه.

حالت های سازگاری

BACKWARD: طرح های جدید داده ها/پیام های قدیمی را می خوانند. مناسب برای یک تولید کننده که بار اضافی را گسترش می دهد.
مصرف کنندگان قدیمی اطلاعات جدید را به درستی می خوانند (نیاز به یک خواننده تحمل).
کامل: ترکیبی از هر دو (سخت تر، راحت تر برای قراردادهای عمومی).
NONE: بدون چک - فقط برای جعبه های شن و ماسه.

• رویدادها: اغلب BACKWARD (تولید کننده اختیاری را گسترش می دهد).
• API های عمومی: FULL یا BACKWARD + خواننده تحمل سخت در مشتریان.
• نمونه های داخلی: به طور موقت NONE، اما نه در تنه.

ایمن (افزودنی) در مقابل تغییرات خطرناک

• یک فیلد/نوع اختیاری اضافه کنید.
• پسوند Enum با مقادیر جدید (با خواننده تحمل).
• اضافه کردن طرح ریزی جایگزین/رویداد («.enriched»).
• کاهش محدودیتها («minLength», «maximum» ↑, but not ↓)

• حذف/تغییر نام فیلدها یا تغییر نوع/اجباری آنها.
• تغییر معانی statuses/codecs/order در threads.
• استفاده مجدد از تگ های protobuf
• تغییر کلید پارتیشن بندی در رویدادها.

ثبت نام سازمان

نامگذاری و آدرس دهی

گروهها/فضاها: «پرداختها»، «kyc»، «حسابرسی».
نام: پرداخت مجاز است. v1 '(رویدادها)، "پرداختها. V1 CaptureRequest '(gRPC) ", سفارشات. V1 دستور "(طرح JSON).
عمده در نام، افراد زیر سن قانونی در نسخه ابرداده/طرح.

فراداده ها

'مالک' (فرمان)، 'دامنه'، 'SLAS' (SLO/SLA)، 'امنیت. tier '(PII/PCI),' retention ',' compatibility _ mode ',' sunset ',' changelog '.

مدیریت چرخه عمر

پیش نویس → نقد و بررسی → تایید شده → منتشر شده → مستهلک → غروب آفتاب.
اعتبار سنج های خودکار/لاینترها، طراحی و بررسی دستی (API Guild)، یادداشت های انتشار.

ادغام در CI/CD

1. پیش تعهد: لاینترهای محلی (ابزارهای طیفی/Buf/Avro).
2. PR-pipeline: schema-diff → بررسی حالت سازگاری ؛ مسدود کردن شکستن.
3. Artifact انتشار: فشار طرح سازگار به رجیستری + تولید SDK/مدل.
4. Runtime-guard (اختیاری): Gateway/producer payload را در برابر طرح فعلی تأیید می کند.

• 'openapi-diff -- دم در شکستن'
• 'buf breaking -- against
  '
• 'AVRO-COMPAT --MODE عقب ماندگی'
• تولید نمونه های طلایی و اجرای آزمایشات CDC.

تکامل طرح ها: شیوه ها

اول افزودنی: новые поля - 'اختیاری/nullable' (JSON), 'اختیاری' (proto3), پیش فرض в آورو.
مدل هرم معکوس: هسته پایدار است، غنی سازی در نزدیکی و اختیاری است.
Dual-emit/dual-write برای major: ما «v1» و «v2» را به صورت موازی منتشر می کنیم.
طرح غروب آفتاب: تاریخ، استفاده، هشدارها، آداپتورها.
خواننده تحمل: مشتریان زمینه های ناشناخته را نادیده می گیرند و به درستی enum جدید را اداره می کنند.

نمونه هایی از طرح ها و چک

طرح JSON (قطعه، زمینه افزودنی)

json
{
"$id": "orders.v1.Order",
"type": "object",
"required": ["id", "status"],
"properties": {
"id": { "type": "string", "format": "uuid" },
"status": { "type": "string", "enum": ["created", "paid", "shipped"] },
"risk_score": { "type": "number", "minimum": 0, "maximum": 1 }
},
"additionalProperties": true
}

Avro (پیش فرض برای سازگاری)

json
{
"type": "record",
"name": "PaymentAuthorized",
"namespace": "payment.v1",
"fields": [
{ "name": "payment_id", "type": "string" },
{ "name": "amount", "type": "long" },
{ "name": "currency", "type": "string" },
{ "name": "risk_score", "type": ["null", "double"], "default": null }
]
}

Protobuf (برچسب ها را دوباره استفاده نکنید)

proto syntax = "proto3";
package payments.v1;

message CaptureRequest {
string payment_id = 1;
int64 amount = 2;
string currency = 3;
optional double risk_score = 4; // additive
}
// tag=4 зарезервирован под risk_score, его нельзя менять/удалять без v2

ثبت رویداد و پارتیشن بندی

نامگذاری رویدادها: "دامنه. فعالیت. v {major} '(' پرداخت. دستگیر شد. v1 ')

کلید پارتیشنبندی بخشی از قرارداد است («payment _ id», «user _ id»).
هسته در مقابل غنی شده: '.v1' (هسته) و '.enriched. v1 '(جزئیات).
سازگاری رجیستری: حالت ها در سطح موضوع/نوع ؛ CI تغییرات ناسازگار را رد می کند.

مدیریت مهاجرت

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

• Dual-emit (Events): به موازات «v1 »/« v2»، مهاجرت مصرف کننده/طرح ریزی، سپس حذف «v1».
• پخش: پیش بینی های مجدد از ورود به یک نمودار جدید (فقط با سازگاری و مهاجرت).
• آداپتورها: دروازه/پروکسی که «v1↔v2» را برای مشتریان پیچیده ترجمه می کنند.

ایمنی و انطباق

برچسب PII/PCI در نمودار: 'x-pii: true'، 'x-sensitivity: high'.
سیاست های دسترسی: چه کسی می تواند طرح ها را منتشر/اصلاح کند (RBAC)، نسخه های منتشر شده را امضا کند.
رمزنگاری: امضای نسخه های طرح، گزارش های حسابرسی غیر قابل تغییر (WORM).

حق فراموش شدن: فیلدهایی را مشخص کنید که نیاز به پاک کردن رمزگذاری/رمزنگاری دارند. راهنمایی در ثبت نام

قابلیت مشاهده و حسابرسی

داشبورد: تعداد تغییرات، انواع (جزئی/عمده)، سهم PR های رد شده، استفاده از نسخه.
دنباله حسابرسی: چه کسی طرح را تغییر داد، پیوندهایی به PR/ADR، انتشار مرتبط.

معیارهای زمان اجرا (Runtime metrics): درصد پیامهایی که اعتبارسنجی آنها با شکست مواجه شده است. حوادث سازگاری

ابزار (پشته نمونه)

طرحواره OpenAPI/JSON: تفاوت طیفی، OpenAPI، طرحواره.
Protobuf/gRPC: Buf، buf-breaking، linters.
Avro/Events: ثبت طرحواره Confluent/Redpanda، ابزارهای Avro، Karapace.
GraphQL: بازرس GraphQL، کدنویسی GraphQL.
Registers/catalogs: Artifact Registry، رجیستری مبتنی بر Git، کاتالوگ Backstage، UI سفارشی.
مستندات: قرمز/چراغ جلو، Swagger-UI، GraphiQL.

ضد الگوهای

Swagger-wash: این طرح واقعیت سرویس را منعکس نمی کند (یا برعکس).
بررسی سازگاری غیر فعال: «فوری» → شکستن محصول.
استفاده مجدد از برچسب های protobuf: فساد اطلاعات خاموش.
تنها حالت سازگاری «برای همه چیز»: دامنه های مختلف نیاز به حالت های مختلف.
CDC های خام به عنوان طرح های عمومی: نشت مدل DB، عدم امکان تکامل.

چک لیست پیاده سازی

• تعریف فرمت مصنوعی و حالت سازگاری توسط دامنه.
• Linters و schema-diff در CI پیکربندی شده اند، PR هنگام شکستن مسدود می شود.
• فعال برای خواننده تحمل مشتریان ؛ 'additionalProperties = true' (در صورت لزوم).
• تغییرات عمده از طریق RFC/ADR، یک طرح غروب آفتاب و dual-emit/dual-write وجود دارد.
• مدارها با PII/PCI و سطوح دسترسی مشخص شده اند ؛ حسابرسی امکان پذیر است.
• استفاده از نسخه و داشبورد خرابی سازگاری.
• تولید SDK/مدل از رجیستری بخشی از خط لوله است.
• مستندات و نمونه های طلایی به صورت خودکار به روز می شوند.

سوالات متداول

آیا بدون رجیستری امکان ذخیره طرح ها در Git وجود دارد ؟

بله، اما رجیستری API های سازگاری، جستجو، ابرداده، سیاست متمرکز و اعتبار سنجی در پرواز را اضافه می کند. بهترین گزینه Git به عنوان ذخیره سازی + UI/سیاست در بالا است.

چگونه حالت سازگاری را انتخاب کنم ؟

به جهت تغییر نگاه کنید: اگر تولیدکننده payload را گسترش دهد - BACKWARD. برای API/SDK عمومی - کامل. برای نمونه های سریع - به طور موقت NONE (نه در تنه).

در صورت لزوم شکستن چه باید کرد ؟

آماده سازی v2: دوگانه انتشار/دوگانه اجرا، غروب آفتاب، آداپتورها، تله متری استفاده، راهنماهای مهاجرت.

آیا باید Payload را در زمان اجرا تأیید کنم ؟

برای دامنه های بحرانی، بله: این از پیام های ناخواسته جلوگیری می کند و تشخیص را سرعت می بخشد.

نتیجه گیری

رجیستری طرح، تکامل داده ها را از improvisation خطرناک به یک فرایند قابل کنترل تبدیل می کند: قوانین قابلیت همکاری یکنواخت، اعتبار سنجی خودکار، نسخه های قابل درک و یک تاریخ شفاف. اضافه کردن به آن نظم و انضباط افزودنی اول، خواننده تحمل، دو انتشار و غروب آفتاب - و قرارداد خود را به سرعت توسعه خواهد یافت، بدون خرابی و حوادث شب.