Alamofire: چیست، توابع کلاینت HTTP و کاربرد در توسعه

Alamofire چیست؟

Alamofire کتابخانه‌ای برای کار با درخواست‌های HTTP در پلتفرم‌های اپل است که کاملاً در Swift نوشته شده است. توسعه آن در سال 2014 به عنوان جایگزینی برای کتابخانه AFNetworking به زبان Objective-C آغاز شد و به سرعت به استانداردی برای ارتباطات شبکه در جامعه iOS تبدیل شد.

این کتابخانه بر روی فریمورک سیستمی URLSession ساخته شده است و API سطح پایین آن را در زنجیره‌های فراخوانی مختصر انتزاع می‌کند. 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 از طریق یک API یکپارچه پیاده‌سازی شده‌اند. هر متد پارامترهای درخواست، هدرها را می‌پذیرد و پاسخ را به صورت Result برمی‌گرداند. توسعه‌دهنده نیازی به پیکربندی دستی URLRequest ندارد — کتابخانه این کار را به طور خودکار بر اساس آرگومان‌های ارسالی انجام می‌دهد.

اعتبارسنجی پاسخ‌های سرور

اعتبارسنجی پاسخ‌ها در Alamofire امکان بررسی کدهای وضعیت و محتوای پاسخ را قبل از ارسال داده‌ها به برنامه فراهم می‌کند. کتابخانه از شرایط اعتبارسنجی سفارشی از طریق closure پشتیبانی می‌کند که کنترل کامل بر مدیریت خطا را فراهم می‌کند. به طور پیش‌فرض فقط کدهای وضعیت 200–299 بررسی می‌شوند.

رمزگذاری خودکار پارامترها

پارامترهای درخواست به طور خودکار بسته به نوع انتخاب شده رمزگذاری می‌شوند: URL-encoding برای درخواست‌های GET و JSON-encoding برای POST. Alamofire همچنین از رمزگذاری Property List و رمزگذارهای سفارشی از طریق پروتکل ParameterEncoder پشتیبانی می‌کند که امکان تطبیق فرمت با هر سروری را فراهم می‌کند.

مدیریت جلسه و رهگیرها

جلسه Alamofire امکان پیکربندی مهلت‌های زمانی، گواهینامه‌های SSL، هدرهای HTTP پیش‌فرض و پروکسی را فراهم می‌کند. رهگیرهای EventMonitor امکان ردیابی رویدادهای چرخه حیات درخواست را فراهم می‌کنند: ایجاد، ارسال، دریافت پاسخ و تکمیل. این برای ثبت رویدادها، تحلیل و اشکال‌زدایی مشکلات شبکه در محیط تولید مفید است.

Alamofire چگونه کار می‌کند؟

Alamofire از معماری مبتنی بر Session استفاده می‌کند که نمونه URLSession و پیکربندی شبکه را کپسوله می‌کند. هر درخواست از زنجیره‌ای از handlerها عبور می‌کند: آداپتورها، سیاست‌های تکرار، اعتبارسنج‌ها و سریال‌سازها که انعطاف‌پذیری و قابلیت توسعه را تضمین می‌کند.

مدل Session و Request

شیء Session تمام درخواست‌های شبکه در برنامه را مدیریت می‌کند. این شیء با پیکربندی شامل مهلت‌های زمانی، هدرهای پیش‌فرض و گواهینامه‌ها ایجاد می‌شود. هر فراخوانی AF.request یک DataRequest برمی‌گرداند که می‌توان قبل از ارسال آن را تغییر داد. Alamofire به طور خودکار Retain Cycle را از طریق ارجاع‌های ضعیف به جلسه مدیریت کرده و از نشت حافظه جلوگیری می‌کند.

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 انجام می‌شود. URL مخزن: 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 از آپلود فایل‌ها، داده‌ها و فرم‌های چندبخشی پشتیبانی می‌کند. کتابخانه به طور خودکار پیشرفت را مدیریت کرده و امکان ردیابی وضعیت آپلود را از طریق closureهای 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 سرور می‌توان درخواست را پس از 2 ثانیه تکرار کرد و در 401 — توکن احراز هویت جدیدی درخواست کرد.

رویکرد AFError با شمارش تضمین می‌کند که توسعه‌دهنده هیچ نوع خطایی را از دست ندهد — کامپایلر کامل بودن پردازش را بررسی می‌کند. این کد را در مقایسه با مدیریت خطا از طریق NSError در URLSession خالص قابل‌اعتمادتر و قابل‌پیش‌بینی‌تر می‌کند.

سیاست‌های تکرار و درخواست‌های مجدد

پروتکل RequestRetrier متد retry را تعریف می‌کند که درخواست، جلسه، خطا و closure تکمیل را دریافت می‌کند. در این متد توسعه‌دهنده تصمیم می‌گیرد که آیا درخواست را تکرار کند و پس از چه زمانی. Alamofire پیاده‌سازی داخلی RetryPolicy را برای سناریوهای معمول فراهم می‌کند، اما برای کد تولید توصیه می‌شود سیاست‌های خود را با در نظر گرفتن منطق تجاری ایجاد کنید.

AFError یک شمارش با موارد تودرتو برای دسته‌های مختلف خطا است. توسعه‌دهنده می‌تواند هر نوع را جداگانه پردازش کند: برای زمان‌های انتظار تکرار درخواست را پیش‌بینی کند، برای خطاهای سرور — پیام قابل فهمی به کاربر نشان دهد. Alamofire از سیاست‌های تکرار سفارشی از طریق پروتکل RequestRetrier پشتیبانی می‌کند.

اعتبارسنجی داخلی کدهای وضعیت در محدوده 200–299 و نوع محتوای پاسخ را بررسی می‌کند. برای اعتبارسنجی گسترده می‌توان شرایط سفارشی را از طریق closure validate اضافه کرد که امکان بررسی منطق تجاری پاسخ را قبل از ارسال داده‌ها به لایه UI فراهم می‌کند.