GraphQL-Request 项目中 Upload 扩展导致请求错误的分析与解决

在 GraphQL 客户端库 graphql-request 的使用过程中，开发者发现当启用 Upload 扩展时，即使是不包含文件上传的普通 GraphQL 请求也会出现执行错误。本文将深入分析这一问题的成因，并探讨其解决方案。

问题现象

当开发者使用 Upload 扩展时，向 GraphQL 服务器发送的请求会收到如下错误响应：

{
    "errors": [
        {
            "message": "The request did not contain a valid GraphQL request...",
            "extensions": {
                "stellate": {
                    "code": "INVALID_QUERY",
                    "details": {}
                }
            }
        }
    ]
}

值得注意的是，当不使用 Upload 扩展时，服务器返回的 Content-Type 头为 application/graphql-response+json; charset=utf-8，而启用扩展后则变为 application/json。

问题根源

经过代码审查发现，问题出在 Upload 扩展的实现逻辑上。当前实现中，Upload 扩展会无条件地清空请求的 Content-Type 头，而实际上这一操作应该仅在请求包含文件上传时执行。

具体来说，在 Upload 扩展的代码中，存在以下关键逻辑：

// 当前实现：无条件清空Content-Type
requestInit.headers = {
    ...requestInit.headers,
    'content-type': undefined
}

这种处理方式导致了所有请求（无论是否包含上传）的 Content-Type 头都被移除，进而影响了服务器的请求处理逻辑。

解决方案

正确的实现应该是仅在检测到请求中包含文件上传时，才清空 Content-Type 头。这是因为：

1. 对于普通 GraphQL 请求，保持标准的 application/json 或 application/graphql-response+json Content-Type 是必要的
2. 只有包含文件上传的多部分表单请求才需要特殊的 Content-Type 处理

修改后的逻辑应该类似于：

// 改进实现：仅在包含上传时清空Content-Type
if (containsUploads(variables)) {
    requestInit.headers = {
        ...requestInit.headers,
        'content-type': undefined
    }
}

技术背景

理解这一问题的关键在于了解 GraphQL 文件上传的规范实现：

1. 标准 GraphQL 请求：使用 JSON 格式，Content-Type 通常为 application/json
2. 文件上传请求：需要使用 multipart/form-data 格式，此时浏览器会自动设置合适的 Content-Type 边界值
3. GraphQL 响应：服务器可能使用 application/graphql-response+json 来表示符合 GraphQL 响应规范的 JSON 数据

Upload 扩展的设计初衷是为了简化文件上传的实现，但当前的实现过于激进地处理了 Content-Type，导致了兼容性问题。

影响范围

这一问题会影响所有同时满足以下条件的场景：

1. 使用了 graphql-request 的 Upload 扩展
2. 应用中混合了普通 GraphQL 请求和文件上传请求
3. 服务器端对 Content-Type 有严格校验

特别是使用某些 GraphQL 网关或托管服务（如 Stellate）时，这一问题更容易显现，因为这些服务往往对请求格式有更严格的验证。

最佳实践

在使用 Upload 扩展时，开发者应注意：

1. 检查扩展的版本，确保使用的是修复后的版本
2. 如果必须使用旧版本，可以考虑条件性地启用扩展
3. 对于复杂的应用，考虑将文件上传功能分离到专门的 API 端点
4. 始终测试混合请求场景下的行为

总结

GraphQL 客户端库中的功能扩展需要谨慎处理请求头等关键元数据。Upload 扩展的这一问题提醒我们，即使是看似简单的功能增强，也可能因为边界条件处理不当而产生意想不到的副作用。通过条件性地处理 Content-Type 头，可以确保扩展功能既满足文件上传需求，又不干扰普通 GraphQL 请求的正常工作。