Alamofire — ما هو، عميل HTTP بلغة Swift وكيف يعمل

ما هو Alamofire؟

Alamofire هو عميل HTTP بلغة Swift تم إنشاؤه بواسطة Alamofire Software Foundation (في الأصل بواسطة Mattt Thompson في 2014). تقوم المكتبة بتجريد تفاصيل URLSession منخفضة المستوى، مما يوفر واجهة برمجة تطبيقات نظيفة ومعبرة للاتصال بالشبكة.

الفلسفة الأساسية لـ Alamofire هي بناء جملة السلسلة، حيث يتم تمرير معلمات الطلب (URL، الطريقة، الرؤوس، المعلمات، المشفر) من خلال استدعاءات متسلسلة. وهذا يجعل الكود أكثر قابلية للقراءة ويقلل من احتمالية الأخطاء المتعلقة بتكوين URLRequest غير صحيح. يسمح النهج التصريحي بالتركيز على ما يجب القيام به بدلاً من تفاصيل كيفية إعداد الاتصال. يصف المطور النتيجة المرجوة، وتتولى المكتبة أعمال الشبكة منخفضة المستوى.

تمت صيانة المكتبة بنشاط منذ 2014 ومرت بسبعة إصدارات رئيسية. Alamofire 5، الحالي اعتباراً من 2025–2026، يتضمن دعم Combine وasync/await ومحولات الاستجابة وEventMonitor لتصحيح الأخطاء وRequestInterceptor لاعتراض الطلبات. كل إصدار رئيسي جلب تحسينات كبيرة: Alamofire 4 أضاف دعم Codable، Alamofire 5 أضاف Combine Publishers ونظام اعتراض طلبات محسّن.

يشمل نظام Alamofire البيئي مكتبات إضافية: AlamofireImage لتحميل الصور وتخزينها مؤقتاً، AlamofireNetworkActivityIndicator لمؤشر الشبكة في شريط حالة iOS، وAlamofireObjectMapper للتكامل مع ObjectMapper. هذه المكونات تجعل Alamofire حزمة شبكات كاملة، وليس مجرد عميل HTTP.

التثبيت والإعداد

يتم تثبيت Alamofire عبر Swift Package Manager (موصى به) أو CocoaPods أو Carthage. في Xcode، ما عليك سوى فتح قائمة File → Add Packages، ولصق رابط المستودع، وتحديد الإصدار.

// Swift Package Manager — أضف إلى Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// استيراد في الملف
import Alamofire

بعد التثبيت، يتوفر Alamofire عالمياً من خلال مساحة الاسم AF(اختصار Alamofire) دون أي إعداد إضافي. تبدأ معظم المشاريع بإعداد Session بتكوينها الخاص — وهذا يسمح بتعيين URL أساسي ورؤوس افتراضية ومهل زمنية ومعالجات شهادات TLS.

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
let session = Session(configuration: configuration)

إنشاء جلسة مخصصة عبر Session(configuration:) ضروري عندما يكون هناك حاجة لتكوين فريد لأجزاء مختلفة من التطبيق — على سبيل المثال، جلسة منفصلة لتنزيل الصور مع تخزين مؤقت قوي وجلسة أخرى لطلبات API مع المصادقة. تقبل Session في Alamofire ليس فقط التكوين ولكن أيضاً المعترض وserverTrustManager وcachedResponseHandler وredirectHandler، مما يوفر تحكماً كاملاً في سلوك الشبكة في جميع مراحل الطلب.

المميزات الرئيسية

توفر Alamofire مجموعة واسعة من الوظائف التي تغطي معظم سيناريوهات التفاعل الشبكي في تطبيقات iOS. دعنا نلقي نظرة على المميزات الرئيسية.

طلبات HTTP

يشمل بناء جملة الطلب الأساسي الطريقة وURL والمعلمات والتشفير. جميع طرق HTTP القياسية مدعومة عبر enum HTTPMethod: get، post، put، patch، delete. يمكن تشفير المعلمات كمعلمات URL (URLEncoding) أو نص JSON (JSONEncoding) أو بيانات متعددة الأجزاء (MultipartFormData).

AF.request("https://api.example.com/users", method: .post,
           parameters: ["name": "Alex", "role": "developer"])
    .validate()
    .responseDecodable(of: User.self) { response in
        switch response.result {
        case .success(let user):
            print("تم إنشاؤه بواسطة المستخدم: \(user)")
        case .failure(let error):
            print("خطأ: \(error)")
        }
    }

تتحقق طريقة validate() تلقائياً من رمز الحالة (200–299) ونوع المحتوى، وتعيد خطأً في حالة الاستجابة غير المتوقعة، مما يلغي الحاجة للتحقق اليدوي من statusCode. يستخدم responseDecodable بروتوكول Decodable لإلغاء تسلسل JSON تلقائياً إلى هياكل Swift — وهذا يلغي JSONSerialization اليدوي ويقلل الكود المتكرر عند العمل مع REST APIs.

معالجة الاستجابات

يدعم Alamofire عدة أنواع من معالجات الاستجابة: response (بيانات خام)، responseJSON (قاموس/مصفوفة)، responseString (نص)، responseData (Data)، وresponseDecodable (نموذج Decodable). يمكن أن تكون محولات الاستجابة مخصصة — لـ protobuf أو التنسيقات الرسومية أو البروتوكولات الخاصة.

رفع وتنزيل الملفات

لرفع البيانات إلى الخادم، يتم استخدام upload، الذي يدعم Data وFile وMultipartFormData. يتم تنزيل الملفات الكبيرة عبر download مع إمكانية الاستئناف من خلال resumeData بعد انقطاع الاتصال. تدعم كلتا العمليتين تتبع التقدم عبر uploadProgress وdownloadProgress بقيم كسرية من 0 إلى 1 للعرض في واجهة المستخدم.

الرفع المتعدد الأجزاء مع Alamofire مناسب بشكل خاص: تقبل طريقة upload(multipartFormData:) إغلاقاً حيث تتم إضافة أجزاء النموذج عبر append. يمكن أن يحتوي كل جزء على بيانات أو ملف أو دفق، بالإضافة إلى اسمه الخاص ونوع mime. يحسب Alamofire تلقائياً حدود الأجزاء المتعددة ويضبط رأس Content-Type الصحيح، مما يوفر على المطور عناء تشكيل نص الطلب يدوياً. للملفات الكبيرة، يوصى باستخدام موفري التدفق بدلاً من تحميل الملف بأكمله في الذاكرة — وهذا يمنع تجاوز حد الذاكرة على الأجهزة المحمولة محدودة الموارد. السيناريو النموذجي هو إرسال صورة المستخدم مع بيانات الملف الشخصي في طلب متعدد الأجزاء واحد، مما يقلل عدد استدعاءات HTTP ويبسط المعالجة على الخادم.

Alamofire مقابل URLSession

مقارنة Alamofire مع URLSession الأصلي تساعد في اتخاذ القرارات المعمارية. Alamofire لا يحل محل URLSession — بل يبني فوقه ويستخدم نفس آليات التكوين والتخزين المؤقت والمهام الخلفية. جميع ميزات URLSession متاحة عبر Alamofire، ولكن ببناء جملة تصريحي أكثر ملاءمة.

في المشاريع الكبيرة، يقلل Alamofire كود طلبات الشبكة بنسبة 30–50% ويبسط معالجة الأخطاء. في المشاريع الصغيرة أو عندما يكون حجم الملف الثنائي قيداً صارماً، يكون URLSession الأصلي أفضل بسبب عدم وجود تبعيات خارجية.

يتكامل Alamofire 5 الحديث مع Combine من خلال الخاصية publishDecodable، التي تعيد Publisher، مما يسمح بسلاسل طلبات تفاعلية مع معالجة الأخطاء وتحويل البيانات. بالنسبة لـ async/await، تتوفر الطرق باللاحقة value — على سبيل المثال، AF.request(url).serializingDecodable(User.self).value، مما يجعل بناء الجملة موجزاً للغاية ويذكرنا بالعمل مع URLSession الأصلي. عند استخدام async/await، لم تعد الإغلاقات ضرورية وتتم معالجة الأخطاء من خلال كتل do-catch القياسية في Swift، مما يبسط صيانة الكود وسهولة قراءته على المدى الطويل.

أمثلة الكود

دعنا نلقي نظرة على مثال أكثر تعقيداً — طلب مع معترض يضيف تلقائياً رمز التفويض ويقوم بإعادة المحاولة عند خطأ 401. هذا سيناريو نموذجي للتطبيقات التي تستخدم مصادقة JWT.

class AuthInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest,
               for session: Session,
               completion: @escaping (Result<URLRequest, Error>) -> Void) {
        var request = urlRequest
        request.setValue("Bearer \(TokenManager.shared.token)",
                         forHTTPHeaderField: "Authorization")
        completion(.success(request))
    }

    func retry(_ request: Request,
              for session: Session,
              dueTo error: Error,
              completion: @escaping (RetryResult) -> Void) {
        guard let response = request.response,
              response.statusCode == 401
        else { return completion(.doNotRetry) }
        TokenManager.shared.refreshToken { success in
            completion(success ? .retry : .doNotRetry)
        }
    }
}

يقوم AuthInterceptor بتطبيق بروتوكولين: adapt (يضيف رمزاً لكل طلب) وretry (يحاول تحديث الرمز عند خطأ 401). تتحقق طريقة retry من رمز حالة الاستجابة، وإذا تم استلام 401، تطلب رمزاً جديداً عبر TokenManager. بعد التحديث الناجح، يتم إعادة الطلب تلقائياً.

استخدام المعترض مع جلسة:

let session = Session(interceptor: AuthInterceptor())
session.request("https://api.example.com/profile")
    .responseDecodable(of: Profile.self) { response in
        print(response.result)
    }

جميع الطلبات عبر هذه الجلسة تمر تلقائياً عبر AuthInterceptor — يضاف الرمز إلى الرؤوس، وعند 401، يتم إجراء تحديث وإعادة محاولة. هذا يلغي تكرار كود المصادقة في كل طلب ويتمركز منطق إدارة الرموز.