GraphQL-WS v6.0.0 重大更新解析：WebSocket 订阅协议的全新升级

GraphQL-WS 是一个专门为 GraphQL 订阅功能设计的 WebSocket 协议实现库，它提供了服务端和客户端的完整解决方案。该库通过 WebSocket 连接实现了 GraphQL 的实时数据推送能力，是构建实时应用的理想选择。最新发布的 v6.0.0 版本带来了多项重大改进和优化，下面我们将详细解析这些变化。

核心架构改进

本次升级对库的整体架构进行了优化，最显著的变化是移除了 /lib/ 路径的导入方式，使导入路径更加简洁。例如，原来的 graphql-ws/lib/use/ws 现在简化为 graphql-ws/use/ws。这种改进不仅减少了代码量，也使 API 更加直观。

依赖关系调整

v6.0.0 对依赖关系进行了重大调整：

1. 移除了对 ws v7 的支持，现在仅支持 v8 版本
2. 弃用了 fastify-websocket 的支持，推荐使用 @fastify/websocket
3. 将最低支持的 Node.js 版本提升至 v20
4. 将 graphql 的最低支持版本设置为 ^15.10.1 和 ^16

这些调整确保了库能够利用最新运行时环境的特性和性能优化。

API 重大变更

上下文对象重构

在 @fastify/websocket 集成中，WebSocket 对象在上下文中的引用从 ctx.extra.connection 更名为 ctx.extra.socket，这一变更使命名更加符合语义。

钩子函数简化

所有钩子函数（如 schema、context、onSubscribe 等）不再接收完整的消息对象，而是只接收相关的部分数据。这种设计减少了不必要的序列化操作，提高了性能。例如：

// 旧版
onSubscribe(ctx, message) {
  const id = message.id;
  const payload = message.payload;
}

// 新版
onSubscribe(ctx, id, payload) {
  // 直接使用 id 和 payload
}

错误处理增强

现在，订阅迭代器中抛出的错误会被自动捕获，并通过 ErrorMessage 进行报告，而不是直接终止整个 WebSocket 连接。这一改进使得错误处理更加优雅，符合 GraphQL 规范的最新建议。

客户端优化

客户端现在实现了真正的零依赖，即使在非浏览器环境中使用客户端功能，也不再需要 graphql 作为对等依赖。可以通过 graphql-ws/client 路径导入纯客户端功能：

import { createClient } from 'graphql-ws/client';

废弃功能移除

v6.0.0 移除了多个已弃用的 API：

1. 移除了 isMessage，推荐使用 validateMessage 替代
2. 移除了 isFatalConnectionProblem，推荐使用 shouldRetry 替代

这些变更使 API 更加一致和清晰。

类型系统改进

对类型系统进行了多项优化：

1. ErrorMessage 现在使用 GraphQLFormattedError 类型
2. NextMessage 现在使用 FormattedExecutionResult 类型
3. 各钩子函数的参数类型更加精确

这些改进提供了更好的类型安全性和开发体验。

总结

GraphQL-WS v6.0.0 是一个重大的版本更新，带来了架构上的多项改进和优化。通过简化 API、增强错误处理、优化类型系统等改进，这个版本为开发者提供了更强大、更稳定的 WebSocket GraphQL 订阅实现。对于现有项目，虽然需要一定的迁移工作，但这些变更将为应用带来更好的性能和更清晰的代码结构。