داده، SQL، قراردادها و ماشین حالت · فصل ۵ — JSON Schema، OpenAPI، AsyncAPI، Protobuf و gRPC · 72
Protobuf Compatibility و Message Versioning
داده را ذخیره یا query می‌کند اما constraint، consistency، compatibility و recovery را به یک contract مهندسی تبدیل نمی‌کند. موضوع جاری: «Protobuf Compatibility و Message Versioning». می‌تواند «Protobuf Compatibility و Message Versioning» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
خلاصهٔ درس
داده را ذخیره یا query می‌کند اما constraint، consistency، compatibility و recovery را به یک contract مهندسی تبدیل نمی‌کند. موضوع جاری: «Protobuf Compatibility و Message Versioning».
می‌تواند «Protobuf Compatibility و Message Versioning» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
خروجی این درس
می‌تواند «Protobuf Compatibility و Message Versioning» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
_Locale: fa-IR · Lesson: DAT-015 · Public order: 72_
خروجی و artifact کاری
این درس برای ساختن رکورد تغییر و سازگاری Protobuf نسخه ۱ است: یک artifact تصمیم که مشاهده، فرض، محدودیت و evidence موردنیاز را از هم جدا می‌کند. هدف حفظ یک مدل قابل‌انتقال است، نه حفظ‌کردن نام ابزارها.
می‌تواند «Protobuf Compatibility و Message Versioning» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
مدل مرزی
ممکن است فایل .proto compile شود، اما تغییر آن reader قدیمی، reader جدید، message ذخیره‌شده یا client نوع ProtoJSON را خراب کند. در Protobuf شماره field هویت wire است. پس compatibility به test جهت‌دار قدیم/جدید، reserveکردن identifier حذف‌شده و قضاوت جدا برای binary و JSON نیاز دارد.
در هر بخش سه برچسب نگه دارید: «مشاهده‌شده»، «استنباط محدود» و «نیازمند بررسی». اگر evidence در دسترس نیست، نتیجه را unknown ثبت کنید؛ نام ابزار یا pass شدن یک happy path جای evidence را نمی‌گیرد.
1. شماره field هویت است
نام field ممکن است بدون تغییر binary identity عوض شود، اما تغییر یا reuse شماره تفسیر byteها را تغییر می‌دهد. number را asset پایدار contract بدانید.
2. حذف را reserve کنید
پس از حذف field، شماره و در صورت ارتباط نام آن را reserve کنید تا author آینده identity موجود در داده قدیمی را تصادفی reuse نکند.
3. Compatibility جهت‌دار است
old writer→new reader و new writer→old reader را جدا test کنید. unknown field و default behavior ممکن است یک جهت را قابل قبول و جهت دیگر را data-loss کند.
4. تغییر type هم wire و هم value analysis می‌خواهد
برخی typeها encoding مشترک دارند، اما برای همه valueها safe نیستند. golden message مرزی به‌ویژه برای narrowing و signedness لازم است.
5. ProtoJSON مرز دیگری است
نام field و ruleهای JSON ریسک‌هایی می‌سازند که در binary wire test دیده نمی‌شوند. اگر JSON persist یا exchange می‌شود، مستقل classify شود.
روش پنج‌مرحله‌ای
- شماره، type، cardinality، عضویت oneof و JSON name همه fieldهای موجود را inventory کنید.
- diff پیشنهادی را بنویسید و addition، deletion، rename، number change و type change را جدا classify کنید.
- testهای old-writer/new-reader و new-writer/old-reader را با messageهای representative و boundary اجرا کنید.
- number و name حذف‌شده را reserve و mutation reuse را اجرا کنید که باید در review رد شود.
- اگر JSON persist/exchange می‌شود، judgment ProtoJSON را جدا انجام و data-loss و limit باقی‌مانده را ثبت کنید.
مثال حل‌شده
در v1 پیام OrderCreated دارای order_id = 1، customer_email = 2 و total_cents = 3 است. v2 field اختیاری currency = 4 را اضافه و email را حذف می‌کند. candidate امن، number 2 و name آن را reserve می‌کند. test binary در هر دو جهت اجرا می‌شود؛ reader قدیمی field 4 را نمی‌شناسد و رکورد loss معنایی را ثبت می‌کند. mutation شماره 2 را برای customer_phone reuse می‌کند و با وجود compileشدن رد می‌شود. ProtoJSON جدا review می‌شود.
ماتریس تصمیم و evidence
| موضوع | مرز/مالک | evidence | تصمیم یا محدودیت | |
|---|---|---|---|---|
| order_id | 1/string | 1/string | identity حفظ شد | accept |
| customer_email | 2/string | حذف و reserve | byte قدیمی مبهم نمی‌شود | accept با retention note |
| currency | غایب | 4/string اختیاری | reader قدیمی ignore می‌کند | جهت‌دار compatible با ثبت loss |
| mutation customer_phone | غایب | 2/string | reuse شماره حذف‌شده | reject |
| rename در ProtoJSON | customerEmail | buyerEmail | key ذخیره‌شده تغییر می‌کند | migration جدا |
خطاهای محتمل و روش اصلاح
- اثبات compatibility فقط با compileشدن schema
- reuse شماره field حذف‌شده پس از گذشت زمان
- تعمیم binary compatibility به ProtoJSON
- تلقی تغییر field number به‌عنوان rename بی‌خطر
برای هر مورد، ادعا را محدود کنید، یک counterexample بسازید و بنویسید کدام مشاهده می‌تواند آن را تأیید یا رد کند.
تمرین انتقال
سناریو را طوری تغییر دهید که یکی از فرض‌های مثال دیگر برقرار نباشد. بدون کپی‌کردن تصمیم قبلی، رکورد تغییر و سازگاری Protobuf نسخه ۱ را دوباره بسازید؛ سپس تفاوت decision rule و تفاوت دادهٔ ورودی را توضیح دهید.
این درس چه چیزی را ثابت نمی‌کند
این درس certification، تضمین production یا پوشش همه implementationها را ادعا نمی‌کند. نتیجه فقط در مرز سناریو، sourceهای تاریخ‌دار و observationهای ثبت‌شده معتبر است.
خودسنجی
- [ ] آیا مسئولیت‌ها را از نام framework یا tool جدا کرده‌ام؟
- [ ] آیا دست‌کم یک failure probe و نتیجه موردانتظار آن را نوشته‌ام؟
- [ ] آیا fact، inference و design choice از هم مشخص‌اند؟
- [ ] آیا non-claim و evidence گمشده را ثبت کرده‌ام؟
- [ ] آیا transfer را روی context تغییرکرده و بدون پاسخ آماده انجام داده‌ام؟
منابع و مرز تازگی
sourceها در 2026-09-19 طبق Bible منجمدشده مرور شده‌اند. تاریخ review_due یک trigger برای بازبینی نسخه‌ای است؛ هیچ بسته‌ای نباید درجا و بدون نسخه جدید تغییر کند.
- PROTO3-GUIDE — Official field-number, deletion/reservation and message-update compatibility guidance. (https://protobuf.dev/programming-guides/proto3/; review: 2026-10-17)
- PROTOJSON — Official ProtoJSON format and compatibility considerations. (https://protobuf.dev/programming-guides/json/; review: 2026-10-17)
ارزیابی
پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.
DAT-015-S1 retrieval
DAT-015-S2 application
DAT-015-S3 diagnosis
DAT-015-S4 decision
DAT-015-S5 transfer
ملاک‌های ارزیابی (rubric)
| Dimension | Critical | Sufficient evidence |
|---|---|---|
| contract/protocol correctness | yes | Explanation preserves version/dialect, compatibility/reliability and evidence semantics. |
| evidence quality | yes | Positive, negative and change/repair observations are traceable and separated from inference. |
| scope discipline | yes | Adjacent outcomes and unsupported tool/runtime generalizations are deferred. |
| transfer independence | yes | Changed-context task is solved without decisive scaffold. |
A submission passes only when every critical dimension is sufficient and the learner states missing evidence honestly. AI suggestions are not observed evidence; the learner remains accountable for the final bounded judgment.
منابع و تازگی
مطالعهٔ موارد (case studies)
فایل‌های آزمایشگاه
با fixture امن محلی، رکورد تغییر و سازگاری Protobuf نسخه ۱ را بسازید. ابتدا prediction را بنویسید؛ سپس baseline و failure probeهای اعلام‌شده را ثبت کنید و observation مثبت و منفی را نگه دارید. transfer را بدون کپی تصمیم مثال انجام دهید.
starter عمداً classification یا risk decision نهایی را انتخاب نمی‌کند. evaluate_record.py و evidence template را تکمیل کنید. اجرای python3 ../run_checks.py فقط environment و شکل fileها را بررسی می‌کند و تصمیم محتوایی شما را grade نمی‌کند.
مرز ایمنی: No production system/data, no external account/service dependency, and all failure probes must be bounded and deterministic.
رسانه و اسلایدهای درس
فایل‌های آموزشی (دانلود)