ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

SpacetimeDB Vue 快速入门:5 分钟跑通 Vue 3 + TypeScript 实时应用

SpacetimeDB Vue 快速入门:5 分钟跑通 Vue 3 + TypeScript 实时应用 SpacetimeDB Vue 快速入门5 分钟跑通 Vue 3 TypeScript 实时应用【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本文以 SpacetimeDB 官方 Vue 快速开始文档为主体讲解如何用一条命令创建「服务端模块 Vue 前端」的完整项目spacetime dev --template vue-ts会启动本地 SpacetimeDB 服务器、发布模块、自动生成 TypeScript 客户端绑定并拉起 Vite 开发服务器。读完本文你将掌握 Vue 3 应用连接 SpacetimeDB 的完整链路——从表table与归约器reducer的服务端定义到useSpacetimeDB/useTable/useReducer等 Vue 组合式函数的前端调用再到用 CLI 直接调约器、跑 SQL 查数据、查看模块日志。对应的仓库模板位于 templates/vue-ts文档原文位于 docs/docs/00100-intro/00200-quickstarts/00150-vue.md。前置条件开始之前请确保本机环境满足以下要求Node.js 18Vue 前端Vite、vue-tsc运行所必需的运行时环境SpacetimeDB CLI提供spacetime dev、spacetime call、spacetime sql、spacetime logs等核心命令安装方式见官方安装脚本仓库内对应实现位于 crates/cli。这两项就绪后无需手动安装数据库服务端——spacetime dev会替你在本地拉起并管理 SpacetimeDB 实例。创建项目一条命令启动完整开发环境在任意空目录中执行spacetime dev --template vue-ts这一条命令背后实际上串联起了整个开发生命周期初始化项目从vue-ts模板复制出包含 SpacetimeDB 模块与 Vue 客户端的项目骨架启动本地 SpacetimeDB 服务器在本机启动实时数据库实例发布模块将spacetimedb/目录下的服务端代码编译并发布到本地服务器生成 TypeScript 绑定根据服务端 schema 自动生成src/module_bindings/下的类型与调用代码启动 Vue 开发服务器拉起 Vite提供热更新开发体验。从源码实现看dev子命令的官方描述是“Start development mode with auto-regenerate client module bindings, auto-rebuild, and auto-publish on file changes.”即文件变更时自动重新生成客户端绑定、自动重新构建并自动发布这正是这套工作流的核心价值。相关实现见 crates/cli/src/subcommands/dev.rs。--template参数由 CLI 的--template/-t选项接收其合法值既可以是模板 ID如vue-ts也可以是 GitHub 仓库owner/repo或完整 URL。CLI 内置了模板清单执行spacetime init --template id同样可以按模板初始化项目详见 crates/cli/src/subcommands/init.rs。打开应用项目创建并启动完成后浏览器访问http://localhost:5173即可看到运行中的应用。该模板内置了一个已经连接上 SpacetimeDB 的基础 Vue 应用页面顶部展示连接状态Connected / Disconnected中部是一个可输入姓名的表单下方实时列出数据库中已有的所有人名。项目结构解析模板生成的项目同时包含服务端与客户端代码整体结构如下my-spacetime-app/ ├── spacetimedb/ # 你的 SpacetimeDB 模块 │ └── src/ │ └── index.ts # 服务端逻辑 ├── src/ # Vue 前端 │ ├── App.vue │ └── module_bindings/ # 自动生成的类型与绑定 └── package.json各部分的职责spacetimedb/src/index.ts服务端模块入口定义数据表tables、归约器reducers以及模块生命周期钩子。编辑此文件即可扩展后端逻辑src/App.vueVue 前端主界面在这里构建你的 UIsrc/module_bindings/CLI 根据服务端 schema 自动生成的客户端绑定包含类型安全的表访问器、归约器调用函数与连接器。生成文件头部带有 “THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE WILL NOT BE SAVED.” 的警告注释因此不要手工修改改完服务端代码后重新生成即可见 templates/vue-ts/src/module_bindings/index.ts。模板中还附带了完整的工程化配置vite.config.ts构建配置、index.html入口 HTML、env.d.tsVite 环境变量类型声明、tsconfig.json等与常规 Vite Vue 3 项目一致。理解表Tables与归约器Reducers打开spacetimedb/src/index.ts可以看到模板提供的模块代码。它定义了一张person表以及两个归约器add插入一个人和sayHello向所有人问好import { schema, table, t } from spacetimedb/server; const spacetimedb schema({ person: table( { public: true }, { name: t.string(), } ), }); export default spacetimedb; 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!); });这里沉淀了 SpacetimeDB 最核心的两个抽象表Table存储应用数据的结构。person表通过table({ public: true }, { name: t.string() })声明其中{ public: true }表示该表对客户端公开可被订阅{ name: t.string() }定义列与列类型t.string()来自spacetimedb/server的类型构造器。数据变更会实时同步给所有订阅了该表的客户端归约器Reducer修改数据的函数是写入数据库的唯一途径。add接收{ name: t.string() }参数并通过ctx.db.person.insert({ name })插入一行sayHello通过ctx.db.person.iter()遍历表中所有人并输出日志。客户端不能直接写库只能触发归约器这保证了写入路径的统一与可审计。在仓库模板的 templates/vue-ts/spacetimedb/src/index.ts 中还额外提供了三个生命周期钩子示例是快速开始文档之外值得关注的内容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 });init模块首次发布时调用适合做种子数据初始化onConnect/onDisconnect每个客户端连接/断开时触发可用来记录在线状态或清理会话数据。注意服务端归约器采用 snake_case 命名约定前端代码中的sayHello在线上协议与 CLI 中会表现为say_hello下文 CLI 部分可以印证。Vue 前端如何连接 SpacetimeDB模板的价值不仅在于服务端还在于它演示了 Vue 3 组合式 API 与 SpacetimeDB 客户端 SDK 的整合方式。连接入口main.ts应用入口 templates/vue-ts/src/main.ts 负责建立连接并通过SpacetimeDBProvider把连接注入整棵组件树import { createApp, h } from vue; import App from ./App.vue; import { Identity } from spacetimedb; import { SpacetimeDBProvider } from spacetimedb/vue; import { DbConnection, ErrorContext } from ./module_bindings/index.ts; const HOST import.meta.env.VITE_SPACETIMEDB_HOST ?? ws://localhost:3000; const DB_NAME import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? vue-ts; const TOKEN_KEY ${HOST}/${DB_NAME}/auth_token; const onConnect (_conn: DbConnection, identity: Identity, token: string) { localStorage.setItem(TOKEN_KEY, token); console.log( Connected to SpacetimeDB with identity:, identity.toHexString() ); }; const onDisconnect () { console.log(Disconnected from SpacetimeDB); }; const onConnectError (_ctx: ErrorContext, err: Error) { console.log(Error connecting to SpacetimeDB:, err); }; const connectionBuilder DbConnection.builder() .withUri(HOST) .withDatabaseName(DB_NAME) .withToken(localStorage.getItem(TOKEN_KEY) || undefined) .onConnect(onConnect) .onDisconnect(onDisconnect) .onConnectError(onConnectError); createApp({ render: () h(SpacetimeDBProvider, { connectionBuilder }, () h(App)), }).mount(#app);关键点连接地址与库名可通过环境变量覆盖VITE_SPACETIMEDB_HOST默认ws://localhost:3000即本地开发服务器地址与VITE_SPACETIMEDB_DB_NAME默认vue-ts即项目库名。部署到远端时只需修改环境变量无需改动代码鉴权令牌持久化连接成功回调会把服务端下发的token存入localStorage下次连接时通过.withToken(...)恢复身份实现“一次连接持续免登录”SpacetimeDBProvider来自spacetimedb/vue的 Provider 组件通过 provide/inject 让子组件共享连接实例。响应式数据App.vue主界面 templates/vue-ts/src/App.vue 展示了三个最常用的 Vue 组合式函数import { ref } from vue; import { tables, reducers } from ./module_bindings; import { useSpacetimeDB, useTable, useReducer } from spacetimedb/vue; const conn useSpacetimeDB(); const name ref(); // Subscribe to all people in the database const [people] useTable(tables.person); const addReducer useReducer(reducers.add); const addPerson () { if (!name.value.trim() || !conn.isActive) return; // Call the add reducer addReducer({ name: name.value }); name.value ; };useSpacetimeDB()返回连接上下文conn.isActive表示当前是否已连接前端 UI 可据此禁用表单或显示状态useTable(tables.person)订阅person表的实时数据返回响应式数组people。数据库中的任何变更都会自动触发 Vue 视图更新——这是“实时应用”体验的来源useReducer(reducers.add)返回一个可直接调用的归约器函数addReducer({ name })等价于远程触发服务端的add归约器。调用后服务端写库订阅端随即收到新数据。模板 UI 完整演示了这套闭环form submit.preventaddPerson提交时调用addReducer下方li v-for(person, index) in people则把订阅数据实时渲染为列表。值得一提的是tables与reducers均来自自动生成的 templates/vue-ts/src/module_bindings/index.ts类型定义由服务端 schema 推导而来person_table.ts、add_reducer.ts、say_hello_reducer.ts等因此服务端字段改动后前端调用处的类型检查会立即给出反馈。用 CLI 测试模块打开一个新终端进入项目目录即可通过 SpacetimeDB CLI 直接调用归约器、查询数据、查看日志无需经过前端cd my-spacetime-app # Call the add reducer to insert a person spacetime call add Alice # Query the person table spacetime sql SELECT * FROM person name --------- Alice # Call sayHello to greet everyone spacetime call say_hello # View the module logs spacetime logs 2025-01-13T12:00:00.000000Z INFO: Hello, Alice! 2025-01-13T12:00:00.000000Z INFO: Hello, World!逐条解读spacetime call add Alice调用add归约器并传入参数Alice等价于前端执行addReducer({ name: Alice })spacetime sql SELECT * FROM person用 SQL 直接查询person表返回结果与数据库当前内容一致此时能看到刚插入的Alicespacetime call say_hello触发问候归约器。这里使用的是snake_case 命名say_hello对应服务端源码中的sayHellospacetime logs拉取模块日志可以看到sayHello遍历输出的两行INFO日志——一行来自Alice一行来自代码末尾的Hello, World!。这种“CLI 直连数据库”的验证方式非常适合在写前端之前先验证服务端逻辑是否正确也方便在开发过程中快速造数据、排查问题。常用开发命令与参数模板根目录的 package.json 中预置了常用脚本覆盖了日常开发的全部场景命令作用pnpm dev启动 Vite 开发服务器pnpm build先执行vue-tsc -b做类型检查再执行vite build产出生产构建pnpm preview本地预览生产构建产物pnpm spacetime:generate重新生成客户端绑定spacetime generate --lang typescript --out-dir src/module_bindings --module-path spacetimedbpnpm spacetime:publish:local发布到本地服务器spacetime publish --module-path spacetimedb --server localpnpm spacetime:publish发布到主云maincloudspacetime publish --module-path spacetimedb --server maincloud服务端模块自身的构建与发布脚本位于 templates/vue-ts/spacetimedb/package.jsonspacetime build/spacetime publish。此外spacetime dev还提供了若干常用参数见 crates/cli/src/subcommands/dev.rs 中的参数定义可在不同场景下灵活使用参数说明-t, --template TEMPLATE指定初始化模板 ID 或 GitHub 仓库--module-path PATH服务端模块路径默认project-path/spacetimedb--module-bindings-path PATH生成的客户端绑定目录默认src/module_bindings须为相对路径--client-lang LANG指定生成绑定的语言如typescript、csharp、rust缺省时从项目自动探测--run COMMAND覆盖spacetime.json中的客户端开发服务器启动命令--server-only只运行服务端模块不启动客户端--skip-publish/--skip-generate跳过发布 / 跳过绑定生成步骤--env ENV配置环境名如dev、stagingdev命令下默认dev--no-config忽略spacetime.json配置--server SERVER指定发布目标服务器本地默认local模板约定服务端代码统一放在spacetimedb/目录下这也是spacetime dev对模板项目的统一要求见 crates/cli/src/subcommands/dev.rs 中的注释说明。下一步查阅 TypeScript SDK Reference获取完整的客户端 API 文档连接器、订阅、查询构建器等在 templates/vue-ts 模板基础上继续探索扩展person表字段如t.u32()、t.boolean()、新增归约器、或利用init钩子写入种子数据把VITE_SPACETIMEDB_HOST指向远端服务器或spacetime publish --server maincloud发布到云端体验多客户端实时同步效果。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表