בטנת API וניתוח סטטי

1) מדוע לקשר בין API

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

עיקרון: "חוזים נבדקים באופן אוטומטי; יחסי ציבור ללא ריפוד ירוק אינם מחזיקים מעמד"

2) מתקני קווית

1. חוזים: OpenAPI/ASyncAPI/GraphQL SDL, Protobuf/Avro/JSON Schema.
2. יישום: REST/gRPC pens, תוכנה בינונית, קודי מצב/כותרות.
3. תשתיות: ראשי אבטחה, גבולות, מדיניות מטמון.
4. חפצים קשורים: דוגמאות, אוספי דוור, תוכניות שגיאה.

3) כללים בסיסיים עבור API HTTP (פרופיל מומלץ)

3. 1 סימון וכתובת

snake_case בגופות JSON, קבב-מקרה בנתיבים, או קבב-מקרה אחיד/' v1/... '.
משאבים - ברבים: '/v1/תשלומים ', מקונן '/v1/ארנקים/{ id }/עסקאות'.
מזוהים כנתיב-פאראמים: '/v1/תשלומים/_ payer _ id '(סוג: מחרוזת, פורמט: uuid).

3. 2 שיטות ומדינותName

'קבל' - 200/206; " פוסט '201 (+' מיקום '), קונפליקטים - 409; אימות - 422; גבולות - 429 (+ 'Retry-After').
אל תחזיר 200 על טעויות. שאילתות מותנות - 304 על ידי ”אם-אף התאמה”.

3. 3 שגיאות (תבנית יחידה)

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"...", "details":[{"field":"amount","reason":"min:1"}] }

נדרש: "קוד", "הודעה", "trace _ id'; מקום - באמצעות 'שפת תוכן'.

3. 4 פאגינציה/מסננים

מבוסס על הסמן: ”page _ size”, ”page _ token”, ”next _ page _ token”.
מסננים ומיון - לבנים מתועדים ”פרמטרים”.

3. 5 בטיחות

ערכת אבטחה אחידה: OAuth2/OIDC סקופים או mTLS; להכחיש 'http' (רק 'https').
אל תחזירו כותרות רגישות, מסכו אסימונים בדוגמאות.

3. 6 מגבלות ומימדים

גבולות גוף/כותרת: 413/414/431; תיעד את הערכים המותרים המקסימליים.

4) כלים ומערכת אקולוגית

4. 1 OpenAPI

ספקטרלי (JSON/YAML mint), לינטר רדוקלי (Redocly linter), oas-diff/openapi-diff (semantic diff), סכימה/דרד (בדיקות בתהליך).

4. 2 Protobuf/gRPC

Buf (מוך + שבירת צ 'ק), פרוטולינט, גנרטורים SDK; גנוסטי לניתוח.

4. 3 GraphQL

גרפקל-סכימה-לינטר, גרפקל-מפקח (שבירה).

4. 4 קווי קוד ו ־ SAST

ESLINT, GOLANGCI-WINT, Detekt/Ktlint, Pylint/Flake8, Semgrep (ריח API ותבניות אבטחה).

5) דוגמאות חוק: Spectral/Redocly

5. ספקטרלי 1 (דוגמה "ספקטרלי. yaml')

yaml extends: ["spectral:oas", "spectral:asyncapi"]
rules:
openapi-tags: off info-contact: error no-http: error path-kebab-case:
description: "Paths must be kebab-case"
given: "$.paths[]~"
severity: error then:
function: pattern functionOptions: { match: "^/(?:[a-z0-9]+(?--[a-z0-9]+)/?)+$" }
response-error-schema:
description: "Error responses must use standard schema"
given: "$.paths[][].responses[?(@property >= '400')]"
then:
field: "content.application/json.schema.$ref"
function: truthy id-as-uuid:
given: "$..parameters[?(@.name =~ /.id$/i)]"
then:
field: schema.format function: enumeration functionOptions: { values: ["uuid"] }

5. 2 Redocly (שבר ". redocly. yaml')

yaml apis:
main: openapi.yaml lint:
extends:
- recommended rules:
no-ambiguous-paths: error operation-2xx-only: off operation-success-response:
severity: error where:
subject: response filterInParentKeys: ["200","201","204"]
operation-security-defined: error no-plain-http: error

6) פרוטובוף/gRPC: פרופיל buf

6. 1 'אבל. yaml&ft

yaml version: v2 modules:
- path: proto lint:
use:
- DEFAULT except:
- PACKAGE_VERSION_SUFFIX # используем v1 в package breaking:
use:
- WIRE_JSON deps: []

• אל תשתמש שוב במספרי שדה; נמחק - ב 'שמור'.
• שדות חדשים - 'אופציונלי' או עם ברירות מחדל; לא לשנות סוגים/סמנטיקה.

7) דיפ סמנטי ושינויים ”שבירה”

7. 1 HTTP

• שינוי סוג השדה/חובה
• מחק מצב/מסלול/פרמטר
• צמצום טווח אנום;
• שינוי בפורמט הזיהוי (uid = string).

• הוסף שדות אופציונליים
• סטטוסים חדשים שאינם משפיעים על המסלול השמח (לדוגמה, מתועד ”422”)
• הארכת אנום.

7. 2 GRPC/Protobuf

מחיקת שדה ללא ”שמור ”/רזרב - שבירה.
שינוי סוג (int32 = מחרוזת) - שבירה.
הוספת תווית חדשה כאפשרות היא בדרך כלל בטוחה.

8) חוזה וקישור קוד

1. קוד Action: דור של תלתלי SDK/שרת, דוגמאות שליליות במבחנים.

2. קוד project: מבחני מפרט, בדיקה אוטומטית של סטטוסים/כותרות.

• לא מכבד 200&ft when 'error! = = nil';
• חובה 'Idempotency-Key' על נתיבי תשלום כתיבה;
• מסווה אסימונים ביומנים.

9) צינור CI/CD (התייחסות)

pre-commit: spectral lint, redocly lint
PR gate:  openapi-diff (base..PR), buf breaking-check, graphql-inspector build:   schemathesis smoke, unit/integration linters (ESLint/golangci-lint)
release:  publish contracts (artifact/broker), sign & tag

• יש פריצה;
• חוקים בסיסיים הופרו (סטטוס/ביטחון/שגיאות)
• אין דוגמאות/תיאורים של פרמטרים.

10) קטלוג כללים (תבנית לארגון שלך)

מזהים וסוגים

'_ id' -' מחרוזת ',' פורמט: uid'.
שדות כסף - 'מחרוזת '/' עשרוני' עם קנה מידה; מטבע - ISO-4217.

טעויות

מזימה מאוחדת (ראה # 3. 3) קודים: 400/401/403/404/409/422/429/5xx.
תמיד ”trace _ id';” Retry-After עבור 429/503.

עבודת אלילים

סמן בלבד; מקס 'page _ גודל' הוא מתועד.

בטיחות

כל המבצעים - 'בלוק אבטחה'; 'סקופים' מתוארים.
אין ”http:” קישורים; TLS 1. 2+.

מטמון/אידמפוטנטיות

GET - 'ETAG/Last-Modified'; לכתיבה - 'Idempotency-Key' (היכן שניתן ליישם).

תיעוד

'summary', 'תיאור', דוגמאות של בקשות/תגובות (בתוקף).

11) דוגמאות לבדיקות אוטומטיות

11. 1 אימות של כותרות אבטחה חובה (ספקטרלי)

yaml security-headers:
given: "$.paths[][].responses['200'].headers"
then:
function: truthy

11. 2 openapi-diff (פסאודו צעד CI)

openapi-diff --fail-on-incompatible base.yaml pr.yaml

11. 3 בדיקת שבירה של ”באף”

buf breaking --against '.git#branch=main'

12) יכולת הבחנה באיכות החוזים

Metrics: שיתוף של PRs עם מקשר שגיאות, לתקן את הזמן, מספר ניסיונות שבירה, ”חובות” לפי הכללים.
לוחות מחוונים: התקדמות הגירה לסכימת שגיאה מאוחדת, כיסוי עם דוגמאות, יציבות גירסה.

13) תרופות אנטי ־ פטריות

”דוק” חי בנפרד מהקוד * desynchronization. שמור על החוזה קרוב לשירות ולשחרר חפץ ממולכד.
לינטר רק ביד. אני זקוק ליחסי ציבור קשים.
דוגמאות אקראיות (לא דטרמיניסטיות) - פתיתים בבדיקות.
אין דוגמאות שליליות וקודי שגיאה.
המצאה מחדש של ערכת השגיאה עבור כל שירות.
התעלמות מבדיקות שבירת פרוטובוף (שינוי תגיות ”בעין”).

14) פרטים של iGaming/Finance

שדות מטבע - קנה מידה/עיגול קבוע; איסור צף.
כותרות חובה ”X-Tenant',” X-Region ”ועקבות” Tracepart'.
כתיבה-ידיות תשלום: בדיקת עבור 'Idempotency-Key', 'Retry-After' ותיקון 409/201 סמנטיקה.
Webhooks PSP/KYC: HMAC/mTLS מתוארים ב- ' Schemes'; אנטי-שידור חוזר (”X-Timestamp”, חלון).
הגבלות אזוריות ומיקום שגיאות (”Content-Language”).

15) רשימת מוכנות למומחים

[ פרופילי ספקטרלי/רדוקלי ] מעוצבים ומחוברים לפני ההתחייבות ושער יחסי הציבור.

[ ] דפוס שגיאות יחיד ומדינות- מחויב ונבדק.

[ ] Openapi-diff/GraphQL מפקח/buf - שינויים שבירת בלוק.

[ ] דוגמאות לבקשות/תגובות תקפות; עבודת אלילים/פילטרים מתועדים.

[ ] מזימות וסקופים מלאים; אין קישורי http.

[ ] לפרוטובוף: ”שמור” על תגיות שנמחקו; שדות חדשים - אופציונליים.

[ ] Semgrep/code linets מופעל; מיסוך סודות ביומנים.

[ ] מודיע מפרסם חפצי חוזה ודוחות סידור.

[ ] Playbook: כיצד לפעול בעת שבירת דיפה (rollback, hotfix, הודעות לאינטגרטורים).

16) TL; DR

יישום קווי חוזה אוטומטיים (Spectral/Redocly, buf/GraphQL Inspector) ו-Semantic diff, תיקון שגיאה/סטטוס/pagination/security, חיבור PR-gate ופרסום חוזים כחפצים. כל פריצה היא אור בלם. עבור כסף/תשלומים - כללים מיוחדים (idempotency, Retry-After, HMAC/mTLS).