SpacetimeDB 客户端绑定生成实战:从 `spacetime generate` 到类型安全客户端代码
SpacetimeDB 客户端绑定生成实战:从 spacetime generate 到类型安全客户端代码
本文是 SpacetimeDB 客户端开发的核心指南,围绕 spacetime generate 命令展开,系统讲解如何为 TypeScript、C#、Rust、Unreal C++ 四种客户端生成模块绑定(Module Bindings),以及生成代码的结构、重新生成机制与源码级实现原理。读完本文,你将能够独立完成从模块到客户端绑定的完整生成流程,理解表、Reducer、Procedure、View 在每种语言中的生成形态,并掌握排查生成问题的正确姿势。
什么是 Module Bindings(模块绑定)
在客户端应用能够与 SpacetimeDB 数据库交互之前,必须先为你的模块生成客户端绑定。所谓模块绑定,就是一段自动生成的代码,它镜像了模块的 schema 与函数签名,为客户端提供了类型安全的访问层。绑定代码提供的核心能力包括:
- 类型定义(Type definitions):与模块中表、类型一一对应的客户端类型结构;
- 可调用函数(Callable functions):用于调用 Reducer 与 Procedure 的客户端封装;
- 查询接口(Query interfaces):用于订阅(subscription)与本地缓存访问(local cache access)的接口;
- 回调注册(Callback registration):用于监听数据库变更(插入、更新、删除)的回调机制。
绑定保证了客户端与服务端代码在编译期的类型安全——在模块中把某列声明为 u64,生成到客户端后就不会被当作 String 使用,从而在运行时之前捕获大量错误。
使用 spacetime generate 生成绑定
spacetime generate 是 SpacetimeDB CLI 中负责客户端代码生成的子命令。从 CLI 的源码定义(crates/cli/src/subcommands/generate.rs)可以看出,该命令的完整用法为:
spacetime generate [DATABASE] --lang <LANG> [--module-path <DIR> | --bin-path <PATH> | --js-path <PATH>] [--out-dir <DIR> | --uproject-dir <DIR>] [--unreal-module-name <MODULE_NAME>] [OPTIONS]
下面按语言分别介绍推荐用法。
TypeScript
mkdir -p src/module_bindings
spacetime generate --lang typescript --out-dir src/module_bindings --module-path PATH-TO-MODULE-DIRECTORY
生成的 TypeScript 文件位于 src/module_bindings/,在客户端中通过命名空间导入使用:
import * as moduleBindings from './module_bindings';
其中 PATH-TO-MODULE-DIRECTORY 指向模块所在目录——对于 TypeScript 模块而言,即包含模块 package.json 的目录(仓库模板 templates/basic-ts/spacetimedb/package.json 展示了典型结构,其 build 脚本为 spacetime build)。
C#
mkdir -p module_bindings
spacetime generate --lang csharp --out-dir module_bindings --module-path PATH-TO-MODULE-DIRECTORY
生成的 C# 文件位于 module_bindings/,会被自动包含进你的 .NET 工程。PATH-TO-MODULE-DIRECTORY 指向包含模块 .csproj 的目录。
C# 生成还支持 --namespace 参数自定义命名空间,默认值为 SpacetimeDB.Types(见 generate.rs 源码 与 prepare_generate_run_configs 中的默认逻辑)。
Rust
mkdir -p src/module_bindings
spacetime generate --lang rust --out-dir src/module_bindings --module-path PATH-TO-MODULE-DIRECTORY
生成的 Rust 文件位于 src/module_bindings/,在客户端中通过模块声明引入:
mod module_bindings;
PATH-TO-MODULE-DIRECTORY 指向包含模块 Cargo.toml 的目录。
Unreal(C++)
spacetime generate --lang unrealcpp --uproject-dir PATH-TO-UPROJECT --module-path PATH-TO-MODULE-DIRECTORY --unreal-module-name YOUR_MODULE_NAME
生成的 Unreal C++ 文件位于工程的 ModuleBindings 目录,会被自动纳入 Unreal 工程编译。三个占位参数分别说明如下:
- PATH-TO-UPROJECT:Unreal 工程目录(包含
.uproject文件的目录),等价于--out-dir的 Unreal 专用替代; - PATH-TO-MODULE-DIRECTORY:SpacetimeDB 模块目录;
- YOUR_MODULE_NAME:Unreal 模块名,通常就是工程名。该名字被用于生成 DLL 导出宏(如
YOUR_MODULE_NAME_API),是 unrealcpp 模式下的必填参数。
命令参数速查
综合 generate.rs 的参数定义,spacetime generate 的完整参数列表如下:
| 参数 | 简写 | 含义 | 默认值 / 约束 |
|---|---|---|---|
--lang |
-l |
生成语言:rust、csharp、typescript、unrealcpp |
必填;可用别名 rs/ts/cs/uecpp 等 |
--module-path |
-p |
模块工程目录 | 缺省先找 spacetimedb/ 子目录,再找当前目录 |
--bin-path |
-b |
直接指定已编译的 wasm 二进制路径(跳过构建) | 与 --module-path、--build-options 互斥 |
--js-path |
-j |
直接指定已打包的 JS 文件路径(跳过构建) | 与 --module-path、--build-options 互斥 |
--out-dir |
-o |
输出目录 | Rust/TS 默认 src/module_bindings,C# 默认 module_bindings |
--uproject-dir |
— | Unreal 工程目录(仅 --lang unrealcpp 使用) |
unrealcpp 必填 |
--namespace |
— | 生成代码命名空间(仅 C#) | SpacetimeDB.Types |
--unreal-module-name |
— | Unreal 模块名(DLL 导出宏用) | unrealcpp 必填;别名 --module-name |
--module-prefix |
— | 生成类型的前缀(仅 unrealcpp) | 空 |
--build-options |
— | 透传给构建命令的选项 | 空字符串 |
--dotnet-version |
— | 使用的 .NET SDK 主版本 | 视环境检测 |
--include-private |
— | 将私有表/函数也生成进代码(类型始终包含) | false |
--no-config |
— | 忽略 spacetime.json 配置 |
关闭 |
--env |
— | 配置文件分层环境名(如 dev、staging) |
无 |
值得注意的是,源码中实现了客户端语言自动检测:当未指定 --lang 时,CLI 会根据客户端工程中的文件推断语言——存在 package.json 判定为 TypeScript,存在 Cargo.toml 判定为 Rust,存在 .csproj 判定为 C#(见 detect_default_language 及对应单元测试 test_detect_typescript_language_from_client_project)。
生成流程的底层原理
理解 spacetime generate 的内部流程,有助于在出错时快速定位问题。结合 run_prepared_generate_configs 的实现,一次生成过程大致分为五步:
- 获取模块定义(ModuleDef):默认情况下,CLI 先调用
spacetime build编译模块(携带--build-options),拿到 wasm/js 产物;若传了--bin-path或--js-path则跳过构建直接读取;也可以通过--module-def从 JSON 编码的 ModuleDef 生成。 - 提取 schema:通过
spacetimedb-standalone extract-schema <wasm_file>从产物中解析出模块的完整 schema(见 extract_descriptions)。 - 过滤可见性:默认只生成公共表与公共函数,私有表会被跳过并打印提示;只有加
--include-private才会纳入(对应 CodegenVisibility)。 - 逐文件生成:核心的 generate() 函数会依次遍历:公共表 → View → 子模块公共表 → 子模块 View → 自定义类型 → Reducer → Procedure → 子模块 Reducer/Procedure → 全局文件,每种实体交给目标语言的
Lang后端生成OutputFile(文件名 + 代码)。 - 落盘与清理:为每个输出文件创建目录、写入内容,同时扫描输出目录中带有自动生成标记(
// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB,见 AUTO_GENERATED_PREFIX)的过期旧文件并提示删除(需要交互确认或--yes强制);最后用rustfmt(Rust)、dotnet format(C#)等工具对生成代码做格式化。
排序方面,代码生成对表、Reducer、Procedure、View、类型均按名称排序(见 util.rs 中的 iter_* 函数),保证生成结果确定可复现。
此外,spacetime generate 支持通过 spacetime.json 配置多个生成目标(按数据库名 glob 过滤、父子目标继承 module-path、按 (module_path, generate_entry) 去重),这部分在 get_filtered_generate_configs 及其单元测试中有完整覆盖。
会生成什么:四类核心产物
表(Tables)
模块中的每张表都会生成三样东西:
- 类型/类定义:为每一列生成对应的属性;
- 表访问器:挂在
DbConnection上,用于查询客户端本地缓存; - 回调注册方法:用于监听插入、更新、删除事件。
例如模块中的 user 表(含 id、name、email_address 三列):
TypeScript
// Generated type
export default __t.row({
id: __t.u64(),
name: __t.string(),
emailAddress: __t.string(),
});
// Access via DbConnection
conn.db.user
C#
// Generated type
public partial class User
{
public ulong Id;
public string Name;
public string EmailAddress;
}
// Access via DbConnection
conn.Db.User
Rust
// Generated type
pub struct User {
pub id: u64,
pub name: String,
pub email_address: String,
}
// Access via DbConnection
conn.db().user()
Unreal
// Generated type
USTRUCT(BlueprintType)
struct FUser
{
GENERATED_BODY()
UPROPERTY(BlueprintReadWrite)
int64 Id;
UPROPERTY(BlueprintReadWrite)
FString Name;
UPROPERTY(BlueprintReadWrite)
FString EmailAddress;
};
// Access via DbConnection
Context.Db->User
注意:生成后的名称遵循各语言的命名惯例。模块中声明的 email_address 列,在 TypeScript 中变成 emailAddress,在 C# 中变成 EmailAddress,在 Rust 中保持 email_address。这一点在 crates/codegen/src/util.rs 的 collect_case 中通过 convert_case 库统一实现(PascalCase / camelCase 转换),而 Unreal 后端还支持通过 --module-prefix 为类型名加前缀(见 unrealcpp.rs)。
Reducer
模块中的每个 Reducer 都会生成:
- 客户端可调函数:向服务端发送 reducer 调用请求;
- 回调注册方法:监听该 reducer 的执行;
- 类型安全参数:与 reducer 签名严格对应。
例如 create_user reducer:
TypeScript
// Call the reducer
await conn.reducers.createUser({ name, email });
// Register a callback to observe reducer invocations
conn.reducers.onCreateUser((ctx, { name, email }) => {
console.log(`User created: ${name}`);
});
C#
// Call the reducer
conn.Reducers.CreateUser(name, email);
// Register a callback to observe reducer invocations
conn.Reducers.OnCreateUser += (ctx, name, email) =>
{
Console.WriteLine($"User created: {name}");
};
Rust
// Call the reducer
conn.reducers().create_user(name, email);
// Register a callback to observe reducer invocations
conn.reducers().on_create_user(|ctx, name, email| {
println!("User created: {}", name);
});
Unreal
// Call the reducer
Context.Reducers->CreateUser(TEXT("Alice"), TEXT("alice@example.com"));
// Register a callback to observe reducer invocations
Context.Reducers->OnCreateUser.AddDynamic(this, &AMyActor::OnCreateUser);
// Callback function (must be UFUNCTION)
UFUNCTION()
void OnCreateUser(const FReducerEventContext& Ctx, const FString& Name, const FString& Email)
{
UE_LOG(LogTemp, Log, TEXT("User created: %s"), *Name);
}
从 util.rs 的 iter_reducers 可以看出一个细节:生命周期类 reducer(如 init)以及标记为 Internal 可见性的 reducer 不会被生成到客户端——它们本就不应被客户端直接调用。
Procedure
模块中的每个 Procedure 都会生成:
- 客户端可调函数:调用该 procedure;
- 返回值处理:处理 procedure 的返回结果;
- 类型安全参数:与 procedure 签名对应。
例如 fetch_external_data procedure:
TypeScript
// Call the procedure
conn.procedures
.fetchExternalData(url)
.then(result => console.log(`Got result: ${result}`))
.catch(error => console.error(`Error: ${error}`));
C#
// Call the procedure without a callback
conn.Procedures.FetchExternalData(url);
// Call the procedure with a callback for the result
conn.Procedures.FetchExternalData(url, (ctx, result) =>
{
if (result.IsSuccess)
{
Console.WriteLine($"Got result: {result.Value!}");
}
else
{
Console.WriteLine($"Error: {result.Error!}");
}
});
Rust
// Call the procedure without a callback
conn.procedures().fetch_external_data(url);
// Call the procedure with a callback for the result
conn.procedures().fetch_external_data_then(url, |ctx, result| {
match result {
Ok(data) => println!("Got result: {:?}", data),
Err(error) => eprintln!("Error: {:?}", error),
}
});
Unreal
// Call the procedure without a callback
Context.Procedures->FetchExternalData(url, {});
// Call the procedure with a callback for the result
FOnFetchExternalDataComplete Callback;
BIND_DELEGATE_SAFE(Callback, this, AMyActor, OnFetchComplete);
Context.Procedures->FetchExternalData(url, Callback);
// Callback function (must be UFUNCTION)
UFUNCTION()
void OnFetchComplete(const FProcedureEventContext& Ctx, const FString& Result, bool bSuccess)
{
if (bSuccess)
{
UE_LOG(LogTemp, Log, TEXT("Got result: %s"), *Result);
}
else
{
UE_LOG(LogTemp, Error, TEXT("Error"));
}
}
注意 C# 与 Rust 版本都提供了"无回调调用"与"带回调调用"两种形态,Unreal 则通过委托(delegate)绑定完成结果回调,回调函数必须是 UFUNCTION。
View(视图)
模块中的每个 View 都会生成:
- 类型定义:对应视图返回行类型;
- 订阅接口:用于订阅视图结果;
- 查询方法:访问缓存的视图结果;
- 更新回调:当视图拥有已知主键时,生成对应更新回调(
on_update/OnUpdate/onUpdate)。
View 是建立在数据之上的可订阅、可计算的查询。由于 View 在客户端视角与表几乎一致,代码生成时 View 被转换为 TableDef 再走表的生成路径(见 lib.rs 的 generate_view_file),这也是为什么 View 能像表一样挂在 DbConnection 上、支持更新回调的原因。
重新生成绑定
每当修改模块的 schema 或函数签名后,都需要重新运行 spacetime generate。该命令会覆盖输出目录中已存在的生成文件。由于生成文件带有固定的自动生成标记前缀,CLI 还能识别出"上一轮生成、但本轮不再生成"的过期文件,并询问是否删除(源码中对应 run_prepared_generate_configs 的文件清理逻辑)。
需要特别强调:生成代码不会随模块变更自动更新。如果正在积极开发迭代,建议把 spacetime generate 纳入构建或开发工作流(例如 TypeScript 模板的 package.json 中把 spacetime build/spacetime publish 写成 npm scripts,可仿照此模式加入 generate 脚本),避免客户端拿到过期绑定。
使用生成代码
生成绑定之后,就可以连接数据库并开始交互。后续路线:
- 连接 SpacetimeDB:建立客户端连接;
- SDK API 参考:使用生成绑定的完整 API;
- 语言专属参考:Rust、C#、TypeScript、Unreal。
仓库中还提供了大量可直接运行的示例:templates/ 目录下的 basic-ts、basic-rs、basic-cs、basic-cpp、chat-react-ts 等模板,以及 modules/ 目录下的 sdk-test-* 系列模块(如 sdk-test-view-pk、sdk-test-procedure、sdk-test-connect-disconnect),它们都演示了"模块 + 生成绑定 + 客户端调用"的完整闭环,是学习绑定用法的绝佳素材。
疑难解答
找不到模块目录(Missing module directory)
如果 spacetime generate 找不到你的模块,请确认 --module-path 指向的是包含模块工程文件(Cargo.toml、.csproj 或 package.json)的目录。源码在找不到模块时会明确报错并给出三种补救建议(见 prepare_generate_run_configs 中的校验):
- 传入正确的
--module-path; - 在
spacetime.json中配置module-path; - 改用
--bin-path/--js-path直接指向已构建产物,跳过源码构建。
绑定过期(Outdated bindings)
如果客户端看不到新增的表或 reducer,请确认在更新模块之后重新运行了 spacetime generate。如前文所述,生成代码不会在模块变化时自动更新;此外还需留意 schema 迁移对旧客户端的影响——自动迁移文档明确指出,客户端不会自动感知 schema 变化,删除表等破坏性变更要求客户端使用重新生成的新绑定后再重连(见 自动迁移文档)。
私有表没有生成
默认情况下只有公共表/公共函数会进入生成结果,这是刻意的可见性控制(对应 CodegenVisibility::OnlyPublic)。如果确实需要,可加 --include-private 让私有表也参与生成(类型本身始终包含),但请评估在客户端暴露内部结构的风险。