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は2つのプロトコルを実装しています。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の場合は更新と再試行が実行されます。これにより、すべてのリクエストでの認証コードの重複が排除され、トークン管理ロジックが集中化されます。