بطانة واجهة برمجة التطبيقات والتحليل الثابت

1) لماذا ربط واجهة برمجة التطبيقات

• منع التغييرات غير المتوافقة والضمنية
• وتوحيد الأوضاع والأخطاء والتجميع والأمن ؛
• وجعل المواصفات قابلة للتحقق منها آلياً وإطلاقها قابلاً للتنبؤ ؛
• تقليل تكلفة المراجعة ووقت الصعود.

المبدأ: "تفحص العقود تلقائيا ؛ العلاقات العامة بدون وصلة خضراء لا تصمد"

2) مرافق التبطين

1. العقود: OpenAPI/AsyncAPI/GraphQL SDL، Protobuf/Avro/JSON Schema.
2. التنفيذ: أقلام REST/gRPC، البرامج الوسيطة، رموز الحالة/الرؤوس.
3. البنية التحتية: رؤوس أمنية، حدود، سياسات التخزين المؤقت.
4. القطع الأثرية ذات الصلة: أمثلة، مجموعات ساعي البريد، مخططات الخطأ.

3) القواعد الأساسية لـ HTTP API (الملف الشخصي الموصى به)

3. 1 التدوين وعنوان URL

snake_case في أجسام JSON، أو حالة كباب في المسارات، أو حالة كباب موحدة/'/v1/... '.
الموارد - الجمع: '/v1/المدفوعات '، متداخلة - '/v1/wallets/{ id }/المعاملات'.
المعرفات على أنها مسار بارام: '/v1/payments/{ payment _ id} '(النوع: سلسلة، تنسيق: uid).

3. 2 الطرق والأوضاع

"احصل" - 200/206 ؛ " POST' - 201 (+ 'الموقع')، النزاعات - 409 ؛ المصادقة - 422 ؛ حدود - 429 (+ «إعادة المحاولة بعد»).
لا تعيد 200 للأخطاء. استفسارات مشروطة - 304 بواسطة «If-None-Match».

3. 3 أخطاء (شكل واحد)

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

مطلوب: 'رمز'، 'رسالة'، 'تتبع _ معرف' ؛ locale - via 'Content-Language'.

3. 4 فلاتر/فلاتر

قائمة على المؤشر: «page _ size», «page _ token», ответ: «next _ page _ token».
المرشحات والفرز - تم توثيق القوائم البيضاء في «المعلمات».

3. 5 السلامة

المخطط الأمني الموحد: النطاقات OAuth2/OIDC أو نظام التحليل اللوجستي ؛ إنكار "http" (فقط "https').
لا تعيد الرؤوس الحساسة، قناع الرموز في الأمثلة.

3. 6 القيود والأبعاد

العنوان/حدود الجسم: 413/414/431 ؛ توثيق القيم القصوى المسموح بها.

4) الأدوات والنظام الإيكولوجي

4. 1 OpenAPI

Spectral (JSON/YAML lint), Redocly linter, oas-diff/openapi-diff (semantic diff), schemathesis/dredd (checks in progress).

4. 2 Protobuf/gRPC

buf (الوبر + كسر الفحص)، البروتولينت، مولدات SDK ؛ غنوصي للتحليل.

4. 3 رسم بياني QL

graphql-schema-linter, graphql-inspector (breaking).

4. 4 محددات الكود و SAST

ESLint، golangci-lint، Detekt/Ktlint، Pylint/Flake8، Semgrep (رائحة API ونماذج الأمان).

5) أمثلة القاعدة: الطيف/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) Protobuf/gRPC: ملف تعريف buf

6. 1 'بوف. يا "

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

• لا تعيد استخدام أرقام الحقول ؛ محذوفة - في «محفوظة».
• مجالات جديدة - «اختيارية» أو متخلفة عن السداد ؛ لا تغير الأنواع/الدلالات.

7) تغييرات دلالية و «كسر»

7. 1 HTTP

• نوع حقل التغيير/إلزامي
• تحذف الحالة/المسار/البارامتر
• وتضييق النطاق/التضييق ؛
• تغيير تنسيق المعرف (أويد → سلسلة).

• أضف مجالات اختيارية
• حالات جديدة لا تؤثر على المسار السعيد (على سبيل المثال، موثق «422»)
• تمديد enum.

7. 2 gRPC/Protobuf

حذف حقل بدون «محفوظ »/إعادة ترقيم - كسر.
تغيير النوع (int32 → سلسلة) - كسر.
عادة ما تكون إضافة علامة جديدة على أنها اختيارية آمنة.

8) ربط العقود والرموز

1. عقد → الرمز: توليد SDK/server stubs، أمثلة سلبية في الاختبارات.

2. رمز → العقد: اختبارات المواصفات، التحقق التلقائي من الحالات/الرؤوس.

• عدم السماح بـ «return 200» عندما «خطأ! = لا شيء» ؛
• إلزامية «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' - 'string', 'format: uuid'.
حقول المال - 'سلسلة '/' فاصلة عشرية' بمقياس ؛ العملة - ISO-4217.

أخطاء

مخطط موحد (انظر الفقرة 3). 3)، الرموز: «400/401/403/404/409/422/429/5xx».
' إعادة المحاولة بعد 429/503.

التثبيت

المؤشر فقط ؛ تم توثيق «max page _ size».

السلامة

جميع العمليات - كتلة «الأمن» ؛ تم وصف «النطاقات».
لا توجد روابط «http:» ؛ TLS 1. 2+.

ذاكرة التخزين المؤقت/الخصوصية

Для GET - 'ETag/آخر تعديل' ؛ للكتابة - «Idempotency-Key» (عند الاقتضاء).

الوثائق

«summary»، «description»، أمثلة على الطلبات/الردود (صالحة).

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-check

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

12) إمكانية رصد نوعية العقود

المقاييس: حصة العلاقات العامة مع ربط الأخطاء، تحديد الوقت، عدد محاولات الكسر، «الديون» وفقًا للقواعد.
لوحات القيادة: تقدم الهجرة إلى مخطط الخطأ الموحد، والتغطية بالأمثلة، واستقرار الإصدار.

13) أنتيباترن

يعيش "Doc' بشكل منفصل عن الكود → عدم التزامن. حافظ على العقد قريبًا من الخدمة وأصدر قطعة أثرية محفوظة.
بطانة فقط باليد. أحتاج إلى بوابة علاقات عامة صلبة.
أمثلة عشوائية (غير حتمية) - رقائق في الشيكات.
لا توجد أمثلة سلبية ورموز خطأ.
إعادة اختراع مخطط الخطأ لكل خدمة.
تجاهل فحوصات كسر Protobuf (تغيير العلامات «بالعين»).

14) تفاصيل iGaming/Finance

حقول العملات - جدول ثابت/تقريب ؛ حظر الطفو.
الرؤوس الإلزامية "X-Tenant' و" X-Region "وتتبع" traceparent ".
مقابض كتابة الدفع: التحقق من «Idempotency-Key» و «Retry-After» والدلالات الصحيحة 409/201.
شبكات الويب PSP/KYC: HMAC/mTLS موصوفة في «مخططات الأمان» ؛ مكافحة إعادة التشغيل («X-Timestamp»، النافذة).
القيود الإقليمية وتوطين الأخطاء («لغة المحتوى»).

15) قائمة التحقق من الاستعداد

• تم تصميم الملفات الشخصية الطيفية/المتراجعة وتوصيلها في بوابة الالتزام المسبق وبوابة العلاقات العامة.
• نمط وحالات خطأ واحد - تم الالتزام بها والتحقق منها.
• openapi-diff/GraphQL مفتش/buf - تغييرات كسر الكتلة.
• أمثلة على الطلبات/الردود صحيحة ؛ التوثيق/المرشحات.
• تملأ المخططات والنطاقات الأمنية ؛ لا توجد روابط http.
• بالنسبة لـ Protobuf: «محفوظة» على العلامات المحذوفة ؛ حقول جديدة - اختيارية.
• تمكين وصلات Semgrep/code ؛ إخفاء الأسرار في جذوع الأشجار.
• تنشر شركة CI القطع الأثرية للعقود وتقارير الوصلات.
• دليل اللعبة: كيفية التصرف عند كسر ديفا (التراجع، hotfix، الإشعارات إلى المدمجين).

16) TL ؛ د

تنفيذ الربط التلقائي للعقود (Spectral/Redocly، buf/GraphQL Inspector) و diff الدلالي، وإصلاح خطأ واحد/الحالة/الوقوف/نظام الأمان، وربط بوابة العلاقات العامة ونشر العقود كقطع أثرية. أي كسر هو ضوء الفرامل. للمال/المدفوعات - قواعد خاصة (الخصوصية، 'Retry-After'، HMAC/mTLS).