在客户端构建高性能响应式数据存储与乐观更新时使用…

适用于需要客户端优先、实时查询、乐观变更且与 TanStack Query 集成的 React 应用。

适用场景

解决思路

1. 运行 `npm install @tanstack/react-db @tanstack/query-db-collection` 安装依赖。
2. 使用 `createCollection` 和 `queryCollectionOptions` 创建集合，提供 `queryKey`、`queryFn`、`getKey`、`schema`，并实现 `onInsert`、`onUpdate`、`onDelete` 处理函数以同步服务器。
3. 根据数据量选择同步模式：`eager`（默认，适合 <10k 行）、`on-demand`（适合 >50k 行或搜索场景）、`progressive`（适合协作场景），在 `queryCollectionOptions` 中设置 `syncMode`。
4. 使用 `useLiveQuery` 订阅实时查询，例如 `query.from({ todos: todoCollection }).where(({ todos }) => eq(todos.completed, false))`。
5. 使用查询构建器 API：`.from()`、`.where()`、`.orderBy()`、`.limit()` 来构建查询。
6. 使用 `.innerJoin()` 连接多个集合，例如将 todo、user、project 集合连接。
7. 从 `@tanstack/db` 导入过滤操作符（如 `eq`、`lt`、`and`），并在 `where` 中使用它们。
8. 执行乐观变更：直接调用 `collection.insert(...)`，无需手动 `onMutate` 或 `onError` 回滚，系统自动更新所有相关 live queries 并在失败时回滚。
9. 对于 on-demand 同步，在 `queryFn` 中使用 `parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)` 解析 `filters`、`sorts`、`limit`，并映射为 API 参数（如 `URLSearchParams`），然后请求 API。
10. 在模块级别定义 collections（单例），不要在组件内创建。
11. 使用 joins 而不是视图特定 API，一次加载规范化集合。
12. 让 TanStack Query 处理数据获取，TanStack DB 作为其增强层，不要试图完全替代 Query。
13. 使用 `parseLoadSubsetOptions` 将实时查询谓词映射到 API 参数。
14. 依赖自动乐观更新，不要手动管理乐观状态。
15. 使用 schemas 进行运行时验证和 TypeScript 类型推断。
16. 利用增量计算，让引擎处理过滤，而不是在渲染中手动 `.filter()`。
17. 为集合提供 `getKey` 以进行正确的规范化。
18. 不要忘记为服务器同步提供 mutation handlers（`onInsert`、`onUpdate`、`onDelete`）。

适用边界 · 注意事项

• 不要试图用 TanStack DB 完全替代 TanStack Query，DB 构建在 Query 之上。
• 不要在组件内部创建 collections，应在模块级别创建。
• 不要手动使用 `.filter()` 在渲染中过滤，应使用 live query 的 `where` 子句。