Apollo Kotlin 从 v2 到 v3 的 Token 刷新机制迁移指南

背景概述

在 GraphQL 客户端开发中，身份验证和 Token 刷新是常见的需求。Apollo Kotlin 从 v2 升级到 v3 后，拦截器机制发生了重大变化，这给开发者带来了迁移挑战。本文将深入解析如何将 v2 版本的 Token 刷新机制平滑迁移到 v3。

v2 与 v3 拦截器机制对比

v2 拦截器特点

v2 版本采用回调式拦截器：

• 基于 ApolloInterceptor 接口实现
• 通过 interceptAsync 方法处理请求
• 使用 CallBack 回调通知结果
• 支持同步/异步处理
• 需要手动管理重试计数器和状态

v3 拦截器革新

v3 版本引入了更现代的响应式编程模型：

• 基于 Kotlin Flow 实现
• 使用 intercept 方法返回 Flow
• 内置响应式操作符支持
• 简化了异步处理逻辑
• 自动处理背压和取消

迁移方案详解

核心迁移步骤

1. 转换回调为挂起函数 将原有的回调式 Token 刷新函数改造为挂起函数，这是适配 Flow 的基础：

suspend fun refreshTokenSuspend() = suspendCoroutine { continuation ->
    refreshToken { result ->
        continuation.resume(result)
    }
}

2. 重构拦截器逻辑 使用 Flow 操作符重构核心逻辑：

class ApolloRequestInterceptor : ApolloInterceptor {
    private val maxRetryCount = 1
    private val mutex = Mutex()

    override fun <D : Operation.Data> intercept(
        request: ApolloRequest<D>,
        chain: ApolloInterceptorChain
    ): Flow<ApolloResponse<D>> {
        return chain.proceed(request)
            .onEach { response ->
                if (!isAuthorized(response)) {
                    val result = mutex.withLock {
                        refreshTokenSuspend()
                    }
                    if (!result) throw RefreshFailedException()
                }
            }
            .retryWhen { cause, attempt ->
                cause is RefreshFailedException && attempt < maxRetryCount
            }
    }
}

3. 授权状态检查 保持原有的响应解析逻辑，但适配新的响应类型：

private fun isAuthorized(response: ApolloResponse<*>): Boolean {
    return response.errors?.none { error ->
        error.extensions?.get("code") in setOf("AUTH_NOT_AUTHORIZED", "AUTH_NOT_AUTHENTICATED")
    } ?: true
}

关键注意事项

1. 线程安全

   • 使用 Mutex 保证 Token 刷新操作的原子性
   • 避免并发刷新导致的竞态条件

2. 错误处理

   • 区分可重试错误和不可重试错误
   • 合理设置最大重试次数

3. 性能考量

   • 避免不必要的 Token 刷新
   • 考虑添加 Token 有效性缓存

4. 拦截器顺序

   • 确保该拦截器在拦截器链的最后位置
   • 这样能获取到完整的解析后响应

高级优化建议

1. 结合 OkHttp 拦截器 虽然本文方案可以解析响应体，但对于纯 HTTP 层面的认证问题，建议：

   • 使用 OkHttp 拦截器处理 HTTP 401 错误
   • 两者结合实现完整的认证方案

2. 响应缓存控制 在重试请求时禁用缓存：

   chain.proceed(request.newBuilder().fetchFromCache(false).build())
   

3. 状态管理

   • 考虑使用 SharedFlow 广播 Token 状态变化
   • 其他组件可以监听并做出相应反应

总结

Apollo Kotlin v3 的响应式拦截器机制虽然需要一定的学习成本，但提供了更强大和灵活的处理能力。通过本文的迁移方案，开发者可以保留原有业务逻辑的核心价值，同时享受 v3 版本带来的现代编程范式优势。关键是要理解 Flow 的操作符特性，并合理设计错误处理流程，这样就能构建出健壮的认证刷新机制。

对于复杂的业务场景，建议结合 OkHttp 拦截器和 Apollo 拦截器各自的优势，构建分层的认证处理体系，既能处理 HTTP 层面的认证问题，也能应对 GraphQL 特有的业务错误。