SpacetimeDB 多语言支持全景服务端模块语言与客户端 SDK 选型指南【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本指南基于 SpacetimeDB 1.12.0 官方文档Language Support展开系统梳理服务端数据库模块支持的三种语言Rust、C#、TypeScript与客户端 SDK 覆盖的四种语言/平台Rust、C#、TypeScript、Unreal Engine并结合本仓库中的模板工程、Quickstart 文档与 SDK 源码给出可落地的选型建议与入门路径。读完本文你将能够根据自身技术栈快速确定服务端与客户端语言组合并通过spacetimeCLI 一键生成类型安全的客户端绑定代码。一、总览两端双轨的语言支持体系SpacetimeDB 的语言支持被清晰地划分为两条轨道服务端数据库模块Server Database Modules用于定义数据库 schema 与服务器端业务逻辑支持Rust、C#、TypeScript三种语言客户端 SDKClient SDKs用于编写连接数据库的客户端应用支持Rust、C#、TypeScript、Unreal EngineC 与 Blueprint四种语言/平台。需要强调的是服务端与客户端语言可以自由组合——例如用 TypeScript 写服务端模块、用 Rust 写客户端或用 Rust 写模块、在 Unity 中用 C# SDK 接入。spacetimeCLI 负责在二者之间架起类型安全的桥梁它能够针对你的数据库模块自动生成类型安全的客户端代码详见本文第五节。仓库中的 templates 目录为每种组合提供了开箱即用的模板工程basic-rs、basic-cs、basic-ts、basic-cpp以及react-ts、vue-ts、svelte-ts等前端框架模板是体验多语言支持的捷径。二、服务端数据库模块三种语言、两种运行时2.1 模块与数据库的关系在深入语言细节之前必须先厘清两个基础概念详见 The Database Module模块Module你编写的代码包含 schema表与业务逻辑reducers、procedures、views编译后部署到 SpacetimeDB数据库Database模块的运行实例拥有模块的 schema 与逻辑外加真实存储的数据。同一个模块可以部署到多个数据库如测试、预发布、生产环境彼此数据独立。当模块代码更新并重新发布时SpacetimeDB 会同步更新数据库的 schema 与逻辑已有数据得以保留。2.2 三种语言与两种运行时的对应关系语言运行方式目标人群仓库证据Rust编译为 WebAssemblyWasm追求高性能的场景templates/basic-rs、crates/bindingsC#编译为 WebAssemblyWasmUnity / .NET 开发者templates/basic-cs、crates/bindings-csharpTypeScript运行于 V8 引擎Web 开发者templates/basic-ts、crates/bindings-typescript从源码结构可以推断Rust 与 C# 模块均编译为 Wasm由 Wasm 运行时承载TypeScript 模块则直接在 V8 引擎中执行因此 TypeScript 模块的启动与热更新链路与 Wasm 模块有所不同。这是选择服务端语言时最重要的底层差异。2.3 Rust 模块高性能 WasmRust 是 SpacetimeDB 的原生语言模块 SDK 以spacetimedbcrate 形式提供仓库中对应的绑定层实现位于 crates/bindings 与 crates/bindings-macro。使用spacetime dev从 basic-rs 模板 创建项目spacetime dev --template basic-rs my-spacetime-app模板中的服务端逻辑spacetimedb/src/lib.rs展示了表与 reducer 的基本形态见 Rust Quickstartuse spacetimedb::{ReducerContext, Table}; #[spacetimedb::table(name person, public)] pub struct Person { name: String, } #[spacetimedb::reducer] pub fn add(ctx: ReducerContext, name: String) { ctx.db.person().insert(Person { name }); } #[spacetimedb::reducer] pub fn say_hello(ctx: ReducerContext) { for person in ctx.db.person().iter() { log::info!(Hello, {}!, person.name); } log::info!(Hello, World!); }关键要点#[spacetimedb::table]宏声明表结构public表示对客户端公开#[spacetimedb::reducer]标记的 reducer 是唯一允许写入数据库的服务端函数所有写入都以事务方式执行ctx.db.person()提供对表的访问句柄支持insert、iter等操作。2.4 C# 模块面向 Unity 与 .NET 的 WasmC# 模块同样编译为 WebAssembly借助 .NET 的 WASI 实验性工作负载WASI experimental workload实现。在创建项目之前需要先安装对应工作负载见 C# Quickstartdotnet workload install wasi-experimental spacetime dev --template basic-cs my-spacetime-appC# 模块的服务端代码spacetimedb/Lib.cs与 Rust 版本在概念上一一对应using SpacetimeDB; public static partial class Module { [SpacetimeDB.Table(Name Person, Public true)] public partial struct Person { public string Name; } [SpacetimeDB.Reducer] public static void Add(ReducerContext ctx, string name) { ctx.Db.Person.Insert(new Person { Name name }); } [SpacetimeDB.Reducer] public static void SayHello(ReducerContext ctx) { foreach (var person in ctx.Db.Person.Iter()) { Log.Info($Hello, {person.Name}!); } Log.Info(Hello, World!); } }注意 C# 版本的命名约定为 PascalCaseAdd、SayHello、Person与 Rust 的 snake_caseadd、say_hello、person形成对应——SDK 在生成客户端绑定时会自动完成大小写风格转换。本仓库中的 bindings-csharp/BSATN.Codegen 与 Codegen 目录即承担了 C# 侧序列化与代码生成的实现。2.5 TypeScript 模块Web 开发者的 V8 直跑TypeScript 模块不需要编译为 Wasm而是直接运行在 V8 引擎上服务端 SDK 为spacetimedb/server见 TypeScript Quickstartspacetime dev --template basic-ts my-spacetime-app服务端代码spacetimedb/src/index.tsimport { schema, table, t } from spacetimedb/server; export const spacetimedb schema( table( { name: person }, { name: t.string(), } ) ); spacetimedb.reducer(add, { name: t.string() }, (ctx, { name }) { ctx.db.person.insert({ name }); }); spacetimedb.reducer(say_hello, (ctx) { for (const person of ctx.db.person.iter()) { console.info(Hello, ${person.name}!); } console.info(Hello, World!); });TypeScript 模块采用声明式 APIschema()/table()定义表结构t.string()等类型构造器描述列类型spacetimedb.reducer()注册 reducer。对于熟悉 JavaScript/Node.js 的团队这是上手成本最低的服务端选项。2.6 三种语言模块的共性无论选择哪种语言模块都由三类服务端函数构成见 The Database ModuleReducers事务性地修改数据的服务端函数是写入数据库的唯一途径Procedures可执行 HTTP 请求等外部操作并返回结果的函数Beta 阶段Views基于数据的只读计算查询可订阅。此外数据库命名遵循正则/^[a-z0-9](-[a-z0-9])*$/仅小写字母数字、以连字符分隔每个数据库在创建时还会获得唯一的十六进制Identity客户端既可用名称也可用 Identity 连接。三、客户端 SDK四种语言/平台客户端Clients是连接到 SpacetimeDB 数据库的应用程序。官方 SDK 覆盖 Rust、C#、TypeScript 与 Unreal EngineC 与 Blueprint四种语言/平台对应仓库目录分别为 sdks/rust、sdks/csharp、sdks/typescript 与 sdks/unreal。3.1 Rust 客户端 SDKRust 客户端通过spacetimedb_sdkcrate 提供见 Rust Reference核心类型为按模块生成的DbConnectioncargo add spacetimedb_sdk连接数据库采用 builder 模式至少需要指定 URI 与模块名或数据库 Identitymodule_bindings::DbConnection::builder() .with_uri(ws://localhost:3000) // SpacetimeDB 实例地址 .with_module_name(my-spacetime-app) // 数据库名称或 Identity .on_connect(|conn, identity, token| { /* 连接成功回调 */ }) .with_token(None) // 传 None 表示匿名连接 .build()?;Rust SDK 在消息处理策略上提供了高度灵活性开发者可根据应用形态选择方法行为适用场景run_threaded()在后台线程中持续推进连接简单 CLI 客户端run_async()在异步任务中推进连接async 运行时如 tokioframe_tick()主线程中非阻塞地推进连接游戏每帧驱动3.2 C# 客户端 SDKC# SDK 与 Unity 深度集成也是 Unity 项目中接入 SpacetimeDB 的标准路径。SDK 的 .NET 实现位于 sdks/csharp/src同时提供SpacetimeDB.ClientSDK.csproj与SpacetimeDB.ClientSDK.Godot.csproj两个工程说明其同时支持 .NET 与 Godot 环境详见 C# Reference。3.3 TypeScript 客户端 SDKTypeScript 客户端 SDK 可同时运行于浏览器与 Node.js 环境见 TypeScript Referencenpm install spacetimedb官方文档特别提示旧包名clockworklabs/spacetimedb-sdk自 SpacetimeDB 1.4.0 起已废弃统一改用spacetimedb包且需要 1.4.0 版本的 CLI 来生成新包对应的绑定代码。仓库中的 sdks/typescript/src 提供了完整实现templates 下的react-ts、vue-ts、svelte-ts、solid-ts、angular-ts、astro-ts、nextjs-ts、nuxt-ts、remix-ts、tanstack-ts、nodejs-ts、deno-ts、bun-ts等模板则覆盖了主流 Web 框架。3.4 Unreal Engine 客户端 SDKUnreal SDK 提供 C 与 Blueprint 两套 API用于构建接入 SpacetimeDB 的 UE 游戏客户端见 Unreal Reference。仓库中的 sdks/unreal 包含完整插件源码与示例工程demo/Blackholio/client-unreal 则是使用该 SDK 的真实游戏客户端示例。Unreal 侧的连接同样采用 builder 模式核心方法包括WithUri设置实例 URI、WithModuleName设置数据库名称/Identity、WithToken认证令牌与WithCompressionWebSocket 压缩方式。教程入口见 Unreal Tutorial Part 1。四、Unity 专项支持SpacetimeDB 在立项之初就将多人 Unity 游戏的服务器后端作为首要设计目标C# SDK 与 Unity 项目可实现无缝集成见 Unity Tutorial Part 1。Unity 技术栈的典型组合是服务端C# 模块与 Unity 共用语言团队心智负担最低或 Rust 模块追求极致性能客户端Unity 中的 C# SDK。仓库中的 demo/Blackholio/client-unity 是一个完整的 Unity 多人游戏客户端示例展示了真实项目中 C# SDK 的用法。此外sdks/csharp 目录中还包含了unity-meta-skeleton~与大量.meta文件表明 SDK 工程结构对 Unity 导入流程做了专门适配。五、CLI 自动生成类型安全的客户端绑定无论选择哪个客户端 SDK第一步都是为模块生成类型安全绑定bindings。spacetime generate命令会根据模块的 schema 与函数签名生成客户端代码详见 Generating Client Bindings# TypeScript 客户端 spacetime generate --lang typescript --out-dir src/module_bindings --project-path PATH-TO-MODULE-DIRECTORY # C# 客户端 spacetime generate --lang cs --out-dir module_bindings --project-path PATH-TO-MODULE-DIRECTORY # Rust 客户端 spacetime generate --lang rust --out-dir client/src/module_bindings --project-path PATH-TO-MODULE-DIRECTORY # Unreal 客户端 spacetime generate --lang unrealcpp --uproject-dir PATH-TO-UPROJECT --project-path PATH-TO-MODULE-DIRECTORY --module-name YOUR_MODULE_NAME各语言的PATH-TO-MODULE-DIRECTORY均指向模块工程文件Cargo.toml/.csproj/package.json所在目录。生成的绑定代码为模块中的每个组件提供表Tables类型定义 DbConnection上的表访问器 on_insert/on_delete/on_update回调注册方法用于观察客户端缓存的增删改Reducers客户端可调用的函数如conn.reducers.createUser(name, email) 运行结果回调ProceduresBeta客户端调用函数 返回值处理回调Views返回类型定义 订阅接口 缓存查询方法。例如模块中的create_userreducer 在 Rust 客户端中会生成conn.reducers().create_user(name, email); conn.reducers().on_create_user(|ctx, name, email| { println!(User created: {}, name); });重要提醒生成代码不会随模块变更自动更新。每当修改模块的 schema 或函数签名后必须重新运行spacetime generate覆盖旧绑定否则客户端将无法感知新增的表与 reducer详见 codegen 文档的 Troubleshooting 部分。六、快速上手的模板与学习路径6.1 模板工程矩阵仓库 templates 目录为服务端 × 客户端的常见组合提供了可直接运行的模板其中与本文主题直接相关的包括模板服务端语言客户端basic-rsRustRustbasic-csC#C#basic-tsTypeScriptTypeScriptbasic-cppRustCchat-react-tsTypeScriptReact TypeScriptspacetime dev --template 模板名 项目名会同时完成启动本地 SpacetimeDB 服务器、编译并发布模块、生成客户端绑定一步到位。6.2 推荐的入门路径根据团队技术栈选定服务端语言性能优先选 RustUnity/.NET 团队选 C#Web 团队选 TypeScript运行对应 Quickstart 创建项目Rust / C# / TypeScript用spacetime call、spacetime sql、spacetime logs验证模块三种语言的 CLI 交互完全一致spacetime call my-spacetime-app add Alice spacetime sql my-spacetime-app SELECT * FROM person spacetime call my-spacetime-app say_hello spacetime logs my-spacetime-app选定客户端 SDK执行spacetime generate生成绑定查阅语言专属参考文档深入 APIRust、C#、TypeScript、Unreal。6.3 深入阅读指引服务端模块核心概念The Database Module客户端绑定生成Generating Client Bindings语言专属 SDK 参考Rust、C#、TypeScript、Unreal完整示例项目demo/Blackholio包含 Rust、C#、TypeScript、C、Unity、Godot、Unreal 全部客户端实现服务端 SDK 源码Rust 绑定见 crates/bindings、C# 见 crates/bindings-csharp、TypeScript 见 crates/bindings-typescript七、小结如何选择语言组合综合官方文档与本仓库证据可以给出如下选型建议高性能实时后端Rust 模块Wasm 任意客户端 SDKUnity 多人游戏C# 模块与客户端共用语言或 Rust 模块 C# SDKSpacetimeDB 官方文档明确将 Unity 后端作为首要设计目标Web 应用 / 全栈 TypeScript 团队TypeScript 模块V8 直跑 TypeScript SDK模板覆盖几乎所有主流前端框架UE 游戏TypeScript 或 Rust 模块 Unreal SDKC 与 Blueprint 双 API。服务端三种语言、客户端四种语言/平台之间的自由组合加上spacetime generate一键生成类型安全绑定的工作流构成了 SpacetimeDB 完整的语言支持生态——这也是其以光速开发Development at the speed of light理念在工程体验层面的直接体现。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考