# 官方扩展:`ext/web` 动态网站
| | |
|---|---|
| 状态 | **Superseded(作者面)· 历史能力档案** — 现行作者面见 **[ext-web-artifact.md](ext-web-artifact.md)** · ADR [0007](../adr/0007-web-document-endpoint.md) |
| 日期 | 2026-08-11(W8:2026-08-29;请求上下文:2026-09-18;Artifact 重构:2026-09-28) |
| 相关 | [ext-web-artifact.md](ext-web-artifact.md) · [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) · **[ext-web-request-context.md](ext-web-request-context.md)** |
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
| 本文目的 | **历史**类 API 与能力矩阵;新站请勿按本文 `compose_*` / `app.configure` 写作 |
> **2026-09-28**:作者面迁移到 Document / Endpoint / Resource。C1 已由 ADR 0007 修订。下文保留作迁移对照,**不是**现行推荐 API。
---
## 0. 一句话
**现行**:`.mq.md` Artifact(`type: web|endpoint`)描述页面与交互;见 [ext-web-artifact.md](ext-web-artifact.md)。
**历史(废止)**:`ext/web` 曾用 GFM 表格 + `# page`/`# app` 类方法拼装站点。该模型因 God Object / 碎片 DSL / 隐式路由被破坏性替换。
---
## 1. 为何要做网络扩展库
### 1.1 问题
若没有专用扩展,作者只能:
- 手写 JSON 袋、`json.set` 拼装组件/样式;或
- 要求改语言(让表格单元格求值、点号取值等)。
二者都破坏 Marqdo 的「代码即文档」。
### 1.2 答案
在 **`ext/web/web.mq.md`(英文)** 与 **`ext/web/网页.mq.md`(中文)** 中各提供一套 **`#` 类**:
- 作者只写**表** + **少量实例方法调用**;
- 表单元格保持**字面量**;
- **寻址字符串**由类方法解析;
- **导入英文文件 → 只用英文 API;导入中文文件 → 只用中文 API**(见 [stdlib-i18n.md](stdlib-i18n.md))。
### 1.3 硬约束(评审锁定)
| # | 约束 |
|---|------|
| C1 | **修订(ADR 0007)**:核心可识别 Artifact `type: web\|endpoint`(及 ZH);**不**新增 CORE_CONSTRUCTS 标记;单元格求值 / import 句法不变;装配语义仍在 ext + plugin。旧文「禁止为 web 改核心」作废 |
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水(现行见 ext-web-artifact A2) |
| C3 | 中英分文件;同文件禁止混 API(现行 A3) |
| C4 | **废止**「页面表 + compose」心智 → Document Artifact + `pages/` · `api/` |
| C5 | 破坏性重写作者面(ADR 0007);原生 Go 演进见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) |
| C6 | DB 迁至 **`ext/data`**;CRUD 仍须完整(`select` / `查询`) |
| C7 | 表单校验仍须在写库前执行;挂载经 declared Endpoint / system `/_form`(inspect 可见) |
| A1–A8 | **现行硬约束**见 [ext-web-artifact.md](ext-web-artifact.md) §9 |
---
## 2. 作者心智与目录
```text
myapp/
index.mq.md # 入口 + 首页:页面表 +(可选)就地主体表 + 类方法 + listen
pages/ # 子页:同形的页面表(导出布局表或由入口再装配)
components/ # 可复用组件:导出与路径同名的 ##,体为 |属性|值|样式|
styles/ # 样式模块:每个样式一个 ##,体为 |属性|值|
db/ # 库:schema 表 +(可选)open/种子
data/ # sqlite 等运行时数据(gitignore)
```
| 表种 | 列 | 一句话 |
|------|-----|--------|
| **页面表** | `组件` \| `样式` | 本页用哪些组件、各套哪套样式 |
| **组件 / 主体表** | `属性` \| `值` \| `样式` | 前端属性 ↔ 取值(库字段或字面量)↔ 样式名 |
| **样式表** | `属性` \| `值` | CSS 声明 |
| **库结构表** | `字段` \| `类型` \| `可空` | schema |
---
## 3. 表内寻址约定(单元格仍是字符串)
单元格**不求值**。下列写法是 **web 扩展约定的路径文本**,由 `# 页面` / `# 样式` / `# 数据库` 的方法解析。
### 3.1 反引号与裸名
| 含义 | 写法 | 例 |
|------|------|-----|
| 要「去导入树 / 定义里解析」的名字 | 反引号 `` `名` `` | `` `nav` ``、`` `title` ``、`` `topnav` ``、`` `articles` ``(表名) |
| 字面量(文案、URL、CSS 属性名/值、SQL 类型、**列名**) | **裸**或 `"…"` | `首页`、`/about`、`font-size`、`integer`、`title`(作为列名时) |
### 3.2 路径形态(锁定)
| 场景 | 形态 | 例 | 方法内语义 |
|------|------|-----|------------|
| 引用导入模块的导出 | `模块.`导出`` | `nav.`nav``、`shell.`topnav`` | 在**站点入口模块**的 import 树上调用 `模块.导出`(零参 `##`),取回表 Value |
| 引用库字段 | `模块.`表`.列` | `articles.`articles`.title` | 模块名 = 命名空间(对应导入的 db 文件);`` `表` `` = 库表名;**列名裸写**(列不是变量)→ 运行时绑定 `表.列` |
| 前端属性名 | `` `title` `` | 组件表「属性」列 | 解析为字段名 `title` |
| 样式引用 | 同「模块.导出」或纯样式名 | `shell.`card-title`` | 取回 `|属性|值|` 表并编译为 CSS 类 |
**刻意不做的事:**
- 不把「组件变量名」魔法等同于「库表名」;
- 不要求作者写 `json.set` 才能把 `nav` 放进袋;
- 不把 `articles.`articles`.title` 做成语言级表达式。
### 3.3 与模块命名空间的关系
- 库名来自 frontmatter 导入(茎名或 `as`),**裸名**,见 [module-namespace.md](module-namespace.md)。
- `nav.`nav`` 中:前段 `nav` = 导入库名;`` `nav` `` = 该库上的 `## nav` 导出。
- 组件/样式文件应导出 **与路径第二段同名的 `##`**,直接返回表(不要 `## bag` / `## bind` 袋)。
---
## 4. 规范示例:`index.mq.md`(作者面唯一样板)
**语言与导入绑定(锁定,纠正手写混用):**
| 导入 | 库名(默认茎) | 类 / 方法 / 形参 |
|------|----------------|------------------|
| `import web:ext/web/web.mq.md` | `web` | **仅英文**:`page` · `compose_components` · `db` · `app` · `components=` … |
| `导入 网页:ext/web/网页.mq.md` | `网页` | **仅中文**:`页面` · `组件装配` · `数据库` · `应用` · `组件=` … |
禁止:`import web:ext/web/web.mq.md` 后写 `web.页面` / `` `页`.组件装配 ``(英文库混中文成员)。
禁止:在 `web.mq.md` 文件内定义中文 `## 组件装配` 别名。中英对等靠**两个文件**,不靠同一文件双份导出。
### 4.1 英文面(导入 `web.mq.md`)
```markdown
---
title: web-site
description: Home = page table; main may be inline; class methods assemble.
import:
web: ext/web/web.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
side: components/side.mq.md
foot: components/foot.mq.md
articles: db/articles.mq.md
db: db/index.mq.md
---
# main
`home` =
| 组件 | 样式 |
|------|------|
| nav.`nav` | shell.`topnav` |
| side.`side` | shell.`side-panel` |
| foot.`foot` | |
Main content is not a reusable component, so it is authored here.
`index` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | articles.`articles`.title | shell.`card-title` |
| `body` | articles.`articles`.body | shell.`card-body` |
*`store` = > db.open *
*`page` = > web.page title="Marqdo Web Site" intro="
Web Site
" *
*`page` = > `page`.compose_components components=`home` *
*`page` = > `page`.compose_main main=`index` *
*`app` = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
> `app`.listen
```
说明:表头列名可用中文(`组件`/`样式`/`属性`/`值`)——那是**表约定词汇**,不是库成员名;库成员必须与导入语言一致。
### 4.2 中文面(导入 `网页.mq.md`)
```markdown
---
title: 站点
导入:
网页: ext/web/网页.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
side: components/side.mq.md
foot: components/foot.mq.md
articles: db/articles.mq.md
db: db/index.mq.md
---
# main
`首页` =
| 组件 | 样式 |
|------|------|
| nav.`nav` | shell.`topnav` |
| side.`side` | shell.`side-panel` |
| foot.`foot` | |
主体不是可复用组件,因此就地撰写。
`index` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | articles.`articles`.title | shell.`card-title` |
| `body` | articles.`articles`.body | shell.`card-body` |
*`库` = > db.open *
*`页` = > 网页.页面 标题="站点" 引言="站点
" *
*`页` = > `页`.组件装配 组件=`首页` *
*`页` = > `页`.主体装配 主体=`index` *
*`应用` = > 网页.应用 页面=`页` 数据库=`库` 后台=True 主机=127.0.0.1 端口=18081 *
> `应用`.监听
```
**允许出现在 index 的非表内容:** frontmatter 导入、开库一行、构造页面/应用并装配、`listen` / `监听`。
**不允许:** `json.*` 袋、手写 `/_part` 注册、中英 API 混用。
---
## 5. 类 API(分文件 · 分语言)
依据 [stdlib-i18n.md](stdlib-i18n.md):**导入哪个文件,就用哪套名字。**
`ext/web/web.mq.md` = 全英文;`ext/web/网页.mq.md` = 全中文。中文实现可委托插件同一套原语,或薄封装英文库,但**对外导出的 `#` / `##` / 形参名必须是中文**。
### 5.1 页面 · `page` / `页面`
**英文(`web.mq.md`):**
```markdown
# page
+ `title`=…
+ `intro`=…
## compose_components
+ `components` # page table |组件|样式|
## compose_main
+ `main` # bind table |属性|值|样式|
```
**中文(`网页.mq.md`):**
```markdown
# 页面
+ `标题`=…
+ `引言`=…
## 组件装配
+ `组件`
## 主体装配
+ `主体`
```
| 行为 | 说明 |
|------|------|
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=`index`) |
| compose_list / 列表装配 | 副绑定(独立 query/order);可选 target 注入引言元素;见 [ext-web-request-context.md](ext-web-request-context.md) |
**槽位推断:** 由组件导出名决定(`nav`→顶栏,`side`→侧栏,`foot`→底栏;其余→main)。
### 5.2 样式 · `style` / `样式`
**英文:** `# style` · `## process` · `+ style=` / `name=` / `path=`
**中文:** `# 样式` · `## 样式处理` · `+ 样式=` / `名=` / `路径=`
页面装配可内部调用;作者一般不必在 index 显式调。
### 5.3 数据库 · `db` / `数据库`
完整**增删改查**;页面绑定、种子、`/admin`、表单提交共用。
**英文(`web.mq.md`):**
```markdown
# db
+ `url`=…
## init
+ `name`
+ `fields` # or table= schema
## insert
+ `table`
+ `rows`
## select
+ `table`
+ `where`=None # optional simple filters
+ `limit`=200
## get
+ `table`
+ `id`
## update
+ `table`
+ `id`
+ `row`
## delete
+ `table`
+ `id`
## exec
+ `sql`
+ `args`=None # escape hatch: raw SQL (not everyday authoring)
```
**中文(`网页.mq.md`):**
```markdown
# 数据库
+ `地址`=…
## 初始化
+ `数据库表` # 或 名= + 字段=
## 插入
+ `表`
+ `行` # 或 多行=
## 查询
+ `表`
+ `条件`=None
+ `上限`=200
## 获取
+ `表`
+ `id`
## 更新
+ `表`
+ `id`
+ `行`
## 删除
+ `表`
+ `id`
## 执行
+ `sql`
+ `参数`=None
```
| 中文 | 英文 | 职责 |
|------|------|------|
| 初始化 | `init` | 建表;登记表名 |
| 插入 | `insert` | 增 |
| 查询 | `select` | 查列表(可带简单条件 / limit) |
| 获取 | `get` | 按主键一行 |
| 更新 | `update` | 改 |
| 删除 | `delete` | 删 |
| 执行 | `exec` | 可选原始 SQL(进阶) |
`table=` / `表=` 接受表名或句柄;行数据优先 GFM 表。
**命名锁定:** 列表查询用 `select` / `查询`,**不用** `all`;原始 SQL 用 `exec` / `执行`,避免与 `select` 混淆。
### 5.4 应用 · `app` / `应用`
**英文:** `# app` · `## route` · `## static` · `## listen` · 形参 `page` `db` `admin` `host` `port`
**中文:** `# 应用` · `## 路由` · `## 静态` · `## 监听` · 形参 `页面` `数据库` `后台` `主机` `端口`
`listen` / `监听`:加载插件、注入 `db_url`、按页面 part 提供 `/_part/{id}`(首页)与 `{path}/_part/{id}`(`app.route` 页)、可选 `static` 目录挂载、启动 HTTP。作者不必手写 part 注册。
`static` / `静态`:`dir=`(或 `目录=`)+ 可选 `mount=`(默认 `/static`);`listen` 时用 `tower-http` 提供只读文件服务。
### 5.5 表单 · `form` / `表单`(规划锁定)
用户输入也走「表 + 类方法」,与页面/库同一心智;**提交最终调用 `# db` 的 insert/update**,不另开旁路。
**英文(`web.mq.md`):**
```markdown
# form
+ `table`=None # bound db table name (optional until submit)
+ `action`=insert # insert | update
+ `id`=None # required when action=update
## fields
+ `fields` # |字段|标签|类型|必填|默认|…
## validate
+ `rules`=None # |字段|规则|消息|… (optional extra rules)
+ `data` # submitted row / map
## render
# → HTML form (or form descriptor for page slot)
## submit
+ `data`
+ `db` # db handle
```
**中文(`网页.mq.md`):**
```markdown
# 表单
+ `表`=None
+ `动作`=插入 # 插入 | 更新
+ `id`=None
## 字段
+ `字段`
## 校验
+ `规则`=None
+ `数据`
## 渲染
## 提交
+ `数据`
+ `数据库`
```
#### 5.5.1 字段表(作者面)
```markdown
`文章表单` =
| 字段 | 标签 | 类型 | 必填 | 默认 |
|------|------|------|------|------|
| title | 标题 | text | true | |
| body | 正文 | textarea | false | |
```
| 列 | 含义 |
|----|------|
| `字段` | 对应库列名(裸名或 `` `列` ``,与 schema 对齐) |
| `标签` | 展示文案(字面量) |
| `类型` | 控件/值类型:`text` `textarea` `number` `email` `url` `checkbox` `select` … |
| `必填` | 是否必填 |
| `默认` | 可选默认值 |
| `来源` / `source` | 可选;见 [ext-web-request-context.md](ext-web-request-context.md):`client`(默认)/ `session.username` / `route.NAME` / `now`;非 client 不渲染且服务端盖戳 |
#### 5.5.2 校验表(作者面)
```markdown
`文章校验` =
| 字段 | 规则 | 消息 |
|------|------|------|
| title | required | 标题不能为空 |
| title | max:120 | 标题过长 |
| body | max:8000 | 正文过长 |
```
| 规则(初版) | 含义 |
|--------------|------|
| `required` | 非空 |
| `min:N` / `max:N` | 字符串长度或数值范围 |
| `email` / `url` | 格式 |
| `match:字段` | 与另一字段相等(如确认密码) |
| `in:a,b,c` | 枚举 |
schema 上的「可空 / 类型」在 **submit 时自动并入校验**(不必重复写 `required`,但校验表可覆盖消息)。
#### 5.5.3 行为流程
```text
render → 按字段表出 HTML(或嵌入 page 主区)
用户填写 → POST /_form/{id} 或同页提交
validate → 合并 schema + 校验表;失败则带回字段级错误、不写库
submit → action=insert → db.insert;action=update → db.update
→ 成功后刷新槽位或跳转(由 form 选项约定)
```
| 层 | 校验 |
|----|------|
| **服务端(必须)** | `validate` 在写库前执行;唯一可信边界 |
| **浏览器(可选增强)** | 同源规则可生成 `required`/`maxlength` 等 HTML 属性;**不能**替代服务端 |
`/admin` 的新建/编辑页 = 内置 form:字段来自 schema,校验来自类型/可空;与站点自定义 form **同一套** `validate` + `db.insert`/`update`。
#### 5.5.4 与页面的关系
- 表单可以是独立路由页,或页面表里的一个「组件」导出(仍用 `|属性|值|样式|` 描述展示,提交走 form 类)。
- **`page.compose_form id=… form=…`**:把 form 嵌入该页主区;`listen` 从首页与路由页收集表单并挂载 `/_form/{id}`(`app.mount_form` 仍可用)。校验失败时若表单有所属页,则带回该页壳重渲染。
### 5.6 文件职责
| 文件 | 内容 |
|------|------|
| `ext/web/web.mq.md` | 英文 `# page` `# style` `# db` `# form` `# app` |
| `ext/web/网页.mq.md` | 中文 `# 页面` `# 样式` `# 数据库` `# 表单` `# 应用`(可包装英文实现,**不得**把中文名写进 `web.mq.md`) |
---
## 6. 模块导出形状(配合寻址)
### 6.1 组件 `components/nav.mq.md`
```markdown
## nav
`nav` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | `nav`.`title` | |
| `href` | `nav`.`href` | |
**`nav`**
```
说明:组件**内部**绑定仍可用 `` `表`.`列` ``(表名+列名皆引用)。与 index 主体里「模块命名空间 + 裸列名」的 `articles.`articles`.title` 分工:
- **跨文件、带导入命名空间** → `模块.`表`.列`;
- **组件文件内、表已明确** → `` `表`.`列` `` 即可。
(若评审希望全站统一为一种形态,可在评审意见中二选一;默认允许上述两种。)
### 6.2 样式 `styles/shell.mq.md`
每个样式一个 `##`,**禁止** `## bag` + `json.set`:
```markdown
## topnav
… |属性|值| …
**`topnav`**
## card-title
…
```
### 6.3 库 `db/articles.mq.md` / `db/index.mq.md`
- `articles`:`## schema`(或同名导出)返回结构表;
- `index`:`## open` → 确保插件、建库、init、幂等种子,返回 `# 数据库` 句柄。
---
## 7. 运行时职责划分
```text
作者 .mq.md 表(字面量单元格)
│
▼
ext/web 类方法(Marqdo)
│ 解析路径;需要时经 ABI host_query
│ 调用入口模块 import 树上的 lib.member
▼
plugins/web(HTTP / SQL / HTML 壳)
│
▼
浏览器:四区布局 + /_part 局部刷新 + /admin(可选)
```
| 层 | 做 | 不做 |
|----|----|------|
| Marqdo 核心 | 表→Value、类/方法、import | 不识别 web 路径语法 |
| `ext/web/*.mq.md` | 作者 API、中英面、委托插件 | 不直接 `host_*` |
| `plugins/web` | **Go** `libweb`(HTTP / SQL / HTML 壳;见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md)) | 不要求作者写袋 |
**实现要点(评审通过后再做):**
1. ABI `host_query("call_lib_path")`:在**站点入口模块**上执行 `lib.member`;
2. 插件函数由类方法调用(如 compose_components / compose_main);
3. `listen` 合并页面内 part,注入 `db_url`。
---
## 8. 全部废弃 · 从头开发(锁定)
**旧有网络扩展库内容一律作废**,包括但不限于:
| 范围 | 处理 |
|------|------|
| [`plugins/web/`](../../plugins/web/) | 评审通过后**删除或清空**,按本文重写 cdylib |
| [`ext/web/`](../../ext/web/)(`web.mq.md` / `网页.mq.md` / templates) | 同上,**不**在旧 L1 上打补丁 |
| 依赖旧 API 的示例(如当前 `examples/web-site`、`web-demo`、`man-write-site` 可跑胶水版) | 按 §4 规范重写或暂时移除 |
| 依赖旧 API 的 gold / 单测 | 删除后按新 API 重写 |
| 本文之前的袋式 / assemble / wire / `## bag` 等作者面 | 永久移出正典 |
**禁止**:在遗留代码上「修到能跑」再文档化。
**允许**:实现时参考旧代码中的 HTTP/SQLite 技术经验,但**新树另起**,不以 ABI 表面或作者面兼容为目标。
历史摸索中明确不再回归的作者面模式:
- `json.parse` / `json.set` 拼 components/styles 袋;
- 手写 `web.assemble` + 袋参数;
- 手写 part JSON + `` `app`.part ``;
- `|前端变量|后端数据库|` 填路由;
- 「变量名即表名」魔法默认表;
- 样式 `## bag`;掏空 index 只留 `wire.boot`。
---
## 9. 非本波次(可记入路线图)
- Postgres / Redis / S3 驱动细节(SQLite 已落地);
- ~~复杂权限与多租户~~ → **可配置 RBAC** 见 [ext-web-rbac.md](ext-web-rbac.md);**多租户** 见 [ext-web-tenant.md](ext-web-tenant.md)(path/subdomain/header + `tenant_scope`);
- ~~重客户端 SPA~~ → **Native SPA** 见 [ext-web-spa.md](ext-web-spa.md)(WASM + 路由表 + `store_set` memory);
- ~~实时协同编辑~~ → **Collab MVP** 见 [ext-web-collab.md](ext-web-collab.md)(WS room LWW 文本 + presence);
- 子页路由糖的更多约定(`# 应用.route` 已够用)。
---
## 10. 评审清单
请确认或批注:
1. **§3 路径**:`模块.`导出`` 与 `模块.`表`.列`(列裸名)是否定为唯一正典?组件内 `` `表`.`列` `` 是否保留?
2. **§4 index**:开库是否允许单独一行 `` db.open ``,还是必须进一步藏进 `web.应用`?
3. **§5 分文件**:英文 `web.mq.md` / 中文 `网页.mq.md` 是否严格分语言、禁止混排?
4. **§5.3**:列表查询用 `select` / `查询`、原始 SQL 用 `exec` / `执行` 是否认可?
5. **§5.5 表单/校验**:字段表、校验表、服务端必校、admin 共用是否认可?
6. **§5 槽位**:仅由组件导出名推断,是否足够?
7. **§8 废弃**:是否确认**全部推倒重来**、不兼容旧实现?
评审通过后:冻结本文为 Accepted → **清空旧 web 扩展代码** → 按本文从零实现(骨架 → db CRUD/`select` → form/validate → 页面装配 → app listen → 规范示例 → gold)。