أنماط بوابة API وأفضل الممارسات للتطبيقات الحديثة

**تتعامل بوابات واجهة برمجة التطبيقات (API) مع ما متوسطه 83% من إجمالي حركة مرور المؤسسة، وتعمل كنقطة دخول واحدة لتطبيقات العميل. ** تعمل بوابة واجهة برمجة التطبيقات (API) المصممة جيدًا على تبسيط الاتصال بين العميل والخادم، وتفرض سياسات الأمان، وتوفر إمكانية المراقبة عبر جميع الخدمات. ويصبح التصميم السيئ التصميم بمثابة عنق الزجاجة ونقطة الفشل الوحيدة.

يغطي هذا الدليل أنماط بنية بوابة API واختيار التكنولوجيا وأفضل ممارسات التنفيذ لتطبيقات الويب وأنظمة تخطيط موارد المؤسسات (ERP) ومنصات التجارة الإلكترونية.

الوجبات الرئيسية

• تعمل بوابات واجهة برمجة التطبيقات (API) على مركزية الاهتمامات الشاملة (المصادقة، وتحديد المعدل، والتسجيل) للتخلص من الازدواجية عبر الخدمات
• يعمل تحديد المعدل على مستوى البوابة على حماية الخدمات الخلفية من ارتفاع حركة المرور وإساءة الاستخدام
• تعمل أنماط قواطع الدائرة على منع حالات الفشل المتتالية عندما تكون الخدمات النهائية غير صحية
• يتيح إصدار واجهة برمجة التطبيقات (API) من خلال البوابة تطورًا متوافقًا مع الإصدارات السابقة لسطح واجهة برمجة التطبيقات (API) الخاص بك

---

أنماط البوابة الأساسية

النموذج 1: توجيه الطلب

تقوم البوابة بتوجيه الطلبات إلى الخدمة الخلفية المناسبة بناءً على مسار URL أو الرؤوس أو سمات الطلب الأخرى.

# Nginx as API gateway
upstream api_service {
    server api-1:3001;
    server api-2:3001;
}

upstream auth_service {
    server auth:9000;
}

upstream web_service {
    server web:3000;
}

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

    location /api/v1/ {
        proxy_pass http://api_service;
    }

    location /auth/ {
        proxy_pass http://auth_service;
    }

    location / {
        proxy_pass http://web_service;
    }
}

النموذج 2: المصادقة والترخيص

مركزية المصادقة على البوابة لتجنب تنفيذها في كل خدمة.

// NestJS middleware for JWT validation at the gateway level
@Injectable()
export class GatewayAuthMiddleware implements NestMiddleware {
  constructor(private readonly jwtService: JwtService) {}

  async use(req: Request, res: Response, next: NextFunction) {
    // Skip public endpoints
    if (this.isPublicEndpoint(req.path)) {
      return next();
    }

    const token = this.extractToken(req);
    if (!token) {
      throw new UnauthorizedException('Missing authentication token');
    }

    try {
      const payload = await this.jwtService.verifyAsync(token);
      req['user'] = payload;
      next();
    } catch {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractToken(req: Request): string | undefined {
    // Check cookie first, then Authorization header
    return req.cookies?.ecosire_auth
      || req.headers.authorization?.replace('Bearer ', '');
  }

  private isPublicEndpoint(path: string): boolean {
    const publicPaths = ['/health', '/api/v1/products', '/api/v1/blog'];
    return publicPaths.some(p => path.startsWith(p));
  }
}

النموذج 3: تحديد المعدل

// Rate limiting configuration per endpoint type
const rateLimits = {
  public: { windowMs: 60000, max: 100 },     // 100 req/min for public APIs
  authenticated: { windowMs: 60000, max: 500 }, // 500 req/min for authenticated users
  admin: { windowMs: 60000, max: 1000 },       // 1000 req/min for admin
  webhooks: { windowMs: 60000, max: 50 },       // 50 req/min for webhooks
};

النموذج 4: قاطع الدائرة

عند فشل خدمة المصب، يمنع قاطع الدائرة حالات الفشل المتتالية:

[Closed] --> (failures exceed threshold) --> [Open] --> (timeout expires) --> [Half-Open]
    ^                                                                            |
    |                                        (success)                           |
    +--------------------------------------------------------------------<-------+
    |                                        (failure)                           |
    |                                           +-------->  [Open]

الدول:

• مغلق: تمر الطلبات بشكل طبيعي. تتبع عدد الفشل.
• فتح: تفشل جميع الطلبات على الفور دون الاتصال بالخدمة. إرجاع الاستجابة المخزنة مؤقتًا/الاحتياطية.
• نصف مفتوح: السماح بطلب واحد من خلاله. إذا نجحت، أغلق الدائرة. إذا فشلت، أعد فتحه.

النموذج 5: التخزين المؤقت للاستجابة

# Cache GET responses for public endpoints
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;

location /api/v1/products {
    proxy_pass http://api_service;
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
    proxy_cache_valid 404 1m;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    add_header X-Cache-Status $upstream_cache_status;
}

---

استراتيجيات إصدار واجهة برمجة التطبيقات

توصية: إصدار مسار URL. وهو الأكثر وضوحًا والأكثر قابلية للتصحيح والأسهل للتوجيه على مستوى البوابة.

التغييرات العاجلة مقابل التغييرات غير العاجلة

---

مقارنة تكنولوجيا البوابة

بالنسبة لمعظم الشركات الصغيرة والمتوسطة: يعد Nginx كافيًا. فهو يتعامل مع التوجيه وإنهاء طبقة المقابس الآمنة (SSL) وتحديد المعدل والتخزين المؤقت بحمل أقل من مللي ثانية. قم بالترقية إلى Kong عندما تحتاج إلى إمكانات المكونات الإضافية المتقدمة (OAuth2 وطلب التحويل والتحليلات).

---

إمكانية الملاحظة عند البوابة

تسجيل الطلب

log_format gateway '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   '$request_time $upstream_response_time '
                   '$http_x_request_id';

access_log /var/log/nginx/gateway.log gateway;

مجموعة المقاييس

تتبع هذه المقاييس على مستوى البوابة:

• معدل الطلب حسب نقطة النهاية والطريقة ورمز الحالة
• توزيع زمن الوصول (P50، P95، P99) حسب نقطة النهاية
• معدل الخطأ حسب نقطة النهاية ونوع الخطأ
• ** معدل الوصول إلى الحد الأقصى ** من قبل العميل
• نسبة إصابة ذاكرة التخزين المؤقت حسب نقطة النهاية
• وقت الاستجابة المنبع مقابل وقت الاستجابة الإجمالي

---

معالجة الأخطاء عند البوابة

استجابات الأخطاء المتسقة

يجب أن تقوم البوابة بتطبيع استجابات الأخطاء من خدمات الواجهة الخلفية المختلفة:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The requested service is temporarily unavailable",
    "requestId": "req_abc123",
    "timestamp": "2026-03-16T14:32:01Z"
  }
}

إعادة المحاولة وتكوين المهلة

location /api/ {
    proxy_pass http://api_service;

    # Timeout configuration
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;

    # Retry on connection errors only (not on 5xx)
    proxy_next_upstream error timeout;
    proxy_next_upstream_tries 2;

    # Custom error pages
    error_page 502 503 504 /api-error.json;
}

تدهور رشيق

عندما تكون خدمة الواجهة الخلفية غير الهامة معطلة، يمكن للبوابة تقديم الاستجابات المخزنة مؤقتًا أو البيانات الاحتياطية بدلاً من إرجاع الأخطاء:

---

أنماط أمان البوابة

التحقق من صحة الطلب

التحقق من صحة بنية الطلب قبل إعادة توجيهه إلى الخدمات الخلفية:

• رفض الطلبات ذات أنواع المحتوى غير المعروفة
• فرض الحد الأقصى لحجم نص الطلب لكل نقطة نهاية
• التحقق من صحة الرؤوس المطلوبة (إصدار API ونوع المحتوى)
• إزالة الرؤوس المشبوهة (رؤوس القفزات، والرؤوس الداخلية للخادم)

القائمة المسموح بها لعنوان IP لنقاط النهاية الإدارية

location /api/admin/ {
    allow 203.0.113.0/24;  # Office IP range
    allow 10.0.0.0/8;      # Internal network
    deny all;

    proxy_pass http://api_service;
}

طلب التحويل

يمكن للبوابة إضافة الرؤوس أو تعديلها أو إزالتها قبل إعادة التوجيه:

location /api/ {
    proxy_pass http://api_service;

    # Add security headers
    proxy_set_header X-Request-ID $request_id;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;

    # Remove internal headers from responses
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
}

---

الأسئلة المتداولة

هل نحتاج إلى بوابة API لتطبيق متجانس؟

نعم، ولكن واحدة أبسط. حتى بالنسبة للوحدة المتراصة، يوفر Nginx باعتباره وكيلًا عكسيًا إنهاء SSL، وتحديد المعدل، وخدمة الملفات الثابتة، ورؤوس الأمان. لا تحتاج إلى Kong أو AWS API Gateway لوحدة متراصة، ولكنك تحتاج إلى شيء ما بين الإنترنت وخادم التطبيقات الخاص بك.

كيف نتعامل مع تجاوز فشل بوابة API؟

قم بتشغيل مثيلات بوابة متعددة خلف موازن التحميل السحابي (AWS ALB، Cloudflare). في حالة فشل أحد مثيلات البوابة، يقوم موازن التحميل بتوجيه حركة المرور إلى المثيلات السليمة. بالنسبة إلى Nginx، استخدم عمليات التحقق من الصحة النشطة والإزالة التلقائية للمصادر غير الصحية.

هل يجب على بوابة API التعامل مع المصادقة أم يجب على كل خدمة؟

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

كيف نتعامل مع CORS في بوابة API؟

قم بتكوين CORS على مستوى البوابة لتجنب تكرار رؤوس CORS عبر الخدمات. قم بتعيين Access-Control-Allow-Origin على نطاقات الواجهة الأمامية المحددة الخاصة بك (لا تستخدم * مطلقًا في الإنتاج باستخدام بيانات الاعتماد). تعامل مع طلبات OPTIONS للاختبار المبدئي عند البوابة لتقليل الحمل على خدمات الواجهة الخلفية.

---

ما يأتي بعد ذلك

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

اتصل بـ ECOSIRE للحصول على استشارات حول بنية واجهة برمجة التطبيقات، أو استكشف دليل DevOps للحصول على خريطة طريق البنية التحتية الكاملة.

---

تم النشر بواسطة ECOSIRE - مساعدة الشركات على إنشاء بنية أساسية لواجهة برمجة التطبيقات (API) قابلة للتطوير.