Retrofit — その概要、HTTPライブラリ、アプリケーションでの使用方法

Retrofitとは？

Retrofitは、Square社によって開発されたAndroidアプリケーションでHTTPリクエストを行うためのライブラリです。Javaインターフェースとアノテーションを通じてREST APIを宣言的に定義するアプローチを提供し、ネットワーク対話コードをクリーンで予測可能にします。

Retrofitの核となる考え方は、開発者がAPIをメソッドとアノテーションを持つインターフェースとして記述し、ライブラリが自動的に実装を生成するというものです。このアプローチにより、すべてのエンドポイントが型付けされ、URLやパラメーターのエラーが実行時ではなくコンパイル時に検出されます。

Retrofitはすべての一般的なHTTPメソッドとデータ形式をサポートしています。このライブラリはSquare社とコミュニティによって積極的にメンテナンスされており、新しいバージョンが定期的にリリースされ、現在のバージョン2.11はJava 17とKotlin 2.0をサポートしています。RetrofitはAndroid向けの最も人気のあるHTTPクライアントであり続けています。

Retrofitは同じくSquare社による効率的なHTTPクライアントであるOkHttpの上で動作します。この組み合わせにより、キャッシュ、リクエストインターセプト、トランスポートプロトコルレベルでの接続管理が提供されます。このライブラリは同期呼び出しと非同期呼び出しの両方をサポートしています。

2013年の初回リリース以来、Retrofitはいくつかのメジャーアップデートを経てきました。現在のバージョンRetrofit 2は、初版の経験に基づいて完全に書き直され、非同期処理のためのコンバーターとアダプターのより柔軟なシステムを提供しています。

Retrofitのアーキテクチャは関心の分離の原則に従っています。インターフェースはAPI契約のみを定義し、コンバーターはシリアライゼーションを担当し、アダプターは非同期処理を管理します。これにより、他のコードを変更することなく任意のコンポーネントを置き換えることができます。例えば、エンドポイントの定義を変更せずにGsonからMoshiに切り替えることができます。

Retrofitの主な機能

Retrofitは、モバイルアプリケーションにおけるほぼすべてのネットワーク対話シナリオをカバーする一連の機能を提供します。主な利点はAPI定義の宣言的なスタイルです。

宣言的なエンドポイントアノテーション

アノテーション @GET、@POST、@PUT、@PATCH、@DELETE、@HTTPを使用すると、インターフェース内で直接HTTPメソッドとURLテンプレートを指定できます。パスパラメーターは@Path、クエリパラメーターは@Query、リクエストボディは@Bodyで設定します。このアプローチにより、アプリケーションのAPIレイヤーが完全に型付けされます。

シリアライゼーションのためのコンバーター

コンバーターはHTTPレスポンスをJavaオブジェクトに変換し、その逆も行います。RetrofitはGson、Moshi、Jackson、Protobuf、Wireをサポートしています。開発者はConverter.Factoryを介して必要なコンバーターを接続し、ライブラリはそれをすべてのリクエストとレスポンスに自動的に適用します。

非同期処理のためのアダプター

アダプター CallAdapterを使用すると、APIメソッドの戻り値の型を変更できます。標準のCallの代わりに、RxJava用のObservable、Kotlinコルーチン用のDeferred、またはLiveDataを使用できます。これにより、ネットワークリクエストを選択したアプリケーションアーキテクチャに統合できます。

動的URLとヘッダー

動的 URLは@Urlアノテーションで設定され、実行時にエンドポイントを渡すことができます。ヘッダーは@Headersで静的に、または@Headerパラメーターで動的に指定できます。すべてのリクエストにグローバルヘッダーを適用するには、OkHttpインターセプターを使用して各送信リクエストにヘッダーを追加します。

Retrofitの動作仕組み

Retrofitは3つの段階で動作します。APIインターフェースの定義、Retrofitインスタンスの作成、リクエストの実行です。ライブラリはアノテーションとコンバーターに基づいて実行時にインターフェースの実装を生成します。

リクエストのライフサイクル

APIメソッドが呼び出されると、Retrofitはアノテーションと引数に基づいてRequestオブジェクトを作成します。リクエストは実行のためにOkHttpに渡されます。レスポンスを受け取った後、ライブラリはそれをConverter.Factoryに渡して必要な型に変換します。CallAdapterは結果を非同期ラッパーでラップします。各段階はカスタマイズ可能です。

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val api = retrofit.create(ApiService::class.java)

Retrofitのインストールと設定

Retrofitのインストールは、Androidの標準ビルドシステムであるGradleを通じて行います。ライブラリはMaven Centralから配布されており、プロジェクトのbuild.gradleにいくつかの依存関係を追加する必要があります。

依存関係の追加

build.gradleファイル（モジュールレベル）に、Retrofit、Gsonコンバーター、OkHttpの依存関係を追加します。集中管理のために、ルートのbuild.gradleでライブラリのバージョンを変数に抽出することをお勧めします。Retrofit 2には最低限Android API 21が必要です。

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Retrofitインスタンスの作成

RetrofitインスタンスはBuilderを介して作成されます。必須パラメーターはbaseUrlとConverterFactoryです。冗長な接続を避けるために、RetrofitとOkHttpClientにはシングルトンを使用することをお勧めします。logging-interceptorを追加すると、開発中のネットワークリクエストのデバッグが容易になります。

Kotlinプロジェクトでは、Callタイプの代わりにAPIインターフェースでsuspend関数を使用することをお勧めします。これによりコードが簡素化され、コルーチンの構造化された並行性を利用できます。Callからsuspendに切り替える場合は、インターフェースの戻り値の型を変更するだけで、残りのコードは自動的に適応します。

Retrofitの使用例

以下の例は、AndroidアプリケーションでのRetrofitの典型的な使用シナリオを示しています。単純なGETリクエストからサーバーへのファイルアップロードまでをカバーします。

クエリパラメーター付きGETリクエスト

クエリ文字列パラメーター付きの単純なGETリクエストは基本操作です。@Queryアノテーションが自動的にURLにパラメーターを追加し、suspend関数によってメインスレッドをブロックせずにコルーチンからリクエストを呼び出せます。

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

JSONボディ付きPOSTリクエスト

JSONボディ付きのPOSTリクエストは、@Bodyアノテーションを使用してオブジェクトを渡します。GsonConverterFactoryはUserオブジェクトを自動的にJSONにシリアライズします。Kotlinコルーチンは、Callbackインターフェースなしでバックグラウンドスレッドでのリクエスト実行を保証します。

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "アンナ・イワノワ", email = "anna@example.com")
val created = api.createUser(user)

Multipartによるファイルアップロード

@Multipartアノテーションと@Partを組み合わせることで、サーバーにファイルをアップロードできます。Retrofitは必要なヘッダーを含むmultipartリクエストを自動的に生成します。OkHttpはRequestBodyを介してアップロードの進行状況を管理し、ユーザーにインジケーターを表示できます。

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Retrofitのエラーハンドリングとインターセプター

Retrofitでのエラー処理は、OkHttpのメカニズムとKotlinコルーチンの組み合わせに基づいています。OkHttpインターセプターを使用すると、リクエストのログ記録、認証ヘッダーの追加、アプリケーションコードに到達する前のエラー処理が可能です。

集中エラーハンドリングのために、API呼び出しのラッパーをsealed class Resultとして作成することがよくあります。このクラスには、データを持つSuccessと例外を持つErrorの2つのサブクラスがあります。ViewModelは統一された結果を受け取り、各関数でエラーハンドリングコードを重複させることなく、対応するユーザーインターフェース状態を表示できます。

インターセプターには2つのタイプがあります。アプリケーションインターセプターはサーバー送信前にリクエストを変更し、ネットワークインターセプターは受信後のレスポンスを処理します。例えば、インターセプターは401を受信したときに自動的にアクセストークンを更新し、開発者の介入なしに新しいトークンでリクエストを再試行できます。

Interceptorによるリクエストロギング

ロギングインターセプター HttpLoggingInterceptorは、ネットワークリクエストのデバッグに不可欠なツールです。Logcatにリクエストメソッド、URL、ヘッダー、ボディ、レスポンスコードを出力します。ログレベルは、最小限の情報の場合はBASIC、ヘッダーの場合はHEADERS、完全な内容の場合はBODYに設定できます。本番環境では、BASICを使用するか、ロギングを完全に無効にすることをお勧めします。

OkHttpのインターセプターは2つのタイプに分類されます。リクエストを変更するアプリケーションインターセプターと、生のネットワークデータを処理するネットワークインターセプターです。ロギングインターセプターは自動的にリクエストとレスポンスの詳細をLogcatに出力します。

コルーチンレベルでのエラー処理は、suspend関数の呼び出しをtry-catchで囲んで行います。Retrofitはエラーを、4xxおよび5xxコードの場合はHttpException、ネットワークがない場合はUnknownHostException、タイムアウト超過の場合はSocketTimeoutExceptionとして返します。統一処理のためにsealed class Resultを使用することをお勧めします。