Android 网络层与 Retrofit 实践

// gradle/libs.versions.toml
[versions]
retrofit = "2.11.0"
okhttp = "4.12.0"
kotlinxSerialization = "1.7.3"

[libraries]
retrofit              = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-serialization = { module = "com.squareup.retrofit2:converter-kotlinx-serialization", version.ref = "retrofit" }
okhttp                = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }
okhttp-logging        = { module = "com.squareup.okhttp3:logging-interceptor", version.ref = "okhttp" }
okhttp-mockwebserver  = { module = "com.squareup.okhttp3:mockwebserver", version.ref = "okhttp" }
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerialization" }

dependencies {
    implementation(libs.retrofit)
    implementation(libs.retrofit.serialization)
    implementation(libs.okhttp)
    implementation(libs.okhttp.logging)
    testImplementation(libs.okhttp.mockwebserver)
}

interface ArticleApi {

    @GET("articles")
    suspend fun list(
        @Query("page") page: Int,
        @Query("size") size: Int = 20
    ): List<ArticleDto>

    @GET("articles/{id}")
    suspend fun detail(@Path("id") id: String): ArticleDto

    @POST("articles")
    suspend fun create(@Body body: CreateArticleRequest): ArticleDto

    @FormUrlEncoded
    @POST("login")
    suspend fun login(
        @Field("username") username: String,
        @Field("password") password: String
    ): TokenDto
}

@Serializable
data class ArticleDto(
    val id: String,
    val title: String,
    @SerialName("updated_at") val updatedAt: Long,
    val tags: List<String> = emptyList()
)

val json = Json {
    ignoreUnknownKeys = true   // 服务端加字段不崩
    explicitNulls = false
    coerceInputValues = true
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
    .client(okHttpClient)
    .build()

object HttpClientFactory {

    val client: OkHttpClient by lazy {
        OkHttpClient.Builder()
            .connectTimeout(10, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .writeTimeout(30, TimeUnit.SECONDS)
            .callTimeout(60, TimeUnit.SECONDS)
            .retryOnConnectionFailure(true)
            .connectionPool(ConnectionPool(5, 5, TimeUnit.MINUTES))
            .addInterceptor(AuthInterceptor())
            .addInterceptor(HttpLoggingInterceptor().apply {
                level = if (BuildConfig.DEBUG)
                    HttpLoggingInterceptor.Level.BODY
                else
                    HttpLoggingInterceptor.Level.NONE
            })
            .build()
    }
}

class AuthInterceptor(private val tokenStore: TokenStore) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val token = tokenStore.accessToken
        val request = chain.request().newBuilder()
            .apply { if (token != null) header("Authorization", "Bearer $token") }
            .build()
        return chain.proceed(request)
    }
}

class TokenAuthenticator(
    private val tokenStore: TokenStore,
    private val refreshApi: RefreshApi
) : Authenticator {
    override fun authenticate(route: Route?, response: Response): Request? {
        if (responseCount(response) >= 2) return null   // 防死循环
        val newToken = runBlocking { refreshApi.refresh(tokenStore.refreshToken) }
            ?: return null
        tokenStore.save(newToken)
        return response.request.newBuilder()
            .header("Authorization", "Bearer ${newToken.accessToken}")
            .build()
    }

    private fun responseCount(response: Response): Int {
        var count = 1
        var prior = response.priorResponse
        while (prior != null) { count++; prior = prior.priorResponse }
        return count
    }
}

@GET("articles")
suspend fun list(
    @Header("X-Client-Version") version: String,
    @HeaderMap extras: Map<String, String>
): List<ArticleDto>

sealed interface ApiResult<out T> {
    data class Success<T>(val data: T) : ApiResult<T>
    data class HttpError(val code: Int, val message: String) : ApiResult<Nothing>
    data class NetworkError(val cause: IOException) : ApiResult<Nothing>
    data class UnknownError(val cause: Throwable) : ApiResult<Nothing>
}

suspend fun <T> safeApiCall(block: suspend () -> T): ApiResult<T> =
    try {
        ApiResult.Success(block())
    } catch (e: HttpException) {
        ApiResult.HttpError(e.code(), e.message())
    } catch (e: IOException) {
        ApiResult.NetworkError(e)
    } catch (e: CancellationException) {
        throw e                    // 取消必须重新抛出
    } catch (e: Throwable) {
        ApiResult.UnknownError(e)
    }

class RetryInterceptor(
    private val maxRetries: Int = 3
) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        var attempt = 0
        var lastError: IOException? = null

        while (attempt <= maxRetries) {
            try {
                val response = chain.proceed(request)
                if (response.isSuccessful || response.code < 500) return response
                response.close()                    // 5xx 才重试
            } catch (e: IOException) {
                lastError = e
            }
            attempt++
            if (attempt > maxRetries) break
            val backoff = (1L shl attempt) * 200L       // 400ms, 800ms, 1600ms
            Thread.sleep(backoff)
        }
        throw lastError ?: IOException("retry exhausted")
    }
}

val pinner = CertificatePinner.Builder()
    .add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
    .add("api.example.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=")
    .build()

val client = OkHttpClient.Builder()
    .certificatePinner(pinner)
    .build()

class ArticleApiTest {

    private lateinit var server: MockWebServer
    private lateinit var api: ArticleApi

    @Before fun setUp() {
        server = MockWebServer()
        server.start()
        api = Retrofit.Builder()
            .baseUrl(server.url("/"))
            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
            .build()
            .create(ArticleApi::class.java)
    }

    @After fun tearDown() = server.shutdown()

    @Test
    fun `list parses response`() = runTest {
        server.enqueue(MockResponse()
            .setResponseCode(200)
            .setBody("""[{"id":"1","title":"hi","updated_at":1}]""")
            .addHeader("Content-Type", "application/json"))

        val result = api.list(page = 1)

        assertEquals(1, result.size)
        assertEquals("hi", result[0].title)
    }
}