Alamofire لـ Swift: دليل كامل مع أمثلة

ما هو Alamofire ولماذا تحتاجه

Alamofire هي مكتبة أنيقة وقوية للعمل مع طلبات الشبكة بلغة Swift. توفر واجهة سهلة الاستخدام لتنفيذ طلبات HTTP، ومعالجة الردود، وتحميل وتنزيل البيانات، بالإضافة إلى العمل مع المصادقة والتسلسل. مكتوبة بلغة Swift النقية، وتدعم iOS وmacOS وtvOS وwatchOS.

الأسباب الرئيسية لاستخدام Alamofire:

\n
• سهولة الاستخدام — واجهة برمجة تطبيقات بديهية تقلل من حجم الكود مقارنة بـ URLSession.
\n
• التسلسل التلقائي — دعم مدمج لـ JSON و Property List والتنسيقات المخصصة.
\n
• سلاسل الطلبات — سهولة دمج عدة طلبات ومعالجتها بالتسلسل.
\n
• معالجة الأخطاء — معلومات مفصلة عن أخطاء الشبكة والخادم.
\n
• دعم SSL-pinning — اتصال آمن بالخادم.
\n
• تحميل الملفات — دعم تتبع التقدم واستئناف التحميل.
\n
• مجتمع نشط — تحديثات منتظمة والعديد من الأمثلة.
\n

تثبيت Alamofire

يتم تثبيت Alamofire عبر Swift Package Manager (SPM) أو CocoaPods أو Carthage. الطريقة الموصى بها هي SPM.

التثبيت عبر Swift Package Manager (SPM)

\n
1. في Xcode، افتح مشروعك: File → Add Packages...
\n
2. أدخل رابط المستودع: https://github.com/Alamofire/Alamofire.git
\n
3. اختر الإصدار (أحدث إصدار مستقر) واضغط Add Package.
\n
4. تأكد من إضافة الحزمة إلى الهدف الخاص بك.
\n

التثبيت عبر CocoaPods

# Podfile\nplatform :ios, '13.0'\nuse_frameworks!\n\ntarget 'YourApp' do\n  pod 'Alamofire', '~> 5.9'\nend

بعد ذلك، قم بتنفيذ pod install.

التثبيت عبر Carthage

# Cartfile\ngithub "Alamofire/Alamofire" ~> 5.9

ثم قم بتنفيذ carthage update --platform iOS.

بداية سريعة مع مثال كود

بعد التثبيت، قم باستيراد المكتبة ونفذ طلب GET بسيط:

import Alamofire\n\n// طلب GET بسيط\nAF.request("https://jsonplaceholder.typicode.com/posts/1")\n    .responseJSON { response in\n        switch response.result {\n        case .success(let data):\n            print("البيانات المستلمة: \\(data)")\n        case .failure(let error):\n            print("خطأ: \\(error.localizedDescription)")\n        }\n    }

هذا الكود يرسل طلبًا إلى API اختباري، ويستقبل JSON ويطبعه في وحدة التحكم. يقوم Alamofire تلقائيًا بمعالجة جلسة URL وإنشاء الطلب وتسلسل الرد.

الطرق والوظائف الأساسية لـ Alamofire

دعنا نستعرض 10 طرق رئيسية للمكتبة مع شرح مفصل وأمثلة.

1. AF.request() — طلب HTTP أساسي

ما يفعله: يرسل طلب HTTP بأي طريقة (GET, POST, PUT, DELETE إلخ) إلى عنوان URL محدد.

المعلمات:

\n
• _ url: URLConvertible — عنوان URL أو سلسلة نصية لعنوان URL.
\n
• method: HTTPMethod = .get — طريقة HTTP (get, post, put, delete, patch وغيرها).
\n
• parameters: Parameters? = nil — قاموس معاملات الطلب.
\n
• encoding: ParameterEncoding = URLEncoding.default — طريقة ترميز المعاملات.
\n
• headers: HTTPHeaders? = nil — رؤوس الطلب.
\n
• interceptor: RequestInterceptor? = nil — معترض لتعديل الطلب.
\n

مثال:

let parameters: [String: Any] = [\n    "userId": 1,\n    "title": "منشور جديد",\n    "body": "نص المنشور"\n]\n\nAF.request("https://jsonplaceholder.typicode.com/posts",\n           method: .p