spacetimedb-best-practices

SpacetimeDB 最佳实践

SpacetimeDB 应用的综合开发指南，涵盖 TypeScript 服务端模块以及与 React 的客户端 SDK 集成。指南分为 8 个类别，按影响程度排序，为自动重构和代码生成提供参考。

Package： spacetimedb（v1.4.0+）

适用场景

在以下情况下，请参考这些指南：

• 使用 TypeScript 编写 SpacetimeDB 服务端模块
• 设计表架构和索引
• 实现用于状态变更的 reducer
• 设置客户端订阅和查询
• 将 SpacetimeDB 集成到 React 应用中
• 优化实时同步性能

按优先级划分的规则类别

优先级	类别	影响	前缀
1	模块设计	严重	module-
2	表架构与索引	严重	table-
3	Reducer 模式	高	reducer-
4	订阅优化	高	subscription-
5	客户端状态管理	中高	client-
6	React 集成	中	react-
7	TypeScript 模式	中	ts-
8	实时同步	中低	sync-

快速参考

服务端模块 API（TypeScript）

import { spacetimedb, table, t, ReducerContext } from 'spacetimedb';

// Define tables with the table builder
const Player = table(
  { name: 'player', public: true },
  {
    identity: t.identity().primaryKey(),
    name: t.string(),
    score: t.u64().index(),
    isOnline: t.bool().index(),
  }
);

// Define reducers
spacetimedb.reducer('create_player', { name: t.string() }, (ctx: ReducerContext, { name }) => {
  ctx.db.player.insert({
    identity: ctx.sender,
    name,
    score: 0n,
    isOnline: true,
  });
});

// Lifecycle hooks
spacetimedb.init((ctx: ReducerContext) => { /* module init */ });
spacetimedb.clientConnected((ctx: ReducerContext) => { /* client connected */ });
spacetimedb.clientDisconnected((ctx: ReducerContext) => { /* client disconnected */ });

客户端 SDK API（TypeScript）

import { DbConnection } from './generated';

// Build connection
const conn = DbConnection.builder()
  .withUri('ws://localhost:3000')
  .withModuleName('my-module')
  .onConnect((ctx, identity, token) => {
    // Setup subscriptions
    conn.subscription(['SELECT * FROM player WHERE isOnline = true']);
  })
  .onDisconnect((ctx, error) => { /* handle disconnect */ })
  .build();

// Call reducers
await conn.reducers.createPlayer('Alice');

// Access tables
const player = conn.db.player.identity.find(identity);

React 集成

import { useTable, where, eq } from 'spacetimedb/react';
import { DbConnection, Player } from './generated';

function OnlinePlayers() {
  const { rows: players } = useTable<DbConnection, Player>(
    'player',
    where(eq('isOnline', true))
  );

  return players.map(p => <div key={p.identity.toHexString()}>{p.name}</div>);
}

规则类别

1. 模块设计（严重）

• module-single-responsibility - 每个领域概念使用一个模块
• module-lifecycle - 适当使用生命周期钩子（init、clientConnected、clientDisconnected）
• module-error-handling - 在模块代码中妥善处理错误
• module-type-exports - 导出供客户端使用的类型

2. 表架构与索引（严重）

• table-primary-keys - 选择合适的主键策略
• table-indexing - 为经常查询的列添加 .index()
• table-relationships - 正确建模表之间的关系
• table-column-types - 使用合适的 SpacetimeDB 类型

3. Reducer 模式（高）

• reducer-atomicity - 让 reducer 保持原子性并专注于单一职责
• reducer-validation - 在 reducer 入口处验证输入
• reducer-authorization - 对敏感操作检查调用方身份
• reducer-batch-operations - 在单个 reducer 中批量执行相关变更

4. 订阅优化（高）

• subscription-selective - 仅订阅所需数据
• subscription-filters - 使用订阅过滤器减少数据传输
• subscription-cleanup - 不再需要订阅时进行清理
• subscription-batching - 在客户端连接时批量设置订阅

5. 客户端状态管理（中高）

• client-connection-lifecycle - 妥善处理连接和重新连接
• client-optimistic-updates - 使用乐观更新，让 UI 响应更迅速
• client-error-recovery - 妥善处理 reducer 错误
• client-identity - 安全管理身份令牌

6. React 集成（中）

• react-use-subscription - 正确使用订阅钩子
• react-table-hooks - 使用 useTable<DbConnection, Type>() 获取响应式数据
• react-reducer-hooks - 调用 conn.reducers.* 并妥善处理错误
• react-connection-status - 向用户显示连接状态

7. TypeScript 模式（中）

• ts-generated-types - 使用 SpacetimeDB CLI 生成的类型
• ts-strict-mode - 启用严格 TypeScript 模式，以提升类型安全性
• ts-discriminated-unions - 使用可辨识联合表示状态
• ts-type-guards - 实现类型守卫，以便在运行时进行验证

8. 实时同步（中低）

• sync-conflict-resolution - 处理并发修改
• sync-offline-support - 在需要时采用离线优先设计
• sync-debounce-updates - 对快速 UI 更新进行防抖
• sync-presence - 高效实现用户在线状态

如何使用

阅读各个规则文件，了解详细说明和代码示例：

rules/module-single-responsibility.md
rules/table-primary-keys.md
rules/_sections.md

每个规则文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 补充背景信息和参考资料

完整编译文档

查看包含所有展开规则的完整指南：AGENTS.md