GraphQL Kotlin 项目中 APQ 功能在 Spring Server 中的实现问题分析

背景介绍

GraphQL Kotlin 是一个用于构建 GraphQL 服务的 Kotlin 库，它提供了对自动持久化查询(APQ)的支持。APQ 是 GraphQL 的一项优化技术，允许客户端发送查询的哈希值而不是完整的查询字符串，从而减少网络传输数据量。

问题现象

在 Spring Server 实现中，当启用 APQ 功能时，系统无法正确处理初始的 GET 请求。具体表现为：

1. 首次发送不带查询参数的 GET 请求时，服务器返回 400 错误
2. 即使后续发送带有查询参数的请求后，缓存机制也无法正常工作
3. 自动持久化查询提供者(AutomaticPersistedQueriesProvider)未被触发执行

技术分析

问题的根源在于 SpringGraphQLRequestParser 的实现存在以下缺陷：

1. GET 请求处理不完整：当前实现未能正确处理仅包含扩展信息(extensions)而不含查询(query)的 GET 请求
2. 扩展字段映射缺失：标准类中未映射 extensions 字段，导致后续查询解析出现问题
3. 错误处理不恰当：当遇到持久化查询未找到的情况时，未能返回预期的 PersistedQueryNotFound 错误

解决方案

通过分析问题，可以采取以下改进措施：

1. 扩展请求解析逻辑：修改 SpringGraphQLRequestParser 以支持仅含扩展信息的 GET 请求
2. 完善字段映射：确保 extensions 字段能够被正确解析和映射
3. 优化错误响应：在持久化查询未命中时返回标准化的错误信息

实现示例

以下是改进后的请求解析器实现核心逻辑：

@Component
class CustomSpringGraphQLRequestParser(
    private val objectMapper: ObjectMapper
) : SpringGraphQLRequestParser(objectMapper) {

    private val mapTypeReference: MapType = 
        TypeFactory.defaultInstance().constructMapType(HashMap::class.java, String::class.java, Any::class.java)

    override suspend fun parseRequest(request: ServerRequest): GraphQLServerRequest? {
        if (request.method() == HttpMethod.GET && 
            request.queryParam("extensions").isPresent && 
            request.queryParam("extensions").get().contains("persistedQuery")
        ) {
            return getRequestFromGet(request)
        }
        return super.parseRequest(request)
    }

    private fun getRequestFromGet(serverRequest: ServerRequest): GraphQLServerRequest {
        val query = serverRequest.queryParam("query").orElse("")
        val operationName: String? = serverRequest.queryParam("operationName").orElseGet { null }
        val variables: String? = serverRequest.queryParam("variables").orElseGet { null }
        val graphQLVariables: Map<String, Any>? = variables?.let {
            objectMapper.readValue(it, mapTypeReference)
        }
        val extensions: Map<String, Any>? = serverRequest.queryParam("extensions").takeIf { it.isPresent }?.get()?.let {
            objectMapper.readValue(it, mapTypeReference)
        }

        return GraphQLRequest(
            query = query,
            operationName = operationName,
            variables = graphQLVariables,
            extensions = extensions
        )
    }
}

技术影响

此问题的修复将带来以下改进：

1. 完整的 APQ 支持：使 Spring Server 能够正确处理自动持久化查询流程
2. 性能优化：减少网络传输数据量，提高查询效率
3. 标准化实现：与其他 GraphQL 实现保持行为一致性

总结

GraphQL Kotlin 项目中 Spring Server 的 APQ 功能实现存在缺陷，主要问题集中在请求解析阶段。通过扩展请求解析器功能并完善字段映射，可以解决这一问题，使 APQ 功能正常工作。这一改进不仅修复了功能缺陷，还提升了系统的标准化程度和性能表现。