Alamofire — این چیست، HTTP-کلاینت در Swift و چگونه کار می‌کند

Alamofire چیست؟

Alamofire یک کلاینت HTTP برای Swift است که توسط Alamofire Software Foundation (در ابتدا توسط Mattt Thompson در سال 2014) ساخته شده است. این کتابخانه جزئیات سطح پایین URLSession را انتزاع می‌کند و یک API تمیز و رسا برای ارتباطات شبکه‌ای ارائه می‌دهد.

فلسفه اصلی 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 را باز کنید، URL مخزن را وارد کرده و نسخه را مشخص کنید.

// Swift Package Manager — به Package.swift اضافه کن
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// import در فایل
import Alamofire

پس از نصب، Alamofire از طریق فضای نام AF (مخفف Alamofire) بدون پیکربندی اضافی در دسترس است. اکثر پروژه‌ها با راه‌اندازی Session با پیکربندی خود شروع می‌کنند — این امکان تنظیم URL پایه، هدرهای استاندارد، مهلت زمانی و مدیریت گواهی TLS را فراهم می‌کند.

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

ایجاد Session سفارشی از طریق Session(configuration:) زمانی ضروری است که پیکربندی منحصر به فردی برای بخش‌های مختلف برنامه مورد نیاز باشد — به عنوان مثال، یک Session جداگانه برای بارگذاری تصاویر با ذخیره‌سازی تهاجمی و یک Session دیگر برای درخواست‌های API با احراز هویت. Session Alamofire نه تنها پیکربندی، بلکه interceptor، serverTrustManager، cachedResponseHandler و redirectHandler را نیز می‌پذیرد که امکان کنترل کامل رفتار شبکه را در تمام مراحل درخواست فراهم می‌کند.

قابلیت‌های اصلی

Alamofire مجموعه گسترده‌ای از قابلیت‌ها را فراهم می‌کند که اکثر سناریوهای ارتباط شبکه‌ای در برنامه‌های iOS را پوشش می‌دهد. بیایید به مهم‌ترین آنها نگاهی بیندازیم.

درخواست‌های HTTP

نحو پایه درخواست شامل متد، URL، پارامترها و encoding است. تمام متدهای استاندارد HTTP از طریق enum HTTPMethod پشتیبانی می‌شوند: get، post، put، patch، delete. پارامترها می‌توانند به عنوان پارامترهای URL (URLEncoding)، بدنه JSON (JSONEncoding) یا فرمت multipart (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 API کاهش می‌دهد.

پردازش پاسخ‌ها

Alamofire از چندین نوع پردازشگر پاسخ پشتیبانی می‌کند: response (داده خام)، responseJSON (دیکشنری/آرایه)، responseString (متن)، responseData (Data) و responseDecodable (مدل Decodable). مبدل‌های پاسخ را می‌توان سفارشی برای protobuf، فرمت‌های گرافیکی یا پروتکل‌های شخصی ایجاد کرد.

بارگذاری و دانلود فایل‌ها

برای بارگذاری داده‌ها روی سرور از upload استفاده می‌شود که از Data، File و MultipartFormData پشتیبانی می‌کند. دانلود فایل‌های بزرگ از طریق download با قابلیت ازسرگیری از طریق resumeData پس از قطع یا شکست اتصال انجام می‌شود. هر دو عملیات از ردیابی پیشرفت از طریق uploadProgress و downloadProgress با مقادیر کسری از 0 تا 1 برای نمایش در رابط کاربری پشتیبانی می‌کنند.

بارگذاری Multipart با Alamofire بسیار راحت است: متد upload(multipartFormData:) یک closure دریافت می‌کند که در آن بخش‌های فرم از طریق append اضافه می‌شوند. هر بخش می‌تواند حاوی داده، فایل یا جریان و همچنین نام و نوع mime خود باشد. Alamofire به طور خودکار مرزهای multipart را محاسبه کرده و هدر Content-Type صحیح را تنظیم می‌کند که توسعه‌دهنده را از تشکیل دستی بدنه درخواست بی‌نیاز می‌کند. برای فایل‌های بزرگ، توصیه می‌شود به جای بارگذاری کل فایل در حافظه از انتقال جریانی (stream provider) استفاده شود — این کار از تجاوز به محدودیت حافظه در دستگاه‌های همراه با منابع محدود جلوگیری می‌کند. یک سناریوی معمول — ارسال آواتار کاربر همراه با داده‌های پروفایل در یک درخواست multipart که تعداد فراخوانی‌های HTTP را کاهش داده و پردازش سمت سرور را ساده می‌کند.

Alamofire در مقابل URLSession

مقایسه Alamofire و URLSession بومی به تصمیم‌گیری معماری کمک می‌کند. Alamofire جایگزین URLSession نمی‌شود — بلکه بر روی آن ساخته شده و از همان مکانیزم‌های پیکربندی، ذخیره‌سازی و وظایف پس‌زمینه استفاده می‌کند. تمام قابلیت‌های URLSession از طریق Alamofire، اما با نحو اعلامی راحت‌تر در دسترس هستند.

در پروژه‌های بزرگ، Alamofire حجم کد درخواست‌های شبکه را 30–50٪ کاهش داده و مدیریت خطا را ساده می‌کند. در پروژه‌های کوچک یا با الزامات سختگیرانه برای اندازه باینری، URLSession بومی به دلیل عدم وجود وابستگی‌های خارجی ترجیح داده می‌شود.

Alamofire 5 مدرن از طریق ویژگی publishDecodable با Combine یکپارچه می‌شود که یک Publisher برمی‌گرداند و امکان ساخت زنجیره‌های درخواست واکنش‌گرا با مدیریت خطا و تبدیل داده را فراهم می‌کند. برای async/await متدهایی با پسوند value در دسترس هستند — به عنوان مثال، AF.request(url).serializingDecodable(User.self).value که نحو را بسیار مختصر کرده و کار با URLSession بومی را تداعی می‌کند. هنگام استفاده از async/await نیاز به closureها از بین می‌رود و مدیریت خطا از طریق بلوک‌های استاندارد 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 توکن جدیدی درخواست می‌کند. پس از به‌روزرسانی موفق، درخواست به طور خودکار تکرار می‌شود.

استفاده از رهگیر با Session:

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

تمام درخواست‌ها از طریق این Session به طور خودکار از AuthInterceptor عبور می‌کنند — توکن به هدرها اضافه شده و در صورت 401، به‌روزرسانی و تکرار انجام می‌شود. این کار کد احراز هویت را در هر درخواست تکراری حذف کرده و منطق کار با توکن‌ها را متمرکز می‌کند.