Thực Hiện Các Yêu Cầu Mạng với Retrofit và OkHttp

Retrofit và OkHttp vẫn là stack gọi REST mặc định của app Android năm 2026. Không phải vì không có lựa chọn khác, mà vì hai thư viện này đã giải quyết đúng những việc khó: quản lý kết nối, ánh xạ interface sang HTTP, và biến JSON thành object có kiểu. Vấn đề của phần lớn app không nằm ở thư viện, mà ở cấu hình: client không timeout, interceptor log cả token, vòng retry áp cho cả POST. Bốn thứ đó đủ để một app “chạy được” biến thành app không qua được security review.

Cập nhật 2026

  • Retrofit + OkHttp vẫn là chuẩn cho REST. Gson sang vai legacy; kotlinx.serialization là converter Kotlin-first, dùng được cả trên Kotlin Multiplatform.
  • Retrofit hỗ trợ suspend native từ lâu, nên artifact retrofit-kotlin-coroutines-adapter trong bài cũ không còn cần thiết.
  • Version Retrofit/OkHttp không được pin trong bài: fact base của series chưa xác minh bản stable 2026. Lấy số từ Maven Central, đừng chép từ blog.
  • HTTP/3 client của JDK 26 thuộc java.net.http, không phải OkHttp — đừng gộp hai thứ.

OkHttp và Retrofit: hai tầng, một stack

OkHttp là tầng thấp: mở socket, TLS handshake, multiplex HTTP/2, giữ connection pool, đọc cache, chạy interceptor. Retrofit là tầng cao: đọc annotation trên interface, dựng Request, giao cho OkHttp, rồi đưa Response qua converter để thành object. Bạn có thể dùng OkHttp một mình; bạn không thể dùng Retrofit mà thiếu một HTTP client bên dưới.

Hiểu ranh giới này để biết lỗi thuộc tầng nào: timeout và certificate là OkHttp; sai đường dẫn hay sai kiểu trả về là Retrofit.

Tầng OkHttp Retrofit
Vai trò Gửi byte, TLS, HTTP/2, pool, cache Map interface sang request, gọi converter
Cấu hình OkHttpClient Retrofit.Builder + converter
Lỗi điển hình IOException, SSLException HttpException, SerializationException
Test MockWebServer MockWebServer + base URL giả

Cài đặt: dependency, base URL, quyền Internet

Điền ba biến version vào gradle.properties sau khi kiểm tra Maven Central. Plugin kotlin-serialization phải cùng version với Kotlin bạn dùng (hiện tại 2.4.21). buildConfigField giữ base URL ở một chỗ; đừng hard-code trong class.

Base URL phải kết thúc bằng dấu /, còn đường dẫn trong annotation không bắt đầu bằng /. Thiếu slash, Retrofit ném IllegalArgumentException ngay lúc build instance. App chỉ cần quyền INTERNET; đừng thêm usesCleartextTraffic="true" để “cho nhanh”. Android 9+ chặn cleartext mặc định, và bật nó lên là tắt luôn một lớp bảo vệ.

// File: app/build.gradle.kts
// Ba property này khai báo trong gradle.properties, lấy bản stable từ Maven Central
val retrofitVersion: String by project
val okHttpVersion: String by project
val serializationVersion: String by project

dependencies {
    implementation("com.squareup.retrofit2:retrofit:$retrofitVersion")
    implementation("com.squareup.retrofit2:converter-kotlinx-serialization:$retrofitVersion")
    implementation("com.squareup.okhttp3:okhttp:$okHttpVersion")
    implementation("com.squareup.okhttp3:logging-interceptor:$okHttpVersion")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion")
    testImplementation("com.squareup.okhttp3:mockwebserver3-junit4:$okHttpVersion")
}

android {
    buildFeatures { buildConfig = true }
    defaultConfig {
        buildConfigField("String", "API_BASE_URL", "\"https://api.example.com/\"")
    }
}

Interface Retrofit: suspend, @GET, @POST, @Path, @Query, @Body

Chọn kiểu trả về theo cách bạn muốn xử lý lỗi. suspend fun post(id): Post trả thẳng object, non-2xx sẽ ném HttpException — gọn cho happy path. Response<Post> cho bạn status, header và errorBody() — cần khi API trả lỗi có cấu trúc riêng.

@Path URL-encode giá trị; @Query bỏ qua tham số null; @Body đi qua converter; @Header và @Headers set header tĩnh. Tất cả chạy trên dispatcher của OkHttp, nên đừng bọc thêm withContext(Dispatchers.IO) — vô nghĩa và che mất chỗ thực sự chặn main.

// File: data/remote/BlogApi.kt
@Serializable
data class Post(
    val id: Long,
    val title: String,
    val body: String,
    @SerialName("user_id") val userId: Int,
)

@Serializable
data class NewPost(val title: String, val body: String, @SerialName("user_id") val userId: Int)

interface BlogApi {
    @GET("posts")
    suspend fun posts(@Query("user_id") userId: Int?): List<Post>

    @GET("posts/{id}")
    suspend fun post(@Path("id") id: Long): Post

    @POST("posts")
    suspend fun create(@Body post: NewPost): Post

    @GET("posts")
    suspend fun postsPage(@Query("_page") page: Int): Response<List<Post>>
}

Converter: kotlinx.serialization thay Gson

Với dự án Kotlin, dùng converter-kotlinx-serialization. Nó sinh serializer lúc compile, không reflection, tôn trọng nullability của Kotlin và dùng lại được cho KMP. Cấu hình ignoreUnknownKeys = true để backend thêm field không làm app crash; coerceInputValues = true để null sai kiểu thành giá trị mặc định thay vì ném.

Gson vẫn chạy, nhưng là legacy: reflection, không phân biệt String? với String, nuốt field lạ và không chia sẻ được với iOS. Nếu codebase còn Gson, đừng trộn hai converter trong một instance Retrofit — chuyển theo từng endpoint.

private val json = Json {
    ignoreUnknownKeys = true
    coerceInputValues = true
}

private val retrofit = Retrofit.Builder()
    .baseUrl(BuildConfig.API_BASE_URL)
    .client(okHttpClient)
    .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
    .build()

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

OkHttpClient: timeout, interceptor, logging

Một OkHttpClient cho cả process. Tạo mới mỗi request là bỏ connection pool, cache và thread pool — chậm hơn và dễ cạn file descriptor. callTimeout chặn toàn bộ call kể cả retry nội bộ; connectTimeout cho handshake; readTimeout cho từng lần đọc. Đặt callTimeout trước, rồi các timeout con nhỏ hơn để lỗi xuất hiện sớm.

Interceptor ở tầng application thấy request trước khi OkHttp xử lý redirect và retry; đó là chỗ đúng để gắn Authorization. Logging chỉ bật ở debug: BASIC đủ thấy method, URL, status và thời gian; BODY chỉ khi đã redact và không bao giờ ở release. Token nằm ở header, refresh token hay nằm trong body — cả hai đều không được vào log hay crash report.

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

private val logging = HttpLoggingInterceptor().apply {
    level = if (BuildConfig.DEBUG) HttpLoggingInterceptor.Level.BASIC
            else HttpLoggingInterceptor.Level.NONE
    redactHeader("Authorization")
}

val okHttpClient: OkHttpClient = OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(20, TimeUnit.SECONDS)
    .writeTimeout(20, TimeUnit.SECONDS)
    .callTimeout(30, TimeUnit.SECONDS)
    .addInterceptor(AuthInterceptor(tokenStore))
    .addInterceptor(logging)
    .cache(Cache(File(context.cacheDir, "http"), 10L * 1024 * 1024))
    .build()

Xử lý lỗi: Response, HttpException, IOException

Loại Khi nào Xử lý
HttpException Server trả non-2xx, hàm trả thẳng T Đọc code + errorBody; 4xx không retry, 401 thì refresh token
IOException DNS, timeout, mất mạng, TLS handshake Retry nếu idempotent; UI báo “không có kết nối”
SerializationException JSON không khớp schema Coi là lỗi tích hợp, không retry, log có kiểm soát
Envelope lỗi trong 2xx API trả 200 kèm error Validate ở repository, không tin status một mình

Đặt một kiểu Result riêng ở ranh giới repository, đừng rải try/catch khắp ViewModel. Chú ý CancellationException: nó là RuntimeException, nên catch (Exception) sẽ nuốt mất cancellation và làm coroutine không dừng đúng. Bắt cụ thể và rethrow.

sealed interface ApiResult<out T> {
    data class Success<T>(val data: T, val fromCache: Boolean = false) : ApiResult<T>
    data class HttpError(val code: Int, val errorBody: String?) : ApiResult<Nothing>
    data class NetworkError(val cause: IOException) : ApiResult<Nothing>
    data class ParseError(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(), runCatching { e.response()?.errorBody()?.string() }.getOrNull())
    } catch (e: IOException) {
        ApiResult.NetworkError(e)
    } catch (e: CancellationException) {
        throw e
    } catch (e: SerializationException) {
        ApiResult.ParseError(e)
    }

Retry với exponential backoff — chỉ khi idempotent

retryOnConnectionFailure của OkHttp chỉ xử lý lỗi tầng kết nối, không phải retry nghiệp vụ. Retry ứng dụng phải tự viết và phải tôn trọng idempotency: GET, HEAD, PUT, DELETE an toàn; POST và PATCH không, trừ khi bạn gửi Idempotency-Key và server thực sự hỗ trợ.

Chỉ retry lỗi tạm thời: 408, 429, 500, 502, 503, 504 và IOException. 400, 401, 403, 404, 422 retry chỉ làm chậm lỗi. Backoff exponential kèm jitter, tối đa 3–4 lần, và đọc Retry-After nếu server gửi. Cần retry sống qua process death thì dùng WorkManager, không phải vòng lặp trong ViewModel.

suspend fun <T> retryIdempotent(
    maxAttempts: Int = 3,
    baseDelayMs: Long = 500,
    block: suspend (attempt: Int) -> T,
): T {
    var lastError: Throwable? = null
    repeat(maxAttempts) { attempt ->
        try {
            return block(attempt)
        } catch (e: IOException) {
            lastError = e
            if (attempt == maxAttempts - 1) throw e
            delay(baseDelayMs * (1L shl attempt) + Random.nextLong(0, 300))
        } catch (e: HttpException) {
            lastError = e
            val retryable = e.code() in setOf(408, 429, 500, 502, 503, 504)
            if (!retryable || attempt == maxAttempts - 1) throw e
            delay(baseDelayMs * (1L shl attempt) + Random.nextLong(0, 300))
        }
    }
    throw lastError ?: IllegalStateException("retry exhausted")
}

Cache và ETag: offline không cần tự viết

Cache của OkHttp chỉ hoạt động khi server hợp tác. Thiếu Cache-Control hay ETag, OkHttp không tự bịa policy. Với ETag, lần sau OkHttp gửi If-None-Match; server trả 304, OkHttp ghép body cũ thành 200 cho bạn — tiết kiệm băng thông, không cần code thêm.

Đặt max-age ngắn cho list, no-store cho dữ liệu nhạy cảm. Response có token phải là private; cache trên disk là cache dùng chung, user sau có thể đọc dữ liệu user trước nếu header sai. Khi offline, dùng onlyIfCached để lấy bản cũ; nếu không có, OkHttp trả 504 và bạn hiển thị empty state thay vì treo spinner.

@GET("posts")
@Headers("Cache-Control: max-age=60, stale-while-revalidate=300")
suspend fun postsCached(@Query("user_id") userId: Int?): List<Post>

val offlineOnly = CacheControl.Builder()
    .onlyIfCached()
    .maxStale(7, TimeUnit.DAYS)
    .build()

TLS và certificate pinning: khi nào đáng, khi nào thành bom

Certificate pinning nghĩa là app chỉ chấp nhận đúng public key (SPKI hash) của server, kể cả khi một CA bị compromise hoặc người dùng cài CA giả để MITM. Đáng làm với app ngân hàng, ví, hoặc nơi cấp token; thường là overkill cho app đọc nội dung.

Rủi ro thật: xoay certificate mà quên pin dự phòng làm app cũ chết hàng loạt, và không có cách vá từ xa. Vì vậy luôn có ít nhất hai pin, pin intermediate hoặc CA thay vì leaf nếu có thể, ghi ngày hết hạn và kế hoạch gỡ pin ngay từ đầu. Debug build cần bypass, bản release không được có bypass đó. Pinning không thay thế kiểm tra hostname và TLS thông thường; nó là lớp thêm. Với cấu hình khai báo, network_security_config có pin-set kèm expiration — dễ gỡ hơn code nhưng ít linh hoạt hơn.

val pinner = CertificatePinner.Builder()
    .add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=") // pin chính
    .add("api.example.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=") // pin dự phòng
    .build()

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

Test lớp mạng với MockWebServer

MockWebServer cho bạn một server HTTP thật trên loopback: kiểm tra converter, status, header và cả retry mà không cần mạng. Enqueue response theo thứ tự, assert request path và method. Chạy ở unit test JVM, không cần emulator.

Một điểm dễ sai: test chỉ happy path. Hãy enqueue 401, 500, body rỗng và JSON thiếu field — đó là những case làm app crash ngoài đời. Code dưới dùng API builder của mockwebserver3; nếu bạn còn ở OkHttp 4.x, thay bằng MockResponse().setResponseCode(...).setBody(...).

@Test
fun `parse body va nem HttpException khi 404`() = runTest {
    val server = MockWebServer()
    server.start()
    try {
        server.enqueue(MockResponse.Builder()
            .code(200)
            .body("""{"id":1,"title":"A","body":"B","user_id":1}""")
            .addHeader("Content-Type", "application/json")
            .build())
        server.enqueue(MockResponse.Builder().code(404).build())

        val api = Retrofit.Builder()
            .baseUrl(server.url("/"))
            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
            .build()
            .create(BlogApi::class.java)

        assertEquals("A", api.post(1L).title)
        assertFailsWith<HttpException> { api.post(2L) }
    } finally {
        server.shutdown()
    }
}

Repository và chiến lược offline

Repository là nơi duy nhất biết dữ liệu đến từ network hay cache. UI quan sát Room/DataStore, network chỉ ghi vào đó. Nhờ vậy offline vẫn có dữ liệu, còn khi có mạng thì refresh. Đừng dùng isConnected làm điều kiện duy nhất: mạng có thể connected nhưng là captive portal. Kiểm tra NET_CAPABILITY_VALIDATED, và coi connectivity chỉ là tín hiệu refresh sớm — request vẫn phải xử lý IOException.

Sync nền bằng WorkManager với constraint network; đừng giữ coroutine sống bằng service tự chế.

class PostRepository(
    private val api: BlogApi,
    private val dao: PostDao,
) {
    fun posts(): Flow<List<Post>> = dao.observeAll()

    suspend fun refresh(userId: Int?): ApiResult<Unit> = safeApiCall {
        val remote = api.posts(userId)
        dao.replaceAll(remote)
    }
}

Bẫy thường gặp

Bẫy Hậu quả Cách sửa
runBlocking hoặc .execute() trên main ANR, NetworkOnMainThreadException Gọi suspend từ viewModelScope
Tạo Retrofit mới mỗi request Mất pool, cache; chậm và cạn socket Một client, cấp qua DI
Log BODY và Authorization ở release Lộ token trong log hoặc crash report BASIC ở debug, redactHeader, NONE ở release
Không đặt timeout Spinner vô hạn, ANR connect, read, write, callTimeout
Retry POST mù Đơn hàng hoặc thanh toán trùng Chỉ retry idempotent; dùng Idempotency-Key
200 kèm error vẫn coi là success UI hiện dữ liệu rỗng, bug câm Validate envelope ở repository
Bỏ qua status, gọi body()!! NPE khi 204 hoặc 4xx Kiểm tra isSuccessful, xử lý HttpException
catch (Exception) Nuốt CancellationException Bắt cụ thể, rethrow cancellation

Nhìn sang 2027

JDK 26 thêm HTTP/3 cho java.net.http. Đó là client của JVM, không phải OkHttp, và không đi vào app Android qua Retrofit. OkHttp vẫn là stack HTTP/1.1 + HTTP/2 cho Android; đừng đổi cấu hình TLS hay pinning chỉ vì nghe “HTTP/3”. Nếu bạn chia sẻ logic giữa Android và iOS, Ktor client là lựa chọn KMP hợp lý hơn Retrofit.

Checklist trước khi merge

  • Một OkHttpClient duy nhất, có đủ bốn timeout, được cấp qua DI.
  • Converter là kotlinx.serialization; không còn Gson trộn trong cùng instance.
  • Logging NONE ở release, Authorization bị redact ở debug.
  • Mọi lỗi đi qua một kiểu ApiResult; không có catch (Exception) trần.
  • Retry chỉ áp cho idempotent, có backoff và giới hạn số lần.
  • Có test MockWebServer cho 200, 404, 500 và body thiếu field.
  • Dữ liệu có token không bị cache công khai; pinning (nếu dùng) có pin dự phòng.

Đọc tiếp trong series

Nếu API của bạn là GraphQL thay vì REST, bài Apollo-Android và GraphQL đi vào cùng vấn đề ở một giao thức khác. Để hiểu cách suspend chạy trên dispatcher nào, đọc Coroutines, Threads và RxJava. Bài Repository, Factory và Builder giải thích mẫu thiết kế đứng sau lớp repository ở trên. Và nếu bạn cần nhìn lại toàn bộ đường đi, mở lộ trình Android 2026.