Apollo Kotlin中处理GraphQL认证错误的实践指南

背景介绍

在使用Apollo Kotlin客户端与GraphQL服务器交互时，开发者经常会遇到一个特殊场景：服务器总是返回HTTP 200状态码，即使请求中包含认证错误(如JWT过期)，这些错误信息被封装在GraphQL响应体中。这种设计虽然符合GraphQL规范，但给客户端处理认证失败带来了挑战。

问题分析

传统HTTP应用中，认证失败通常通过401状态码表示，客户端可以据此触发重新认证流程。但在GraphQL中，所有响应都返回200状态码，错误信息通过响应体的errors字段传递。这种差异导致开发者需要寻找替代方案来处理认证失效情况。

解决方案

方案一：使用ApolloInterceptor实现GraphQL层重试

ApolloInterceptor可以在GraphQL操作层面拦截和处理响应。当检测到认证错误时，可以触发重试机制：

.addInterceptor(object : ApolloInterceptor {
    override fun <D : Operation.Data> intercept(
        request: ApolloRequest<D>,
        chain: ApolloInterceptorChain
    ): Flow<ApolloResponse<D>> {
        return chain.proceed(request)
            .onEach { response ->
                if (response.errors?.any { it.message.contains("JWTExpired") } == true) {
                    throw RetryException()
                }
            }
            .retryWhen { cause, attempt ->
                cause is RetryException && attempt < MAX_RETRIES
            }
    }
})

方案二：结合HttpInterceptor更新认证令牌

对于常规HTTP请求，可以结合HttpInterceptor实现令牌自动更新：

.addInterceptor(object : HttpInterceptor {
    @Volatile
    private var token: String = initialToken

    override suspend fun intercept(
        request: HttpRequest,
        chain: HttpInterceptorChain
    ): HttpResponse {
        val response = chain.proceed(
            request.newBuilder()
                .addHeader("Authorization", token)
                .build()
        )
        
        if (response.statusCode == 401) {
            token = refreshToken()
            return chain.proceed(
                request.newBuilder()
                    .addHeader("Authorization", token)
                    .build()
            )
        }
        return response
    }
})

WebSocket连接的特殊处理

订阅(Subscription)操作通过WebSocket进行，其认证处理与常规HTTP请求不同：

1. WebSocket连接建立时的认证头需要在初始化时设置
2. 后续消息不再携带HTTP头信息
3. 认证错误同样通过GraphQL响应体返回

最新版本的Apollo Kotlin已支持在WebSocket连接中动态更新请求头，开发者可以通过设置request.httpHeaders来传递认证信息。

最佳实践建议

1. 统一错误处理：在应用层封装统一的错误处理逻辑，避免分散在各处
2. 重试策略：为认证错误实现指数退避重试机制，避免频繁请求
3. 令牌管理：实现集中式的令牌管理，确保所有网络请求使用最新令牌
4. 用户反馈：在令牌刷新期间提供适当的用户界面反馈

总结

处理GraphQL中的认证错误需要开发者理解其与传统REST API的区别。通过合理使用Apollo Kotlin提供的拦截器机制，可以实现健壮的认证错误处理和自动恢复流程。对于订阅操作，需要注意WebSocket连接的特殊性，并确保使用支持动态更新请求头的客户端版本。