Android Developer Roadmap: Bắt tay vào làm quen với Apollo-Android và GraphQL

Đổi Retrofit sang một endpoint POST duy nhất không tự làm app nhanh hơn: GraphQL chỉ dịch chuyển chi phí, bớt request và DTO viết tay nhưng thêm schema, codegen và một tầng cache phải hiểu đúng. Trong lộ trình Android 2026, Apollo Kotlin — tên cũ là Apollo Android — là client chuẩn cho việc đó.

Bài này dựng một luồng hoàn chỉnh: schema, operation, client, query, mutation, cache và subscription.

Cập nhật 2026

  • Apollo Kotlin 5.2.0 (09/2026) là bản 5.x mới nhất; nhánh 4.4.x vẫn được vá (10/2026) cho dự án chưa migrate. Package không đổi: com.apollographql.apollo — “Apollo Android” chỉ còn là tên cũ.
  • Normalized cache tách sang repo riêng, artifact com.apollographql.cache:normalized-cache và normalized-cache-sqlite, kèm compiler plugin riêng. Cách chọn policy cũng đổi tên: fetchPolicy(FetchPolicy.CacheFirst) thay cho cachePolicy của nhánh 2.x/3.x.
  • Task downloadApolloSchema đã bị xoá ở v5; tải schema bằng block introspection trong Gradle hoặc Apollo Kotlin CLI.
  • Kotlin 2.4.21 là bản stable hiện tại. Apollo sinh code bằng Gradle plugin ở bước build, không đi qua KSP; KSP2 trong app chỉ phục vụ Room/Hilt.

GraphQL giúp gì và làm khó gì trên Android

GraphQL là một hợp đồng: server công bố schema, client khai báo đúng những field cần, server trả đúng shape đó. Không còn /users rồi /users/{id}/orders; chỉ một endpoint và selection nằm ngay trong code.

Lợi ích thật nằm ở hai chỗ. Over-fetching biến mất: REST trả cả object hai mươi field khi bạn cần ba. Under-fetching cũng vậy: một query lấy user, đơn hàng và số comment thay vì ba round trip. Ngoài ra, gõ sai tên field là lỗi compile chứ không phải lỗi runtime trên máy người dùng.

Chiều ngược lại cũng thật. Cache HTTP theo URL biến mất vì mọi request đều POST vào cùng một path; bạn phải dùng normalized cache và tự khai báo cache key. Upload file theo GraphQL multipart spec cần scalar riêng và server hỗ trợ, trong khi một endpoint multipart REST làm xong trong vài dòng. Với CRUD ba bảng và hai màn hình, chi phí schema và pipeline lớn hơn phần lợi. Một endpoint duy nhất cũng làm CDN cache và dashboard theo status code khó hơn.

Bài toán GraphQL REST
Màn hình tổng hợp nhiều nguồn dữ liệu, backend nhiều team Một query, một round trip, schema là hợp đồng Ghép nhiều endpoint, client tự phối dữ liệu
Feed lớn, field thay đổi theo A/B test Selection theo màn hình, thêm field không phá client cũ Versioning endpoint hoặc trả thừa field
Upload ảnh, video Multipart spec, scalar Upload, cấu hình thêm Endpoint multipart quen thuộc, ít bẫy
CRUD đơn giản, vài màn hình Thêm schema, codegen, cache — chi phí không hoàn vốn Retrofit + DTO là đủ

Kết luận: chọn GraphQL khi client quyết định hình dạng dữ liệu; chọn REST khi luồng đơn giản và cần cache HTTP.

Schema, operation và codegen

Apollo cần hai đầu vào: schema server và các file operation. Mọi file .graphql trong module gộp thành một document, nên tên operation và fragment phải unique.

# File: app/src/main/graphql/schema.graphqls (rút gọn từ schema thật)
type Query {
  products(first: Int!): [Product!]!
}

type Mutation {
  addLine(variantId: ID!, quantity: Int!): CartLine!
}

type Subscription {
  cartUpdated: CartLine!
}

type Product {
  id: ID!
  name: String!
  price: Float!
}

type CartLine {
  id: ID!
  quantity: Int!
}

Directive của client không nằm trong schema backend. Khai báo chúng ở extra.graphqls cạnh schema, rồi khai báo cache key cho từng type:

# File: app/src/main/graphql/extra.graphqls
@link(url: "https://specs.apollo.dev/cache/v0.4", import: ["@typePolicy", "@fieldPolicy"])

extend type Product @typePolicy(keyFields: "id")
extend type CartLine @typePolicy(keyFields: "id")

Ba operation dùng trong bài:

# File: app/src/main/graphql/Products.graphql
query Products($first: Int!) {
  products(first: $first) {
    id
    name
    price
  }
}

# File: app/src/main/graphql/AddLine.graphql
mutation AddLine($variantId: ID!, $quantity: Int!) {
  addLine(variantId: $variantId, quantity: $quantity) {
    id
    quantity
  }
}

# File: app/src/main/graphql/CartUpdated.graphql
subscription CartUpdated {
  cartUpdated {
    id
    quantity
  }
}

Build sinh ProductsQuery, AddLineMutation và lớp Data chỉ chứa field đã chọn — model theo query, không theo schema. Phiên bản Apollo, Kotlin và OkHttp để version catalog quản lý.

// File: app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.apollo)            // id: com.apollographql.apollo
}

android {
    compileSdk = 36
    defaultConfig {
        minSdk = 24
        targetSdk = 36
    }
}

apollo {
    service("shop") {
        packageName.set("com.example.shop.graphql")
        // compiler plugin của normalized cache; version lấy từ catalog
        plugin("com.apollographql.cache:normalized-cache-apollo-compiler-plugin:${libs.versions.apolloCache.get()}")
        pluginArgument("com.apollographql.cache.packageName", packageName.get())
    }
}

dependencies {
    implementation(libs.apollo.runtime)                 // com.apollographql.apollo:apollo-runtime
    implementation(libs.apollo.normalizedCache)         // com.apollographql.cache:normalized-cache
    implementation(libs.apollo.normalizedCacheSqlite)   // ...:normalized-cache-sqlite
}

Khi backend đổi schema, tải lại bằng block introspection có token thay vì copy tay — task downloadApolloSchema đã bị xoá ở v5.

Khởi tạo ApolloClient với OkHttp

Trên Android/JVM, OkHttp là engine mặc định của Apollo. Truyền okHttpClient khi cần timeout, proxy hay interceptor sẵn có; header auth dùng HttpInterceptor của Apollo để token refresh không phụ thuộc tầng HTTP.

// File: di/NetworkModule.kt
class AuthorizationInterceptor(private val tokens: TokenStore) : HttpInterceptor {
    override suspend fun intercept(request: HttpRequest, chain: HttpInterceptorChain): HttpResponse =
        chain.proceed(
            request.newBuilder()
                .addHeader("Authorization", "Bearer ${tokens.accessToken()}")
                .build()
        )
}

val okHttpClient = OkHttpClient.Builder()
    .callTimeout(20, TimeUnit.SECONDS)
    .build()

val apolloClient = ApolloClient.Builder()
    .serverUrl("https://api.example.com/graphql")
    .okHttpClient(okHttpClient)
    .addHttpInterceptor(AuthorizationInterceptor(tokenStore))
    .cache(
        MemoryCacheFactory(maxSizeBytes = 8 * 1024 * 1024)
            .chain(SqlNormalizedCacheFactory(context, "apollo-cache.db")),
        enableOptimisticUpdates = true
    )
    .subscriptionNetworkTransport(
        WebSocketNetworkTransport.Builder()
            .serverUrl("wss://api.example.com/graphql")
            .protocol(GraphQLWsProtocol())
            .build()
    )
    .build()

cache() là extension do compiler plugin sinh ra trong package bạn cấu hình, phải import thủ công. Chuỗi memory rồi SQLite cho đọc nóng nhanh và dữ liệu sống qua lần mở app. Client nên là singleton trong DI, vì tạo mới mỗi màn hình sẽ dựng lại cache và connection pool; cách tổ chức quanh nó xem ở bài Repository, Factory và Builder.

Query và ApolloCall với coroutines

apolloClient.query(...) trả về ApolloCall, một mô tả request chưa chạy. Gọi execute() — hàm suspend — để thực thi; Apollo tự đẩy I/O sang Dispatchers.IO, nên gọi từ viewModelScope là an toàn. Cần nhiều lần emit (cache rồi network, hoặc watcher) thì dùng toFlow(); riêng CacheAndNetwork không dùng được với execute() vì nó emit hai lần.

// File: feature/catalog/CatalogViewModel.kt
val call: ApolloCall<ProductsQuery.Data> = apollo.query(ProductsQuery(first = 20))
val response = call
    .fetchPolicy(FetchPolicy.CacheFirst)
    .execute()                 // suspend: gọi trong viewModelScope

// response.data — có thể null hoặc chỉ một phần
// response.errors — GraphQL error
// response.exception — fetch error

Ba loại lỗi, ba cách xử lý

ApolloResponse có ba field phải đọc đúng thứ tự. exception là fetch error: offline, timeout, 500, JSON lệch schema — không có data, chỉ còn retry hoặc báo lỗi. errors là GraphQL error: server trả 200 nhưng một field fail (thiếu quyền, id không tồn tại) và data có thể vẫn có phần khác. data là dữ liệu, có thể partial.

Vì vậy đừng viết if (response.data != null) rồi bỏ qua errors: màn hình có thể hiện sản phẩm nhưng thiếu giá, và log không có gì. dataOrThrow() tiện cho happy path nhưng ném khi có bất kỳ error, tức là mất luôn phần data đọc được. Với normalized cache, serverErrorsAsException và cacheMissesAsException mặc định bật: cache hit một phần thành exception với data null; đặt false nếu muốn partial read.

Normalized cache và fetch policy

Cache chuẩn hoá bẻ response thành từng object, mỗi object một entry theo cache key, field tham chiếu object khác bằng reference. Với key đúng, hai query cùng chứa một Product chỉ có một entry, và sửa entry đó cập nhật mọi watcher. Nhưng key mặc định là đường dẫn field (products.0, cart.line) — trùng lặp và không ổn định. @typePolicy(keyFields: "id") buộc key thành Product:42, kèm typename để không đụng type khác; field key được codegen tự thêm vào selection.

Fetch policy Hành vi Dùng khi
CacheFirst (mặc định) Đọc cache; miss hoặc lỗi thì gọi network Mặc định cho màn hình đọc
NetworkFirst Gọi network; lỗi thì rơi về cache Cần dữ liệu mới, vẫn phải có gì đó để hiện
NetworkOnly Bỏ qua cache, luôn gọi network Sau mutation, pull-to-refresh, dữ liệu nhạy cảm
CacheOnly Chỉ đọc cache, miss là exception Offline mode, dữ liệu đã đồng bộ sẵn
CacheAndNetwork Emit cache trước, rồi emit network Hiện ngay rồi cập nhật; chỉ dùng với toFlow()

Đặt policy ở cấp operation, đừng đặt toàn cục. Với màn hình cần phản ứng theo cache, dùng .watch(): mỗi lần entry liên quan đổi, Flow emit lại và UI không phải tự đồng bộ. Xoá cache khi logout bằng apollo.apolloStore.clearAll() — gọi trên Dispatchers.IO, không phải main.

Mutation và optimistic update

Mutation dùng cùng execute(), nhưng một quy tắc quyết định cache: response phải chứa đúng những field bị thay đổi. Mutation addLine trả id và quantity, nên entry CartLine được cập nhật và watcher giỏ hàng được notify. Chỉ trả id thì server đã đổi mà cache vẫn giá trị cũ — lỗi phổ biến nhất khi thêm mutation.

suspend fun addLine(variantId: String, quantity: Int): CartLine {
    val response = apollo
        .mutation(AddLineMutation(variantId = variantId, quantity = quantity))
        .execute()

    response.exception?.let { throw it }
    return response.data?.addLine?.toDomain() ?: throw ApiException(response.errors)
}

Optimistic update lấp khoảng trống trước khi server trả lời. Bật bằng enableOptimisticUpdates = true lúc cấu hình cache (mặc định tắt để khỏi tốn bộ nhớ theo dõi), rồi gọi .optimisticUpdates(data) trên mutation với instance Data sinh ra, dựng từ đúng selection. Dữ liệu đó ghi vào cache và watcher chạy ngay; khi response về, cache ghi đè bằng kết quả thật, còn nếu request fail thì entry optimistic bị gỡ. Chỉ dùng cho thao tác dự đoán được kết quả — số lượng, toggle, thứ tự — đừng đoán id do server sinh.

Subscription qua WebSocket

Subscription là query sống dài, kết quả trả về Flow chứ không phải một response. Cấu hình transport như trên rồi collect trong scope có lifecycle:

fun cartUpdates(): Flow<CartLine> = apollo
    .subscription(CartUpdatedSubscription())
    .toFlow()
    .mapNotNull { it.data?.cartUpdated?.toDomain() }

Chọn đúng subprotocol: mặc định của Apollo vẫn là SubscriptionWsProtocol (subscriptions-transport-ws, không còn được bảo trì). Nếu server dùng graphql-ws, truyền GraphQLWsProtocol() như trên; sai protocol thì socket vẫn mở nhưng không có message nào. Huỷ collection là huỷ subscription — đừng collect trong scope sống lâu hơn màn hình.

Repository hoàn chỉnh

Gom query, mutation và subscription vào một chỗ, map sang domain model để kiểu sinh ra không lọt lên UI:

// File: data/CatalogRepository.kt
class CatalogRepository(
    private val apollo: ApolloClient,
    private val logger: Logger,
) {
    suspend fun products(first: Int = 20): Result<List<Product>> = runCatching {
        val response = apollo
            .query(ProductsQuery(first = first))
            .fetchPolicy(FetchPolicy.CacheFirst)
            .execute()
        response.exception?.let { throw it }
        val data = response.data ?: throw ApiException(response.errors)
        if (!response.errors.isNullOrEmpty()) logger.w("GraphQL partial: ${response.errors.map { it.message }}")
        data.products.map { it.toDomain() }
    }

    suspend fun addLine(variantId: String, quantity: Int): Result<CartLine> = runCatching {
        val response = apollo
            .mutation(AddLineMutation(variantId = variantId, quantity = quantity))
            .execute()
        response.exception?.let { throw it }
        response.data?.addLine?.toDomain() ?: throw ApiException(response.errors)
    }

    fun cartUpdates(): Flow<CartLine> = apollo
        .subscription(CartUpdatedSubscription())
        .toFlow()
        .mapNotNull { it.data?.cartUpdated?.toDomain() }

    suspend fun clearOnLogout() = withContext(Dispatchers.IO) {
        apollo.apolloStore.clearAll()
    }
}

ViewModel chỉ cần viewModelScope.launch { repo.products().fold(...) }; chi tiết scope xem ở bài lập trình bất đồng bộ. Result gói cả fetch lẫn GraphQL error thành một đường thất bại, còn partial errors vẫn log riêng.

Bảy bẫy thường gặp

  • N+1 query. Lặp danh sách id rồi gọi query(ProductQuery(id)) trong forEach biến một màn hình thành hai mươi round trip. Sửa bằng một query nhận danh sách id, hoặc nhiều alias trong cùng document. Query batching giảm số HTTP request nhưng không sửa được thiết kế sai.
  • Cache key không unique. Không khai báo @typePolicy thì key là đường dẫn field; cùng một object xuất hiện ở hai query thành hai entry và watcher không báo nhau. Khai báo key field ổn định, ghép nhiều field nếu một field không đủ unique.
  • Bỏ qua partial errors. Chỉ kiểm tra data != null là bỏ qua errors; UI hiện dữ liệu thiếu mà không ai biết. Log errors kèm path, và có trạng thái UI cho field lỗi.
  • Query quá lớn. Query trải bốn màn hình với hàng trăm field làm payload phình và cache ghi nhiều. Chia theo màn hình, phân trang bằng biến, dùng fragment.
  • Không dùng persisted query. Mỗi request gửi nguyên document vài KB; server parse lại từ đầu. Bật Automatic Persisted Queries phía client và server để giảm payload và chặn query tùy ý.
  • Để introspection mở trên production. Lộ toàn bộ schema kể cả field nội bộ. Tắt trên prod, tải schema lúc build bằng token, và đừng đóng gói apollo-debug-server vào release.
  • Chặn main thread. execute() đã chạy trên IO, nhưng runBlocking trong init hay composable, clearAll() trên main, hoặc map/sort nặng sau khi có data vẫn làm khựng frame. Đưa transform sang Dispatchers.Default.

Checklist

  • Đặt schema.graphqls và toàn bộ .graphql trong src/main/graphql/, commit schema vào Git, tải lại qua introspection có token.
  • Khai báo @typePolicy(keyFields: "id") cho mọi type có id ổn định; kiểm tra cache id sau lần query đầu.
  • Bật enableOptimisticUpdates chỉ khi đã có mutation cần phản hồi tức thì.
  • Mặc định CacheFirst, chỉ đặt NetworkOnly ở nơi thật cần.
  • Xử lý đủ ba nhánh exception / errors / data trong mọi repository call.
  • Chọn GraphQLWsProtocol khớp server và huỷ collection khi màn hình dừng.

Nhìn về 2027

Normalized cache tách repo riêng đã có phân trang, expiration, garbage collection và partial reads, nên các bản 5.x tiếp theo sẽ bổ sung ở tầng cache nhiều hơn runtime. apollo-compiler vẫn experimental; Kotlin 2.5.0 dự kiến ra mắt tháng 12/2026. App mới nên lên 5.x từ đầu.

Bài trước và bài tiếp theo

Nền tảng mạng REST nằm ở Retrofit và OkHttp; cách bọc client vào tầng dữ liệu ở Repository, Factory và Builder. Toàn bộ thứ tự học nằm trong lộ trình lập trình viên Android.