الملحقات والأدوات الوسيطة في واجهة برمجة التطبيقات البوابة

1) لماذا تحتاج إلى ملحقات وأدوات وسيطة

• توحد السلامة (authN/authZ، WAF، CORS)،
• يحمي الاستقرار (حد السعر، قاطع الدائرة، سياسات إعادة التجربة)،
• يدير العقد (المصادقة على المخططات، التحويلات)،
• يعطي إمكانية الرصد (المقاييس، الجذوع، التعقب)،
• يقلل التكلفة (التخزين المؤقت والتفريغ وقواعد الكناري)

المفتاح: الحد الأدنى من زمن الوصول واتساق التطبيق الواضح.

2) فصول الإضافات وما تفعله

1. تحديد الهوية/التوثيق

مزودو JWT/JWKS، OAuth2/OIDC، مفاتيح API، mTLS (شهادة العميل).
توقيعات HMAC (خطوط الويب/الشركاء)، DPoP/PO على الحافة.

2. الإذن

RBAC/ABAC/OPA/Cedar (PDP) مع مخبأ الحل المحلي.
BOLA-guard: التحقق من «المستأجر »/« المالك» في الرؤوس/السياق.

3. حماية الشبكة والبروتوكول

WAF (OWASP CRS)، ومضادات الروبوتات (معدل/سلوكي)، ومرشحات Geo/IP/ASN، وملامح TLS.
CORS, CSP headers, Fetch-Metadata filters, CORP/COOP/COEP.

4. الاستقرار

تحديد الأسعار (دلو رمزي/GCRA) والحصص والقدرة التنافسية.
قاطع الدائرة، المهلة، التزامن التكيفي، تساقط الأحمال.
سياسة إعادة المحاولة مع المهلة لكل تجربة والركض.

5. التحويلات والتحقق

المسار/التعداد الرئيسي، إعادة كتابة الجسم، JSON/XML ↔، gRPC ↔ HTTP.
التحقق من صحة المخطط (OpenAPI/JSON Schema/Protobuf)، تطبيع الهوية.

6. التخزين المؤقت والأداء

مخبأ الاستجابة/الشظايا، ETag/If-None-Match، الضغط، brotli.
طلب الانهيار (الدمج) لنفس المفاتيح.

7. إمكانية الملاحظة ومراجعة الحسابات

مقاييس RED/USE، تسجيل القرارات (429/403/5xx)، التعقب (W3C Trace-Context/OpenTelemetry)، أخذ العينات (الذيل/التكيف).
ترويسات أمن مراجعة الحسابات ونسخ السياسات.

8. دورة الحياة والتشغيل

كناري/أزرق أخضر، أعلام مميزة، حلول الظل (سجل، لا تطبيق)، هجرات الإصدار.

3) إجراءات التطبيق (السلسلة الموصى بها)

[Ingress TLS]
→ Early-Deny (ASN/Geo, IP allow/deny)
→ mTLS / Client Cert Auth
→ JWT/OAuth2 AuthN (JWKS cache)
→ OPA/ABAC AuthZ (solution cache)
→ Rate Limit / Concurrency
→ Circuit / Timeout / Retries (пер-try)
→ Schema Validation (request)
→ Transform (headers/path/body) / CORS
→ Caching (lookup)
→ Upstream Proxy (app)
← Caching (store) / Compression
← Response Transform / Schema Validation (response)
← Logging / Tracing / Metrics / Security Headers

المبدأ: سابقًا - أرخص/أكثر فتكًا (إنكار، أوث، حدود)، لاحقًا - «مستحضرات التجميل» (التحول، ذاكرة التخزين المؤقت).

4) الأداء والكاردينالية

التزم بخطوات O (1) دون طلبات خارجية على الطريق الساخن.
جميع «المكالمات الخارجية» الإضافية (PDP/JWKS) تتم عبر TTL قصيرة وتحديث غير متزامن.
ملصقات/ملصقات للمقاييس - كاردينالية محدودة («مستأجر»، «خطة»، «مسار»، ولكن ليس «مستخدم _ هوية»).
الملحقات «الثقيلة» (WAF، تحويل الجسم) - تمكين انتقائي لكل مسار.

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

5. 1 المبعوث: JWT + RateLimite + OPA + Retires (زائف)

yaml static_resources:
listeners:
- name: public_listener filter_chains:
- filters:
- name: envoy. filters. network. http_connection_manager typed_config:
route_config:
name: main virtual_hosts:
- name: api domains: ["api. example. com"]
routes:
- match: { prefix: "/v1/payments" }
route:
cluster: payments timeout: 350ms retry_policy:
retry_on: connect-failure,reset,5xx,gateways num_retries: 1 per_try_timeout: 200ms http_filters:
- name: envoy. filters. http. jwt_authn typed_config:
providers:
oidc:
issuer: https://auth. example. com/
remote_jwks:
http_uri: { uri: https://auth. example. com/.well-known/jwks. json, cluster: jwks, timeout: 2s }
cache_duration: 300s forward: true
- name: envoy. filters. http. ext_authz  # OPA/Cedar PDP typed_config:
http_service:
server_uri: { uri: http://opa:8181, cluster: opa, timeout: 50ms }
authorization_request: { allowed_headers: { patterns: [{ exact: "authorization" }, { exact: "x-tenant" }] } }
- name: envoy. filters. http. ratelimit typed_config:
domain: public-api rate_limit_service:
grpc_service: { envoy_grpc: { cluster_name: rl } }
- name: envoy. filters. http. router

5. 2 NGINX/OpenResty: HMAC + Lua + Redis (زائف)

nginx lua_shared_dict jwks 10m;
lua_shared_dict limits 10m;

server {
listen 443 ssl http2;

Early deny by ASN/Geo if ($bad_asn) { return 403; }

HMAC signature check (webhooks/partners)
set_by_lua_block $sig_ok {
return verify_hmac_signature(ngx. var. http_x_signature, ngx. var. request_time, ngx. var. request_body)
}
if ($sig_ok = 0) { return 401; }

Token bucket in Redis access_by_lua_block {
local key = ngx. var. binary_remote_addr.. ":".. ngx. var. request_uri local allowed, retry_after = ratelimit_allow(key, 50, 100)
if not allowed then ngx. header["Retry-After"] = retry_after return ngx. exit(429)
end
}

proxy_read_timeout 300ms;
proxy_connect_timeout 100ms;
proxy_pass http://app_backend;
}

5. 3 كونغ: ملحقات على طول الطريق

yaml services:
- name: payments url: http://payments:8080 routes:
- service: payments paths: ["/v1/payments"]
plugins:
- name: jwt config: { key_claim_name: kid, secret_is_base64: false, run_on_preflight: false }
- name: opa config: { server_url: "http://opa:8181/v1/data/authz/allow", timeout: 50 }
- name: rate-limiting config: { second: 50, policy: redis, redis_host: redis, fault_tolerant: true }
- name: correlation-id config: { header_name: "traceparent" }
- name: response-transformer config: { add: { headers: ["Strict-Transport-Security:max-age=31536000"] } }

5. 4 أباتشي APISIX: JWT + Limite + Proxy-Mirror (ظل)

yaml routes:
- uri: /v1/wallets/
plugins:
openid-connect:
client_id: wallet discovery: "https://auth. example. com/.well-known/openid-configuration"
scope: "openid"
limit-count:
count: 100 time_window: 60 key_type: "var"
key: "remote_addr"
proxy-mirror:          # shadow traffic host: "http://shadow-backend:8080"
upstream_id: 1

5. 5 Traefik: سلسلة البرامج الوسطى

yaml http:
middlewares:
hsts-headers:
headers:
stsSeconds: 31536000 stsIncludeSubdomains: true ratelimit:
rateLimit:
average: 50 burst: 100 routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: app middlewares:
- hsts-headers
- ratelimit

6) نسخ متعددة الإيجارات والسياسات

مفتاح التوجيه: «{مستأجر، مخطط، منطقة، مسار، إصدار}».
تقرأ الملحقات «المستأجر» من mTLS SAN/JWT stamp/header → تطبيق الحدود/الحصص/القواعد على المستأجر.
الإصدار السياسات («policy _ version»)، إدخال changelog و canary out.

7) الاختبار والبدء

قبل الإصدار

اختبارات سلسلة العقود (إذا كان الجدول آنذاك): auth→deny، auth→allow، rate→429، schema→422.
التحميل: رشقات نارية × 10، هضاب طويلة، أنماط «قذرة» (بطيئة البريد).
الفوضى: تدهور PDP/JWKS/Redis - يجب أن يكون مغلقًا/تدهورًا إلى الحد الأدنى من الأمان.

الإصدار

'Report-Only '/shadow-mode (log solutions without application).
حركة مرور الكناري 1-5٪ + مقارنة مترية (p95/p99، 4xx/5xx/429).
التراجع التلقائي عن SLO/التنبيهات.

8) إمكانية الرصد والمقاييس

• 'http _ requests _ total {الطريق، المستأجر، الخطة، الحالة}'
• 'request _ turnation _ seconds _ bucket {route}' (p95/p99)
• 'rate _ limited _ total {policy}', 'retry _ total {reason}', 'circuit _ state'
• 'authn _ fail _ total {reason}', 'authz _ densed _ total {action}'
• 'schema _ validation _ fail _ total {routh}'
• الآثار: يمتد لكل مرشح، السمات «policy _ version»، «المستأجر»، «الحد _ key».
• الجذوع (مأخوذة عينات): محاليل الرفض/429/5xx ذات الأسباب و 'التعقب _ id'.
• لوحات القيادة: ملخص تنفيذي، لكل مسار، لكل مستأجر، سياسيون «ساخنون».

9) السلامة والتشغيل

جميع الأسرار (HMAC، JWKS private، API keys) - في KMS/Vault، وليس في ملفات التهيئة.
سياسة الرفض الافتراضي للطرق الحساسة.
مخبأ TTL JWKS/PDP قصير، تحديثات غير متزامنة مع عودة.
هجرة مخططات التحول - تحريرها ؛ «كسر» - عبر الكتابة المزدوجة.
حد من حجم الجسم (DoS) وعمق JSON.

10) أنتيباترن

مجموعة شاملة من الملحقات على كل مسار → مللي ثانية إضافية وفواتير.
التبعيات الخارجية للملحقات بدون مخبأ/مهلة → فترات زمنية متتالية.
عدم وجود ترتيب مرشح: التحويل/المنطق الأول، ثم الحدود - غير صحيح.
الكاردينالية العالية للملصقات المترية (raw 'user _ id '/' ip').
مزج authN/authZ في أنماط التحول (حلول ضمنية في Lua/Jinja).
تسجيل الأسرار/الرموز.
مجموعة/مجموعة Redis عالمية واحدة لجميع الحدود بدون كسر/احتياطي.

11) تفاصيل iGaming/Finance

لكل مستأجر/لكل ولاية قضائية: KYC/AML، العقوبات، حدود المدفوعات المسؤولة.
السياسات الصعبة لطرق الدفع: مهلات قصيرة، تكرار واحد، الخصوصية («مفتاح الخصوصية»).
محيط مقسم لـ PSP/KYC SDK (مجالات منفصلة/سلاسل ملحقة).
مراجعة سجلات القرارات غير القابلة للتغيير (الاستنتاجات، والمنع، ورفض العقوبات).

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

• ترتيب المرشح هو authN authZ حدود الدائرة/المهلة مخطط تحويل المخبأ.
• مجموعة الملحقات لكل مسار ؛ ثقيلة - فقط عند الضرورة.
• JWKS/PDP مع TTL قصيرة ومخبأ ؛ المهلة والاستراتيجيات الاحتياطية.
• السعر/الحصة/التوافق - تم تصميم المفاتيح وتخزينها.
• مجموعة مترية RED/USE، وتتبع OTel، وأخذ عينات من الذيل/التكيف.
• وضع الظل الكناري +، التراجع التلقائي بواسطة SLO.
• أسرار في KMS/Vault ؛ التكوينات - مع الهجرات.
• حدود الجسم/الرأس ؛ حماية كبيرة الحجم/بطيئة.
• وثائق العملاء: الرموز 401/403/409/422/429/5xx، «Retry-After»، مثال الرؤوس.

13) TL ؛ د

بناء سلسلة «فشل مبكر → التوثيق/الترخيص → حدود/ثبات → التحقق → التحويل/ذاكرة التخزين المؤقت → القياس عن بعد». قم بتمكين الملحقات اللازمة فقط لكل مسار، وتخزين الحلول الخارجية (JWKS/PDP)، وتحديد المهلات وإعادة تجربة السياسات، والتحكم في كاردينالية المقاييس. أطلق عن طريق الظل/الكناري، احتفظ بالأسرار في KMS/Vault وقياس تأثير كل ملحق على p95/p99.