批处理指南 | TanStack Pacer Docs

批处理是一种强大的技术，用于将多个操作组合在一起并将其作为一个单元进行处理。与确保每个操作都单独处理的队列不同，批处理收集项目并按可配置的组进行处理，从而提高效率并减少开销。本指南介绍了 TanStack Pacer 的批处理概念。

批处理概念

批处理会随时间收集项目，或者直到达到一定大小为止，然后一次性处理所有项目。这非常适合批量处理项目比逐个处理更有效的情况。批处理可以通过以下方式触发：

达到最大批处理大小
等待最大时间量
自定义��辑（例如，特殊项目或条件）

批处理可视化

text

批处理 (每 3 个项目或每 2 秒处理一次)
时间轴: [每个滴答 1 秒]
调用:        ⬇️  ⬇️  ⬇️     ⬇️  ⬇️     ⬇️  ⬇️  ⬇️
批处理:       [ABC]   []      [DE]      []      [FGH]  []
已执行:     ✅             ✅         ✅
             [===============================]
             ^ 项目被分组并一起处理

             [项目累积]   [处理批处理]   [清空]
                在批处理中           作为组         批处理

批处理 (每 3 个项目或每 2 秒处理一次)
时间轴: [每个滴答 1 秒]
调用:        ⬇️  ⬇️  ⬇️     ⬇️  ⬇️     ⬇️  ⬇️  ⬇️
批处理:       [ABC]   []      [DE]      []      [FGH]  []
已执行:     ✅             ✅         ✅
             [===============================]
             ^ 项目被分组并一起处理

             [项目累积]   [处理批处理]   [清空]
                在批处理中           作为组         批处理

何时使用批处理

批处理在以下情况下效果最佳：

分组处理项目更有效（例如，网络请求、数据库写入）
你想减少昂贵操作的频率
你需要控制处理的速率或大小
你想将突发活动防抖为更少的操作

何时不使用批处理

批处理在以下情况下可能不理想：

每个项目都必须立即单独处理（使用队列）
你只关心最新的值（使用防抖）

Tip

如果你发现自己正在进行可以分组的重复调用，批处理可以帮助你优化性能和资源使用。

TanStack Pacer 中的批处理

TanStack Pacer 通过 Batcher 类和简单的 batch 函数提供批处理功能。两者都允许你收集项目并按可配置的批次进行处理。

batch 的基本用法

batch 函数提供了一种创建批处理函数的简单方法：

import { batch } from '@tanstack/pacer'

// 创建一个最多处理 3 个项目或每 2 秒处理一次的批处理器
const processBatch = batch<number>(
  (items) => {
    // 处理批处理
    console.log('正在处理批处理：', items)
  },
  {
    maxSize: 3, // 收集到 3 个项目时处理
    wait: 2000, // 或者 2 秒后，以先到者为准
    onItemsChange: (batcher) => {
      console.log('当前批处理：', batcher.peekAllItems())
    }
  }
)

// 添加要批处理的项目
processBatch(1)
processBatch(2)
processBatch(3) // 触发批处理
processBatch(4)
// 或者等待 2 秒以处理下一个批处理

import { batch } from '@tanstack/pacer'

// 创建一个最多处理 3 个项目或每 2 秒处理一次的批处理器
const processBatch = batch<number>(
  (items) => {
    // 处理批处理
    console.log('正在处理批处理：', items)
  },
  {
    maxSize: 3, // 收集到 3 个项目时处理
    wait: 2000, // 或者 2 秒后，以先到者为准
    onItemsChange: (batcher) => {
      console.log('当前批处理：', batcher.peekAllItems())
    }
  }
)

// 添加要批处理的项目
processBatch(1)
processBatch(2)
processBatch(3) // 触���批处理
processBatch(4)
// 或者等待 2 秒以处理下一个批处理

batch 函数返回一个将项目添加到批处理的函数。批处理会根据你的配置自动处理。

Batcher 类的高级用法

Batcher 类提供了对批处理行为的完全控制：

import { Batcher } from '@tanstack/pacer'

// 创建一个最多处理 5 个项目或每 3 秒处理一次的批处理器
const batcher = new Batcher<number>(
  (items) => {
    // 处理批处理
    console.log('正在处理批处理：', items)
  },
  {
    maxSize: 5, // 收集到 5 个项目时处理
    wait: 3000, // 或者 3 秒后
    getShouldExecute: (items, batcher) => items.includes(42), // 自定义触发器
    onItemsChange: (batcher) => {
      console.log('当前批处理：', batcher.peekAllItems())
    }
  }
)

// 将项目添加到批处理
batcher.addItem(1)
batcher.addItem(2)
batcher.addItem(3)
// ...

// 手动处理当前批处理
batcher.execute()

// 控制批处理
batcher.stop()  // 暂停批处理
batcher.start() // 恢复批处理

import { Batcher } from '@tanstack/pacer'

// 创建一个最多处理 5 个项目或每 3 秒处理一次的批处理器
const batcher = new Batcher<number>(
  (items) => {
    // 处理批处理
    console.log('正在处理批处理：', items)
  },
  {
    maxSize: 5, // 收集到 5 个项目时处理
    wait: 3000, // 或者 3 秒后
    getShouldExecute: (items, batcher) => items.includes(42), // 自定义触发器
    onItemsChange: (batcher) => {
      console.log('当前批处理：', batcher.peekAllItems())
    }
  }
)

// 将项目添加到批处理
batcher.addItem(1)
batcher.addItem(2)
batcher.addItem(3)
// ...

// 手动处理当前批处理
batcher.execute()

// 控制批处理
batcher.stop()  // 暂停批处理
batcher.start() // 恢复批处理

Batcher 选项

Batcher 选项允许你自定义批处理的处理方式和时间：

maxSize：每个批处理的最大项目数（默认值：Infinity）
wait：处理批处理前等待的最长时间（毫秒）（默认值：Infinity）
getShouldExecute：用于确定是否应处理批处理的自定义函数
onExecute：处理批处理后的回调
onItemsChange：添加项目或处理批处理后的回调
onIsRunningChange：批处理器运行状态更改时的回调
started：批处理器是否立即开始运行（默认值：true）

Batcher 方法

Batcher 类提供了几种用于批处理管理的方法：

batcher.addItem(item)           // 将项目添加到批处理
batcher.execute()               // 手动处理当前批处理
batcher.stop()                  // 暂停批处理
batcher.start()                 // 恢复批处理
batcher.getSize()               // 获取当前批处理大小
batcher.getIsEmpty()            // 检查批处理是否为空
batcher.getIsRunning()          // 检查批处理器是否正在运行
batcher.peekAllItems()           // 获取当前批处理中的所有项目
batcher.getBatchExecutionCount()// 已处理的批处理数
batcher.getItemExecutionCount() // 已处理的项目数
batcher.setOptions(opts)        // 更新批处理器选项
batcher.getOptions()            // 获取当前选项

batcher.addItem(item)           // 将项目添加到批处理
batcher.execute()               // 手动处理当前批处理
batcher.stop()                  // 暂停批处理
batcher.start()                 // 恢复批处理
batcher.getSize()               // 获取当前批处理大小
batcher.getIsEmpty()            // 检查批处理是否为空
batcher.getIsRunning()          // 检查批处理器是否正在运行
batcher.peekAllItems()           // 获取当前批处理中的所有项目
batcher.getBatchExecutionCount()// 已处理的批处理数
batcher.getItemExecutionCount() // 已处理的项目数
batcher.setOptions(opts)        // 更新批处理器选项
batcher.getOptions()            // 获取当前选项

自定义批处理触发器

你可以使用 getShouldExecute 根据自定义逻辑触发批处理：

const batcher = new Batcher<number>(
  (items) => console.log('正在处理批处理：', items),
  {
    getShouldExecute: (items) => items.includes(99),
  }
)

batcher.addItem(1)
batcher.addItem(99) // 立即触发批处理

const batcher = new Batcher<number>(
  (items) => console.log('正在处理批处理：', items),
  {
    getShouldExecute: (items) => items.includes(99),
  }
)

batcher.addItem(1)
batcher.addItem(99) // 立即触发批处理

动态配置

你可以在运行时更新批处理器选项：

batcher.setOptions({
  maxSize: 10,
  wait: 1000,
})

const options = batcher.getOptions()
console.log(options.maxSize) // 10

batcher.setOptions({
  maxSize: 10,
  wait: 1000,
})

const options = batcher.getOptions()
console.log(options.maxSize) // 10

性能监控

Batcher 提供了监控其性能的方法：

console.log(batcher.getBatchExecutionCount()) // 已处理的批处理数
console.log(batcher.getItemExecutionCount())  // 已处理的项目数

console.log(batcher.getBatchExecutionCount()) // 已处理的批处理数
console.log(batcher.getItemExecutionCount())  // 已处理的项目数

框架适配器

每个框架适配器都围绕批处理器类构建了方便的钩子和函数。诸如 useBatcher 或 createBatcher 之类的钩子是小型包装器，可以减少某些常见用例中你自己代码所需的样板代码。