android-retrofit

Retrofit を使用した Android のネットワーキング

手順

Retrofit を使用してネットワークレイヤーを実装する際は、最新の Android のベストプラクティス（2025 年）に従ってください。

1. URL の操作

Retrofit では、置換ブロックとクエリパラメーターを使用して URL を動的に更新できます。

• 動的パス：相対 URL に {name} を使用し、パラメーターには @Path("name") を使用します。
• クエリパラメーター：個別のパラメーターには @Query("key") を使用します。
• 複雑なクエリ：動的なパラメーターのセットには @QueryMap Map<String, String> を使用します。

interface SearchService {
    @GET("group/{id}/users")
    suspend fun groupList(
        @Path("id") groupId: Int,
        @Query("sort") sort: String?,
        @QueryMap options: Map<String, String> = emptyMap()
    ): List<User>
}

2. リクエストボディとフォームデータ

オブジェクトを JSON ボディとして送信することも、フォームエンコード形式やマルチパート形式を使用することもできます。

• @Body：設定済みのコンバーター（JSON）を使用してオブジェクトをシリアライズします。
• @FormUrlEncoded：データを application/x-www-form-urlencoded 形式で送信します。@Field を使用します。
• @Multipart：データを multipart/form-data 形式で送信します。@Part を使用します。

interface UserService {
    @POST("users/new")
    suspend fun createUser(@Body user: User): User

    @FormUrlEncoded
    @POST("user/edit")
    suspend fun updateUser(
        @Field("first_name") first: String,
        @Field("last_name") last: String
    ): User

    @Multipart
    @PUT("user/photo")
    suspend fun uploadPhoto(
        @Part("description") description: RequestBody,
        @Part photo: MultipartBody.Part
    ): User
}

3. ヘッダーの操作

ヘッダーはメソッドに静的に設定することも、パラメーターを介して動的に設定することもできます。

• 静的ヘッダー：@Headers を使用します。
• 動的ヘッダー：@Header を使用します。
• ヘッダーマップ：@HeaderMap を使用します。
• グローバルヘッダー：OkHttp の Interceptor を使用します。

interface WidgetService {
    @Headers("Cache-Control: max-age=640000")
    @GET("widget/list")
    suspend fun widgetList(): List<Widget>

    @GET("user")
    suspend fun getUser(@Header("Authorization") token: String): User
}

4. Kotlin のサポートとレスポンス処理

suspend 関数を使用する場合、戻り値の型は次の 2 つから選べます。

1. 直接ボディ（User）：デシリアライズされたボディを返します。2xx 以外のレスポンスでは HttpException をスローします。
2. Response<User>：ステータスコード、ヘッダー、エラーボディにアクセスできます。2xx 以外の結果でも例外はスローされません。

@GET("users")
suspend fun getUsers(): List<User> // Throws on error

@GET("users")
suspend fun getUsersResponse(): Response<List<User>> // Manual check

5. Hilt とシリアライズの設定

Hilt モジュールで Retrofit のインスタンスをシングルトンとして提供します。

@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {

    @Provides
    @Singleton
    fun provideJson(): Json = Json {
        ignoreUnknownKeys = true
        coerceInputValues = true
    }

    @Provides
    @Singleton
    fun provideOkHttpClient(): OkHttpClient = OkHttpClient.Builder()
        .addInterceptor(HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BODY })
        .connectTimeout(30, TimeUnit.SECONDS)
        .build()

    @Provides
    @Singleton
    fun provideRetrofit(okHttpClient: OkHttpClient, json: Json): Retrofit = Retrofit.Builder()
        .baseUrl("https://api.github.com/")
        .client(okHttpClient)
        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
        .build()
}

6. リポジトリーでのエラー処理

UI の状態をクリーンに保つため、ネットワーク例外は必ずリポジトリーレイヤーで処理してください。

class GitHubRepository @Inject constructor(private val service: GitHubService) {
    suspend fun getRepos(username: String): Result<List<Repo>> = runCatching {
        // Direct body call throws HttpException on 4xx/5xx
        service.listRepos(username)
    }.onFailure { exception ->
        // Handle specific exceptions like UnknownHostException or SocketTimeoutException
    }
}

7. チェックリスト

• すべてのネットワーク呼び出しで suspend 関数を使用します。
• 特定のステータスコード（例：401 Unauthorized）を処理する必要がある場合は、Response<T> を優先します。
• URL の手動連結ではなく、@Path と @Query を使用します。
• デバッグ用のロギングと適切なタイムアウトを設定して OkHttpClient を構成します。
• レイヤー間の依存を切り離すため、API DTO をドメインモデルにマッピングします。