بوابة API والتوجيه

1) دور بوابة API في الهندسة المعمارية

• يقبل حركة المرور الواردة (HTTP/HTTP2/HTTP3، WebSocket، gRPC)
• الطرق وفقا للقواعد (المضيف/المسار/الرؤوس/الأسلوب/الاستعلام/الجغرافيا/الوزن/الصحة) ؛
• تطبق السياسات الشاملة: التوثيق/الإذن، تحديد الأسعار، الاتحاد العالمي للغابات، المركز المركزي للبحوث الزراعية، التخزين المؤقت ؛
• إجراء تحولات (تطبيع الرؤوس/الأجسام، gRPC↔JSON، خياطة الرسم البياني QL) ؛
• ويوفر الاستقرار (المهلات، والإعادة، وقاطع الدوائر، والكشف الخارجي) ؛
• ويتيح إمكانية الرصد وإعداد الفواتير (السجلات والمقاييس والآثار والحصص) ؛
• يعزل الطوبولوجيا الداخلية (شبكة الخدمات والخدمات الخاصة).

غالبًا ما يستخدم في أزواج: Edge/API-Gateway + Ingress/Mesh (المبعوث/Istio/Linkerd) - الأول يقرر السياسة الخارجية، والثاني - الشرق والغرب.

2) الطوبولوجيات النموذجية

بوابة عالمية واحدة (CDN/edge POP → L7 بوابة → الخدمات) - سياسات مركزية بسيطة.
البوابات الإقليمية (لكل منطقة) + التوجيه الجغرافي/زمن الانتقال الذكي.
متعدد المستأجرين: طرق/مناطق فرعية/مفاتيح مخصصة، وحصص وحدود لكل مستأجر.
Hybrid: on-prem + cloud، رابط/نظر خاص، خلفيات خاصة خلف بوابة API.

3) قواعد توجيه L7

• المضيف/المسار: 'api. مثال على ذلك. com' → '/v1/ords/'.
• العناوين: "X-Client" و "X-Region" و "User-Agent" و "Accept'.
• الطريقة/نوع المحتوى: تمييز JSON/Proto/GraphQL.
• استعلام/جزء: حذر - يؤثر على ذاكرة التخزين المؤقت/المتغيرات.
• Geo/Latency: أقرب ملوثات عضوية ثابتة/منطقة، فشل تحت التدهور.
• مرجح/كناري: توزيع حركة المرور 90/10، 50/50، لزج بواسطة ملف تعريف الارتباط.
• تقارب الجلسة: يعتمد على التجزئة على المفتاح/الرمز (احذر عند التحجيم).

yaml nginx. ingress. kubernetes. io/canary: "true"
nginx. ingress. kubernetes. io/canary-weight: "10" # 10% traffic to new backend

yaml match: { prefix: "/orders", headers: [{name: "X-Experiment", exact_match: "new"}] }
route: { cluster: orders-v2 }

4) البروتوكولات والتوافق

REST/JSON - افتراضي، وصف OpenAPI للتحقق من صحة العميل/توليده.
gRPC - Proto ثنائي فوق HTTP/2 ؛ بالنسبة للعملاء الخارجيين، استخدم ترميز gRPC-JSON.
الرسم البياني QL - الخدمات المجمعة ؛ على المحيط، رصد مدى تعقيد/عمق الاستفسارات.
WebSocket/SSE - ثنائي الاتجاه/الدفع ؛ ضع في اعتبارك المهلة اللزجة.
HTTP/2/3 (QUIC) - تعدد الإرسال/البداية السريعة ؛ تحقق من توافق WAF/proxy.

5) الأمن: التوثيق والإذن

5. 1 النقل

TLS 1. 2 + على المحيط، HSTS، OCSP الدبابيس، PFS.
mTLS لواجهة برمجة التطبيقات B2B/internal وآلة إلى آلة.
IP allowist/denylist، قيود جغرافية.

5. طبقة تطبيق 2

OAuth2/OIDC: رموز حامل JWT، التوقيع/انتهاء الصلاحية/التحقق من الجمهور.
NMAS/signations: date + canonized line + signature (AWS-like) - protection against resultation, repetition (nonce/time window).
مفاتيح واجهة برمجة التطبيقات: كمحدد هوية فقط ؛ - من خلال المكتب الإقليمي لأفريقيا وآسيا والمحيط الهادئ/النطاقات.
CORS: صريح للسماح بالمنشأ، مخبأ ما قبل الرحلة.
WAF: التوقيعات (OWASP API Top 10)، الشذوذ، حماية الروبوت، حقول JSON المتكررة.
DDoS/إساءة استخدام: الحد من الاتصال، دلو رمزي/دلو متسرب، بيرست + متوسط السرعة، حظر ديناميكي.

yaml plugins:
- name: oidc config: { issuer: "...", client_id: "...", client_secret: "...", scopes: ["orders. read"] }
- name: rate-limiting config: { minute: 600, policy: local }

6) التحقق والتحول والتوافق

المخططات: التحقق من صحة الجسم/الرؤوس/البارامترات وفقًا لـ OpenAPI/JSON-Schema/Protobuf.
التحولات: تطبيع الحقل، وإخفاء PII، وإضافة رؤوس الارتباط ('traceparent'، 'x-request-id').
النسخة الأصلية: «Header: X-API-Version», prefixes '/v1 ', resource-versioning; سياسة الاستنكار и غروب الشمس.
المقارنة الخلفية: الحقل الإضافي فقط ؛ تجنب تغييرات «كسر» بدون نسخة جديدة.
الخصوصية: «مفتاح الخصوصية» для POST ؛ البوابة تخزن المفاتيح في Redis مع TTL.

7) المرونة: سياسات الاتصال

المهلة: الاتصال/القراءة/الكتابة ؛ تخلف معقول (على سبيل المثال 1s/5s/5s).
Referies: for safe and idempost; جيتر، تراجع أسي، محاولات قصوى.
قاطع الدائرة: مفتوح على الأخطاء/زمن الانتقال ؛ نصف مفتوح للعينات.
الكشف الخارجي - إزالة الحالات السيئة من المسبح.
الحاجز/المنافسة: قيود على الطلبات المتزامنة لكل مسار.
الفشل: التحلل النشط/السلبي للمنطقة.
حركة المرور في الظل: يعمل V2 «رمادي» بالتوازي مع V1 (لا يوجد تأثير على الاستجابة) للمقارنة.

yaml circuit_breakers:
thresholds:
- priority: DEFAULT max_connections: 1024 max_pending_requests: 2048 max_retries: 3

8) التخزين المؤقت والأداء

HTTP- кеш: "Cache-Control' و" ETag/If-None-Match "و" Vary "و" while-whine-revalidate ".
مخابئ الحافة/الملوثات العضوية الثابتة: CDNs لواجهات برمجة التطبيقات الثابتة والمخبأة (GETs الخفية).
الضغط: «gzip/br» (لا تضغط بالفعل).
انهيار الطلب («الاندماج»): الجمع بين الطلبات المتوازية المتطابقة.
تشكيل الاستجابة: الحقول/المرشحات، القائمة على المؤشر، حدود الحجم.

9) إمكانية الرصد والتشغيل

Метрики: 'l7 _ req _ total {route, method, code}', 'latency _ ms {p50, p95, p99}', 'upstream _ rors',' retry _ count', 'cb _ state', '429 _ rate', 'conta _ usage {مستأجر}'.
Logs: structural, with 'trace _ id/span _ id', 'user _ id/tenant _ id',' client _ ip '.
الآثار: سياق تتبع W3C ("traceparent'،" tracestate ")، ينتشر إلى المنبع.
مراجعة الحسابات: من تسبب في ماذا، وما هي الحقوق ؛ المتاجر الثابتة لواجهات برمجة التطبيقات الحساسة.
SLO/SLA: الهدف P99، ميزانية الخطأ ؛ المستوى الجذري أفضل من المستوى العالمي.

10) إدارة خطة القدرات

حصة لكل مستأجر/مفتاح/تجمع العملاء، بدقيقة/ساعة/يوم.
Burst + حدود مستدامة ؛ دلو متسرب للتنعيم.
الإنصاف: عند التحميل الزائد - طابور عادل بدلاً من «المواجهة لأول مرة».
الأولويات: الطرق النظامية/الحرجة ذات الأولوية والمجموعات المخصصة.

11) إدارة التغيير والإصدارات

الكناري/الأزرق الأخضر: توجيه الوزن ؛ تقدم تلقائي على SLO (أخطاء/زمن انتقال).
ميزة بوابات/أعلام خلفية: تمكين بالرأس/رمز مميز.
معدات التحقق من صحة الظل/الظل: مقارنة الأجسام/الأوضاع، وتحمل الدلتا.
التدريج: المجالات/المسارات المخصصة ('المرحلة. api... ، والمفاتيح الفردية والحصص.

12) أمثلة التكوين

12. 1 NGINX - الحد الأساسي وبوابة ذاكرة التخزين المؤقت

nginx map $http_x_request_id $reqid { default $request_id; }

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

server {
listen 443 ssl http2;
server_name api. example. com;

security add_header Strict-Transport-Security "max-age = 31536000" always;

location /v1/ {
limit_req zone=perip burst=30 nodelay;
proxy_set_header X-Request-ID $reqid;
proxy_set_header Authorization $http_authorization;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;

proxy_cache api_cache;
proxy_cache_valid 200 10s;
proxy_cache_use_stale error timeout updating;
proxy_pass http://orders-v1;
}
}

12. 2 مبعوث - مسار التوازن وإعادة التوجيه

yaml routes:
- match: { prefix: "/orders" }
route:
weighted_clusters:
clusters:
- name: orders-v1 weight: 90
- name: orders-v2 weight: 10 retry_policy:
retry_on: "5xx,reset,connect-failure"
num_retries: 2 per_try_timeout: 2s

12. 3 Traefik - أدوات وسيطة ورؤوس

yaml http:
middlewares:
secHeaders:
headers:
stsSeconds: 31536000 contentTypeNosniff: true routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: svc-orders middlewares: ["secHeaders"]

13) الأنماط المضادة

حد عالمي واحد على الجميع - «الجيران الطيبون» يعانون بسبب «الضجيج».
عمليات إعادة التدوير دون الخصوصية → الآثار المزدوجة (المدفوعات، الكيانات المنشأة).
تجاهل «المهلة »/« حجم الجسم الأقصى» → يعلق/يرهق العمال.
مزج سياسات الحافة ومنطق الأعمال في البوابة (ترجيح المحيط).
عدم التحقق من صحة المخططات → وهشاشة العملاء و «كسر» الإصدارات.
Naked WebSocket باستثناء auth/limits/ille-time.
الأسرار في العناوين الرئيسية دون تناوب ؛ لا يوجد mTLS في B2Bs الداخلية.

14) كتب اللعب التجريبية (أيام اللعبة)

عاصفة الطلبات: فحص محدد/حصة، سلوك 429، تدهور.
فقدان مجموعة واحدة: إعادة توزيع الفشل/الوزن ؛ طيور الكناري SLO.
الإجابات المرجحة: الحد الأقصى للجسم/المهلة ؛ قطع المفاصل.
الحقن/الشذوذ: قواعد WAF، تثبيط JSON المتكرر، أعماق GraphQL الكبيرة.
فشل التتبع في التحقق من انتشار «التتبع» وأخذ العينات.
الأسرار: دوران المفتاح/JWKS، انتهاء صلاحية الرمز، تحمل انحراف الساعة.

15) قائمة التنفيذ المرجعية

• المجالات/المسارات/الإصدارات المحددة، OpenAPI/Proto المنشورة.
• تم تشكيل TLS/mTLS و HSTS والإدارة السرية والتناوب.
• التوثيق (OIDC/HMAC)، RBAC/scopes، تمكين CORS.
• حدود/حصص لكل مستأجر، طوابير عادلة، 429-UX.
• توجيه الوزن/الرأس وخطة الكناري والتراجع.
• المهلة/إعادة النظر/كسر الدائرة/السياسات الخارجية.
• التحقق من صحة المخطط، والتحولات، وإخفاء PII.
• Edge- кеш/ETag، الدمج، gzip/br.
• إمكانية الرصد: المقاييس والسجلات والمسارات ولوحات القيادة والتنبيهات.
• كتب التشغيل: الحوادث، تناوب المفاتيح، قوائم الكتلة، الجمعة السوداء.

16) الأسئلة الشائعة

س: كيف تختلف بوابة API عن شبكة الخدمة ؟

أ: البوابة - الشمال - الجنوب (المحيط الخارجي، السياسات الشاملة). الشبكة - الشرق - الغرب (الاتصال داخل الرصيف/MTLS/retrai). غالبا ما تستخدم معا.

س: أين تنفذ auth: في البوابة أو الخدمات ؟

ج: كلا المستويين: بوابة - خشنة (المصادقة، الحقوق الأساسية/الحصص)، الخدمة - دقيقة (أدوار/سمات المجال).

س: متى يلزم إعادة ترميز gRPC-JSON ؟

ج: عندما يتطلب gRPC الداخلي والخارج REST/JSON والعملاء/المتصفحات البسيطة.

س: كيف تختار استراتيجية الإصدار ؟

ج: لواجهات برمجة التطبيقات العامة - رؤوس الحرمان «/vN »+ والتداخل الطويل. بالنسبة لنظام الأعلام/التوافق الداخلي.

17) المجاميع

بوابة API ليست مجرد وكيل، ولكنها مركز للسياسات والمرونة. ويتيح التوجيه السليم، والأمن، والحدود، والتحقق من الصحة، وقابلية الملاحظة إمكانية التنبؤ وسرعة الإطلاقات. اجمع بين بوابة الحافة وشبكة الخدمة، وأتمتة طيور الكناري والحصص، واختبار الإخفاقات - وسيصبح المحيط دواسة الوقود الخاصة بك، وليس عنق الزجاجة.