طراحی پروتکل اول

پروتکل اول چیست ؟

پروتکل اول رویکردی است که در آن یک قرارداد تعامل بین اجزاء (خدمات، مشتریان، شرکای خارجی) قبل از پیاده سازی طراحی و ثابت می شود. کد، ذخیره سازی، زیرساخت ها و اسناد مربوط به قرارداد است و به طور خودکار از آن تولید می شود و نه برعکس.

بر خلاف کد اول، که در آن API تنها یک محصول جانبی از کد است، پروتکل اول باعث می شود پروتکل یک مصنوع اولیه: آن را صاحب مفاهیم دامنه، مدل داده ها، وضعیت، خطاها، معناشناسی idempotency، SLO/SLI، و حتی سیاست نسخه.

چرا به آن نیاز دارید ؟

سازگاری و قابل پیش بینی بودن رابط ها در سراسر سازمان.
نصب سریع (SDK/stable/client autogeneration، خطاها و کدهای یکنواخت).
تکامل قابل اعتماد (سازگاری طرح ها، قراردادهای تست، سیاست نسخه روشن).
تمرکز محصول: بحث در مورد رفتار، SLA و ادغام UX قبل از نوشتن کد.
اتوماسیون: CI/CD مصنوعات (مشتریان، خرده سرور، اعتبار سنج) را از یک منبع واحد حقیقت جمع آوری می کند.
امنیت و انطباق: حقوق، پوشش PII، سیاست های نگهداری در قرارداد ذکر شده است.

رویکرد اصلی

1. تنها منبع حقیقت (SSOT) - مشخصات ماشین قابل خواندن:

REST: OpenAPI/JSON Schema.
رویدادها و جریان: AsyncAPI، Avro/JSON Schema.
RPC: Protobuf (gRPC)، Thrift، Smithy.
GraphQL: دستورات/سیاست های SDL +.
2. ترتیبات قبل از اجرای: واژه نامه دامنه، کدهای خطا، معانی idemotency، مهلت، retrays، deduplication.
3. Autogeneration: مشتری/سرور خرد، انواع، SDK ها، قراردادهای تست، moks، مجموعه Postman، Terraform/OpenAPI Gateway config.
4. حکومت: linters/سیاست (نامگذاری, صفحه بندی, فیلتر, خطاها), بررسی از طریق انجمن API, تغییر مشاوره برای نسخه های اصلی.
5. سازگاری: تایید دقیق از «افزودنی فقط» منتشر, نسخه معنایی, canary/آزمون مصرف کننده محور.
6. قابلیت مشاهده در سطح قرارداد: شناسه های همبستگی، مدل های خطا، بودجه های تاخیر در پروتکل بیان شده است.

روند به نظر می رسد (اسکلت)

1. شروع: مختصر محصول → سفرهای کاربر → API/پروتکل PRD (منابع/روش ها/رویدادها، SLA/SLO، خطاها، محدودیت ها).
2. مدل سازی: مشخصات پیش نویس (OpenAPI/AsyncAPI/Proto) + طرح داده ها، فرهنگ لغت اصطلاحات.
3. قراردادها و یکپارچگی UX: نمونه های بارگیری، قراردادهای خطا، نقشه های وضعیت، قوانین نسخه بندی.
4. بررسی و حاکمیت: خطوط/استانداردها، بحث در مورد متغیرهای دامنه، قفل در MGC (حداقل قرارداد گارانتی).
5. تولید خودکار مصنوعات: SDK ها، stabs، رفع تست، خرده های زیرساختی (دروازه ها، دامنه های IAM).
6. پیاده سازی و تست قرارداد: تامین کننده و مصرف کنندگان تحت بررسی سازگاری در CI قرار می گیرند.
7. قابلیت مشاهده و SLO: ردیابی همبستگی-شناسه، کاتالوگ خطا، بودجه بازپرداخت/اتمام وقت.
8. انتشار و تکامل: اولین افزودنی، سیاست رد، قناری، پرچم قابلیت A/B.

پروتکل های تعامل و سبک

استراحت/HTTP

استانداردها: مدل منبع، 'GET/POST/PATCH/DELETE'، صفحه بندی (مکان نما)، فیلترها، مرتب سازی.
زمینه ها و طرح ها: طرح JSON، فرمت ('تاریخ-زمان'، 'uuid')، ناوردا (regex/enum/min-max).
خطاها: فرمت واحد («نوع»، «کد»، «عنوان»، «جزئیات»، «ردیابی _ id»)، نقشه برداری به پشته HTTP.
کنترل تغییر: ETag/If-Match، کلید های idempotent برای POST، معانی صریح 409/422.

gRPC/RPC

Protobuf: شماره گذاری برچسب پایدار، «اختیاری»، عدم استفاده مجدد از فیلدهای حذف شده.
مهلت ها و اولویت ها در قرارداد ؛ وضعیت پایدار (OK، INVALID_ARGUMENT، FAILED_PRECONDITION، و غیره).
جریان: مشخصات سفارش پیام، فشار پشتی، تریلر نهایی.

رویداد محور (Kafka/NATS/SNS/SQS)

AsyncAPI: تم ها/کانال ها، کلید های پارتیشن بندی، کنوانسیون های کلیدی deduplication، retentions، دقیقا یک بار معنایی "در مقابل" حداقل یک بار "

رویداد اصلی و غنی سازی: حداقل بار و پسوند جداگانه ؛ version 'event _ type '/' schema _ version'.
Idempotency: 'event _ id'، 'producer _ id'، سیاست در retrays و deduplication.

GraphQL

SDL به عنوان یک قرارداد، دستورالعمل برای استهلاک، محدودیت در عمق و پیچیدگی، کد خطا/پسوند قرارداد.

ادغام با اصول معماری

هرم معکوس/مسیر بحرانی اول: در مشخصات، برجسته MGC (حداقل اجباری)، پسوند - از طریق ؟ شامل = "/توانایی ها.
جاده های هموار: مجموعه ای از قالب های مشخصات آماده (پرداخت، KYC، حسابرسی، جستجو، فایل ها) + خطوط.
API Gateways & Service Mesh: سیاست های مبتنی بر قرارداد (محدودیت نرخ، محدوده auth، تکرار، قطع کننده مدار).

نسخه و تکامل

• جزئی = فیلدها/کانال های افزودنی تنها.
• عمده = تغییرات شکستن (حذف، تغییر نام، تغییر معانی).
• سیاست رد: پنجره های پشتیبانی، هدر های «غروب آفتاب»، رویدادهای اطلاع رسانی.
• قراردادهای مبتنی بر مصرف کننده (CDC): تأیید اینکه API فعلی مصرف کنندگان خاص را برآورده می کند.
• دایرکتوری طرح: رجیستری طرح/Artifact رجیستری با تاریخ و قوانین سازگاری (BACKWARD/FORWARD/FULL).

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

احراز هویت/مجوز به عنوان بخشی از قرارداد (حوزه های OAuth2/OIDC، mTLS، ادعاهای JWT).
PII/PCI: پوشش، فرمت های نشانه گذاری، زمینه های با حالت های ذخیره سازی ویژه/TTL.
سیاست های حسابرسی: ویژگی های مورد نیاز («بازیگر»، «موضوع»، «عمل»، «رخ داده است _ در»، «ردیابی _ id»).
محدودیت ها: هدر محدودیت نرخ، سهمیه، اندازه پیام، مهلت.

قابلیت مشاهده قرارداد

همبستگی/درخواست-ID: مورد نیاز در مشخصات.
کاتالوگ خطا - لیست ثابت از کدها و SLA ها برای حل و فصل.
SLI/SLO: تاخیر p50/p95، نسبت پاسخ های موفق، نسبت رویدادهای سازگار، نسبت تکرارهای idempotent.

تست و کیفیت

تست های قرارداد (ارائه دهنده ↔ مصرف کننده)، schema diff در CI، نسل سرورهای ساختگی.
نمونه های طلایی: نمونه های مرجع درخواست/پاسخ، وسایل برای e2e.
هرج و مرج/تزریق تاخیر: چک کردن زمان/بازپرداخت، تخریب پسوند هنگام صرفه جویی در MGC.

نمونه قالب های دامنه

پرداخت (REST + رویدادها)

'POST/payments' → '201 Created' with 'payment _ id', 'status = authorized'.
پرداخت مراسم. مجاز است. v1 '(ядро):' {payment_id، مقدار، ارز، روش، occurred_at} '.
پرداخت تمدیدی غنی شده v1 ': میزان خطر، جغرافیایی، اثر انگشت دستگاه.
خطاها: «422» (اعتبار سنجی)، «402» (پرداخت مورد نیاز)، «409» (تکراری).
SLA: مجوز ≤ 800ms p95 ؛ رویداد هسته ≤ 2c تاخیر p95.

KYC (gRPC + صف)

RPC 'StartVerification (user_id)' → 'operation _ id'.
رویدادهای پیشرفت در موضوع "kyc. وضعیت. v1 '(' در انتظار '→' تایید/رد ').
این قرارداد زمینه های PII، عمر مفید، پوشش، کدهای شکست علت را تعیین می کند.

حسابرسی (فقط رویداد)

بله، بله. ضبط شده v1 '(ядро):' actor ',' subject ',' action ',' رخ داد _ at ',' trace _ id '.
غنی سازی: IP، دستگاه، جغرافیایی - یک رویداد/موضوع جداگانه، هسته را مسدود نمی کند.

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

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: طیف، OpenAPI Diff، Buf (protobuf)، بررسی سازگاری SR Confluent.
Генерация: OpenAPI Generator, Buf/I, GraphQL Codegen, AsyncAPI Generator.
دروازه: Kong/Apigee/Azure/GCP GW، نماینده.
Тесты: Pact/CDC، Dredd، Schemathesis، Hoverfly، MockServer.
Register: فهرست راهنمای برنامهها + Schema Registry/Artifact Registry.
مستندات: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

ضد الگوهای

کد اول به طور تصادفی: «MVP اول در کنترل»، مشخصات پس از واقعی، اختلاف بین اسناد و رفتار.
Swagger-wash: یک OpenAPI رسمی بدون قوانین واقعی (خطاها، محدودیت ها، SLA ها، نسخه ها).

شکستن سازگاری: حذف فیلد/تغییر نوع بدون نسخه اصلی ؛ استفاده مجدد از تگ های protobuf

پاسخ «ضخیم» بدون صفحه بندی/فیلتر ؛ عدم توانمندی.
امنیت خارج از قرارداد: auth/scopes در ویکی شرح داده شده است، اما نه در مشخصات.

ارتباط با فرآیند سازمان

API Guild: استانداردهای متولی، تغییر بررسی، آموزش.
اسناد طراحی: برای هر API - PRD، ADR (راه حل ها)، SLA، ماتریس ریسک.
مدیریت تغییر: فرآیند RFC، یادداشت های انتشار، راهنماهای مهاجرت، انحراف جدول زمانی.
جاده آسفالت و قالب: ژنراتور چارچوب خدمات از مشخصات (اسکلت گرداننده، اعتبار سنجی، ورود به سیستم).

چک لیست

قبل از شروع

• یک PRD و یک واژه نامه دامنه وجود دارد.
• سبک انتخاب شده (REST/gRPC/Event/GraphQL) و فرمت طرح.
• MGC ها، خطاها، SLA/SLO ها، قوانین idempotency تعریف شده است.

در حال توسعه

• مشخصات عبور linters و بررسی.
• SDK/پایدار/ثابت تولید خودکار پیکربندی شده است.
• تست قرارداد (CDC) در CI شامل; schema-diff تغییرات ناسازگار را مسدود می کند.

قبل از انتشار

• مستندات یکپارچه با مثال ها و کدهای خطا.
• قرارداد قابل مشاهده: همبستگی ID، کاتالوگ خطا، داشبورد SLI.
• سیاست نسخه و کاهش ارزش اعلام شده است.

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

پروتکل اول چه تفاوتی با API اول دارد ؟

اغلب اصطلاحات به جای یکدیگر استفاده می شوند. در این مقاله تحت پروتکل اول، ما بر دقت قرارداد و پوشش تمام سبک ها (REST/RPC/Events/GraphQL)، از جمله SLA، ایمنی و قابلیت مشاهده تاکید می کنیم.

آیا این پیشرفت را کند می کند ؟

شروع ممکن است کمی طولانی تر باشد، اما پس از آن ما در ادغام، ثبات و سرعت توسعه موازی (تولید خودکار، SDK های پایدار) برنده می شویم.

با آزمایشهای سریع چه کنیم ؟

از نسخه های «پیش نویس» طرح ها (پیش نویس)، پرچم های ویژگی و sandboxes استفاده کنید، اما از خطوط و قوانین سازگاری اساسی استفاده نکنید.

مجموع

طراحی پروتکل اول باعث می شود که قرارداد مرکز معماری باشد: ما رفتار را هماهنگ می کنیم، طرح ها را ثابت می کنیم، تولید و آزمایش های خودکار را انجام می دهیم، به صورت افزایشی تکامل می یابیم. در نتیجه، ما یکپارچگی قابل پیش بینی، سرعت بالای توسعه و مقاومت سیستم ها در برابر تغییرات در مقیاس و فرمان را دریافت می کنیم.