JavaScript：GraphQL Live Query（实时查询）

生态项目与库

项目简介

GraphQL Live Query 是由 n1ru4l 开发的开源库，旨在为任意 GraphQL Schema 或数据传输层提供“实时查询”能力。它允许客户端通过普通的 GraphQL 查询操作获得实时更新，而无需显式定义或使用 GraphQL Subscription。

项目地址：https://github.com/n1ru4l/graphql-live-query
npm 包名：@n1ru4l/graphql-live-query

核心特性

• 与传输无关：无论底层使用 HTTP、WebSocket 还是其他传输方式，都可以实现实时数据推送。
• 兼容任意 GraphQL Schema：无需修改现有 Schema，只需引入库并在查询中声明实时标记。
• 使用简单：通过 @live 指令即可将普通查询升级为实时查询。
• 灵活集成：可作为 GraphQL 执行流程中的中间件或工具函数使用，支持自定义数据源变更通知。

安装

使用 npm 安装：

npm install @n1ru4l/graphql-live-query

或使用 yarn：

yarn add @n1ru4l/graphql-live-query

基本用法

在 GraphQL 查询中添加 @live 指令，表示该查询需要实时更新：

query PostLiveQuery($id: ID!) @live {
  post(id: $id) {
    id
    title
    content
  }
}

服务端使用 graphql-live-query 处理该指令。库会跟踪查询依赖的数据，并在相关数据发生变化时重新执行查询，将最新结果推送给客户端。

以下是一个简单的服务端集成示意：

import { execute } from 'graphql';
import { createLiveQueryStore } from '@n1ru4l/graphql-live-query';

const liveQueryStore = createLiveQueryStore({
  execute,
  // 可选：配置数据源变更监听
});

// 在 GraphQL 执行流程中使用 liveQueryStore，例如处理 @live 指令
const result = await liveQueryStore.execute({
  schema,
  document: queryDocument,
  variableValues: variables,
  contextValue: context,
});

当数据源发生变化时，调用对应的方法通知 liveQueryStore，即可触发实时查询更新。

工作原理简述

GraphQL Live Query 的核心思想是将查询转换为可观察的流：

1. 服务端解析查询中的 @live 指令。
2. 根据查询中涉及的数据资源建立依赖关系。
3. 当底层数据发生变化时，自动重新执行查询。
4. 将新旧数据对比，仅推送发生变更的部分（可选）。
5. 客户端保持查询订阅，持续接收实时数据。

这种方式使得实时功能可以复用现有 GraphQL 查询逻辑，而无需为每个实时场景单独编写 Subscription 解析器。

相关资源

• GitHub 仓库
• npm 包页面

该库特别适合需要快速为现有 GraphQL API 增加实时能力的场景，尤其推荐给希望降低实时功能复杂度的团队。