把服务端 Python 应用搬进浏览器,难点不只是让 Python 代码跑起来,还要让页面跳转、JavaScript、CSS 和插件像正常网站一样工作。
Datasette Lite 的重写,重点解决的就是后一层问题:通过 WebAssembly 和 Pyodide 执行 Python,通过 Service Worker 接管页面与资源请求,让浏览器中的 Datasette 更接近常规服务端部署的使用体验。
用一个 URL 描述演示环境
Datasette Lite 支持通过 URL 参数组合应用、数据和依赖配置,包括:
- 加载 SQLite 数据库、JSON、CSV 或 SQL 脚本。
- 从 PyPI 加载指定的 Datasette 发布版本。
- 指定 Datasette 代码仓库中的提交、标签或分支。
- 选择不同版本的 SQLite。
- 从 PyPI 或 wheel 文件地址安装额外插件,包括使用 JavaScript 的可视化插件。
这类配置既适合分享开发中的功能,也适合构造缺陷复现环境,无须为每个演示单独启动完整的 Web 服务器。
例如,安装 datasette-maplibre 插件,并加载包含国家 GeoJSON 边界的数据库后,可以展示汇总地图,以及数据表中的单独边界地图。
常用参数
| 参数或片段 | 作用 |
|---|---|
install |
安装插件,可重复传入以加载多个插件 |
url |
指定要加载的数据库文件地址 |
metadata |
加载元数据配置,为首页和表格添加说明等内容 |
ref |
指定 Datasette 版本或代码引用 |
sql |
加载 SQL 脚本 |
sqlite |
选择 SQLite 版本 |
#/… |
指定应用内页面及相关界面状态 |
通过地址加载远程数据时,文件托管端需要提供允许跨域读取的 CORS 响应头。
URL 片段也可以携带嵌套的界面状态。例如,%23 是 # 的 URL 编码,可用于在指定数据视图的同时,向地图插件传递视角和着色字段。
旧版为什么难以支持 JavaScript 插件?
Datasette Lite 的首版于 2022 年推出。它在 Web Worker 中运行 Pyodide 和 Datasette,模拟请求,再用 innerHTML 把返回的 HTML 插入顶层页面。
这种方式能展示基本页面,但存在两个限制:
- 通过
innerHTML插入的脚本标签不会执行。 - 当时的请求模拟方式无法正常加载额外的 JavaScript 和 CSS 文件。
因此,能执行 Python,不等于能完整运行一个带前端交互的 Web 应用。 问题不只在语言运行时,还在浏览器如何获取和处理应用的响应。
新架构:拦截请求,而不是插入 HTML
新版让父页面创建一个 iframe,并用 Service Worker 拦截 iframe 发出的页面和静态资源请求。请求路径采用统一的会话前缀:
/app/<session>/
/app/<session>/data/places
/app/<session>/-/static/navigation-search.js
/app/<session>/-/static/app.css
一次请求大致经过以下流程:
- iframe 请求某个 Datasette 页面或资源。
- Service Worker 拦截请求,并将其交给对应标签页。
- 父页面脚本把请求转发给 Web Worker。
- Web Worker 中的 Pyodide 运行 Python,通过 ASGI 桥接层调用 Datasette;需要时查询 SQLite。
- 状态码、响应头和响应体沿相反路径返回。
- Service Worker 向浏览器交付
Response,由 iframe 正常加载和渲染。
可以把它理解为一条运行在浏览器内部的请求链路:
iframe
→ Service Worker
→ 父页面
→ Web Worker:Pyodide → ASGI → Datasette → SQLite
→ 响应沿原路径返回
关键变化是:浏览器拿到的是请求对应的响应,而不是被手动塞进页面的 HTML。 页面脚本和样式资源因此能够沿正常加载路径工作。
多个标签页如何互不干扰?
同一站点的 Service Worker 会被多个标签页共享。如果所有请求都指向同一个 Datasette 实例,不同演示所需的插件和配置就会混在一起。
为此,每个父页面都会生成随机会话 ID,并把它放进 /app/<session>/ 路径。Service Worker 根据这个 ID,将请求转发给对应标签页及其专属 Web Worker。
各部分的职责如下:
| 组件 | 职责 |
|---|---|
| Service Worker | 拦截和路由请求 |
| 父页面 | 中转消息、关联会话 |
| Web Worker | 运行 Pyodide、Datasette 和数据库 |
| iframe | 加载与展示应用页面 |
保留 Web Worker 还有生命周期方面的考虑:Service Worker 可能被浏览器终止,不能依赖它长期保存 Python 运行状态。 因此,请求路由与应用运行时被放在了不同组件中。
用版本切换复现问题
指定版本的价值不仅在于试用功能,也在于对比行为变化。
一个分页问题的演示分别指定了 Datasette 1.0a42 和 1.0a43:前者点击下一页后出现空白的第二页,后者展示修复后的行为。将相同数据与页面参数搭配不同版本,就能直接比较修复前后的表现。
SQLite 也采用类似方式:sqlite 参数会解析到对应的 WebAssembly wheel,将其安装进 Pyodide 环境,再配置 Datasette 使用该版本。
配套的 SQL 对比工具还能在多个 SQLite 版本上执行同一条查询,用于检查版本间的结果差异。
其他 Python 应用能否采用这套方案?
这套请求转发架构并不依赖 Datasette 独有的能力,可以作为其他 Python 应用构建浏览器预览环境的参考。对于在 写好标智库 等社区交流开发工具设计的读者,一个值得讨论的问题是:哪些应用适合把运行环境直接编码进可分享的 URL?
不过,迁移仍有边界:
- 依赖兼容性:包含 C 或 Rust 扩展的依赖,需要兼容 Pyodide 的 WebAssembly 构建。
- 数据库选择:SQLite 已适合这种运行方式,PostgreSQL、MySQL 等方案则没有同样成熟的实践路径。
Datasette Lite 展示了一种值得关注的开发工具形态:用 URL 描述应用、数据与版本组合,让功能演示和缺陷复现环境直接在浏览器中运行。它的关键不只是“Python 能在浏览器里执行”,还在于通过请求转发,让整个 Web 应用沿浏览器正常的页面与资源加载路径工作。

Top comments (0)