Apollo Kotlin 4.1.0版本中HTTP错误响应的异常处理变更解析

在Apollo Kotlin 4.1.0版本中，开发者可能会注意到一个重要的行为变更：当HTTP请求失败时（例如返回401状态码），响应对象中不再包含异常信息。这一变化源于对GraphQL over HTTP规范中application/graphql-response+json媒体类型的支持。

变更背景 在4.0.1版本中，当HTTP请求失败时，ApolloResponse会包含一个ApolloHttpException，开发者可以直接从响应中获取异常信息。而在4.1.0版本中，响应对象可能既没有数据(data)也没有错误(errors)，这给错误处理带来了新的挑战。

技术原理 这一变更实际上是对GraphQL over HTTP规范的更好支持。根据规范，GraphQL服务应该使用application/graphql-response+json媒体类型来返回响应，其中包含了标准化的错误处理机制。当服务端采用这种响应格式时，所有错误信息都应该通过GraphQL errors字段传递，而不是依赖HTTP状态码。

解决方案 对于需要恢复旧有行为的开发者，可以通过以下方式实现：

1. 使用ApolloInterceptor拦截请求：

.addInterceptor(object : ApolloInterceptor {
    override fun <D : Operation.Data> intercept(
        request: ApolloRequest<D>,
        chain: ApolloInterceptorChain,
    ): Flow<ApolloResponse<D>> {
        return chain.proceed(request).onEach {
            val httpInfo = it.executionContext[HttpInfo]
            if (httpInfo != null && httpInfo.statusCode !in 200..299) {
                throw ApolloHttpException(httpInfo.statusCode, httpInfo.headers, null, "HTTP请求失败")
            }
        }
    }
})

2. 更推荐的做法是让服务端在GraphQL errors中包含详细的错误信息：

{
  "errors": [
    {
      "message": "授权失败",
      "extensions": {
        "code": 401
      }
    }
  ]
}

最佳实践 建议开发者逐步过渡到使用GraphQL层的错误处理机制，而不是依赖HTTP状态码。这种方式具有以下优势：

• 错误信息更加结构化
• 可以包含多个错误
• 支持自定义错误代码和元数据
• 符合GraphQL规范

对于暂时无法修改服务端实现的场景，可以使用上述拦截器方案作为过渡方案。

总结 Apollo Kotlin 4.1.0的这一变更虽然带来了短期的适配成本，但从长远来看推动了对GraphQL规范更好的支持。开发者应当根据自身项目情况选择合适的适配方案，并考虑推动服务端实现更规范的GraphQL错误响应机制。