Retrofit：概要、Android HTTPクライアントの特徴

Retrofitとは？

Retrofitは、Androidプラットフォーム上でREST APIと型付きで連携するためのライブラリで、Square社によって開発されました。アノテーションを付与したJavaまたはKotlinのインターフェースを通じてHTTPリクエストを宣言的に記述する方法を提供し、手動によるJSONパースやHTTP接続管理を完全に不要にします。

このライブラリは2013年にAsyncTaskやHttpURLConnectionといった煩雑なソリューションの代替として登場しました。2025年現在、Retrofitはそのシンプルさと型安全性により、Androidアプリにおけるネットワーク通信のデファクトスタンダードであり続けています。JetBrains Developer Ecosystem 2024の調査によると、65%以上のAndroid開発者が商用プロジェクトでRetrofitを使用しています。

Retrofitの代替手段との主な違いは宣言的アプローチにあります。開発者は「何をすべきか」（どのエンドポイントを呼び出すか、どのパラメータを渡すか）を記述し、「どのように行うか」（接続を開く方法、InputStreamの読み取り方法、JSONの解析方法）は記述しません。これにより、HttpURLConnectionの手動使用と比較してボイラープレートコードが60～70%削減されます。

Retrofitの仕組み

動作原理 RetrofitはJavaの動的プロキシに基づいています。開発者がアノテーション付きインターフェースのメソッドを呼び出すと、RetrofitはProxy.newProxyInstanceメカニズムを介して呼び出しをインターセプトし、HTTPリクエストに変換します。プロセス全体はコンパイル時のコード生成なしで実行時に発生します。

Retrofit.Builderインスタンスを作成する際に、ベースURLとコンバーターファクトリが指定されます。BuilderはOkHttpClientを構成し、タイムアウト、インターセプター、接続プール、キャッシュを設定します。create(Class)メソッドはインターフェースの実装を生成し、通常のクラスのように呼び出せるプロキシオブジェクトを返します。

リクエスト実行チェーンは次のようになります：アノテーションがHTTPメソッドを抽出し、パラメータがURLまたはリクエストボディに挿入され、コンバーターがボディをシリアライズし、OkHttpがリクエストを実行し、コンバーターがレスポンスをデシリアライズし、結果が指定された型で返されます。各段階は分離されており、カスタム実装に置き換えることができます。例えば、テスト用にOkHttpClientをMockWebServerに置き換えたり、API変更時にコンバーターを交換したりできます。

重要な特徴として、Retrofitはストリーミングデータ転送を直接サポートしていません。ストリーミングには、インターフェースメソッドの戻り値の型としてOkHttp ResponseBodyが使用されます。また、Retrofitはリクエストのキャンセルを自動的に管理しません。キャンセルするにはCallへの参照を保持し、cancel()を呼び出す必要があります。Kotlinのsuspend関数では、親コルーチンがキャンセルされるとリクエストのキャンセルが自動的に行われます。

Callオブジェクトのライフサイクル

Call<T>は単一のHTTPリクエストを表すオブジェクトです。実行（executeまたはenqueue）後、Callを再利用することはできません。繰り返しリクエストを行うには、インターフェースメソッドを呼び出して新しいCallを作成する必要があります。これにより、同じリクエストが誤って2回送信されるのを防ぎ、サーバーでの重複操作を回避します。

Kotlinでは、Callの代わりにsuspend関数が使用され、リクエストのライフサイクルを自動的に管理します。Retrofitは実行をDispatchers.IOに切り替え、結果をコルーチンに返します。これにより、CallとCallbackを使用するバージョンと比較してコードが30～40%削減されます。

HTTPメソッドのためのRetrofitアノテーション

アノテーションは、RetrofitでHTTPリクエストを構成するための主要なメカニズムです。各アノテーションは標準のHTTPメソッドに対応し、エンドポイントへの相対パスを受け入れます。RetrofitはGET、POST、PUT、DELETE、PATCH、HEAD、OPTIONSをサポートしています。

リクエストパラメータのアノテーション

@Pathは値をURLセグメントに代入します：@Path("id") Int idはパス内の{id}を置き換えます。@Queryはクエリパラメータを追加します：@Query("page") Int pageは?page=5になります。@Bodyは選択したコンバーターによる自動シリアライゼーションでリクエストボディにオブジェクトを渡します。@Headerと@HeadersはHTTPヘッダーを管理します（静的または動的）。

これらのアノテーションを組み合わせることで、任意のRESTエンドポイントを記述できます。例えば、エンドポイントPOST /api/users/{id}/posts?limit=10には、@POST、id用の@Path、limit用の@Query、渡すオブジェクト用の@Bodyが必要です。Retrofitは自動的に正しいHTTPリクエストを組み立てます。さらに、@Url（動的URL）、@Field（フォームエンコードされたボディ）、@Partと@PartMap（ファイルを含むマルチパートリクエスト用）もサポートされています。

KotlinでのRetrofitコード例

実践的な例として、GitHub API用のインターフェースを見てみましょう。リポジトリのリストを取得するメソッドを持つKotlinインターフェースが作成されます。RepoデータクラスがJSONレスポンスの構造を記述します。

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

インターフェースを記述した後、Builderを介してRetrofitインスタンスが作成されます。ベースURL、コンバーター、OkHttpClientは一度設定され、依存性注入を通じて再利用されます。

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

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

Responseラッパーを使用したレスポンス処理

HTTPステータスコードの柔軟な処理には、Response<T>ラッパーを使用します。これにより、4xxおよび5xxエラーで例外をスローすることなく、レスポンスコード、ヘッダー、ボディにアクセスできます。これにより、try-catchなしで404や500を処理できます。

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "Error: ${response.code()}")
}

Retrofitのコンバーターとシリアライゼーション

コンバーターは、オブジェクトをHTTPボディに変換し、その逆を行うRetrofitのコンポーネントです。Retrofitはシリアライゼーションをコアに組み込まず、代わりにConverter.Factoryによるモジュラーアプローチを採用しており、任意のシリアライゼーションライブラリをプラグインできます。

最も一般的なコンバーターは、Gsonライブラリに基づくGoogleのGsonConverterFactoryです。ほとんどのプロジェクトで動作し、カスタムTypeAdapterやJsonDeserializerをサポートします。ただし、Gsonはリフレクションを使用し、Kotlinのnull安全性を考慮しないため、予期しないnullフィールドでNPEが発生する可能性があります。

代替としてSquareのMoshiConverterFactoryがあります。型に対してより厳格で、Kotlinサポート（null安全性、デフォルト値）が優れており、リフレクションが不要です。純粋なKotlinプロジェクトには、コンパイル時に@Serializableアノテーションで動作するKotlinx Serialization Converterが最適です。リフレクションを使用せず、sealed class、デフォルト値、マルチプラットフォームをサポートします。

コンバーターの選択はパフォーマンスと型安全性に影響します。Gsonはカスタム設定なしでKotlinのnon-nullフィールドにnullをデシリアライズし、アクセス時にNPEを引き起こす可能性があります。Moshiは@Json(name)アノテーションとfailOnUnknownによってこの問題を解決します。Kotlinx Serializationが最も安全で、コンパイル時にコードを生成するため、実行時の型エラーを完全に排除します。

Retrofit使用時のよくある間違い

suspend関数でのHTTPエラー処理の欠如が最も一般的な問題です。サーバーが4xxまたは5xxを返した場合、RetrofitはHttpExceptionをスローします。try-catchがないとアプリがクラッシュします。戻り値の型としてResponse<T>を使用すると、ボディにアクセスする前にisSuccessfulをチェックできるため、この問題が解決します。

キャッシュ設定の誤りは過剰なトラフィックを引き起こします。Retrofitはレスポンスを自動的にキャッシュしません。このタスクはOkHttpClientがCacheを通じて行います。キャッシュがないと、データが変更されていない場合でもすべてのリクエストが完全に実行されます。OkHttpClientに10 MBのキャッシュを追加すると、同じ情報への繰り返しリクエストでトラフィックが40～60%削減されます。

リクエストごとにRetrofitを作成することは初心者によくある間違いです。Retrofit.Builderは実行時にプロキシクラスを生成するリソース集約型の操作です。正しい方法は、1つのRetrofitインスタンスを作成し、DIフレームワークを通じて再利用することです。Hilt、Koin、Daggerはアプリ全体でシングルトンのRetrofitインスタンスを提供し、メモリを節約してリクエストを高速化します。

認証のためのInterceptorを無視することが4つ目の問題です。各呼び出しに手動でAuthorizationヘッダーを追加する代わりに、OkHttpClientでグローバルなInterceptorを設定します。Interceptorはすべてのリクエストをインターセプトし、Bearerトークンを追加します。Authenticatorは401レスポンスを処理し、トークンを更新して自動的にリクエストを再試行します。これにより認証ロジックが集中化されます。