Alamofire — 개념, Swift HTTP 클라이언트 및 작동 방식

Alamofire란?

Alamofire는 Alamofire Software Foundation(원래 2014년 Mattt Thompson)이 만든 Swift용 HTTP 클라이언트입니다. 이 라이브러리는 저수준 URLSession 세부 사항을 추상화하여 네트워크 통신을 위한 깔끔하고 표현력 있는 API를 제공합니다.

Alamofire의 핵심 철학은 요청 매개변수(URL, 메서드, 헤더, 매개변수, 인코더)를 순차적 호출을 통해 전달하는 체이닝 구문입니다. 이렇게 하면 코드를 더 읽기 쉽게 만들고 잘못된 URLRequest 구성과 관련된 오류 가능성을 줄일 수 있습니다. 선언적 접근 방식을 사용하면 연결 설정의 세부 사항이 아닌 수행해야 할 작업에 집중할 수 있습니다. 개발자가 원하는 결과를 설명하면 라이브러리가 저수준 네트워크 작업을 처리합니다.

이 라이브러리는 2014년부터 활발히 유지 관리되었으며 7개의 주요 버전을 거쳤습니다. 2025~2026년 현재의 Alamofire 5는 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 Alamofire

설치 후 Alamofire는 추가 구성 없이 AF 네임스페이스(Alamofire의 약자)를 통해 전역적으로 사용할 수 있습니다. 대부분의 프로젝트는 자체 구성으로 Session을 설정하는 것으로 시작합니다. 이를 통해 기본 URL, 기본 헤더, 시간 초과 및 TLS 인증서 처리기를 설정할 수 있습니다.

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

Session(configuration:)을 통한 사용자 정의 세션 생성은 애플리케이션의 다른 부분에 고유한 구성이 필요할 때 필요합니다. 예를 들어, 적극적인 캐싱을 사용하는 이미지 다운로드용 세션과 인증이 필요한 API 요청용 다른 세션 등입니다. Alamofire Session은 구성뿐만 아니라 인터셉터, serverTrustManager, cachedResponseHandler 및 redirectHandler도 허용하여 요청의 모든 단계에서 네트워크 동작을 완전히 제어할 수 있습니다.

주요 기능

Alamofire는 iOS 애플리케이션의 대부분의 네트워크 상호작용 시나리오를 포괄하는 광범위한 기능을 제공합니다. 주요 기능을 살펴보겠습니다.

HTTP 요청

기본 요청 구문에는 메서드, URL, 매개변수 및 인코딩이 포함됩니다. HTTPMethod 열거형을 통해 모든 표준 HTTP 메서드가 지원됩니다: get, post, put, patch, delete. 매개변수는 URL 매개변수(URLEncoding), JSON 본문(JSONEncoding) 또는 멀티파트 폼 데이터(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를 통해 재개할 수 있습니다. 두 작업 모두 사용자 인터페이스에 표시하기 위해 0에서 1 사이의 분수 값으로 uploadProgress 및 downloadProgress를 통한 진행 상황 추적을 지원합니다.

Alamofire의 멀티파트 업로드는 특히 편리합니다. upload(multipartFormData:) 메서드는 append를 통해 폼 부분이 추가되는 클로저를 받습니다. 각 부분에는 데이터, 파일 또는 스트림뿐만 아니라 자체 이름과 MIME 유형이 포함될 수 있습니다. Alamofire는 자동으로 멀티파트 경계를 계산하고 올바른 Content-Type 헤더를 설정하여 개발자가 수동으로 요청 본문을 구성하지 않아도 됩니다. 대용량 파일의 경우 전체 파일을 메모리에 로드하는 대신 스트림 제공자를 사용하는 것이 좋습니다. 이는 리소스가 제한된 모바일 장치에서 메모리 제한 초과를 방지합니다. 일반적인 시나리오는 단일 멀티파트 요청에서 프로필 데이터와 함께 사용자 아바타를 전송하여 HTTP 호출 수를 줄이고 서버 측 처리를 간소화하는 것입니다.

Alamofire vs 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를 사용하면 클로저가 더 이상 필요하지 않으며 오류 처리는 표준 Swift do-catch 블록을 통해 수행되어 장기적으로 코드 유지 관리 및 가독성이 향상됩니다.

코드 예제

더 복잡한 예제를 살펴보겠습니다. 인증 토큰을 자동으로 추가하고 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를 통해 새 토큰을 요청합니다. 갱신이 성공하면 요청이 자동으로 재시도됩니다.

세션과 함께 인터셉터 사용:

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

이 세션을 통한 모든 요청은 자동으로 AuthInterceptor를 거칩니다. 헤더에 토큰이 추가되고 401 시 갱신 및 재시도가 수행됩니다. 이렇게 하면 모든 요청에서 인증 코드 중복이 제거되고 토큰 관리 로직이 중앙 집중화됩니다.