Apollo Kotlin 中如何优雅地传递额外请求变量

在 GraphQL 开发中，我们经常需要在请求中传递额外的变量参数。本文将深入探讨在 Apollo Kotlin 客户端中实现这一需求的几种技术方案。

标准变量传递方式

Apollo Kotlin 通过代码生成机制为每个 GraphQL 操作生成对应的模型类。以示例中的 GetBestSellers 操作为例，我们可以直接通过构造函数传递定义好的变量：

val operation = GetBestSellers(ProductCategory.BOOKS)

这种方式会按照 GraphQL 规范自动序列化变量，并包含在请求的 variables 字段中。

需要传递额外变量的场景

某些情况下，开发者可能需要传递未在 GraphQL 操作中声明的额外变量，例如：

1. 应用标识信息
2. 设备元数据
3. 跟踪参数
4. 其他业务上下文信息

这些变量通常用于服务端的日志记录、监控或业务逻辑处理。

技术实现方案

方案一：自定义 HttpRequestComposer

Apollo Kotlin 提供了 HttpRequestComposer 接口，允许开发者完全控制 HTTP 请求的构建过程。我们可以实现自定义的请求构建器来添加额外变量：

class CustomHttpRequestComposer(private val serverUrl: String) : HttpRequestComposer {
    override fun <D : Operation.Data> compose(apolloRequest: ApolloRequest<D>): HttpRequest {
        val operation = apolloRequest.operation
        val customScalarAdapters = apolloRequest.executionContext[CustomScalarAdapters]!!
        
        val body = buildJsonByteString {
            writeObject {
                name("query").value(operation.document())
                name("operationName").value(operation.name())
                name("variables").writeObject {
                    // 序列化原始变量
                    operation.serializeVariables(this, customScalarAdapters, false)
                    // 添加额外变量
                    name("appName").value("MyAppName")
                    name("clientVersion").value("1.0.0")
                }
            }
        }
        
        return HttpRequest.Builder(HttpMethod.Post, serverUrl)
            .body(object : HttpBody {
                override val contentType = "application/json"
                override val contentLength = body.size.toLong()
                override fun writeTo(bufferedSink: BufferedSink) {
                    bufferedSink.write(body)
                }
            })
            .build()
    }
}

方案二：使用 OkHttp 拦截器

对于简单的变量添加需求，可以使用 OkHttp 拦截器来修改请求体：

class VariablesInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val originalRequest = chain.request()
        val originalBody = originalRequest.body?.source()?.readByteString()
        
        val modifiedBody = originalBody?.let { 
            val json = Json.parseToJsonElement(it.utf8())
            val newJson = buildJsonObject {
                putAll(json.jsonObject)
                put("variables", buildJsonObject {
                    json.jsonObject["variables"]?.jsonObject?.let { putAll(it) }
                    put("appName", "MyAppName")
                })
            }
            newJson.toString().toByteString()
        }
        
        val newRequest = originalRequest.newBuilder()
            .post(modifiedBody?.toRequestBody(originalRequest.body?.contentType()))
            .build()
        
        return chain.proceed(newRequest)
    }
}

最佳实践建议

虽然技术上可以实现额外变量的传递，但需要注意以下几点：

1. 遵循 GraphQL 规范：GraphQL 变量机制设计用于操作参数，而非通用数据传输
2. 优先使用 HTTP 头：对于元数据信息，更适合放在 HTTP 头中
3. 考虑服务端兼容性：确保服务端能够正确处理这些额外变量
4. 性能考量：修改请求体会带来额外的序列化开销

总结

在 Apollo Kotlin 中传递额外请求变量可以通过自定义 HttpRequestComposer 或拦截器实现，但开发者应当评估这种做法的必要性。在大多数情况下，使用 HTTP 头传递额外信息是更符合 RESTful 原则的做法。如果确实需要修改请求体，自定义 HttpRequestComposer 提供了更直接和高效的解决方案。