Alamofire — ano ito, HTTP-client sa Swift at paano ito gumagana

Ano ang Alamofire?

Alamofire ay isang HTTP client para sa Swift, na ginawa ng Alamofire Software Foundation (orihinal na Mattt Thompson noong 2014). Ang library ay nag-aabstrak ng mga low-level na detalye ng URLSession, na nagbibigay ng malinis at nagpapahayag na API para sa komunikasyon sa network.

Ang pangunahing pilosopiya ng Alamofire ay chain syntax, kung saan ang mga parameter ng request (URL, method, header, parameter, encoder) ay ipinapasa sa pamamagitan ng sunud-sunod na tawag. Ginagawa nitong mas nababasa ang code at binabawasan ang posibilidad ng mga error na nauugnay sa maling configuration ng URLRequest. Deklaratibong approach ay nagbibigay-daan upang tumuon sa kung ano ang kailangang gawin, hindi sa mga detalye kung paano i-configure ang koneksyon. Inilalarawan ng developer ang nais na resulta, at ang library ang pumapangasiwa sa low-level na trabaho sa network.

Ang library ay aktibong sinusuportahan mula noong 2014 at dumaan sa pitong pangunahing bersyon. Ang Alamofire 5, kasalukuyan para sa 2025–2026, ay may kasamang suporta para sa Combine, async/await, response converter, EventMonitor para sa debugging, at RequestInterceptor para sa pag-intercept ng mga request. Bawat pangunahing bersyon ay nagdala ng makabuluhang pagpapabuti: Alamofire 4 ay nagdagdag ng Codable support, Alamofire 5 — Combine Publishers at pinahusay na sistema ng pag-intercept ng request.

Ang ecosystem ng Alamofire ay may kasamang karagdagang mga library: AlamofireImage para sa pag-load at pag-cache ng mga imahe, AlamofireNetworkActivityIndicator para sa network indicator sa iOS status bar, at AlamofireObjectMapper para sa integration sa ObjectMapper. Ang mga component na ito ay gumagawa sa Alamofire ng isang kumpletong network stack, hindi lamang isang HTTP client.

Pag-install at configuration

Ang Alamofire ay ini-install sa pamamagitan ng Swift Package Manager (inirerekomenda), CocoaPods, o Carthage. Sa Xcode, buksan lamang ang menu File → Add Packages, i-paste ang URL ng repository, at tukuyin ang bersyon.

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

// Import sa file
import Alamofire

Pagkatapos ng pag-install, ang Alamofire ay globally na available sa pamamagitan ng namespace na AF (daglat ng Alamofire) nang walang karagdagang configuration. Karamihan sa mga proyekto ay nagsisimula sa pag-setup ng Session na may sariling configuration — pinapayagan nito ang pagtatakda ng base URL, standard headers, timeouts, at TLS certificate handlers.

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

Ang paggawa ng sariling session sa pamamagitan ng Session(configuration:) ay kinakailangan kapag kailangan ang natatanging configuration para sa iba't ibang bahagi ng app — halimbawa, hiwalay na session para sa pag-load ng mga imahe na may agresibong caching at hiwalay para sa API request na may pagpapatotoo. Ang Alamofire session ay tumatanggap hindi lamang ng configuration, kundi pati na rin ng interceptor, serverTrustManager, cachedResponseHandler, at redirectHandler, na nagbibigay-daan sa kumpletong kontrol ng network behavior sa lahat ng yugto ng request.

Mga pangunahing tampok

Ang Alamofire ay nagbibigay ng malawak na hanay ng mga function na sumasaklaw sa karamihan ng mga senaryo ng komunikasyon sa network sa mga iOS app. Tingnan natin ang mga pangunahing.

HTTP request

Ang pangunahing syntax ng request ay may kasamang method, URL, parameter, at encoding. Lahat ng standard na HTTP method ay sinusuportahan sa pamamagitan ng enum HTTPMethod: get, post, put, patch, delete. Ang mga parameter ay maaaring i-encode bilang URL parameters (URLEncoding), JSON body (JSONEncoding), o multipart format (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("Ginawa ang user: \(user)")
        case .failure(let error):
            print("Error: \(error)")
        }
    }

Ang method na validate() ay awtomatikong sinusuri ang status code (200–299) at content type, nagbabalik ng error sa hindi standard na response, na nag-aalis ng manual na pagsusuri ng statusCode. Ang responseDecodable ay gumagamit ng Decodable protocol para sa awtomatikong deserialization ng JSON sa Swift structure — inaalis nito ang manual na JSONSerialization at binabawasan ang dami ng boilerplate code kapag nagtatrabaho sa REST API.

Pagproseso ng response

Ang Alamofire ay sumusuporta sa ilang uri ng response handler: response (raw data), responseJSON (dictionary/array), responseString (text), responseData (Data), at responseDecodable (Decodable model). Response converter ay maaaring gawing custom — para sa protobuf, graphic formats, o sariling protocol.

Pag-upload at pag-download ng file

Para sa pag-upload ng data sa server ay ginagamit ang upload, na sumusuporta sa Data, File, at MultipartFormData. Ang pag-download ng malalaking file ay ginagawa sa pamamagitan ng download na may kakayahang mag-resume sa pamamagitan ng resumeData pagkatapos ng pagkagambala o pagkaputol ng koneksyon. Parehong operasyon ay sumusuporta sa pagsubaybay ng progreso sa pamamagitan ng uploadProgress at downloadProgress na may fractional values mula 0 hanggang 1 para sa pagpapakita sa user interface.

Ang multipart upload gamit ang Alamofire ay lalong maginhawa: ang method na upload(multipartFormData:) ay tumatanggap ng closure kung saan ang mga bahagi ng form ay idinaragdag sa pamamagitan ng append. Bawat bahagi ay maaaring maglaman ng data, file, o stream, pati na rin ang sariling pangalan at mime type. Awtomatikong kinakalkula ng Alamofire ang multipart boundaries at itinatakda ang tamang Content-Type header, na nagpapalaya sa developer mula sa manual na pagbubuo ng request body. Para sa malalaking file, inirerekomenda ang paggamit ng stream transmission (stream provider) sa halip na i-load ang buong file sa memory — pinipigilan nito ang paglampas sa limitasyon ng memory sa mga mobile device na may limitadong resources. Isang tipikal na senaryo — pagpapadala ng avatar ng user kasama ng data ng profile sa isang multipart request, na nagbabawas ng bilang ng HTTP calls at pinapasimple ang pagproseso sa server side.

Alamofire vs URLSession

Ang paghahambing ng Alamofire at native na URLSession ay tumutulong sa paggawa ng desisyon sa arkitektura. Hindi pinapalitan ng Alamofire ang URLSession — ito ay binuo sa ibabaw nito at gumagamit ng parehong mekanismo ng configuration, caching, at background task. Lahat ng functionality ng URLSession ay available sa pamamagitan ng Alamofire, ngunit may mas maginhawang deklaratibong syntax.

Sa malalaking proyekto, ang Alamofire ay nagbabawas ng dami ng code para sa network request ng 30–50% at pinapasimple ang pag-handle ng error. Sa maliliit na proyekto o may mahigpit na pangangailangan sa laki ng binary, ang native na URLSession ay mas gusto dahil sa kawalan ng external dependencies.

Ang modernong Alamofire 5 ay nag-i-integrate sa Combine sa pamamagitan ng property na publishDecodable, na nagbabalik ng Publisher, na nagbibigay-daan sa pagbuo ng reactive chain ng request na may error handling at data transformation. Para sa async/await, available ang mga method na may suffix na value — halimbawa, AF.request(url).serializingDecodable(User.self).value, na ginagawang lubhang maigsi ang syntax at nagpapaalala ng trabaho sa native na URLSession. Kapag gumagamit ng async/await, nawawala ang pangangailangan para sa closure, at ang error handling ay ginagawa sa pamamagitan ng standard do-catch blocks ng Swift, na pinapasimple ang pagpapanatili ng code at pagbabasa nito sa pangmatagalang panahon.

Mga halimbawa ng code

Tingnan natin ang isang mas kumplikadong halimbawa — isang request na may interceptor na awtomatikong nagdaragdag ng authorization token at nagre-retry sa 401 error. Ito ay isang tipikal na senaryo para sa mga app na may JWT authentication.

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

Ang interceptor na AuthInterceptor ay nag-i-implement ng dalawang protocol: adapt (nagdaragdag ng token sa bawat request) at retry (sumusubok na i-refresh ang token sa 401 error). Ang method na retry ay sinusuri ang status code ng response at, kung nakatanggap ng 401, humihiling ng bagong token sa pamamagitan ng TokenManager. Pagkatapos ng matagumpay na pag-refresh, ang request ay awtomatikong inuulit.

Paggamit ng interceptor sa session:

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

Lahat ng request sa pamamagitan ng session na ito ay awtomatikong dumadaan sa AuthInterceptor — ang token ay idinaragdag sa mga header, at sa 401 ay ginagawa ang refresh at pag-uulit. Inaalis nito ang pagdodoble ng authentication code sa bawat request at isinasentralisa ang logic ng pagtatrabaho sa mga token.