用途:在已配置的 collection 上执行写入,并以乐观更新的方式先改本地状态、再由 mutationFn 持久化,最后等待同步确认。依赖 db-core/collection-setup。
主要能力:collection.insert 支持单条、批量、metadata 与 { optimistic: false };collection.update 使用 Immer 风格 draft 代理,传入回调修改 draft,支持单条或批量 id;collection.delete 支持单条、批量与 metadata。三者都返回 Transaction,可用 tx.when('settled') 等待结算或捕获回滚错误。
核心模式:createOptimisticAction 用于基于意图的变更或跨多个 collection 的原子修改,onMutate 必须同步(返回 Promise 抛 OnMutateMustBeSynchronousError),mutationFn 中应等待服务端状态同步再返回,例如 await postCollection.utils.refetch()。createPacedMutations 用于自动保存,配合 debounceStrategy({ wait: 500 })、throttleStrategy({ wait: 200, leading: true, trailing: true }) 或 queueStrategy({ wait: 0, maxSize: 100 }) 合并或按序持久化。createTransaction({ autoCommit: false }) 用于手动批处理,在 tx.mutate(() => {}) 同步作用域内,collection 操作自动加入环境事务;await 之后的操作不再加入。
限制与常见错误:无 onInsert/onUpdate/onDelete 处理器或环境事务时抛 MissingInsertHandlerError 等;不要在 mutationFn 内触发预加载或 loadSubset(),会造成同步提交等待死锁;update 不能重设主键,否则 KeyUpdateNotAllowedError;插入重复键抛 DuplicateKeyError;提交或回滚后再调 mutate() 抛 TransactionNotPendingMutateError;Query Collection 处理器内不要手动 refetch,因为它会在处理器完成后自动 refetch 并等待;用直接写入工具时可返回 { refetch: false } 跳过。乐观更新存在客户端与服务端状态分歧窗口,失败回滚可能丢弃用户以为已保存的内容,建议显示保存中状态、破坏性操作用 { optimistic: false }、服务端接口保持幂等,并处理 settled 拒绝。部分 API 细节与类型请参考官方事务 API 文档。