
SpacetimeDB Bun 快速上手指南5 分钟构建 TypeScript 实时多人在线应用【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本篇指南基于 SpacetimeDB 官方 Bun 快速入门文档结合仓库内 templates/bun-ts 模板的完整源码从项目脚手架创建、服务端模块编写、Bun 客户端连接与交互到spacetimeCLI 调试验证逐步带你掌握用 SpacetimeDB 与 Bun 构建数据库即服务端实时应用的完整实战流程。读完本文你将能够独立创建、运行并调试一个完整的 SpacetimeDB Bun 全栈应用。适用前提本指南针对 Bun 运行时当前模板要求bun^1.3.2使用 TypeScript 编写服务端与客户端逻辑你无需预先掌握 SpacetimeDB 的内部实现只需具备基础的 TypeScript 与命令行使用经验即可。前置条件开始之前请确保本机已安装以下两个工具Bun一个集运行时、包管理器、构建工具于一体的 JavaScript/TypeScript 运行时。访问 bun.sh 按其官方安装方式安装。SpacetimeDB CLISpacetimeDB 的命令行工具用于创建项目、启动本地服务器、发布模块与查询数据参考官方安装页仓库 crates/cli 即其源码实现。安装完成后可以在终端中执行bun --version与spacetime --version确认两个命令均已就绪。第一步创建项目 —— 一条命令启动开发环境在任意空目录中执行以下命令即可创建包含 SpacetimeDB 模块与 Bun 客户端的新项目spacetime dev --template bun-ts这条命令背后做了一系列事情下载并应用模板拉取bun-ts模板作为项目骨架与仓库 templates/bun-ts 内容一致启动本地 SpacetimeDB 服务器在当前机器上运行一个本地数据库实例默认ws://localhost:3000发布模块将spacetimedb/src/index.ts中定义的表与 reducer 编译发布到本地服务器生成 TypeScript 绑定自动生成客户端用的类型安全绑定代码到src/module_bindings/目录。这意味着你不需要手动安装数据库、配置连接串或编写任何胶水代码一条命令就进入可开发状态。第二步认识项目结构 —— 服务端与客户端一目了然spacetime dev生成的项目结构如下my-spacetime-app/ ├── spacetimedb/ # 你的 SpacetimeDB 模块服务端 │ └── src/ │ └── index.ts # 服务端逻辑表与 reducer 定义 ├── src/ │ ├── main.ts # Bun 客户端脚本 │ └── module_bindings/ # 自动生成的类型绑定勿手改 └── package.json # 客户端依赖与脚本各部分职责spacetimedb/服务端模块目录。它在仓库模板中是独立子包见 templates/bun-ts/spacetimedb/package.json依赖spacetimedb运行时并提供buildspacetime build与publishspacetime publish两个脚本spacetimedb/src/index.ts模块入口定义表结构Tables与 reducer 函数是服务端逻辑的单一真相src/main.tsBun 客户端入口负责连接数据库、订阅数据并实现交互式 CLIsrc/module_bindings/spacetimeCLI 根据服务端模块自动生成的类型安全绑定。每个表、每个 reducer 都会生成独立的类型文件如person_table.ts、add_reducer.ts此目录属于生成产物切勿手工编辑——文件头部的注释也明确声明了这一点。第三步理解表Tables与 Reducer —— SpacetimeDB 的核心心智模型打开spacetimedb/src/index.ts模板默认提供了一张person表和两个 reducer。仓库中该文件的真实实现为import { schema, table, t } from spacetimedb/server; const spacetimedb schema({ person: table( { public: true }, { name: t.string(), } ), }); export default spacetimedb; export const init spacetimedb.init(_ctx { // Called when the module is initially published }); export const onConnect spacetimedb.clientConnected(_ctx { // Called every time a new client connects }); export const onDisconnect spacetimedb.clientDisconnected(_ctx { // Called every time a client disconnects }); export const add spacetimedb.reducer( { name: t.string() }, (ctx, { name }) { ctx.db.person.insert({ name }); } ); export const sayHello spacetimedb.reducer(ctx { for (const person of ctx.db.person.iter()) { console.info(Hello, ${person.name}!); } console.info(Hello, World!); });完整源码见 templates/bun-ts/spacetimedb/src/index.ts比文档示例额外包含init、onConnect、onDisconnect三个生命周期回调钩子。两个核心概念需要理解透彻表Tables存储数据person表声明为{ public: true }表示所有客户端都可以订阅读取。字段name通过类型构建器t.string()声明为字符串类型Reducer 是唯一的写入口reducer 是修改数据的函数客户端无法直接写库只能调用 reducer。addreducer 接收一个{ name: string }参数并执行ctx.db.person.insert({ name })完成插入sayHelloreducer 无参数遍历ctx.db.person.iter()逐条打印问候最后打印Hello, World!。spacetimedb.reducer()的写法是先声明参数 schema作为类型与运行时双重描述再提供实现函数。该 schema 会被spacetimeCLI 用于生成客户端的类型安全调用接口见 templates/bun-ts/src/module_bindings/add_reducer.ts。第四步运行 Bun 客户端 —— 两种启动模式打开第二个终端进入项目根目录执行# 开发模式文件变更自动重载 bun run dev # 单次运行 bun run start两种模式的差异来自 templates/bun-ts/package.json 中的脚本定义{ scripts: { dev: bun --watch src/main.ts, start: bun src/main.ts, build: bun build src/main.ts --outdir dist, spacetime:generate: spacetime generate --lang typescript --out-dir src/module_bindings --module-path spacetimedb } }bun run dev等价于bun --watch src/main.ts利用 Bun 原生 watch 能力编辑src/main.ts后进程自动重启适合开发迭代bun run start直接执行一次附加的spacetime:generate脚本可随时手动重新生成绑定当你修改了服务端模块的表/reducer 后通过bun run spacetime:generate刷新客户端类型。第五步使用交互式 CLI —— 与模块实时对话客户端启动后控制台会依次输出连接信息、身份标识、当前数据快照与可用命令Connecting to SpacetimeDB... URI: ws://localhost:3000 Module: bun-ts Connected to SpacetimeDB! Identity: abc123def456... Current people (0): (none yet) Commands: name - Add a person with that name list - Show all people hello - Greet everyone (check server logs) CtrlC - Quit Alice [Added] Alice Bob [Added] Bob list People in database: - Alice - Bob hello Called sayHello reducer (check server logs)交互逻辑对应的客户端实现见 templates/bun-ts/src/main.ts 中的setupCLI输入任意名称 → 调用conn.reducers.add({ name: text })触发服务端addreducer输入list→ 通过conn.db.person.iter()遍历本地缓存的订阅数据并打印输入hello→ 调用conn.reducers.sayHello({})服务端日志输出问候CtrlC→ 触发SIGINT处理调用conn.disconnect()优雅断开。第六步理解客户端代码 —— DbConnection 与订阅模型src/main.ts是理解 SpacetimeDB TypeScript 客户端的入口。它基于生成的绑定类DbConnection其基类与构建器实现在 sdks/typescript/src/sdk/db_connection_impl.ts完成以下工作import { Identity } from spacetimedb; import { DbConnection, ErrorContext, EventContext, } from ./module_bindings/index.js; // Configuration - Bun supports .env files natively const HOST process.env.SPACETIMEDB_HOST ?? ws://localhost:3000; const DB_NAME process.env.SPACETIMEDB_DB_NAME ?? bun-ts; async function main(): Promisevoid { console.log(Connecting to SpacetimeDB...); console.log( URI: ${HOST}); console.log( Module: ${DB_NAME}); const token await loadToken(); // Build and establish connection DbConnection.builder() .withUri(HOST) .withDatabaseName(DB_NAME) .withToken(token) .onConnect(onConnect) .onDisconnect(onDisconnect) .onConnectError(onConnectError) .build(); }完整实现见 templates/bun-ts/src/main.ts比文档示例增加了onDisconnect/onConnectError错误处理与身份截断显示等细节。关键 API 及其语义DbConnection.builder()链式配置连接。.withUri()指定数据库地址默认ws://localhost:3000.withDatabaseName()指定模块名默认bun-ts.withToken()传入持久化的认证令牌.onConnect/.onDisconnect/.onConnectError注册三类连接生命周期回调subscriptionBuilder()构建订阅。.onApplied(ctx ...)在订阅数据首次落地后回调.subscribeToAllTables()订阅全部表回调中的ctx为SubscriptionEventContext可通过ctx.db.person.iter()读取当前数据快照conn.db.person.onInsert(...)注册表变更回调。任何客户端包括 CLI插入person行时所有已订阅的客户端都会实时收到onInsert事件并打印[Added] ...conn.db即查询构建器生成的tables对象由__makeQueryBuilder构造每个表引用同时充当查询构建器见 templates/bun-ts/src/module_bindings/index.ts。与浏览器应用不同Bun 环境下认证令牌不再依赖localStorage而是通过Bun.file()与Bun.write()持久化到本地文件.spacetimedb-token// Token persistence using Bun APIs const TOKEN_FILE .spacetimedb-token; async function loadToken(): Promisestring | undefined { try { const file Bun.file(TOKEN_FILE); if (await file.exists()) { const text await file.text(); return text.trim() || undefined; } } catch (err) { console.warn(Could not load token:, err); } return undefined; } async function saveToken(token: string): Promisevoid { try { await Bun.write(TOKEN_FILE, token); } catch (err) { console.warn(Could not save token:, err); } }首次连接时服务端下发的 token 会被保存后续启动读取同一 token即可复用同一身份Identity保证数据归属稳定。第七步用 SpacetimeDB CLI 验证与调试除客户端交互外还可以直接用spacetimeCLI 调用 reducer 和查询数据且CLI 的改动会实时同步到运行中的 Bun 客户端这正是订阅机制的效果# 调用 add reducer 插入一个人 spacetime call add Charlie # 查询 person 表 spacetime sql SELECT * FROM person name --- Alice Bob Charlie # 调用 sayHello 向所有人打招呼 spacetime call say_hello # 查看模块日志 spacetime logs 2025-01-13T12:00:00.000000Z INFO: Hello, Alice! 2025-01-13T12:00:00.000000Z INFO: Hello, Bob! 2025-01-13T12:00:00.000000Z INFO: Hello, Charlie! 2025-01-13T12:00:00.000000Z INFO: Hello, World!四个命令的用途spacetime call reducer [args...]远程调用指定 reducer。注意 reducer 在 CLI 中以snake_case命名say_hello而 TypeScript 绑定中为 camelCasesayHellospacetime sql ...以 SQL 直接查询数据库支持SELECT等只读操作spacetime logs实时流式查看模块的console.info等日志输出是调试 reducer 的重要工具。第八步Bun 专属特性 —— 为什么这个模板与众不同该模板特意为 Bun 运行时做了针对性优化主要有四点原生 WebSocket零额外依赖。Bun 内置WebSocket实现无需安装undici之类的 polyfill。SpacetimeDB TypeScript SDK 的 WebSocket 解析逻辑sdks/typescript/src/sdk/ws.ts会优先检测全局WebSocket——在 Bun以及浏览器和 Node ≥ 22环境下直接使用原生实现仅在缺失时才惰性加载undici兜底这正是 Bun 下开箱即用的底层原因。内置 TypeScript 运行能力。Bun 直接执行.ts文件无需tsx、ts-node等转译工具链启动更快、依赖更少。bun --watch同时提供开发期热重载。环境变量自动加载。Bun 原生读取.env文件模板通过SPACETIMEDB_HOST与SPACETIMEDB_DB_NAME两个环境变量配置连接参数默认值分别回落到ws://localhost:3000与bun-ts。配置方式有两种# 方式一命令行内联环境变量 SPACETIMEDB_HOSTws://localhost:3000 \ SPACETIMEDB_DB_NAMEmy-app \ bun run start # 方式二创建 .env 文件Bun 自动加载 echo SPACETIMEDB_HOSTws://localhost:3000 .env echo SPACETIMEDB_DB_NAMEmy-app .env bun run start原生文件 API 持久化令牌。模板使用Bun.file()与Bun.write()读写.spacetimedb-token相对 Node.js 的fs模块在 Bun 上性能更好、写法更简洁。下一步学习路径至此你已经跑通了 SpacetimeDB Bun 的完整开发闭环从spacetime dev --template bun-ts一键创建项目到编写表与 reducer、连接订阅、交互式 CLI 与spacetimeCLI 双向调试再到 Bun 专属特性的运用。如果你想继续深入推荐以下仓库内资源Chat App 完整教程一个完整的聊天应用示例展示多表、多 reducer 与真实业务场景的工程组织TypeScript SDK 参考文档DbConnection、SubscriptionBuilder、reducer 调用与事件上下文的详细 API 说明模板源码 templates/bun-ts本文所有代码的权威来源可对照阅读src/main.ts、spacetimedb/src/index.ts与src/module_bindings/下的生成文件理解绑定层如何与 SDK 运行时协作。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考