Alamofire — bu nədir, Swift-də HTTP-klient və necə işləyir

Alamofire nədir?

Alamofire — Alamofire Software Foundation tərəfindən yaradılmış (əvvəlcə Mattt Thompson 2014-cü ildə) Swift üçün HTTP kliyentidir. Kitabxana URLSession-ın aşağı səviyyəli detallarını abstraksiya edərək şəbəkə əlaqəsi üçün təmiz və ifadəli API təmin edir.

Alamofire-in əsas fəlsəfəsi — sorğu parametrlərinin (URL, metod, başlıqlar, parametrlər, kodlayıcı) ardıcıl çağırışlarla ötürüldüyü zəncir sintaksisidir. Bu, kodu daha oxunaqlı edir və URLRequest-in səhv konfiqurasiyası ilə bağlı xəta ehtimalını azaldır. Deklarativ yanaşma nə etmək lazım olduğuna diqqət yetirməyə imkan verir, əlaqənin necə qurulacağının detallarına deyil. Tərtibatçı istənilən nəticəni təsvir edir, kitabxana isə şəbəkə ilə aşağı səviyyəli işi öz üzərinə götürür.

Kitabxana 2014-cü ildən aktiv şəkildə dəstəklənir və yeddi əsas versiyadan keçmişdir. 2025–2026-cı illər üçün aktual olan Alamofire 5, Combine, async/await, cavab konvertorları, debug üçün EventMonitor və sorğu interceptorları üçün RequestInterceptor dəstəyini əhatə edir. Hər bir əsas versiya əhəmiyyətli təkmilləşdirmələr gətirdi: Alamofire 4 Codable dəstəyini, Alamofire 5 isə Combine Publishers və təkmilləşdirilmiş sorğu interceptor sistemini əlavə etdi.

Alamofire ekosisteminə əlavə kitabxanalar daxildir: şəkillərin yüklənməsi və keşlənməsi üçün AlamofireImage, iOS status barında şəbəkə göstəricisi üçün AlamofireNetworkActivityIndicator və ObjectMapper ilə inteqrasiya üçün AlamofireObjectMapper. Bu komponentlər Alamofire-i sadəcə HTTP kliyenti deyil, tam hüquqlu şəbəkə steki halına gətirir.

Quraşdırma və konfiqurasiya

Alamofire Swift Package Manager (tövsiyə olunur), CocoaPods və ya Carthage vasitəsilə quraşdırılır. Xcode-da File → Add Packages menyusunu açmaq, repozitoriyanın URL-ni yapışdırmaq və versiyanı göstərmək kifayətdir.

// Swift Package Manager — Package.swift-ə əlavə et
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// Faylda import
import Alamofire

Quraşdırmadan sonra Alamofire AF ad sahəsi (Alamofire-in qısaltması) vasitəsilə qlobal olaraq əlavə konfiqurasiya olmadan əlçatandır. Əksər layihələr öz konfiqurasiyası ilə Session-ı qurmağa başlayır — bu, əsas URL, standart başlıqlar, vaxt aşımları və TLS sertifikat işləyicilərini təyin etməyə imkan verir.

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

Session(configuration:) vasitəsilə öz sessiyanızı yaratmaq, tətbiqin müxtəlif hissələri üçün unikal konfiqurasiya tələb olunduqda zəruridir — məsələn, aqressiv keşləmə ilə şəkillərin yüklənməsi üçün ayrıca sessiya və autentifikasiya ilə API sorğuları üçün ayrıca sessiya. Alamofire sessiyası təkcə konfiqurasiyanı deyil, həm də interceptor, serverTrustManager, cachedResponseHandler və redirectHandler qəbul edir ki, bu da sorğunun bütün mərhələlərində şəbəkə davranışını tam idarə etməyə imkan verir.

Əsas xüsusiyyətlər

Alamofire iOS tətbiqlərində şəbəkə əlaqəsinin əksər ssenarilərini əhatə edən geniş funksiyalar dəsti təqdim edir. Əsas olanları nəzərdən keçirək.

HTTP sorğuları

Sorğunun əsas sintaksisi metod, URL, parametrlər və encoding-i əhatə edir. Bütün standart HTTP metodları HTTPMethod enum vasitəsilə dəstəklənir: get, post, put, patch, delete. Parametrlər URL parametrləri (URLEncoding), JSON gövdəsi (JSONEncoding) və ya multipart formatı (MultipartFormData) kimi kodlaşdırıla bilər.

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("İstifadəçi yaradıldı: \(user)")
        case .failure(let error):
            print("Xəta: \(error)")
        }
    }

validate() metodu avtomatik olaraq status kodunu (200–299) və məzmun tipini yoxlayır, qeyri-standart cavabda xəta qaytarır ki, bu da statusCode-un əl ilə yoxlanılmasını aradan qaldırır. responseDecodable JSON-un Swift strukturuna avtomatik deserializasiyası üçün Decodable protokolundan istifadə edir — bu, əl ilə JSONSerialization-ı aradan qaldırır və REST API ilə işləyərkən boilerplate kodunun həcmini azaldır.

Cavabların emalı

Alamofire bir neçə növ cavab işləyicisini dəstəkləyir: response (xam məlumat), responseJSON (lüğət/massiv), responseString (mətn), responseData (Data) və responseDecodable (Decodable model). Cavab konvertorları protobuf, qrafik formatlar və ya öz protokollarınız üçün fərdi yaradıla bilər.

Faylların yüklənməsi və endirilməsi

Məlumatları serverə yükləmək üçün Data, File və MultipartFormData-nı dəstəkləyən upload istifadə olunur. Böyük faylların endirilməsi, əlaqə kəsildikdən sonra resumeData vasitəsilə bərpa imkanı olan download vasitəsilə həyata keçirilir. Hər iki əməliyyat istifadəçi interfeysində göstərmək üçün 0-dan 1-ə qədər kəsr dəyərləri olan uploadProgress və downloadProgress vasitəsilə irəliləyişin izlənilməsini dəstəkləyir.

Alamofire ilə Multipart yükləmə xüsusilə rahatdır: upload(multipartFormData:) metodu append vasitəsilə forma hissələrinin əlavə olunduğu bir closure qəbul edir. Hər bir hissə məlumat, fayl və ya axın, həmçinin öz adı və mime tipini ehtiva edə bilər. Alamofire avtomatik olaraq multipart sərhədlərini hesablayır və düzgün Content-Type başlığını təyin edir ki, bu da tərtibatçını sorğu gövdəsini əl ilə formalaşdırmaqdan xilas edir. Böyük fayllar üçün bütün faylı yaddaşa yükləmək əvəzinə axın ötürülməsindən (stream provider) istifadə etmək tövsiyə olunur — bu, məhdud resurslu mobil cihazlarda yaddaş limitinin aşılmasının qarşısını alır. Tipik ssenari — istifadəçinin avatarını profil məlumatları ilə birlikdə bir multipart sorğusunda göndərmək, bu da HTTP çağırışlarının sayını azaldır və server tərəfində emalı sadələşdirir.

Alamofire vs URLSession

Alamofire və yerli URLSession-ın müqayisəsi memarlıq qərarı qəbul etməyə kömək edir. Alamofire URLSession-ı əvəz etmir — o, onun üzərində qurulur və eyni konfiqurasiya, keşləmə və fon tapşırıqları mexanizmlərindən istifadə edir. URLSession-ın bütün funksiyaları Alamofire vasitəsilə, lakin daha rahat deklarativ sintaksislə əlçatandır.

Böyük layihələrdə Alamofire şəbəkə sorğuları üçün kodun həcmini 30–50% azaldır və xəta idarəetməsini sadələşdirir. Kiçik layihələrdə və ya binar ölçüsünə ciddi tələblər olduqda, xarici asılılıqların olmaması səbəbindən yerli URLSession daha üstündür.

Müasir Alamofire 5, Publisher qaytaran publishDecodable xüsusiyyəti vasitəsilə Combine ilə inteqrasiya edir ki, bu da xəta idarəetməsi və məlumat transformasiyası ilə reaktiv sorğu zəncirləri qurmağa imkan verir. Async/await üçün value şəkilçisi olan metodlar mövcuddur — məsələn, AF.request(url).serializingDecodable(User.self).value, bu da sintaksisi maksimum dərəcədə yığcam edir və yerli URLSession ilə işi xatırladır. Async/await istifadə edərkən closure-lara ehtiyac qalmır və xəta idarəetməsi Swift-in standart do-catch blokları vasitəsilə həyata keçirilir ki, bu da kodun saxlanmasını və uzunmüddətli perspektivdə oxunaqlılığını asanlaşdırır.

Kod nümunələri

Daha mürəkkəb bir nümunəyə baxaq — avtomatik olaraq autentifikasiya tokeni əlavə edən və 401 xətası zamanı təkrar cəhd edən interceptor ilə sorğu. Bu, JWT autentifikasiyası olan tətbiqlər üçün tipik ssenaridir.

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)
        }
    }
}

Interceptor AuthInterceptor iki protokolu tətbiq edir: adapt (hər sorğuya token əlavə edir) və retry (401 xətası zamanı tokeni yeniləməyə çalışır). retry metodu cavabın status kodunu yoxlayır və 401 alındıqda TokenManager vasitəsilə yeni token tələb edir. Uğurlu yeniləmədən sonra sorğu avtomatik olaraq təkrarlanır.

Interceptor-un sessiya ilə istifadəsi:

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

Bu sessiya vasitəsilə bütün sorğular avtomatik olaraq AuthInterceptor-dan keçir — token başlıqlara əlavə olunur, 401 zamanı isə yeniləmə və təkrar həyata keçirilir. Bu, hər sorğuda autentifikasiya kodunun təkrarlanmasını aradan qaldırır və tokenlərlə iş məntiqini mərkəzləşdirir.