سجل المخطط وتطور البيانات

لماذا أحتاج إلى سجل مخطط

وسجل المخطط هو مصدر مركزي للحقيقة بالنسبة لعقود البيانات (واجهات برمجة التطبيقات، والأحداث، والخيوط، والرسائل، والمخازن) التي تنص على ما يلي:

التطور المتوقع: قواعد التوافق والتحقق التلقائي من الكسر.
التكرار والشفافية: تاريخ الإصدارات، من/متى/لماذا تغيرت.
التوحيد القياسي: أسماء موحدة، تنسيقات خطأ، حقول تتبع، بطاقات PII.
التكامل مع CI/CD: منع كسر التغييرات قبل الإنتاج.

يربط السجل بين البروتوكول أولاً وتوافق العقود، مما يجعل التغييرات سريعة وآمنة.

النماذج والتطبيقات

مخطط JSON: حمولات ومستندات وتكوينات REST/HTTP.
أفرو: حافلات الأحداث (كافكا/بولسار)، مدمجة/تطورية عبر الهوية الميدانية.
Protobuf: gRPC/RPC، علامات ثنائية فعالة وصارمة.
GraphQL SDL: مخطط النوع والتوجيه، التطور عبر «@ deprecated».
SQL DDL كقطعة أثرية: نصلح وجهات النظر المتفق عليها (على سبيل المثال، واجهات المتاجر الخارجية) - بحذر.

💡 يمكن لسجل واحد تخزين أنواع متعددة من القطع الأثرية في وقت واحد، ولكن مع سياسات توافق منفصلة.

أنماط التوافق

الخلف: تقرأ المخططات الجديدة البيانات/الرسائل القديمة. مناسب للمنتج الذي يمد الحمولة بشكل إضافي.
إلى الأمام: يقرأ المستهلكون القدامى البيانات الجديدة بشكل صحيح (يتطلب قارئًا متسامحًا).
FULL: يجمع كلاهما (أكثر صرامة، وأكثر ملاءمة للعقود العامة).
لا شيء: لا شيكات - لصناديق الرمل فقط.

التوصيات:

الأحداث: في كثير من الأحيان BACKWARD (المنتج يوسع الحمولة اختيارية).
واجهات برمجة التطبيقات العامة: قارئ متسامح كامل أو متخلف + صارم على العملاء.
النماذج الأولية الداخلية: مؤقتًا لا شيء، ولكن ليس على صندوق السيارة.

آمن (مضاف) مقابل تغييرات خطيرة

مادة مضافة (حسنًا):

أضف حقل/نوع اختياري.
امتداد Enum بقيم جديدة (مع قارئ متسامح).
يضاف إسقاط/حدث بديل ('.
تخفيف القيود ('minLength'، 'maximum' ↑، ولكن ليس ↓).

خطير (استراحة):

حذف/إعادة تسمية الحقول أو تغيير نوعها/إلزاميتها.
تغيير دلالات الحالات/الترميز/الترتيب في الخيوط.
إعادة استخدام علامات protobuf.
تغيير مفتاح التقسيم في الأحداث.

تنظيم التسجيل

التسمية والعنونة

المجموعات/الأماكن: 'المدفوعات'، 'kyc'، 'مراجعة الحسابات'.
الأسماء: الدفع. المأذون به. v1 '(الأحداث)،' المدفوعات. v1. CaptureRequest' (gRPC)، "أوامر. v1. Order '(مخطط JSON).
تخصص في الاسم، القاصرون في البيانات الوصفية/نسخة المخطط.

البيانات الوصفية

"مالك" (أمر)، "نطاق"، "سلاس" (SLO/SLA)، "أمن. المستوى "(PII/PCI)،" الاحتفاظ "،" التوافق _ الوضع "،" غروب الشمس "،" التغيير ".

إدارة دورة الحياة

مشروع استعراض → → تمت الموافقة عليه → إصداره → استنكاره → غروب الشمس.
المصدقات/البطانات التلقائية، مراجعة التصميم اليدوي (API Guild)، ملاحظات الإصدار.

الاندماج في مؤتمر نزع السلاح

1. الالتزام المسبق: الخطوط المحلية (أدوات Spectral/Buf/Avro).
2. PR-pipeline: schema-diff → compatibility mode check; منع الكسر.
3. نشر القطع الأثرية: دفع المخطط المتسق للتسجيل + توليد SDK/النماذج.
4. حراسة وقت التشغيل (اختياري): تتحقق البوابة/المنتج من صحة الحمولة مقابل المخطط الحالي.

مثال على الخطوات في العلاقات العامة:

«openapi-diff - فشل في الانهيار»
«buf breaking - against
»
"avro-compat - mode BACKWARD'
توليد عينات ذهبية وإجراء اختبارات CDC.

تطور المخططات: الممارسات

مضاف أولاً: новые поля - «اختياري/غير قابل للإلغاء» (JSON)، «اختياري» (proto3)، افتراضي в Avro.
نموذج الهرم العكسي: اللب مستقر، والإثراء قريب واختياري.
Dual-emit/dual-write for 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
}

💡 تمت إضافة «risk _ score» لأن → الخلفي اختياري متوافق.

أفرو (افتراضي للتوافق)

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 ').
مفتاح التقسيم هو جزء من العقد («الدفع _ معرف»، «المستخدم _ معرف»).
Core vs Enriched: '.v1' (core) و '.enriched. v1 '(التفاصيل).
توافق السجلات: الطرائق على مستوى الموضوع/النوع ؛ CI يرفض التغييرات غير المتوافقة.

إدارة الهجرة

توسيع عقد → الهجرة → (REST/gRPC):

1. إضافة حقول/جداول 2) بدء الكتابة/قراءة حقول جديدة ؛ 3) تحذف القديمة بعد غروب الشمس.

Dual-emit (Events): موازية لـ 'v1 '/' v2'، هجرة المستهلك/الإسقاط، ثم إزالة 'v1'.
إعادة التشغيل: إعادة تجميع الإسقاطات من السجل إلى مخطط جديد (فقط مع التوافق والمهاجرين).
المحولات: بوابات/وكلاء تترجم «v1↔v2» للعملاء المعقدين.

السلامة والامتثال

ملصقات PII/PCI في الرسم البياني: «x-pii: true»، «x-sensity: high».
سياسات الوصول: من يمكنه نشر/تعديل المخططات (RBAC)، إصدارات التوقيع.
التشفير: توقيع إصدارات المخطط، سجلات التدقيق غير القابلة للتغيير (WORM).
الحق في النسيان: حدد الحقول التي تتطلب محو التشفير/التشفير ؛ التوجيه في السجل.

إمكانية الملاحظة ومراجعة الحسابات

لوحات القيادة: عدد التغييرات، الأنواع (الطفيفة/الرئيسية)، حصة العلاقات العامة المرفوضة، استخدام الإصدار.
مسار التدقيق: من غير المخطط، وصلات العلاقات العامة/ADR، والإصدار ذي الصلة.
مقاييس وقت التشغيل: النسبة المئوية للرسائل التي فشلت في التحقق من صحتها ؛ حوادث التوافق.

أدوات (عينة مكدسة)

OpenAPI/JSON Schema: Spectral, OpenAPI Diff, Schemathesis.
Protobuf/gRPC: Buf، buf-breaking، - linters.
Avro/Events: Confluent/Redpanda Schema Registry، Avro-tools، Karapace.
الرسم البياني QL: مفتش الرسم البياني QL، الرسم البياني QL Codegen.
السجلات/الكتالوجات: سجل القطع الأثرية، السجل القائم على المواد الهضمية، كتالوج الكواليس، واجهة المستخدم المخصصة.
الوثائق: Redocly/Stoplight، Swagger-UI، GraphiQL.

الأنماط المضادة

غسل التبجح: لا يعكس المخطط حقيقة الخدمة (أو العكس).
فحص التوافق المعاق: «عاجل» → انقطاع المنتج.
إعادة استخدام علامات protobuf: فساد البيانات الصامت.
وضع التوافق الفردي «لكل شيء»: تتطلب المجالات المختلفة أوضاعًا مختلفة.
مراكز السيطرة على الأمراض الخام كمخططات عامة: تسريب نموذج DB للخارج، واستحالة التطور.

قائمة التنفيذ المرجعية

شكل القطع الأثرية المحددة ووضع التوافق حسب المجال.
يتم تكوين Linters و Schema-diff في CI، ويتم حظر العلاقات العامة عند الانكسار.
تمكين القارئ المتسامح للعملاء ؛ «addativeProperties = true» (حيثما ينطبق).
تمر التغييرات الرئيسية من خلال RFC/ADR، وهناك خطة غروب الشمس والبعث المزدوج/الكتابة المزدوجة.
يتم وضع علامات على الدوائر مع PII/PCI ومستويات الوصول ؛ يمكن مراجعة الحسابات.
استخدام النسخة وفشل التوافق.
يعد توليد/نماذج SDK من السجل جزءًا من خط الأنابيب.
تحديث الوثائق والعينات الذهبية تلقائيًا.

التعليمات

هل من الممكن بدون سجل تخزين المخططات في Git ؟

نعم، لكن السجل يضيف واجهات برمجة التطبيقات المتوافقة، والبحث، والبيانات الوصفية، والسياسة المركزية، والتحقق أثناء السفر. أفضل خيار هو Git كتخزين + واجهة مستخدم/سياسات في الأعلى.

كيف أختار وضع التوافق ؟

انظر إلى اتجاه التغيير: إذا قام المنتج بتوسيع الحمولة - إلى الخلف. لواجهة برمجة التطبيقات العامة/SDK - FULL. للنماذج الأولية السريعة - مؤقتًا لا شيء (ليس على صندوق السيارة).

ماذا تفعل إذا لزم الأمر كسر ؟

التحضير v2: البعث المزدوج/التشغيل المزدوج، تواريخ غروب الشمس، المحولات، القياس عن بعد للاستخدام، أدلة الهجرة.

هل أحتاج إلى التحقق من صحة الحمولة في وقت التشغيل ؟

بالنسبة للمجالات الحرجة، نعم: هذا يمنع الرسائل غير المرغوب فيها ويسرع التشخيص.

النتيجة

يحول سجل المخطط تطور البيانات من الارتجال المحفوف بالمخاطر إلى عملية يمكن التحكم فيها: قواعد موحدة للتشغيل البيني، والتحقق الآلي، والإصدارات القابلة للفهم، والتاريخ الشفاف. أضف إليه انضباط القارئ المضاف أولاً والمتسامح والبعث المزدوج وغروب الشمس - وستتطور عقودك بسرعة، دون حدوث أعطال وحوادث ليلية.