spacetimedb-reducers

将此技能用于 Reducer 实现和事务型服务端逻辑。

Reducer 核心模式

Reducer 是修改表数据的事务入口。Reducer 成功执行时会提交所有表变更；若抛出异常、返回错误或发生 panic，则所有变更都会回滚。

TypeScript Reducer 结构：

export const create_user = spacetimedb.reducer(
  { name: t.string(), email: t.string() },
  (ctx, { name, email }) => {
    if (name === "") throw new Error("Name cannot be empty");
    ctx.db.user.insert({ id: 0n, name, email });
  },
);

各语言的签名：

• TypeScript：spacetimedb.reducer(args, (ctx, args) => { ... })；无参数时使用 spacetimedb.reducer((ctx) => { ... })。
• C#：[SpacetimeDB.Reducer] public static void Name(ReducerContext ctx, ...)。
• Rust：#[spacetimedb::reducer] pub fn name(ctx: &ReducerContext, ...) -> Result<(), String>；表方法需导入 spacetimedb::Table。
• 生命周期 Reducer 使用各语言语法中的 init、client_connected 和 client_disconnected 变体。

表访问

• 通过生成的表句柄插入行；自增字段使用触发值（0、0n 等）。
• 通过主键或唯一索引查找一行：TypeScript ctx.db.user.id.find(id)，C# ctx.Db.User.Id.Find(id)，Rust ctx.db.user().id().find(id)。
• 通过索引列筛选多行。除非已知表很小，否则应避免在热路径上使用完整的 iter() 扫描。
• 先查找行并修改，然后通过同一主键索引调用更新方法。
• 尽可能通过主键、唯一值或索引筛选条件删除数据。
• 在 SpacetimeDB 2.0 中，TypeScript/C# 使用 ctx.sender，Rust/C++ 使用 ctx.sender() 获取调用方身份。

事务指导

• 保持 Reducer 简短且具有确定性；将外部 I/O 移至过程。
• 嵌套的 Reducer 调用共享同一事务，不会单独提交。
• 若语言支持，则针对预期的验证失败向调用方返回错误；将 panic 或未检查异常留给程序错误。
• 定时 Reducer 从调度表行触发，可能没有客户端发送者。

参考索引

需求	打开
Reducer 基础与表访问	references/functions-reducers.md
生命周期 Reducer	references/functions-reducers-lifecycle.md
Reducer 上下文	references/functions-reducers-reducer-context.md
错误处理	references/functions-reducers-error-handling.md
函数类别	references/functions.md

指南

• 将 Reducer 视为事务：使副作用和错误行为符合参考语义。
• 根据项目的 SpacetimeDB 版本使用 ctx.sender/ctx.sender()；对于从 1.0 迁移到 2.0 的项目，请加载 spacetimedb-upgrade。
• 将架构问题交由 spacetimedb-tables 处理。