Apollo Kotlin 详解：Kotlin 多平台 GraphQL 客户端
后端上了 GraphQL，Android/Kotlin 端要一个既类型安全又能跨平台的客户端——apollographql/apollo-kotlin（Apollo Kotlin）是行业事实答案：Apollo 官方维护的 GraphQL 客户端，运行于 Android 与全部 Kotlin 多平台目标，以代码生成实现从服务端到 App 的 100% 类型安全，内置内存与 SQLite 两级缓存，生产环境服务着全球数百万用户的 App。MIT 协议、公开 Roadmap、三位专职维护者。本文从核心能力、代码生成、缓存机制到上手配置，完整拆解。
1、项目概述
Apollo Kotlin 自我定位为 The industry-leading GraphQL client for Kotlin：覆盖 Android 与所有 Kotlin 多平台目标（JVM、iOS、JS、Native），从 GraphQL schema 与查询文档生成强类型 Kotlin 代码，配合缓存与开发工具构成完整客户端方案。它属于 Apollo 全家桶的客户端分支——同族还有 React/iOS 客户端、Apollo Router、GraphOS 平台等。
基本形态与生态：
- 发布：Maven Central 正式版 + Snapshots + Apollo Previews 三条通道
- 协议为 MIT；专职维护者 Benoit Lubek、Jeff Auriemma、Martin Bonnin
- 工具链：IntelliJ 插件（Apollo GraphQL）、公开 Roadmap、Develocity 构建
- 社区：Kotlin Slack #apollo-kotlin 频道 + Apollo Discourse 论坛
- 教学资源：官方免费课程（Android 教程）与完整文档站
2、四大核心能力
Apollo Kotlin 的卖点可以归成四根支柱，覆盖客户端开发的关键诉求。
四根支柱：
- 100% 类型安全：代码生成贯穿服务端到 App，编译期拦截查询错误
- 智能缓存：内存或 SQLite 缓存开箱即用，规范化存储自动合并
- 现代平台支持：Android 与 KMP 全目标，紧跟 Kotlin / Gradle 新版本
- GraphOS 就绪：Persisted Queries、@defer 指令开箱支持
能力要点：
1. 生产验证充分：全球无数百万级 DAU 应用在用
2. 始终跟进最新 GraphQL、Kotlin、Gradle 版本
3. 官方免费课程 + IntelliJ 插件降低上手门槛
3、代码生成：类型安全的来源
Apollo Kotlin 的工作方式是：把 .graphql 查询文件交给 Gradle 插件，编译期生成对应的 Kotlin 模型与请求类，字段拼错直接编译不过。
// src/main/graphql/queries/GetLaunch.graphql
query GetLaunch($id: ID!) {
launch(id: $id) {
id
site
mission { name missionSize }
rocket { name type }
}
}
// 生成的代码大致形态（示意）
class GetLaunchQuery(id: String) : Query<GetLaunchQuery.Data> {
data class Launch(
val id: String,
val site: String?,
val mission: Mission?,
val rocket: Rocket?
)
}生成要点：
1. 查询、变更、订阅各自生成独立类，参数即构造器入参
2. 可空性与 schema 完全对齐，非空字段不再判空
3. 支持自定义标量映射到 Kotlin 类型
4. 生成代码可配置目标包名、单文件 / 多文件模式
4、缓存机制
GraphQL 的响应是对象图，Apollo 用规范化缓存按对象 ID 分块存储，多查询间自动拼接复用。
// 内存缓存（默认）
val client = ApolloClient.Builder()
.serverUrl("https://api.example.com/graphql")
.build()
// SQLite 持久化缓存（KMP 各平台实现）
val apolloStore = ApolloStore(
normalizedCacheFactory = SqlNormalizedCacheFactory("launches.db")
)
val client = ApolloClient.Builder()
.serverUrl("https://api.example.com/graphql")
.store(apolloStore)
.build()
// 读取时指定缓存策略
val response = client.query(GetLaunchQuery(id = "42"))
.fetchPolicy(FetchPolicy.CacheFirst) // 先缓存后网络
.execute()缓存要点：
1. FetchPolicy 可选 CacheFirst / NetworkFirst / CacheOnly / NetworkOnly
2. 对象规范化：同一对象多处返回只存一份，改一处全更新
3. mutation 后可用 watch 自动推送缓存变更到 UI
4. 内存缓存够小项目用，SQLite 适合大数据量离线场景
5、快速上手：Gradle 配置
引入 Gradle 插件与运行时依赖，即可开始写 .graphql 文件。
// 根项目 build.gradle.kts
plugins {
id("com.apollographql.apollo") version "4.2.0" apply false
}
// 模块 build.gradle.kts
plugins {
id("com.apollographql.apollo")
kotlin("multiplatform")
}
dependencies {
implementation("com.apollographql.apollo:apollo-runtime:4.2.0")
}
apollo {
service("api") {
packageName.set("com.example.graphql")
// schema 与 .graphql 文件默认在 src/<sourceSet>/graphql
}
}上手要点：
1. 版本以 Maven Central 徽章最新为准，示例 4.2.0 为 KDoc 链接所示
2. 初学者走官方 Android 教程，一步步带做完整 App
3. IntelliJ 插件提供语法高亮与 schema 浏览
4. API 详情查 KDoc，Roadmap 上看进行中的特性
6、典型应用场景
Apollo Kotlin 的主战场是"GraphQL 后端 + 多端客户端"的团队。
常见场景：
- Android App：查询、变更、订阅全流程，缓存驱动的响应式 UI
- iOS + Android 共享：KMP 模式一份网络层两端复用
- 离线优先应用：SQLite 规范化缓存 + CacheFirst 策略
- GraphOS 生态团队：Persisted Queries 减负、@defer 渐进加载
- 服务端驱动 UI：订阅监听数据变更实时刷新
使用提醒：
1. 需要 schema 文件：找后端要 SDL 或用 introspection 拉取
2. 缓存键策略要与服务端 ID 规范对齐，否则规范化失效
3. REST 为主的团队入坑前先评估收益，GraphQL 才是主场
7、定位对比：Kotlin GraphQL 方案三选一
把 Apollo Kotlin、手动 HTTP + kotlinx.serialization 与 Ktor 客户端放 在一张桌上，各自的位置清晰起来。
三者对比：
- Apollo Kotlin：代码生成类型安全 + 规范化缓存 + KMP 全平台，官方全家桶
- 手动 HTTP + kxser：无代码生成，类型靠手写模型，灵活但重复劳动
- Ktor 客户端：通用 HTTP 层，配 GraphQL 序列化插件可用，缓存自建
选型建议：
1. 正经 GraphQL 项目，要缓存与类型安全 → Apollo Kotlin
2. 只有一两个简单查询、不想引插件 → Ktor + 手写模型
3. KMP 共享网络层 → Apollo Kotlin（原生支持全部目标）
4. 组合玩法：Apollo 管 GraphQL，Ktor 管其余 REST 接口
8、总结
Apollo Kotlin 是行业领先的 Kotlin GraphQL 客户端（MIT 协议）：代码生成带来端到端类型安全，内存 / SQLite 双缓存规范化存储，覆盖 Android 与全部 Kotlin 多平台目标；GraphOS 特性（Persisted Queries、@defer）开箱即用，IntelliJ 插件、免费课程、KDoc 与公开 Roadmap 构成完整工具链。由 Benoit Lubek、Jeff Auriemma、Martin Bonnin 三位维护者持续演进，全球海量生产 App 验证。
实践要点：按官方 Android 教程起步，先跑通一个查询再上缓存；KMP 项目把 Apollo 放 commonMain，一份网络层多端共享；缓存键与后端对象 ID 规范对齐后再启用 watch，UI 才能稳定联动。使用前提是有 GraphQL schema 文件，REST 为主的团队收益有限。
