Alamofire: bu nədir, HTTP-klient funksiyaları və tətbiq inkişafında istifadəsi

Alamofire nədir?

Alamofire Apple platformalarında HTTP sorğuları ilə iş üçün tamamilə Swift-də yazılmış kitabxanadır. İnkişafı 2014-cü ildə Objective-C AFNetworking kitabxanasına alternativ olaraq başlamış və tezliklə iOS cəmiyyətində şəbəkə ünsiyyəti üçün standarta çevrilmişdir.

Kitabxana sistem freymvorqu URLSession üzərində qurulmuş, onun aşağı səviyyəli API-sini yığcam çağırış zəncirinə abstraksiya edir. Alamofire URLSession-ın bütün funksiyalarını dəstəkləyir: fon sessiyaları, sorğu interceptorları, SSL sertifikatları və cavab serializasiyasının bir neçə üsulu.

Swift Package Index-in məlumatlarına görə, Alamofire GitHub-da 45 000-dən çox ulduzla ən populyar 10 Swift paketi arasındadır. Kitabxana iOS 10+, macOS 10.12+, tvOS 10+ və watchOS 3+ ilə uyğunludur.

Alamofire-in URLSession-dan birbaşa istifadəyə nisbətən əsas üstünlüyü şablon kodunun azaldılmasıdır. Bir AF.request çağırışı URLRequest-in 15–20 sətir əl konfiqurasiyasını, cavab emalını və məlumatların dekodlanmasını əvəz edir. Eyni zamanda kitabxana xüsusi sessiyalar və genişləndirmələr vasitƏsilə qeyri-standart ssenarilər üçün tam çevikliyi qoruyur.

Alamofire-in əsas imkanları

Alamofire mobil tətbiq inkişafının əksər ssenarilərini əhatə edən geniş şəbəkə funksiyaları təqdim edir. Modul arxitekturası sayəsində proqramçı yalnız zəruri komponentləri birləşdirir.

Bütün HTTP metodlarının dəstəyi

HTTP metodları GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS və TRACE vahid API vasitəsilə reallaşdırılıb. Hər bir metod sorğu parametrləri, başlıqları qəbul edir və cavabı Result tipində qaytarır. Proqramçı URLRequest-i özü konfiqurasiya etməli deyil — kitabxana bunu ötürülən arqumentlər əsasında avtomatik edir.

Server cavablarının validasiyası

Validasiya Alamofire-də məlumatları tətbiqə ötürməzdən əvvəl status kodlarını və cavabın məzmununu yoxlamağa imkan verir. Kitabxana closure-lar vasitƏsilə xüsusi validasiya şərtlərini dəstəkləyir və xəta idarəsi üzərində tam nəzarət verir. Susmaya görə yalnız 200–299 status kodları yoxlanılır.

Parametrlərin avtomatik kodlanması

Parametrlər seçilmiş növdən asılı olaraq avtomatik kodlanır: GET sorğuları üçün URL-encoding və POST üçün JSON-encoding. Alamofire həmçinin Property List kodlamasını və ParameterEncoder protokolu vasitƏsilə xüsusi enkoderləri dəstəkləyir və formatı istənilən serverə uyğunlaşdırmağa imkan verir.

Sessiya idarəsi və interceptorlar

Sessiya Alamofire-də vaxt limitlərini, SSL sertifikatlarını, susmaya görə HTTP başlıqlarını və proxy-ni konfiqurasiya etməyə imkan verir. EventMonitor interceptorları sorğunun həyat dövrü hadisələrini izləməyə imkan verir: yaradılma, göndərilmə, cavabın alınması və tamamlanma. Bu, istehsalatda şəbəkə problemlərinin loqlanması, analitikası və sazlanması üçün faydalıdır.

Alamofire necə işləyir?

Alamofire URLSession instansiyasını və şəbəkə konfiqurasiyasını kapsullaşdıran Session əsaslı arxitekturadan istifadə edir. Hər bir sorğu handlerlər zəncirindən keçir: adapterlər, təkrarlama siyasətləri, validatorlər və serializatorlar, bu da çeviklik və genişləndirilə bilmə təmin edir.

Session və Request modeli

Session obyekti tətbiqdəki bütün şəbəkə sorğularını idarə edir. O, vaxt limitləri, susmaya görə başlıqlar və sertifikatları əhatə edən konfiqurasiya ilə yaradılır. Hər AF.request çağırışı göndərilməzdən əvvəl dəyişdirilə bilən DataRequest qaytarır. Alamofire yaddaş sızıntılarının qarşısını almaq üçün sessiyaya zəif istinadlar vasitƏsilə Retain Cycle-ı avtomatik idarə edir.

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) istifadəçi alındı")
        case .failure(let error):
            print("Xəta: \(error.localizedDescription)")
        }
    }

Alamofire-in quraşdırılması və konfiqurasiyası

Quraşdırma Alamofire Swift Package Manager, CocoaPods və ya Carthage vasitƏsilə həyata keçirilir. Yeni layihələr üçün tövsiyə olunan üsul Xcode-a daxil olan SPM-dir, çünki əlavə alətlər tələb etmir və inteqrasiya bir neçə kliklə həyata keçirilir.

Swift Package Manager vasitƏsilə

Paketin Xcode-da əlavə edilməsi File → Add Packages menyusu vasitƏsilə həyata keçirilir. Depo URL-i: https://github.com/Alamofire/Alamofire. Versiyanın son sabit buraxılışa təyin edilməsi tövsiyə olunur. Alamofire semantik versiyalaşdırmanı dəstəkləyir və bütün qırılma dəyişiklikləri CHANGELOG-da sənədləşdirilir.

CocoaPods vasitƏsilə

CocoaPods mövcud infrastrukturu olan layihələr üçün populyar üsul olaraq qalır. Podfile-a pod 'Alamofire' sətrini əlavə edin və pod install-i yerinə yetirin. Alamofire-in xarici asılılıqları yoxdur, bu da inteqrasiyanı sadələşdirir və mövcud layihələrdə versiya konfliktlərini aradan qaldırır.

Alamofire istifadə nümunələri

Nümunələr aşağıda iOS tətbiqlərində Alamofire ilə işin tipik ssenarilərini nümayiş etdirir: sadə GET sorğularından tərəqqiyə nəzarətlə fayl yükləməyə qədər.

GET sorğusu və JSON cavabı

Parametrlərlə sadə GET sorğusu və cavabın Codable modelinə dekodlanması — mobil tətbiqlərdə Alamofire-in ən çox yayılmış istifadə ssenarisidir. Parametrlər avtomatik kodlanır, cavab isə JSONDecoder vasitƏsilə dekodlanır. Kod yığcam və oxunaqlı olur.

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("İstifadəçilər: \(users.count)")
        case .failure(let error):
            print("Xəta: \(error)")
        }
    }

JSON gövdəli POST sorğusu

POST sorğusu serverdə resursların yaradılması üçün istifadə olunur. Alamofire ötürülən obyekti JSONParameterEncoder vasitƏsilə avtomatik kodlayır, proqramçını əl serializasiyasından azad edir. Cavab eyni JSONDecoder vasitƏsilə məlumat modelinə dekodlanır.

let newUser = User(id: 1,
                     name: "İvan Petrov",
                     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("İstifadəçi yaradıldı: \(created)")
        }
    }

Multimedia yüklənməsi

Alamofire-də upload metodu faylların, məlumatların və multipart formalarının yüklənməsini dəstəkləyir. Kitabxana tərəqqiyi avtomatik idarə edir və yükləmə vəziyyətini uploadProgress closure-ları vasitƏsilə izləməyə imkan verir, bu da yerinƏ yetirmə göstəricisini göstərmək üçün rahatdır.

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

AF.upload(imageData,
           to: "https://api.example.com/upload")
    .uploadProgress { progress in
        print("Tərəqqi: \(progress.fractionCompleted * 100)%")
    }
    .responseDecodable(of: UploadResponse.self) { response in
        print("Yükləmə tamamlandı")
    }

Alamofire-də xəta idarəsi və validasiya

Xəta idarəsi Alamofire-də cavab validasiyası və Result tiplərinin kombinasiyasına əsaslanır. Xəta modeli şəbəkə uğursuzluqlarının bütün tipik ssenarilərini əhatə edən AFError-i əhatə edir: vaxtın keçməsi, əlaqənin olmaması, server xətaları və uğursuz serializasiya. Hər bir hal ayrıca işlənir.

Xətadan sonra təkrarlanan cəhdlər üçün Alamofire RequestRetrier mexanizmini təmin edir. Bu protokol təkrarlama siyasətini təyin etməyə imkan verir: cəhd sayı, aralarında gecikmə və təkrarlamanın yerinƏ yetirildiyi şərt. Məsələn, serverin 503 xətası zamanı sorğunu 2 saniyədən sonra təkrarlamaq olar, 401-də isə yeni doğrulama tokeni tələb etmək olar.

AFError yanaşması siyahılama ilə proqramçının heç bir xəta növünü qaçırmamasını təmin edir — kompilyator emalın tamlığını yoxlayır. Bu, kodu təmiz URLSession-da NSError vasitƏsilə xəta idarəsi ilə müqayisədə daha etibarlı və proqnozlaşdırıla bilən edir.

Təkrarlama siyasətləri və təkrarlanan sorğular

RequestRetrier protokolu sorğu, sessiyanı, xətanı və tamamlama closure-nı qəbul edən retry metodunu müəyyən edir. Bu metodda proqramçı sorğunun təkrarlanmasının zəruri olub-olmadığına və hansı vaxtdan sonra qərar verir. Alamofire tipik ssenarilər üçün daxili RetryPolicy təmin edir, lakin istehsalat kodu üçün biznes məntiqini nəzərə alan öz siyasətlərin yaradılması tövsiyə olunur.

AFError müxtəlif xəta kateqoriyaları üçün iç-içə halları olan bir siyahılamadır. Proqramçı hər növü ayrıca emal edə bilər: vaxtın keçməsi üçün sorğunun təkrarlanmasını, server xətaları üçün istifadəçiyə başa düşən mesaj göstərməyi. Alamofire RequestRetrier protokolu vasitƏsilə xüsusi təkrarlama siyasətlərini dəstəkləyir.

Daxili validasiya 200–299 diapazonunda status kodlarını və cavabın məzmun növünü yoxlayır. Genişləndirilmiş validasiya üçün validate closure-ı vasitƏsilə xüsusi şərtlər əlavə edə bilərsiniz, bu da məlumatları UI qatına ötürməzdən əvvəl cavabın biznes məntiqini yoxlamağa imkan verir.