Alamofire: ما هو، وظائف عميل HTTP والتطبيق في التطوير

ما هو Alamofire؟

Alamofire هي مكتبة للعمل مع طلبات HTTP على منصات Apple، مكتوبة بالكامل بلغة Swift. بدأ التطوير في عام 2014 كبديل لمكتبة AFNetworking بلغة Objective-C وسرعان ما أصبحت المعيار للتواصل الشبكي في مجتمع iOS.

المكتبة مبنية فوق إطار النظام URLSession، مما يجرد واجهة برمجية منخفضة المستوى إلى سلاسل استدعاء موجزة. تدعم Alamofire جميع ميزات URLSession: الجلسات الخلفية، معترضات الطلبات، شهادات SSL وطرق متعددة لتسلسل الردود.

وفقاً لـ Swift Package Index، تعد Alamofire من بين أفضل 10 حزم Swift الأكثر شعبية مع أكثر من 45,000 نجمة على GitHub. المكتبة متوافقة مع iOS 10+ وmacOS 10.12+ وtvOS 10+ وwatchOS 3+.

الميزة الرئيسية لـ Alamofire مقارنة بالاستخدام المباشر لـ URLSession هي تقليل الكود النمطي. استدعاء واحد لـ AF.request يحل محل 15–20 سطراً من الإعداد اليدوي لـ URLRequest ومعالجة الردود وفك تشفير البيانات. في الوقت نفسه، تحتفظ المكتبة بالمرونة الكاملة للسيناريوهات المخصصة من خلال الجلسات والإضافات المخصصة.

الإمكانيات الرئيسية لـ Alamofire

Alamofire توفر مجموعة واسعة من وظائف الشبكة التي تغطي معظم سيناريوهات التطوير المحمول. بفضل بنيتها المعيارية، يحتاج المطور فقط إلى تضمين المكونات الضرورية.

دعم جميع طرق HTTP

طرق HTTP GET وPOST وPUT وPATCH وDELETE وHEAD وOPTIONS وTRACE مطبقة عبر واجهة برمجية موحدة. تقبل كل طريقة معاملات الطلب والترويسات وتعيد الرد كنوع Result. لا يحتاج المطور إلى تكوين URLRequest يدوياً — تقوم المكتبة بذلك تلقائياً بناءً على الوسائط المقدمة.

التحقق من صحة ردود الخادم

التحقق من صحة الردود في Alamofire يسمح بفحص رموز الحالة ومحتوى الرد قبل تمرير البيانات إلى التطبيق. تدعم المكتبة شروط تحقق مخصصة من خلال الإغلاقات، مما يعطي تحكماً كاملاً في معالجة الأخطاء. بشكل افتراضي، يتم فحص رموز الحالة 200–299 فقط.

ترميز المعاملات تلقائياً

يتم ترميز المعاملات تلقائياً حسب النوع المحدد: ترميز URL لطلبات GET وترميز JSON لـ POST. تدعم Alamofire أيضاً ترميز Property List وأدوات ترميز مخصصة عبر بروتوكول ParameterEncoder، مما يسمح بتكييف التنسيق مع أي خادم.

إدارة الجلسات والمعترضات

الجلسة في Alamofire تسمح بتكوين مهلات الانتظار وشهادات SSL وترويسات HTTP الافتراضية والبروكسيات. تتيح معترضات EventMonitor تتبع أحداث دورة حياة الطلب: الإنشاء والإرسال واستلام الرد والاكتمال. هذا مفيد للتسجيل والتحليل وتصحيح مشكلات الشبكة في الإنتاج.

كيف يعمل Alamofire؟

Alamofire تستخدم بنية قائمة على Session تغلف مثيل URLSession وتكوين الشبكة. يمر كل request عبر سلسلة من المعالجات: المهايئات وسياسات إعادة المحاولة والمدققات والمسلسلات، مما يضمن المرونة وقابلية التوسع.

نموذج Session وRequest

كائن Session يدير جميع طلبات الشبكة في التطبيق. يتم إنشاؤه مع تكوين يحتوي على مهلات وترويسات افتراضية وشهادات. كل استدعاء AF.request يعيد DataRequest يمكن تعديله قبل الإرسال. تتعامل Alamofire تلقائياً مع دورات الاحتفاظ عبر مراجع ضعيفة للجلسة، مما يمنع تسرب الذاكرة.

import Alamofire

let session = Session(configuration: config)
session.request("https://api.example.com/users")
    .validate()
    .responseDecodable(of: [User].self) { response in
        switch response.result {
        case .success(let users):
            print("تم استلام \(users.count) مستخدم")
        case .failure(let error):
            print("خطأ: \(error.localizedDescription)")
        }
    }

تثبيت وتكوين Alamofire

تثبيت Alamofire يتم عبر Swift Package Manager أو CocoaPods أو Carthage. الطريقة الموصى بها للمشاريع الجديدة هي SPM المدمجة في Xcode، حيث لا تتطلب أدوات إضافية ويتم التكامل ببضع نقرات.

عبر Swift Package Manager

إضافة الحزمة في Xcode تتم عبر القائمة File → Add Packages. عنوان المستودع: https://github.com/Alamofire/Alamofire. يوصى بتثبيت الإصدار على آخر إصدار مستقر. تتبع Alamofire التحكم الدلالي بالإصدارات وجميع التغييرات الجذرية موثقة في CHANGELOG.

عبر CocoaPods

CocoaPods لا يزال خياراً شائعاً للمشاريع ذات البنية التحتية الحالية. أضف السطر pod 'Alamofire' إلى Podfile وقم بتشغيل pod install. Alamofire ليس لها تبعيات خارجية، مما يبسط التكامل ويزيل تعارضات الإصدارات في المشاريع الحالية.

أمثلة استخدام Alamofire

الأمثلة أدناه توضح سيناريوهات الاستخدام النموذجية لـ Alamofire في تطبيقات iOS: من طلبات GET البسيطة إلى رفع الملفات مع تتبع التقدم.

طلب GET والرد JSON

طلب GET بسيط مع معاملات وفك تشفير الرد إلى نموذج Codable هو السيناريو الأكثر شيوعاً لاستخدام Alamofire في التطبيقات المحمولة. يتم ترميز المعاملات تلقائياً وفك تشفير الرد عبر JSONDecoder. الكود مضغوط وقابل للقراءة.

struct User: Codable {
    let id: Int
    let name: String
    let email: String
}

AF.request("https://jsonplaceholder.typicode.com/users",
               method: .get)
    .validate()
    .responseDecodable(of: [User].self) { response in
        switch response.result {
        case .success(let users):
            print("المستخدمون: \(users.count)")
        case .failure(let error):
            print("خطأ: \(error)")
        }
    }

طلب POST مع جسم JSON

طلب POST مع جسم JSON يُستخدم لإنشاء موارد على الخادم. تقوم Alamofire بترميز الكائن الممرر تلقائياً عبر JSONParameterEncoder، مما يوفر على المطور عناء التسلسل اليدوي. يتم فك تشفير الرد إلى نموذج بيانات باستخدام نفس JSONDecoder.

let newUser = User(id: 1,
                     name: "أحمد محمد",
                     email: "ivan@example.com")

AF.request("https://jsonplaceholder.typicode.com/users",
               method: .post,
               parameters: newUser,
               encoder: JSONParameterEncoder.default)
    .validate()
    .responseDecodable(of: User.self) { response in
        if let created = response.value {
            print("تم إنشاء المستخدم: \(created)")
        }
    }

رفع الوسائط

طريقة upload في Alamofire تدعم رفع الملفات والبيانات والنماذج متعددة الأجزاء. تدير المكتبة التقدم تلقائياً وتسمح بتتبع حالة الرفع عبر إغلاقات uploadProgress، وهو مناسب لعرض مؤشر التقدم.

let imageData = UIImage(named: "photo")?.jpegData(compressionQuality: 0.8)

AF.upload(imageData,
           to: "https://api.example.com/upload")
    .uploadProgress { progress in
        print("التقدم: \(progress.fractionCompleted * 100)%")
    }
    .responseDecodable(of: UploadResponse.self) { response in
        print("اكتمل الرفع")
    }

معالجة الأخطاء والتحقق في Alamofire

معالجة الأخطاء في Alamofire مبنية على مزيج من التحقق من صحة الردود وأنواع Result. يشمل نموذج الأخطاء AFError الذي يغطي جميع سيناريوهات فشل الشبكة النموذجية: مهلات الانتظار وفقدان الاتصال وأخطاء الخادم وفشل التسلسل. يتم معالجة كل حالة على حدة.

لمحاولات إعادة بعد الخطأ، توفر Alamofire آلية RequestRetrier. يحدد هذا البروتوكول سياسة إعادة المحاولة: عدد المحاولات والتأخير بينها والشرط الذي يتم بموجبه إجراء إعادة المحاولة. على سبيل المثال، عند خطأ 503 من الخادم، يمكن إعادة المحاولة بعد ثانيتين، بينما عند خطأ 401، يمكن طلب رمز مصادقة جديد.

نهج AFError مع التعداد يضمن ألا يفوت المطور أي نوع خطأ — يتحقق المُجمِّع من اكتمال المعالجة. هذا يجعل الكود أكثر موثوقية وقابلية للتنبؤ مقارنة بمعالجة الأخطاء عبر NSError في URLSession الخام.

سياسات إعادة المحاولة والطلبات المتكررة

بروتوكول RequestRetrier يحدد طريقة إعادة المحاولة التي تستقبل الطلب والجلسة والخطأ وإغلاق الاكتمال. في هذه الطريقة، يقرر المطور ما إذا كان سيعيد محاولة الطلب وبعد أي تأخير. توفر Alamofire تطبيقاً مدمجاً RetryPolicy للسيناريوهات الشائعة، ولكن لكود الإنتاج يوصى بإنشاء سياسات مخصصة مع مراعاة منطق الأعمال.

AFError هو تعداد بحالات متداخلة لفئات مختلفة من الأخطاء. يمكن للمطور معالجة كل نوع على حدة: للمهلات — إعادة محاولة الطلب، لأخطاء الخادم — عرض رسالة مفهومة للمستخدم. تدعم Alamofire سياسات إعادة محاولة مخصصة عبر بروتوكول RequestRetrier.

التحقق المدمج يفحص رموز الحالة في النطاق 200–299 ونوع محتوى الرد. للتحقق الموسع، يمكن إضافة شروط مخصصة عبر إغلاق validate، مما يسمح بالتحقق من منطق الأعمال قبل تمرير البيانات إلى طبقة واجهة المستخدم.