Alamofire: ano ito, mga function ng HTTP client at paggamit sa pag-develop

Ano ang Alamofire?

Alamofire ay isang library para sa pagtatrabaho sa mga HTTP request sa mga platform ng Apple, na ganap na nakasulat sa Swift. Nagsimula ang pag-develop noong 2014 bilang alternatibo sa Objective-C library na AFNetworking at mabilis na naging pamantayan para sa komunikasyon sa network sa komunidad ng iOS.

Ang library ay binuo sa ibabaw ng system framework na URLSession, na nag-aabstrak ng low-level na API nito sa mga maigsi na chain ng tawag. Sinusuportahan ng Alamofire ang lahat ng function ng URLSession: background session, request interceptor, SSL certificate, at maraming paraan ng serialization ng tugon.

Ayon sa Swift Package Index, ang Alamofire ay nasa top 10 ng pinakasikat na Swift package na may mahigit 45 000 na bituin sa GitHub. Ang library ay compatible sa iOS 10+, macOS 10.12+, tvOS 10+ at watchOS 3+.

Ang pangunahing bentahe ng Alamofire kumpara sa direktang paggamit ng URLSession ay ang pagbawas ng template na code. Isang tawag sa AF.request ang pumapalit sa 15–20 linya ng manual na configuration ng URLRequest, pagproseso ng tugon at pag-decode ng data. Kasabay nito, pinapanatili ng library ang buong flexibility para sa hindi pamantayang mga senaryo sa pamamagitan ng custom na session at extension.

Mga pangunahing kakayahan ng Alamofire

Alamofire ay nagbibigay ng malawak na hanay ng mga function para sa pagtatrabaho sa network na sumasaklaw sa karamihan ng mga senaryo ng pag-develop ng mobile application. Dahil sa modular na arkitektura, ang developer ay nagkokonekta lamang ng mga kinakailangang bahagi.

Suporta sa lahat ng HTTP method

Mga HTTP method GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS at TRACE ay ipinapatupad sa pamamagitan ng pare-parehong API. Bawat method ay tumatanggap ng mga parameter ng request, header at nagbabalik ng tugon sa anyo ng Result type. Hindi kailangan ng developer na manually i-configure ang URLRequest — awtomatikong ginagawa ito ng library batay sa mga ibinigay na argumento.

Pag-validate ng mga tugon ng server

Pag-validate ng mga tugon sa Alamofire ay nagpapahintulot ng pagsusuri ng status code at nilalaman ng tugon bago ipadala ang data sa application. Sinusuportahan ng library ang custom na kondisyon ng pag-validate sa pamamagitan ng closure, na nagbibigay ng buong kontrol sa paghawak ng error. Bilang default, ang mga status code na 200–299 lamang ang sinusuri.

Awtomatikong pag-encode ng parameter

Mga parameter ng request ay awtomatikong na-eencode depende sa napiling uri: URL-encoding para sa GET request at JSON-encoding para sa POST. Sinusuportahan din ng Alamofire ang Property List encoding at custom na encoder sa pamamagitan ng ParameterEncoder protocol, na nagpapahintulot ng pag-aangkop ng format sa anumang server.

Pamamahala ng session at mga interceptor

Session ng Alamofire ay nagpapahintulot ng configuration ng timeouts, SSL certificate, default na HTTP header at proxy. Ang mga interceptor na EventMonitor ay nagbibigay-daan sa pagsubaybay ng mga event sa lifecycle ng request: paggawa, pagpapadala, pagtanggap ng tugon at pagkumpleto. Ito ay kapaki-pakinabang para sa logging, analytics at debugging ng mga problema sa network sa produksyon.

Paano gumagana ang Alamofire?

Alamofire ay gumagamit ng arkitekturang batay sa Session, na nag-eencapsulate ng instance ng URLSession at configuration ng network. Bawat request ay dumadaan sa chain ng mga handler: adapter, retry policy, validator at serializer, na tinitiyak ang flexibility at extensibility.

Modelo ng Session at Request

Ang Session object ay namamahala sa lahat ng network request sa application. Ito ay nilikha na may configuration na naglalaman ng timeouts, default na header at certificate. Bawat tawag sa AF.request ay nagbabalik ng DataRequest na maaaring baguhin bago ipadala. Awtomatikong hinahawakan ng Alamofire ang Retain Cycle sa pamamagitan ng mahinang reference sa session, na pumipigil sa memory leak.

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("Natanggap ang \(users.count) na user")
        case .failure(let error):
            print("Error: \(error.localizedDescription)")
        }
    }

Pag-install at configuration ng Alamofire

Pag-install ng Alamofire ay ginagawa sa pamamagitan ng Swift Package Manager, CocoaPods o Carthage. Ang inirerekomendang paraan para sa mga bagong proyekto ay SPM na naka-integrate sa Xcode, dahil hindi ito nangangailangan ng karagdagang tool at ang integrasyon ay ginagawa sa ilang click.

Sa pamamagitan ng Swift Package Manager

Ang pagdagdag ng package sa Xcode ay ginagawa sa pamamagitan ng menu File → Add Packages. URL ng repositoryo: https://github.com/Alamofire/Alamofire. Inirerekomenda na i-fix ang bersyon sa pinakabagong stable release. Sinusuportahan ng Alamofire ang semantic versioning, at lahat ng breaking changes ay na-dodokumento sa CHANGELOG.

Sa pamamagitan ng CocoaPods

CocoaPods ay nananatiling popular na paraan para sa mga proyektong may umiiral na imprastraktura. Idagdag ang linyang pod 'Alamofire' sa Podfile at isagawa ang pod install. Ang Alamofire ay walang panlabas na dependency, na nagpapasimple ng integrasyon at nag-aalis ng conflict ng bersyon sa mga umiiral na proyekto.

Mga halimbawa ng paggamit ng Alamofire

Mga halimbawa sa ibaba ay nagpapakita ng tipikal na senaryo ng pagtatrabaho sa Alamofire sa mga iOS application: mula sa simpleng GET request hanggang sa pag-upload ng file na may kontrol ng progreso.

GET request at JSON na tugon

Simpleng GET request na may parameter at pag-decode ng tugon sa Codable model — ang pinakakaraniwang senaryo ng paggamit ng Alamofire sa mobile application. Ang mga parameter ay awtomatikong na-eencode, at ang tugon ay dinedekode sa pamamagitan ng JSONDecoder. Ang code ay nagiging compact at nababasa.

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("Mga user: \(users.count)")
        case .failure(let error):
            print("Error: \(error)")
        }
    }

POST request na may JSON body

POST request na may JSON body ay ginagamit para sa paggawa ng mga resource sa server. Awtomatikong in-eencode ng Alamofire ang ibinigay na object sa pamamagitan ng JSONParameterEncoder, na nagpapalaya sa developer mula sa manual na serialization. Ang tugon ay dinedekode sa data model sa pamamagitan ng parehong JSONDecoder.

let newUser = User(id: 1,
                     name: "Ivan 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("Ginawa ang user: \(created)")
        }
    }

Pag-upload ng multimedia

Ang upload method sa Alamofire ay sumusuporta sa pag-upload ng mga file, data at multipart form. Awtomatikong pinamamahalaan ng library ang progreso at nagpapahintulot ng pagsubaybay sa estado ng upload sa pamamagitan ng uploadProgress closure, na maginhawa para sa pagpapakita ng indicator ng progreso.

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

AF.upload(imageData,
           to: "https://api.example.com/upload")
    .uploadProgress { progress in
        print("Progreso: \(progress.fractionCompleted * 100)%")
    }
    .responseDecodable(of: UploadResponse.self) { response in
        print("Natapos ang pag-upload")
    }

Paghawak ng error at pag-validate sa Alamofire

Paghawak ng error sa Alamofire ay batay sa kombinasyon ng pag-validate ng tugon at Result type. Ang modelo ng error ay kinabibilangan ng AFError, na sumasaklaw sa lahat ng tipikal na senaryo ng pagkabigo sa network: timeouts, kawalan ng koneksyon, error ng server at hindi matagumpay na serialization. Bawat kaso ay hinahawakan nang hiwalay.

Para sa mga pagsubok muli pagkatapos ng error, ang Alamofire ay nagbibigay ng mekanismong RequestRetrier. Ang protocol na ito ay nagpapahintulot ng pagtukoy ng retry policy: bilang ng mga pagsubok, pagkaantala sa pagitan ng mga ito at kondisyon kung kailan isinasagawa ang pagsubok muli. Halimbawa, sa error 503 ng server, maaaring ulitin ang request pagkatapos ng 2 segundo, at sa 401 — humingi ng bagong authentication token.

Ang AFError na approach na may enumeration ay tumitiyak na hindi makaligtaan ng developer ang anumang uri ng error — sinusuri ng compiler ang pagkakumpleto ng paghawak. Ginagawa nitong mas maaasahan at mahuhulaan ang code kumpara sa paghawak ng error sa pamamagitan ng NSError sa purong URLSession.

Retry policy at paulit-ulit na request

Ang RequestRetrier protocol ay tumutukoy sa retry method na tumatanggap ng request, session, error at completion closure. Sa method na ito, nagpapasya ang developer kung uulitin ang request at pagkatapos ng anong oras. Ang Alamofire ay nagbibigay ng built-in na RetryPolicy implementation para sa tipikal na senaryo, ngunit para sa production code, inirerekomenda na gumawa ng sariling policy na isinasaalang-alang ang business logic.

AFError ay isang enumeration na may nested case para sa iba't ibang kategorya ng error. Maaaring hawakan ng developer ang bawat uri nang hiwalay: para sa timeouts, mag-ayos ng pag-uulit ng request; para sa error ng server — magpakita ng naiintindihang mensahe sa user. Sinusuportahan ng Alamofire ang custom na retry policy sa pamamagitan ng RequestRetrier protocol.

Ang built-in na pag-validate ay sinusuri ang status code sa range na 200–299 at uri ng nilalaman ng tugon. Para sa pinalawig na pag-validate, maaaring magdagdag ng custom na kondisyon sa pamamagitan ng validate closure, na nagpapahintulot ng pagsusuri ng business logic ng tugon bago ipadala ang data sa UI layer.