Apollo Kotlin WASM 跨域请求认证问题解析与解决方案

问题背景

在使用 Apollo Kotlin 进行多平台 GraphQL 开发时，开发者可能会遇到一个特殊场景：在 WASM (WebAssembly) 平台上添加 HTTP 拦截器进行请求认证时，会出现 CORS (跨域资源共享) 问题，而同样的代码在 Android、iOS 和桌面平台上却能正常工作。

现象分析

当在 WASM 环境中执行带有 Authorization 头的 GraphQL 查询或变更请求时，浏览器会先发送一个 OPTIONS 预检请求(preflight request)，而不是直接发送 POST 请求。如果服务器未正确配置 CORS 响应头，浏览器会阻止后续请求，并报错：

Access to fetch at 'http://localhost:8080/graphql' from origin 'http://localhost:8081' has been blocked by CORS policy

技术原理

跨域安全机制

浏览器出于安全考虑，实施了同源策略(Same-Origin Policy)。当 Web 应用尝试从不同源(协议、域名或端口不同)获取资源时，浏览器会强制执行 CORS 检查。

预检请求机制

当请求满足以下任一条件时，浏览器会自动发起预检请求：

1. 使用了 GET、HEAD、POST 以外的 HTTP 方法
2. 设置了自定义头部(如 Authorization)
3. Content-Type 不是 application/x-www-form-urlencoded、multipart/form-data 或 text/plain

WASM 特殊性

WASM 运行在浏览器环境中，因此受到浏览器安全限制，而原生平台(Android/iOS/桌面)不受此限制，这就是为什么问题仅出现在 WASM 平台。

解决方案

客户端代码优化

在 Apollo Kotlin 客户端中，确保正确配置 HTTP 拦截器：

ApolloClient.Builder()
    .serverUrl("http://localhost:8080/graphql")
    .addHttpInterceptor(authInterceptor)
    .httpHeaders(
        listOf(
            HttpHeader("Accept", "application/json"),
            HttpHeader("Content-Type", "application/json"),
        )
    )
    .build()

认证拦截器实现示例：

class AuthorizationInterceptor(
    private val keyValueStorage: KeyValueStorage
) : HttpInterceptor {
    private val mutex = Mutex()

    override suspend fun intercept(
        request: HttpRequest,
        chain: HttpInterceptorChain
    ): HttpResponse {
        var token = mutex.withLock { keyValueStorage.token }
        val response = chain.proceed(request)

        return if (response.statusCode == 401) {
            token = mutex.withLock { keyValueStorage.token }
            chain.proceed(
                request.newBuilder()
                    .addHeader("Authorization", "Bearer $token")
                    .build()
            )
        } else {
            response
        }
    }
}

服务端配置关键

对于 Ktor 服务器，必须正确配置 CORS 插件：

install(CORS) {
    allowMethod(HttpMethod.Options)
    allowMethod(HttpMethod.Get)
    allowMethod(HttpMethod.Post)
    allowMethod(HttpMethod.Put)
    allowMethod(HttpMethod.Delete)
    allowHeader(HttpHeaders.Authorization)
    allowHeader(HttpHeaders.ContentType)
    allowCredentials = true
    anyHost()
}

关键配置项说明：

1. allowMethod: 允许的 HTTP 方法，必须包含 OPTIONS
2. allowHeader: 允许的自定义头部，必须包含 Authorization
3. allowCredentials: 允许携带凭据(cookie、HTTP认证等)
4. anyHost(): 允许所有源，生产环境应替换为具体域名

最佳实践建议

1. 环境区分：在代码中区分 WASM 和其他平台，针对不同环境采用不同配置
2. 安全配置：生产环境应避免使用 anyHost()，改为明确指定允许的源
3. 测试验证：使用浏览器开发者工具监控网络请求，确保预检请求返回 200 状态码
4. 错误处理：在客户端添加 CORS 错误的具体处理逻辑，提供友好提示

总结

Apollo Kotlin 在多平台开发中表现优异，但 WASM 平台由于运行在浏览器环境，需要特别注意 CORS 相关配置。通过正确配置服务端 CORS 策略和优化客户端请求处理，可以完美解决跨域认证问题，实现全平台一致的开发体验。