concepts

SpacetimeDB 核心概念

SpacetimeDB 是一种关系型数据库，同时也是一台服务。它允许你将应用逻辑作为模块直接上传到数据库，从而完全消除传统的 Web／游戏服务层。Rust、C# 和 C++ 模块会编译为 WebAssembly，而 TypeScript 模块则运行在 V8 上。

---

关键规则

1. Reducer 是事务性的。 它们不会向调用方返回数据。请使用订阅来读取数据。
2. Reducer 必须是确定性的。 请勿在 reducer 中使用文件系统、网络、外部时钟或外部随机源。请使用 reducer 上下文（ctx）获取 SpacetimeDB 提供的时间戳和确定性随机值。
3. 通过表／订阅读取数据，而非使用 reducer 的返回值。客户端通过已订阅的查询获取数据。
4. 自动递增 ID 并非连续编号。 出现间隔是正常的，不要用它们排序。请使用时间戳或显式序列列。
5. ctx.sender 是经过身份验证的主体。 切勿信任作为参数传入的身份。

---

功能实现检查清单

1. 后端： 定义用于存储数据的表
2. 后端： 定义用于修改数据的 reducer
3. 客户端： 订阅这些表
4. 客户端： 从 UI 调用这些 reducer
5. 客户端： 渲染表中的数据

---

调试检查清单

1. SpacetimeDB 服务是否正在运行？（spacetime start）
2. 模块是否已发布？（spacetime publish）
3. 是否已生成客户端绑定？（spacetime generate）
4. 检查服务日志中的错误（spacetime logs <db-name>）
5. 客户端是否实际调用了 reducer？

---

表

• 私有表（默认）：只有 reducer 和数据库所有者可以访问。
• 公开表：可通过订阅向客户端开放读取权限。写入仍需要通过 reducer。

请根据访问模式而非实体来组织数据：

Player          PlayerState         PlayerStats
id         <--  player_id           player_id
name            position_x          total_kills
                position_y          total_deaths
                velocity_x          play_time

Reducer

Reducer 是用于修改数据库状态的事务性函数。它们以原子方式运行，不能与外部世界交互，也不会向调用方返回数据。有关语法，请参阅特定语言的服务技能。

事件表

事件表会向客户端广播特定于 reducer 的数据。行不会存储在客户端缓存中（count() 返回 0，iter() 不产生任何内容）；只有 onInsert 回调会触发。

订阅

订阅会实时将数据库行同步到客户端。

1. 订阅： 注册用于描述所需数据的 SQL 查询
2. 接收初始数据： 立即发送所有匹配的行
3. 接收更新： 已订阅的行发生变化时实时接收更新
4. 响应变化： 使用回调（onInsert、onDelete、onUpdate）

最佳实践：

• 按生命周期对订阅分组
• 更新订阅时，先订阅再取消订阅
• 避免查询重叠
• 使用索引提升查询效率

模块

模块包含在数据库内部运行的应用逻辑。

• 表： 定义数据架构
• Reducer： 定义可调用的状态修改函数
• 事件表： 向客户端广播特定于 reducer 的数据
• 视图： 向客户端公开计算所得数据子集的只读函数
• 过程：（不稳定）可产生副作用的函数（HTTP 请求、ctx.withTx）

服务端模块可以使用以下语言编写：Rust、C#、TypeScript、C++

生命周期：编写 → 编译 → 发布（spacetime publish）→ 热切换（重新发布，客户端无需断开连接）

身份

• Identity： 用户长期有效且全局唯一的标识符。
• ConnectionId： 标识特定的客户端连接。
• 授权时始终使用 ctx.sender / ctx.Sender / ctx.sender()。

SpacetimeDB 支持多种 OIDC 提供商，包括 SpacetimeAuth（内置）、Auth0、Clerk、Keycloak、Google 和 GitHub。