终极入门：graphql-subscriptions快速上手，5分钟实现你的第一个实时订阅

【免费下载链接】graphql-subscriptions :newspaper: A small module that implements GraphQL subscriptions for Node.js 项目地址: https://gitcode.com/gh_mirrors/gr/graphql-subscriptions

graphql-subscriptions是一个轻量级Node.js模块，专为实现GraphQL实时订阅功能设计。它能帮助开发者轻松构建基于发布/订阅模式的实时数据更新系统，让你的GraphQL API具备推送更新能力，为应用添加即时通讯、实时通知等动态功能。

🚀 准备工作：安装与环境配置

首先确保你的项目中已安装Node.js环境，然后通过npm或yarn快速安装graphql-subscriptions及其依赖：

npm install graphql-subscriptions graphql
# 或使用yarn
yarn add graphql-subscriptions graphql

如果你使用TypeScript开发，还需要安装类型定义文件：

npm install @types/graphql --save-dev

并确保tsconfig.json中包含以下配置：

{
  "lib": ["esnext.asynciterable"]
}

🔤 定义订阅类型：扩展GraphQL Schema

要使用订阅功能，首先需要在GraphQL模式中定义Subscription类型。打开你的schema文件，添加以下定义：

type Subscription {
  somethingChanged: Result
}

type Result {
  id: String
  message: String
}

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

这段代码声明了一个名为somethingChanged的订阅字段，它将返回Result类型的数据，包含id和message两个属性。

🔄 创建发布订阅系统：PubSub核心实例

graphql-subscriptions提供了简单的发布订阅实现。创建一个新的文件（例如pubsub.js），初始化PubSub实例：

import { PubSub } from 'graphql-subscriptions';

// 创建PubSub实例
export const pubsub = new PubSub();

// 定义事件主题常量
export const SOMETHING_CHANGED_TOPIC = 'something_changed';

这个实例基于Node.js的EventEmitter实现，用于管理事件的发布和订阅。注意：默认实现仅适用于开发环境，生产环境建议使用Redis等分布式PubSub实现。

🔗 实现订阅解析器：连接事件与订阅

接下来需要实现订阅解析器，将GraphQL订阅字段与PubSub系统连接起来。在你的解析器文件中添加：

import { pubsub, SOMETHING_CHANGED_TOPIC } from './pubsub';

export const resolvers = {
  Subscription: {
    somethingChanged: {
      // 订阅解析器返回一个异步迭代器
      subscribe: () => pubsub.asyncIterator(SOMETHING_CHANGED_TOPIC),
    },
  },
};

订阅解析器与查询和变更不同，它返回的是一个AsyncIterator对象，而非直接返回数据。当有新事件发布到指定主题时，这个迭代器会将数据推送给订阅者。

📤 发布事件：触发实时更新

现在你可以在任何需要的地方发布事件，触发实时更新。例如，在某个变更解析器中添加：

import { pubsub, SOMETHING_CHANGED_TOPIC } from './pubsub';

// 在变更解析器中发布事件
const mutationResolvers = {
  createSomething: (_, { input }) => {
    // 处理创建逻辑...
    
    // 发布事件
    pubsub.publish(SOMETHING_CHANGED_TOPIC, {
      somethingChanged: {
        id: '1',
        message: '新内容已创建'
      }
    });
    
    return newItem;
  }
};

当createSomething变更被调用时，会向所有订阅somethingChanged的客户端推送更新数据。

🔍 添加过滤器：精准推送订阅数据

在实际应用中，你可能需要根据特定条件筛选订阅数据。graphql-subscriptions提供了withFilter工具函数来实现这一功能：

import { withFilter } from 'graphql-subscriptions';

export const resolvers = {
  Subscription: {
    somethingChanged: {
      subscribe: withFilter(
        () => pubsub.asyncIterator(SOMETHING_CHANGED_TOPIC),
        (payload, variables) => {
          // 只推送与用户相关的数据
          return payload.somethingChanged.id === variables.userId;
        }
      ),
    },
  },
};

这个过滤器会检查每个发布的事件，只有当条件满足时才会推送给订阅者，大大提高了订阅的精准性和效率。

🔗 连接传输层：使用订阅客户端

graphql-subscriptions本身只处理订阅逻辑，还需要一个网络传输层来处理WebSocket连接。推荐使用subscriptions-transport-ws：

npm install subscriptions-transport-ws

然后配置WebSocket服务器：

import { createServer } from 'http';
import { SubscriptionServer } from 'subscriptions-transport-ws';
import { execute, subscribe } from 'graphql';
import { schema } from './schema';

const server = createServer(app);

// 设置WebSocket服务器
SubscriptionServer.create(
  { schema, execute, subscribe },
  { server, path: '/subscriptions' }
);

客户端可以使用Apollo Client等GraphQL客户端库连接到这个WebSocket端点，接收实时更新。

📝 完整示例代码结构

一个典型的graphql-subscriptions项目结构如下：

src/
├── schema/
│   └── schema.graphql    # 包含Subscription类型定义
├── resolvers/
│   ├── subscription.js   # 订阅解析器
│   └── mutation.js       # 包含发布事件的变更解析器
├── pubsub.js             # PubSub实例和主题定义
└── server.js             # 服务器配置，包含WebSocket设置

通过这个简单的结构，你可以快速搭建起完整的GraphQL订阅系统。

🚀 生产环境注意事项

默认的PubSub实现基于内存EventEmitter，仅适用于开发环境。在生产环境中，你需要使用分布式PubSub实现，例如：

• Redis: graphql-redis-subscriptions
• Kafka: graphql-kafka-subscriptions
• Postgres: graphql-postgres-subscriptions

这些实现允许你在多服务器环境中使用订阅功能，确保消息能够正确地在不同实例之间传递。

💡 快速入门总结

通过graphql-subscriptions实现实时订阅只需四个简单步骤：

1. 定义订阅类型 - 在GraphQL Schema中添加Subscription类型
2. 创建PubSub实例 - 初始化发布订阅系统
3. 实现订阅解析器 - 将订阅字段与PubSub主题关联
4. 发布事件 - 在适当的时机触发实时更新

这个轻量级模块让GraphQL订阅变得简单直观，为你的应用添加实时功能从未如此轻松。无论是构建实时聊天应用、实时仪表板还是协作工具，graphql-subscriptions都能提供坚实的基础。

现在，你已经掌握了graphql-subscriptions的核心用法，快去为你的应用添加实时功能吧！

【免费下载链接】graphql-subscriptions :newspaper: A small module that implements GraphQL subscriptions for Node.js 项目地址: https://gitcode.com/gh_mirrors/gr/graphql-subscriptions