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ợ
suspendnative từ lâu, nên artifactretrofit-kotlin-coroutines-adaptertrong 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ứ.
Mục lục
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
OkHttpClientduy 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,Authorizationbị 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.



