本地优先 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/postgres`

PowerSync：同步引擎

进入 PowerSync，访问 PowerSync.com，创建免费账户，然后启动新项目，打开项目详细信息。

在 PowerSync 仪表板中，创建与 Supabase 的连接，按以下步骤操作：

1. 点击“Create New Instance”。
2. 点击左侧“Database Connections”，然后点击“+”按钮。
3. 粘贴从 Supabase 复制的连接字符串。注意：若字符串中有 `[YOUR-PASSWORD]` 占位符，将其替换为为实例创建的实际密码。
4. 点击“Test Connection”。PowerSync 会连接到之前创建的 Postgres 实例。若在 Supabase 设置中正确运行 `CREATE PUBLICATION` SQL 命令，这一步将成功，会看到绿色“Connection Successful!”状态消息。

配置身份验证

已告诉 PowerSync 如何读取 Supabase 数据（Postgres），现在要告诉它如何信任用户，步骤如下：

1. 在 PowerSync 仪表板中，点击“Client Auth”选项卡。
2. 找到“JWKS URI”字段。
3. 构建 JWKS URL，它是 Supabase 项目 URL 加特定后缀，格式为：`https://[YOUR-PROJECT-ID].supabase.co/auth/v1/.well-known/jwks.json`。注意：可从 Supabase > Settings > API 获取项目 URL。
4. 将 JWKS URL 粘贴到“JWKS URI”字段中，然后点击“Save”。
5. 将“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 install

`npm` 命令完成后，需将应用指向刚刚创建的基础设施，可使用 `.env.local` 环境变量文件实现。打开 `.env.local`，将变量更改为指向服务，代码如下：

VITE_SUPABASE_URL=https://fooizpddffaabqcydusj.supabase.co VITE_SUPABASE_ANON_KEY=sb_publishable_gqUrYxDt04rg74fopz5rUg_ayDxpmgE VITE_POWERSYNC_URL=https://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 应用中，使用原始 SQL：

const { 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 API（REST 或 GraphQL）方法仍是首选。在这些模型中，服务器是唯一的数据源，客户端只是简单的终端。它简单、无状态且易于调试，也很常见。但这种简单性不可避免地带来了延迟成本。每次交互都需要与服务器进行往返通信。如果网络出现问题，应用程序就会冻结。JSON API 要求手动管理加载状态、错误边界和乐观 UI 回滚。

本地优先则改变了这种情况。需要在前期付出更高的成本：需要定义模式、管理本地数据库并考虑同步规则。但作为回报，将获得感觉像原生软件的应用程序。本地优先实现了数据的连续性，即使离开 Wi-Fi 范围也能继续工作，重新连接后数据会在不同设备间同步。

从架构上看，使用了三个主要组件：数据库、同步引擎和客户端。这实际上与传统的 RESTful 栈类似。在本地优先架构中，同步引擎取代了 JSON API 服务器的角色。简而言之，整体复杂度相似，但具体实现有所不同。

本地优先架构对于 JavaScript 和 Web 开发来说是一个令人着迷的发展方向。虽然要克服 JSON API 的巨大惯性并不容易，但这确实是一股新的潮流。本地优先可能永远无法达到 RESTful 架构的普及程度，但本地优先数据和响应式 SQL 是目前值得密切关注的重要趋势之一。

关键词：Web 开发、开发方法、软件开发、库和框架