本地优先 Web 应用开发：React/SQLite 前端、Supabase 后端与 PowerSync 同步引擎实践

本地优先 Web 应用开发React/SQLite 前端、Supabase 后端与 PowerSync 同步引擎的实践与优势并非每天都会出现全新架构如今浏览器内的 SQLite 结合响应式 SQL 和自动同步功能出现了它能让前端即时交互还能保持与后端数据一致作为 RESTful 思维模式的挑战者值得深入探究。并非全新而是改进这个想法并非全新概念多年来开发者一直以各种方式做类似事情如某些应用的离线功能。但这新一代技术栈有所不同开始受广泛关注它叫本地优先数据。此前已宏观介绍该概念现在深入探究细节。其概念简单应用无需向远程服务器请求更改数据权限而是直接将状态写入浏览器中运行的本地 SQLite 数据库通过 WebAssembly然后复杂的后台引擎会将更改同步到云端和其他设备。对 React 开发者来说仍处于响应式范式即便编写原始 SQL 查询数据处理也会自动完成。UI 组件会订阅数据库数据变化时不管是用户本地点击还是云端同步更新UI 会立即更新。就像用 Spotify 时不用下载数百万首歌曲完整目录只下载自己歌单离线也能无延迟收听音乐。用本地优先数据构建的模式类似但功能更强大。可对本地状态进行更改有网络连接时更改会同步到后端也会自动接收外界重要更新。三个架构组件要实现这一点需要三个主要架构组件客户端 UI 和数据库React 和 SQLite Wasm同步引擎PowerSync记录数据库Supabase先设置所需云服务Supabase 和 PowerSync两者都有免费套餐。对于客户端 UI 和数据库使用 Supabase 提供的 React SQLite 演示应用。Supabase记录数据库Supabase 是托管的 Postgres 服务有很多实用功能。示例很简单只需一行数据。访问 Supabase.com创建免费账户然后启动新项目点击项目可查看详细信息。接着创建数据库模式存储数据这是简单模式。在左侧菜单中打开 SQL 编辑器并运行以下代码-- 1. 创建表来存储计数器 CREATE TABLE counters ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), created_at TIMESTAMPTZ DEFAULT NOW(), count INTEGER DEFAULT 0, owner_id UUID DEFAULT auth.uid() ); -- 2. 开启行级安全RLS ALTER TABLE counters ENABLE ROW LEVEL SECURITY; -- 3. 访问策略 CREATE POLICY Users can all on own counters ON counters FOR ALL USING (auth.uid() owner_id); -- 4. 发布表 DROP PUBLICATION IF EXISTS powersync; CREATE PUBLICATION powersync FOR TABLE counters;以上代码各步骤有注释。第一步是标准 SQL 操作创建含几列的表包括随机 UUID 主键。第二步开启行级安全。第三步创建访问策略允许用户访问自己的计数器行由登录 ID 确定auth.uid() owner_id。第四步在 Supabase 实例和 PowerSync 之间建立连接。离开 Supabase 前点击顶部“ Connect”按钮获取连接字符串格式类似postgresql://postgres:[YOUR-PASSWORD]db.fooizpddffaabqcydusj.supabase.co:5432/postgresPowerSync同步引擎进入 PowerSync访问 PowerSync.com创建免费账户然后启动新项目打开项目详细信息。在 PowerSync 仪表板中创建与 Supabase 的连接按以下步骤操作点击“Create New Instance”。点击左侧“Database Connections”然后点击“”按钮。粘贴从 Supabase 复制的连接字符串。注意若字符串中有 [YOUR-PASSWORD] 占位符将其替换为为实例创建的实际密码。点击“Test Connection”。PowerSync 会连接到之前创建的 Postgres 实例。若在 Supabase 设置中正确运行 CREATE PUBLICATION SQL 命令这一步将成功会看到绿色“Connection Successful!”状态消息。配置身份验证已告诉 PowerSync 如何读取 Supabase 数据Postgres现在要告诉它如何信任用户步骤如下在 PowerSync 仪表板中点击“Client Auth”选项卡。找到“JWKS URI”字段。构建 JWKS URL它是 Supabase 项目 URL 加特定后缀格式为https://[YOUR-PROJECT-ID].supabase.co/auth/v1/.well-known/jwks.json。注意可从 Supabase Settings API 获取项目 URL。将 JWKS URL 粘贴到“JWKS URI”字段中然后点击“Save”。将“Audience”设置为“authenticated”点击“Token Claims”下的“() Add”按钮。“Claim”类型选择“aud”“Value”类型选择“authenticated”。此配置告诉 PowerSync“只信任由 Supabase 签名且针对‘authenticated’用户组的令牌。”定义同步规则同步规则是理解架构的关键要素在这里告诉 PowerSync 用户可访问哪些数据这有时也叫用户的数据“形状”。每个用户根据独特配置文件对整体数据有不同“形状”。不想将整个数据库同步到用户笔记本电脑上这在很多方面不可行。相反定义一个同步规则在 PowerSync 中称为“bucket”它是过滤器用于确定哪些数据属于哪个用户。导航到左侧“Sync Rules”会看到 YAML 编辑器将默认代码替换为以下代码edition: 2 bucket_definitions: user_counters: # 1. 从身份验证令牌中识别用户 parameters: SELECT request.user_id() as user_id # 2. 仅同步属于他们的行 data: - SELECT * FROM counters WHERE owner_id bucket.user_id这段代码为用户定义了数据的特殊视图user_counters这是“bucket”即一组数据。request.user_id()PowerSync 会自动从 Supabase 身份验证令牌中提取用户 ID。数据查询此 SQL 在云端运行仅获取 owner_id 列与登录用户匹配的行并将其流式传输到设备。可点击“Validate”检查是否正常工作点击“Deploy”使其生效。React 和 SQLite客户端 UI 和数据库已完成大量管理工作这为构建了基于 SQL 的完整响应式架构。继续开发可使用该架构的客户端为快速了解从 Supabase 克隆演示应用。在命令行中运行$ git clone https://github.com/powersync-community/vite-react-ts-powersync-supabase.git $ cd vite-react-ts-powersync-supabase $ npm installnpm 命令完成后需将应用指向刚刚创建的基础设施可使用 .env.local 环境变量文件实现。打开 .env.local将变量更改为指向服务代码如下VITE_SUPABASE_URLhttps://fooizpddffaabqcydusj.supabase.co VITE_SUPABASE_ANON_KEYsb_publishable_gqUrYxDt04rg74fopz5rUg_ayDxpmgE VITE_POWERSYNC_URLhttps://foofcf18cc2560584a018a12.powersync.journeyapps.com现在可测试 React 应用$ npm run dev:ui演示应用是简单计数器即显示“Increment”按钮并显示计数的网页。虽看起来不特别令人兴奋但背后的数据同步功能很神奇。运行上述命令后会打开浏览器窗口显示“Create Counter”按钮。点击它演示应用会在新窗口中创建计数器同时显示用户 ID 和显示连接和同步状态的面板。可根据需要创建任意数量的计数器每个计数器都在单独的浏览器窗口中。可通过访问 Supabase 仪表板查看“Table”面板确认计数器表中确实为用户插入了一行数据以此验证计数器是否正常工作。另一个好方法是用另一个浏览器/设备或隐身标签登录在第二个浏览器窗口中创建另一个计数器这样可同时看到两个由 Supabase 同步的会话计数器。React 代码App.tsx进展很快但 src/App.tsx 文件中有值得注意的有趣内容。这段代码是应用的主要 React 代码展示了从“向服务器请求数据”到“与本地数据库状态交互”的转变。每个 React 开发者都需关注两个关键部分响应式读取和即时写入。响应式读取useQuery在标准 React 应用中会使用 useEffect 调用 fetch(/api/counters) 来获取数据。在本地优先 React 应用中使用原始 SQLconst { data: counters, isLoading } useQuery( SELECT * FROM ${COUNTER_TABLE} ORDER BY created_at ASC, [], { rowComparator: { keyBy: (item) item.id, compareBy: (item) JSON.stringify(item) } } );这是架构中的“响应式 SQL”部分。useQuery 钩子会订阅本地 SQLite 数据库。当后台工作进程从云端接收到更新或者在本地更新一行数据时这个钩子会立即触发并重新渲染组件。无需手动管理状态或重新获取数据的逻辑也没有中间状态对象。后端状态和前端状态是一致的。即时写入powerSync.execute注意增加计数器时的情况。没有 await api.post(...)也没有加载状态。const updateCounter async (counter: CounterRecord, newCount: number) { // 立即写入本地 SQLite await powerSync.execute( UPDATE ${COUNTER_TABLE} SET count ? WHERE owner_id ?, [newCount, counter.owner_id] ); };这段代码本身很有趣因为它像响应式 SQL 语句。将数据写入本地文件Wasm写入操作在毫秒内完成UI 会通过 useQuery 钩子立即更新。PowerSync 同步引擎会异步捕获更改并将其推送到 Supabase。本地优先与 RESTful 的比较那么所有这些配置和新颖的代码是否值得呢如果构建简单的仪表盘或基于表单的应用程序传统的 JSON APIREST 或 GraphQL方法仍是首选。在这些模型中服务器是唯一的数据源客户端只是简单的终端。它简单、无状态且易于调试也很常见。但这种简单性不可避免地带来了延迟成本。每次交互都需要与服务器进行往返通信。如果网络出现问题应用程序就会冻结。JSON API 要求手动管理加载状态、错误边界和乐观 UI 回滚。本地优先则改变了这种情况。需要在前期付出更高的成本需要定义模式、管理本地数据库并考虑同步规则。但作为回报将获得感觉像原生软件的应用程序。本地优先实现了数据的连续性即使离开 Wi-Fi 范围也能继续工作重新连接后数据会在不同设备间同步。从架构上看使用了三个主要组件数据库、同步引擎和客户端。这实际上与传统的 RESTful 栈类似。在本地优先架构中同步引擎取代了 JSON API 服务器的角色。简而言之整体复杂度相似但具体实现有所不同。本地优先架构对于 JavaScript 和 Web 开发来说是一个令人着迷的发展方向。虽然要克服 JSON API 的巨大惯性并不容易但这确实是一股新的潮流。本地优先可能永远无法达到 RESTful 架构的普及程度但本地优先数据和响应式 SQL 是目前值得密切关注的重要趋势之一。关键词Web 开发、开发方法、软件开发、库和框架