Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the old one-liner form, and migrate lib/ext/examples/tests/docs accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>
126 lines
4.0 KiB
Markdown
126 lines
4.0 KiB
Markdown
# `ext/web` 驱动:Postgres · Redis · S3
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Accepted · 已落地** |
|
||
| 日期 | 2026-08-28 |
|
||
| 相关 | [ext-web.md](ext-web.md) · [roadmap/ext-web.md](../roadmap/ext-web.md) · [ext-abi.md](ext-abi.md) |
|
||
| 目标 | 在**不改作者面 CRUD 心智**的前提下,用 URL 方案切换数据库;另增缓存与对象存储两类驱动。贯彻「表格 + 类方法」:配置即数据,装配即函数。 |
|
||
|
||
---
|
||
|
||
## 0. 一句话
|
||
|
||
**`# db` 的 `url=` 决定后端**:`sqlite:` 默认;`postgres://` / `postgresql://` 走 Postgres,作者面 API 不变。
|
||
**缓存**与**对象存储**是独立类(`# cache` / `# storage`),不塞进 `# db`。
|
||
|
||
---
|
||
|
||
## 1. 边界
|
||
|
||
| 能力 | 归属 | 理由 |
|
||
|------|------|------|
|
||
| SQLite / Postgres CRUD | `plugins/web` + `ext/web` `# db` | 同一套 `init/select/insert/…`;热路径 ABI |
|
||
| Redis 缓存 | `plugins/web` + `ext/web` `# cache` | 键值语义,不是表 CRUD |
|
||
| S3 / MinIO 对象 | `plugins/web` + `ext/web` `# storage` | 对象键 + 字节/路径,不是行 |
|
||
| 禁止 | 核心 `src/host/` | 驱动依赖重,只进 ABI 插件 |
|
||
|
||
---
|
||
|
||
## 2. URL 方案(锁定)
|
||
|
||
| 方案 | 含义 | 例 |
|
||
|------|------|-----|
|
||
| `sqlite:` / 裸路径 | SQLite 文件(既有) | `sqlite:data/site.db` |
|
||
| `postgres://` / `postgresql://` | Postgres | `postgres://user:pass@127.0.0.1:5432/app` |
|
||
| `redis://` / `rediss://` | Redis | `redis://127.0.0.1:6379/0` |
|
||
| `memory:` | **进程内** Redis 兼容后端(金样/离线) | `memory:` |
|
||
| `s3://bucket` + 查询参数 | S3 兼容(含 MinIO) | `s3://mybucket?endpoint=http://127.0.0.1:9000®ion=us-east-1` |
|
||
| `file:` | **本地目录**对象存储(金样/离线) | `file:data/blobs` |
|
||
|
||
凭证:优先 URL 内嵌;S3 亦读环境变量 `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`(或 `S3_ACCESS_KEY` / `S3_SECRET_KEY`)。
|
||
|
||
---
|
||
|
||
## 3. 作者面(代码即文档)
|
||
|
||
### 3.1 数据库 — 只换 URL
|
||
|
||
英文:
|
||
|
||
```markdown
|
||
import:
|
||
web: ext/web/web.mq.md
|
||
|
||
# main
|
||
|
||
*store = > web.db url="postgres://marqdo:marqdo@127.0.0.1:5432/site"*
|
||
*store = > store.init name="posts" fields=`schema`*
|
||
```
|
||
|
||
中文:`网页.数据库` + `url=` 同形。`init` / `select` / `insert` / `paginate` / `事务` **API 不变**。
|
||
|
||
Postgres 差异(实现层消化,作者尽量无感):
|
||
|
||
- `id INTEGER PRIMARY KEY` → `SERIAL PRIMARY KEY`(或 `GENERATED …`)
|
||
- 占位符 `?` → `$1,$2,…`
|
||
- 标识符双引号规则对齐
|
||
|
||
### 3.2 缓存 `# cache` / `# 缓存`
|
||
|
||
```markdown
|
||
*c = > web.cache url="memory:"*
|
||
*c = > c.set key="k" value="v" ttl=60*
|
||
*v = > c.get key="k"*
|
||
*c = > c.del key="k"*
|
||
```
|
||
|
||
方法:`get` · `set`(可选 `ttl` 秒)· `del` · `exists` · `ttl`。
|
||
|
||
配置表可选(装配时合并进 url / 默认 TTL):
|
||
|
||
| 键 | 值 |
|
||
|----|-----|
|
||
| url | redis://127.0.0.1:6379/0 |
|
||
| ttl | 3600 |
|
||
|
||
### 3.3 对象存储 `# storage` / `# 存储`
|
||
|
||
```markdown
|
||
*blob = > web.storage url="file:data/blobs"*
|
||
> `blob`.put key="avatar/1.png" path="local.png" content_type="image/png"
|
||
*got = > `blob`.get key="avatar/1.png"*
|
||
> `blob`.delete key="avatar/1.png"
|
||
*keys = > `blob`.list prefix="avatar/"*
|
||
```
|
||
|
||
方法:`put`(`path=` 本地文件或 `body=` 文本)· `get`(返回 `{ok, body|path, content_type}`)· `delete` · `list`。
|
||
|
||
---
|
||
|
||
## 4. ABI 名
|
||
|
||
| ABI | 说明 |
|
||
|-----|------|
|
||
| 既有 `web_db_*` | 内部按 `url` 方案分发 SQLite / Postgres |
|
||
| `web_cache_new/get/set/del/exists/ttl` | 缓存 |
|
||
| `web_storage_new/put/get/delete/list` | 对象存储 |
|
||
|
||
---
|
||
|
||
## 5. 测试
|
||
|
||
| 金样 | 内容 |
|
||
|------|------|
|
||
| `tests/ext/web-drivers-smoke.mq.md` | `memory:` 缓存往返;`file:` 存储 put/get/list/delete;`web_db_new` 接受 `postgres://` 句柄形状(不要求本机有库) |
|
||
| 可选 live | `MARQDO_TEST_POSTGRES` / `MARQDO_TEST_REDIS` / `MARQDO_TEST_S3` 非空时跑真实连通(CI 默认关) |
|
||
|
||
---
|
||
|
||
## 6. 非本波次
|
||
|
||
- 连接池大小 / 读写分离配置表
|
||
- Redis 集群 / Sentinel
|
||
- S3 预签名 URL 作者面糖(可后续加方法)
|
||
- 把 session 默认改存 Redis(仍默认 SQLite 表;可选后续)
|