Apollo Kotlin 中 WebSocket 订阅与持久化查询的兼容性问题解析

问题背景

在将项目从 Apollo2 迁移到 Apollo3 的过程中，开发团队遇到了一个关于 WebSocket 订阅与持久化查询（Persisted Queries）兼容性的问题。当使用 WebSocketNetworkTransport 进行订阅操作时，系统会抛出 IllegalArgumentException: Flow has more than one element 异常。

问题现象

开发团队在构建 ApolloClient 时启用了自动持久化查询功能（autoPersistedQueries），同时配置了 WebSocket 订阅传输。当执行订阅操作并尝试收集数据流时，系统会抛出上述异常。经过测试发现，如果禁用 autoPersistedQueries，则异常不再出现。

技术分析

异常根源

该异常表明在数据流处理过程中，系统预期只接收单个元素，但实际上收到了多个元素。这通常发生在以下情况：

1. 持久化查询机制尝试将查询转换为哈希值发送给服务器
2. WebSocket 订阅传输层未能正确处理这种转换
3. 数据流中出现了预期外的额外元素

历史背景

在 Apollo2 中，虽然提供了 enableAutoPersistedSubscriptions 选项，但实际上从未真正支持过持久化查询与订阅的结合使用。该选项在底层是被静默禁用的。Apollo3 在设计时移除了这个单独的开关，导致开发者在迁移时遇到了兼容性问题。

解决方案

临时解决方案

对于当前需要继续使用 WebSocket 订阅的项目，可以在执行订阅操作时显式禁用自动持久化查询：

client.subscription(subscription)
    .enableAutoPersistedQueries(false)
    .toFlow()

长期解决方案

Apollo 团队已经针对 HTTP 多部分订阅协议（multipart HTTP subscriptions）与持久化查询的兼容性问题提供了修复。但对于传统的 WebSocket 实现，由于协议实现的多样性，兼容性可能仍然存在问题。

技术建议

1. 评估实际需求：大多数 GraphQL 服务器并不支持 WebSocket 订阅与持久化查询的结合使用，且这种组合的实际收益有限（如无法利用 CDN 缓存）

2. 考虑协议升级：建议逐步迁移到 HTTP 多部分订阅协议，该协议对持久化查询有更好的支持

3. 服务器兼容性：如需使用此功能，应确认后端服务器是否真正支持 WebSocket 订阅与持久化查询的组合

总结

Apollo Kotlin 3.8.5 版本中存在 WebSocket 订阅与持久化查询的兼容性问题。开发者可以通过临时禁用订阅的持久化查询功能来解决当前问题。对于长期解决方案，建议评估实际需求并考虑升级到更现代的订阅协议。Apollo 团队已针对 HTTP 多部分订阅协议提供了修复，但传统 WebSocket 实现的兼容性仍需根据具体后端实现进行评估。