תכנון פרוטוקול ראשון

מהו פרוטוקול-ראשון

פרוטוקול-ראשון (באנגלית: Protocol-first) היא גישה שבה מתבצע חוזה אינטראקציה בין רכיבים (שירותים, לקוחות, שותפים חיצוניים). קוד, אחסון, תשתית ותיעוד כפופים לחוזה ונוצרים ממנו באופן אוטומטי, ולא להיפך.

שלא כמו קוד-ראשון, שבו API הוא רק תוצר לוואי של קוד, פרוטוקול-ראשון הופך את הפרוטוקול לחפץ עיקרי: הוא מחזיק במושגי דומיין, מודלים של נתונים, סטטוסים, שגיאות, סמנטיקה של אימפוטנטיות, SLO/SLI ואפילו מדיניות גירסה.

למה אתה צריך את זה?

עקביות ויכולת חיזוי של ממשקים ברחבי הארגון.
עלייה מהירה למטוס (SDK/stable/client autogeneration, שגיאות וקודים אחידים).
אבולוציה אמינה (תאימות של מזימות, חוזי מבחן, מדיניות גירסה ברורה).
מיקוד מוצר: לדון בהתנהגות, SLA ואינטגרציה של UX לפני כתיבת קוד.
אוטומציה: CI/CD אוסף חפצים (לקוחות, תלושי שרת, מאשרים) ממקור אמת אחד.
ביטחון וציות: זכויות, מיסוך מח "ש, מדיניות השמירה מעוגנת בחוזה.

גישת ליבה

1. מקור אמת יחיד (SSOT) - מפרט ניתן לקריאה במכונה:

מנוחה: OpenAPI/JSON Schema.
אירועים וזרימה: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Trifft, Smithy.
GraphQL: SDL + הוראות/מדיניות.
2. הסדרי קדם-יישום: גלוסרי דומיין, קודי שגיאה, סמנטיקה אידמפוטנטיות, מועדים, מגשים מחדש, שכפול.
3. אוטוגנרציה: לקוחות/שרתים, סוגים, SDKs, חוזי בדיקה, מוקים, אוספי דוור, Terraform/OpenAPI Gateway config.
4. ממשל: לינטרס/מדיניות (שמות, הפגנות, פילטרים, שגיאות), סקירה באמצעות גילדת API, שינוי-ייעוץ לגרסאות עיקריות.
5. תאימות: אימות קפדני של דיפוזיות ”תוספות בלבד”, ויסות סמנטי, מבחנים קנריים/צרכניים.
6. תצפית ברמת החוזה: זיהוי מתאם, מודלי שגיאה, תקציבי עיכוב מאויתים בפרוטוקול.

איך התהליך נראה (שלד)

1. ייזום: product break user trains = API/Protocol PRD (משאבים/שיטות/אירועים, SLA/SLO, שגיאות, גבולות).
2. מודלים: טיוטת מפרט (OpenAPI/ASyncAPI/Proto) + סכימות נתונים, מילון מונחים.
3. חוזים ואינטגרציות UX: דוגמאות טעינת מטען, חוזי שגיאות, מפות מצב, כללי ויסות.
4. סקירה וממשל: לינטרים/סטנדרטים, דיון על דומיין אינווריאנטים, נעילת MGC (חוזה אחריות מינימלית).
5. דור אוטומטי של חפצים: SDKs, דקירות, תיקוני בדיקה, תלושי תשתית (Gateways, IAM scopes).
6. מבחני יישום וחוזים: הספק והצרכנים עוברים בדיקות תאימות במצ "ח.
7. תצפית ו-SLO: איתור מתאם-זיהוי, קטלוג שגיאות, מגש/תקציב זמן.
8. שחרור ואבולוציה: תוסף ראשון, מדיניות דחייה, קנרית, דגלי יכולת A/B.

פרוטוקולי אינטראקציה וסגנונות

REST/HTTP

תקנים: מודל משאבים, 'GET/POST/PATCH/DELETE', pagination (סמן), מסננים, מיון.
שדות ותוכניות: JSON Schema, פורמטים ("תאריך-זמן", "uuid'), אינווריאנטים (regex/enum/min-max).
שגיאות: פורמט יחיד ("סוג", "קוד", "שם", "פרט", "trace _ id'), מיפוי לערימות HTTP.
שינוי בקרה: ETag/If-Match, מפתחות אידמפוטנטים עבור POST, סמנטיקה מפורשת 409/422.

gRPC/RPC

פרוטובוף: תווית יציבה שמספרה, ”אופציונלי”, מפרה שימוש חוזר בשדות שנמחקו.
מועדים וסדרי עדיפויות בחוזה; סטטוסים יציבים (בסדר, INVALID_ARGUMENT, FAILED_PRECONDITION וכו ').
הזרמה: מפרט הזמנת הודעה, תרמיל אחורי, טריילרים אחרונים.

מונע אירועים (קפקא/NATS/SNS/SQS)

ASYNCAPI: נושאים/ערוצים, מפתחות חלוקה, מוסכמות מפתח שכפול, חזרות, סמנטיקה ”נגד” לפחות פעם אחת

אירוע ליבה והעשרה: מטען מינימלי נפרד והרחבות; גרסה ”event _ type ”/” schema _ version”.
idempotency: ”event _ id',” productor _ id', policy on retrays and deflication.

GraphQL

SDL כחוזה, הנחיות לפחת, מגבלות על עומק ומורכבות, קודי שגיאה/חוזה הרחבות.

אינטגרציה עם עקרונות ארכיטקטוניים

פירמידה הפוכה/נתיב ביקורתי ראשון: במפרט, הדגש על MGC (מינימום חובה), הרחבות - דרך '? כולל '/יכולות.
Roads: קבוצה של תבניות מפרט מוכנות (תשלום, KYC, ביקורת, חיפוש, קבצים) + linters.
API Gateways & Service Mesh: מדיניות מבוססת חוזה (rate-limits, auth scopes, retrics, מעגל חשמלי).

Versioning and Evolution

• מינור = שדות תוספים/ערוצים בלבד.
• Major = שבירת שינויים (מחיקות, שינוי שם, שינוי סמנטיקה).
• מדיניות דחייה: תמיכה בחלונות, כותרות ”שקיעה”, אירועי הודעה.
• חוזים המונעים על ידי צרכנים (CDC): אימות כי ה-API הנוכחי מספק צרכנים ספציפיים.
• ספריית סכימה: Schema Registry/Archact Registry עם כללי תאימות והיסטוריה (BACWARD/FORWARD/FULL).

בטיחות וציות

אימות/אישור כחלק מהחוזה (OAuth2/OIDC סקופים, mTLS, JWT טוען).
PII/PCI: מיסוך, תבניות סימון, שדות עם מצבי אחסון/TTL מיוחדים.
מדיניות ביקורת: תכונות דרושות ("שחקן", "נושא", "פעולה", "התרחש _ at", "trace _ id').
גבולות: קצב הגבלת כותרות, מכסות, מידות הודעה, מועדים.

תצפית חוזה

קורלציה/בקשה-זיהוי: נדרש במפרט.
קטלוג שגיאות - רשימה קבועה של קודים ו ־ SLAs לפתרון.

SLI/SLO: p50/p95 latency, פרופורציה של תגובות מוצלחות,

בדיקה ואיכות

מבחני חוזה (ספק ↔ צרכן), סכימת diff ב CI, דור של שרתים מדומים.
דוגמאות זהב: דוגמאות התייחסות של בקשות/תגובות, קבצים עבור e2e.
הזרקת כאוס/איחור: בדיקת זמן/מגש מחדש, הידרדרות של הרחבות בעת שמירת אם-ג 'י-סי.

תבניות דומיין

תשלום (מנוחה + אירועים)

"POST/תשלומים" = "201 נוצר" עם "תשלום _ id'," סטטוס = מורשה ".
התשלום של האירוע. מורשה. (v1): ”payment_id, סכום, מטבע, שיטה, occurred_at”.
תשלום הארכה. מועשר. שיעור סיכון, גיאו, טביעת אצבע של מכשיר.
שגיאות: '422' (אימות), '402' (תשלום נדרש), '409' (שכפול).
SLA: אישור לשימור 800ms p95; אירוע קרנל בלום 2c לג p95.

KYC (תורים gRPC +)

RPC 'StreatVerification (user_id)' ac 'operation _ id'.
אירועי התקדמות בנושא 'kyc. סטטוס. V1 ('תלוי ועומד' 'abc' אושר/נדחה ').
החוזה קובע שדות PII, חיי מדף, מיסוך, קודי כשל סיבתי.

audit (אירוע בלבד)

ביקורת חשבונות. מוקלט. "שחקן", "נושא", "פעולה", "התרחש _ at", "trace _ id'.
העשרה: IP, התקן, geo - אירוע/חוט נפרד, אינו חוסם את הליבה.

כלים ואוטומציה (ערימה משוערת)

OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL.
Spectral, OpenAPI Diff, Buf (פרוטובוף), Confluent SR.
OpenAPI Generator, Buf/Protoc, GraphQL Codegen, ASyncAPI Generator.
שער: Kong/Apigee/Azure/GCP GW, שליח.
Pact/CDC, Dred, Schemathesis, Hoverfly, MockServer.
רשום: Git-directory of schemes + Schema Registry/Argistry.
תיעוד: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

אנטי-דפוסים

קוד ראשון במקרה: MVP ראשון על בקרים, מפרט פוסט עובדתי, אי התאמה בין תיעוד והתנהגות.
Swagger-Watch: OpenAPI פורמלי ללא חוקים אמיתיים (שגיאות, גבולות, SLAs, גרסאות).
הפסקת תאימות: שדה הוסר/שונה סוג ללא גרסה עיקרית; שימוש חוזר בתגי פרוטובוף.
תגובה ”עבה” ללא פולחן/פילטרים; חוסר אידאות.
אבטחה מחוץ לחוזה: auth/Scopes מתוארים בוויקי, אבל לא במפרט.

יחסים לעבד ארגון

נאמני סטנדרטים, ביקורות שינוי, הכשרה.
Docs עיצוב: עבור כל API - PRD, ADR (פתרונות), SLA, מטריצת סיכון.
שינוי ניהול: תהליך RFC, הערות שחרור, מדריכי נדידה, ציר זמן סטייה.
Saved Road & Templates: מחולל מסגרת שירות מהמפרט (שלד מטפל, אימות, רישום).

בדיקות

לפני תחילת

[ ] יש PRD וגלוסרי דומיין.

[ ] סגנון נבחר (Rest/gRPC/Event/GraphQL) ופורמט סכימה.

[ ] MGCs, טעויות, SLA/SLOs, כללי אידמפוטנטיות מוגדרים.

תחת פיתוח

[ ] מפרט עובר ספינים וסקירה.

[ ] SDK/Stable/Fixture אוטומטית מוגדרת.

[ ] בדיקות חוזה (CDC) כלולות במצ "ח; סכימה-דיף חוסמת שינויים לא מתאימים.

לפני השחרור

[ ] תיעוד אינטגרטור עם דוגמאות וקודי שגיאה.

[ ] ניתן לצפות בחוזה: זיהוי מתאם, קטלוג שגיאות, לוחות מחוונים של SLI.

[ ] מדיניות ורסיונינג ופחת מוכרזים.

FAQ

איך פרוטוקול-ראשון שונה API-ראשון?
לעיתים קרובות משתמשים במונחים להחלפה. במאמר זה תחת הפרוטוקול הראשון, אנו מדגישים את הקפדה על החוזה וכיסוי כל הסגנונות (REST/RPC/Events/GraphQL), כולל SLA, בטיחות ויכולת תצפית.

האם זה יאט את הפיתוח?
ההתחלה עשויה להיות קצת יותר ארוכה, אבל אז אנחנו מנצחים על אינטגרציה, יציבות ומהירויות פיתוח מקבילות (דור אוטומטי, SDKs יציב).

מה לעשות עם ניסויים מהירים?
השתמש בגרסאות ”טיוטה” של סכימות (טיוטה), דגלים מאופיינים וארגזי חול, אך לא מדלג על סיכות וכללי תאימות בסיסיים.

סך הכל

העיצוב הראשון של הפרוטוקול הופך את החוזה למרכז הארכיטקטורה: אנו מתאמים התנהגות, מתקנים תוכניות, כתוצאה מכך, אנו מקבלים אינטגרציות צפויות, מהירות פיתוח גבוהה והתנגדות של מערכות לשינויים בקנה מידה ובפיקוד.