SpacetimeDB 客户端绑定生成实战:从 `spacetime generate` 到类型安全客户端代码

原创2026-09-12 18:02:201,671 阅读
文章标签:数据库关系型数据库后端WebSocketWebAssembly游戏开发Serverless实时分析运维

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 的实现,一次生成过程大致分为五步:

  1. 获取模块定义(ModuleDef):默认情况下,CLI 先调用 spacetime build 编译模块(携带 --build-options),拿到 wasm/js 产物;若传了 --bin-path 或 --js-path 则跳过构建直接读取;也可以通过 --module-def 从 JSON 编码的 ModuleDef 生成。
  2. 提取 schema:通过 spacetimedb-standalone extract-schema <wasm_file> 从产物中解析出模块的完整 schema(见 extract_descriptions)。
  3. 过滤可见性:默认只生成公共表与公共函数,私有表会被跳过并打印提示;只有加 --include-private 才会纳入(对应 CodegenVisibility)。
  4. 逐文件生成:核心的 generate() 函数会依次遍历:公共表 → View → 子模块公共表 → 子模块 View → 自定义类型 → Reducer → Procedure → 子模块 Reducer/Procedure → 全局文件,每种实体交给目标语言的 Lang 后端生成 OutputFile(文件名 + 代码)。
  5. 落盘与清理:为每个输出文件创建目录、写入内容,同时扫描输出目录中带有自动生成标记(// 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 脚本),避免客户端拿到过期绑定。

使用生成代码

生成绑定之后,就可以连接数据库并开始交互。后续路线:

仓库中还提供了大量可直接运行的示例: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 中的校验):

  1. 传入正确的 --module-path;
  2. 在 spacetime.json 中配置 module-path;
  3. 改用 --bin-path / --js-path 直接指向已构建产物,跳过源码构建。

绑定过期(Outdated bindings)

如果客户端看不到新增的表或 reducer,请确认在更新模块之后重新运行了 spacetime generate。如前文所述,生成代码不会在模块变化时自动更新;此外还需留意 schema 迁移对旧客户端的影响——自动迁移文档明确指出,客户端不会自动感知 schema 变化,删除表等破坏性变更要求客户端使用重新生成的新绑定后再重连(见 自动迁移文档)。

私有表没有生成

默认情况下只有公共表/公共函数会进入生成结果,这是刻意的可见性控制(对应 CodegenVisibility::OnlyPublic)。如果确实需要,可加 --include-private 让私有表也参与生成(类型本身始终包含),但请评估在客户端暴露内部结构的风险。

登录后查看全文
SpacetimeDB