TanStack Query 中的流式查询(streamedQuery)详解

TanStack Query 中的流式查询(streamedQuery)详解

query 🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query. 项目地址: https://gitcode.com/gh_mirrors/qu/query

什么是流式查询

在 TanStack Query 中，streamedQuery 是一个实验性功能，它允许开发者创建能够处理流式数据的查询函数。这种查询特别适合处理来自 AsyncIterable 的数据流，比如服务器推送(Server-Sent Events)、WebSocket 或分块传输的数据。

核心概念

流式查询与传统查询的主要区别在于：

1. 数据接收方式：传统查询一次性获取所有数据，而流式查询可以分批次接收数据
2. 状态管理：流式查询在收到第一个数据块后会进入 success 状态，但仍保持 fetching 状态直到流结束
3. 数据存储：所有接收到的数据块会被存储在数组中

基本用法

import { experimental_streamedQuery as streamedQuery } from '@tanstack/react-query'

const query = queryOptions({
  queryKey: ['data'],
  queryFn: streamedQuery({
    queryFn: fetchDataInChunks,
  }),
})

配置选项详解

必需选项

• queryFn：返回 AsyncIterable 数据流的函数
  • 接收一个 QueryFunctionContext 参数
  • 必须返回 Promise<AsyncIterable >

可选选项

• refetchMode：定义重新获取数据时的行为

  • 'reset'（默认）：清除所有数据并回到 pending 状态
  • 'append'：将新数据追加到现有数据之后
  • 'replace'：流结束后将所有数据写入缓存

• maxChunks：缓存中保留的最大数据块数

  • 默认无限制
  • 设置后会保留最新的 N 个数据块，移除最旧的数据块

实际应用场景

流式查询特别适合以下场景：

1. 实时聊天应用：持续接收新消息
2. 股票行情展示：实时更新价格数据
3. 大文件下载进度：分块显示下载进度
4. 日志流监控：实时显示服务器日志

状态管理细节

流式查询的状态变化有其特殊性：

1. 初始状态：查询开始时处于 pending 状态
2. 首次数据接收：收到第一个数据块后转为 success 状态
3. 持续接收：保持 fetching 状态直到流结束
4. 错误处理：如果流中出现错误，查询会转为 error 状态

性能考虑

使用流式查询时需要注意：

1. 内存管理：大量数据块可能占用较多内存，合理设置 maxChunks
2. 渲染性能：频繁更新可能导致组件多次渲染，考虑使用防抖或节流
3. 网络开销：长时间保持连接可能增加服务器负担

实验性状态说明

目前 streamedQuery 仍处于实验阶段，这意味着：

1. API 可能在后续版本中发生变化
2. 社区反馈将影响最终实现
3. 生产环境使用需谨慎评估

最佳实践建议

1. 对于简单的流式需求，可以先尝试传统查询配合轮询
2. 复杂场景再考虑使用流式查询
3. 明确设置数据更新策略（append/reset/replace）
4. 合理设置最大数据块数避免内存泄漏
5. 考虑添加错误边界处理流中断情况

流式查询为 TanStack Query 带来了处理实时数据的能力，开发者现在可以更优雅地实现各种实时应用场景。随着该功能的成熟，它将成为处理流式数据的首选方案。

query 🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query. 项目地址: https://gitcode.com/gh_mirrors/qu/query