داده، SQL، قراردادها و ماشین حالت · فصل ۵ — JSON Schema، OpenAPI، AsyncAPI، Protobuf و gRPC · 71
AsyncAPI برای Event Contracts
داده را ذخیره یا query می‌کند اما constraint، consistency، compatibility و recovery را به یک contract مهندسی تبدیل نمی‌کند. موضوع جاری: «AsyncAPI برای Event Contracts». می‌تواند «AsyncAPI برای Event Contracts» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
خلاصهٔ درس
داده را ذخیره یا query می‌کند اما constraint، consistency، compatibility و recovery را به یک contract مهندسی تبدیل نمی‌کند. موضوع جاری: «AsyncAPI برای Event Contracts».
می‌تواند «AsyncAPI برای Event Contracts» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
خروجی این درس
می‌تواند «AsyncAPI برای Event Contracts» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
_Locale: fa-IR · Lesson: DAT-014 · Public order: 71_
خروجی و artifact کاری
این درس برای ساختن رکورد بازبینی قرارداد رویداد AsyncAPI نسخه ۱ است: یک artifact تصمیم که مشاهده، فرض، محدودیت و evidence موردنیاز را از هم جدا می‌کند. هدف حفظ یک مدل قابل‌انتقال است، نه حفظ‌کردن نام ابزارها.
می‌تواند «AsyncAPI برای Event Contracts» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
مدل مرزی
payload schema فقط یک بخش event contract است. قرارداد به channel/address، operation و action از دید application توصیف‌شده، message identity، فرض‌های protocol binding، example و مرز صریح delivery guarantee نیاز دارد. AsyncAPI این بخش‌ها را inspectable می‌کند؛ broker را اجرا و durability یا ordering را ثابت نمی‌کند.
در هر بخش سه برچسب نگه دارید: «مشاهده‌شده»، «استنباط محدود» و «نیازمند بررسی». اگر evidence در دسترس نیست، نتیجه را unknown ثبت کنید؛ نام ابزار یا pass شدن یک happy path جای evidence را نمی‌گیرد.
1. پیش از payload، channel را مدل کنید
message در context ارتباطی معنا دارد. logical channel، rule مربوط به runtime address و application توصیف‌شده را ثبت کنید.
2. send و receive به perspective وابسته‌اند
action هر operation نسبت به application توصیف‌شده تفسیر می‌شود. بدون system boundary صریح، label مطلق producer/consumer ندهید.
3. Message identity مهم است
name، header، correlation، content type، payload schema و example باید سازگار باشند. shape مشترک payload دو message را خودکار معادل نمی‌کند.
4. Binding فرض protocol را محدود می‌کند
binding مربوط به Kafka، AMQP، MQTT یا HTTP metadata خاص protocol را ثبت می‌کند، اما انطباق configuration واقعی broker را ثابت نمی‌کند.
5. Reliability تصمیم جداست
exactly-once، ordering، retention، retry، dead-letter و idempotence evidence مستقل می‌خواهند و از valid بودن AsyncAPI نتیجه نمی‌شوند.
روش پنج‌مرحله‌ای
- application توصیف‌شده و system boundary آن را اعلام کنید.
- channel/address، message identity، header، payload schema و example را بسازید.
- operationها را اضافه و send/receive را از perspective همان application تفسیر کنید.
- exampleها را validate و reference message، operation action و binding assumption را عمداً خراب کنید.
- ویژگی‌های transport/delivery خارج از document را ثبت کنید تا evidence deployment جدا بگیرند.
مثال حل‌شده
document مربوط به Orders service، channel orders.created و operation با action نوع receive دارد، چون application توصیف‌شده مصرف‌کننده message است. OrderCreated دارای correlation ID، JSON payload schema و example معتبر است. یک mutation، operation را به PaymentCaptured وصل می‌کند و دیگری action را با همان perspective برعکس می‌کند؛ review هر دو را می‌گیرد. Kafka binding فقط assumption است و retry/dead-letter بیرون proof می‌ماند.
ماتریس تصمیم و evidence
| موضوع | مرز/مالک | evidence | تصمیم یا محدودیت |
|---|---|---|---|
| application | Orders projection | boundary اعلام شد | actionها با این perspective |
| channel | orders.created | address و link message | runtime mapping جدا verify شود |
| message | OrderCreated | header/payload/example | identity فراتر از payload shape |
| binding | metadata مربوط به Kafka | assumption مستند | config broker ثابت نشد |
| delivery | retry/order/DLQ | proof محلی ندارد | تصمیم operational جدا |
خطاهای محتمل و روش اصلاح
- نتیجه‌گیری exactly-once یا ordering از valid بودن document
- تقلیل event contract به payload schema
- تفسیر مطلق send/receive بدون perspective application
- فرض انطباق broker صرفاً به‌دلیل وجود binding
برای هر مورد، ادعا را محدود کنید، یک counterexample بسازید و بنویسید کدام مشاهده می‌تواند آن را تأیید یا رد کند.
تمرین انتقال
سناریو را طوری تغییر دهید که یکی از فرض‌های مثال دیگر برقرار نباشد. بدون کپی‌کردن تصمیم قبلی، رکورد بازبینی قرارداد رویداد AsyncAPI نسخه ۱ را دوباره بسازید؛ سپس تفاوت 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 برای بازبینی نسخه‌ای است؛ هیچ بسته‌ای نباید درجا و بدون نسخه جدید تغییر کند.
- ASYNCAPI-3.1 — Current AsyncAPI 3.1.0 specification: channels, messages, operations, action semantics and bindings. (https://www.asyncapi.com/docs/reference/specification/v3.1.0; review: 2026-10-17)
- ASYNCAPI-REL-3.1 — Official 3.1.0 release note and current-version context. (https://www.asyncapi.com/blog/release-notes-3.1.0; review: 2026-10-17)
ارزیابی
پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.
DAT-014-S1 retrieval
DAT-014-S2 application
DAT-014-S3 diagnosis
DAT-014-S4 decision
DAT-014-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 امن محلی، رکورد بازبینی قرارداد رویداد AsyncAPI نسخه ۱ را بسازید. ابتدا 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.
رسانه و اسلایدهای درس
فایل‌های آموزشی (دانلود)