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>
21 KiB
官方扩展:ext/web 动态网站
| 状态 | Superseded(作者面)· 历史能力档案 — 现行作者面见 ext-web-artifact.md · ADR 0007 |
| 日期 | 2026-08-11(W8:2026-08-29;请求上下文:2026-09-18;Artifact 重构:2026-09-28) |
| 相关 | ext-web-artifact.md · markdown-mapping.md · module-namespace.md · objects.md · ext-abi.md · ext-cli.md · stdlib-i18n.md · web-assets-and-images.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 曾用 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)。
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 |
| C6 | DB 迁至 ext/data;CRUD 仍须完整(select / 查询) |
| C7 | 表单校验仍须在写库前执行;挂载经 declared Endpoint / system /_form(inspect 可见) |
| A1–A8 | 现行硬约束见 ext-web-artifact.md §9 |
2. 作者心智与目录
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`` |
取回 ` |
刻意不做的事:
- 不把「组件变量名」魔法等同于「库表名」;
- 不要求作者写
json.set才能把nav放进袋; - 不把
articles.articles.title做成语言级表达式。
3.3 与模块命名空间的关系
- 库名来自 frontmatter 导入(茎名或
as),裸名,见 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)
---
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="<h1>Web Site</h1>" *
*`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)
---
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 *
*`页` = > 网页.页面 标题="站点" 引言="<h1>站点</h1>" *
*`页` = > `页`.组件装配 组件=`首页` *
*`页` = > `页`.主体装配 主体=`index` *
*`应用` = > 网页.应用 页面=`页` 数据库=`库` 后台=True 主机=127.0.0.1 端口=18081 *
> `应用`.监听
允许出现在 index 的非表内容: frontmatter 导入、开库一行、构造页面/应用并装配、listen / 监听。
不允许: json.* 袋、手写 /_part 注册、中英 API 混用。
5. 类 API(分文件 · 分语言)
依据 stdlib-i18n.md:导入哪个文件,就用哪套名字。
ext/web/web.mq.md = 全英文;ext/web/网页.mq.md = 全中文。中文实现可委托插件同一套原语,或薄封装英文库,但对外导出的 # / ## / 形参名必须是中文。
5.1 页面 · page / 页面
英文(web.mq.md):
# page
+ `title`=…
+ `intro`=…
## compose_components
+ `components` # page table |组件|样式|
## compose_main
+ `main` # bind table |属性|值|样式|
中文(网页.mq.md):
# 页面
+ `标题`=…
+ `引言`=…
## 组件装配
+ `组件`
## 主体装配
+ `主体`
| 行为 | 说明 |
|---|---|
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=index) |
| compose_list / 列表装配 | 副绑定(独立 query/order);可选 target 注入引言元素;见 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):
# 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):
# 数据库
+ `地址`=…
## 初始化
+ `数据库表` # 或 名= + 字段=
## 插入
+ `表`
+ `行` # 或 多行=
## 查询
+ `表`
+ `条件`=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):
# 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):
# 表单
+ `表`=None
+ `动作`=插入 # 插入 | 更新
+ `id`=None
## 字段
+ `字段`
## 校验
+ `规则`=None
+ `数据`
## 渲染
## 提交
+ `数据`
+ `数据库`
5.5.1 字段表(作者面)
`文章表单` =
| 字段 | 标签 | 类型 | 必填 | 默认 |
|------|------|------|------|------|
| title | 标题 | text | true | |
| body | 正文 | textarea | false | |
| 列 | 含义 |
|---|---|
字段 |
对应库列名(裸名或 `列`,与 schema 对齐) |
标签 |
展示文案(字面量) |
类型 |
控件/值类型:text textarea number email url checkbox select … |
必填 |
是否必填 |
默认 |
可选默认值 |
来源 / source |
可选;见 ext-web-request-context.md:client(默认)/ session.username / route.NAME / now;非 client 不渲染且服务端盖戳 |
5.5.2 校验表(作者面)
`文章校验` =
| 字段 | 规则 | 消息 |
|------|------|------|
| 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 行为流程
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
## nav
`nav` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | `nav`.`title` | |
| `href` | `nav`.`href` | |
**`nav`**
说明:组件内部绑定仍可用 `表`.`列`(表名+列名皆引用)。与 index 主体里「模块命名空间 + 裸列名」的 articles.articles.title 分工:
- 跨文件、带导入命名空间 →
模块.表.列; - 组件文件内、表已明确 →
`表`.`列`即可。
(若评审希望全站统一为一种形态,可在评审意见中二选一;默认允许上述两种。)
6.2 样式 styles/shell.mq.md
每个样式一个 ##,禁止 ## bag + json.set:
## topnav
… |属性|值| …
**`topnav`**
## card-title
…
6.3 库 db/articles.mq.md / db/index.mq.md
articles:## schema(或同名导出)返回结构表;index:## open→ 确保插件、建库、init、幂等种子,返回# 数据库句柄。
7. 运行时职责划分
作者 .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) |
不要求作者写袋 |
实现要点(评审通过后再做):
- ABI
host_query("call_lib_path"):在站点入口模块上执行lib.member; - 插件函数由类方法调用(如 compose_components / compose_main);
listen合并页面内 part,注入db_url。
8. 全部废弃 · 从头开发(锁定)
旧有网络扩展库内容一律作废,包括但不限于:
| 范围 | 处理 |
|---|---|
plugins/web/ |
评审通过后删除或清空,按本文重写 cdylib |
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-tenant.md(path/subdomain/header +tenant_scope);重客户端 SPA→ Native SPA 见 ext-web-spa.md(WASM + 路由表 +store_setmemory);实时协同编辑→ Collab MVP 见 ext-web-collab.md(WS room LWW 文本 + presence);- 子页路由糖的更多约定(
# 应用.route已够用)。
10. 评审清单
请确认或批注:
- §3 路径:
模块.导出与 `模块.`表`.列`(列裸名)是否定为唯一正典?组件内表.列`` 是否保留? - §4 index:开库是否允许单独一行
db.open,还是必须进一步藏进web.应用? - §5 分文件:英文
web.mq.md/ 中文网页.mq.md是否严格分语言、禁止混排? - §5.3:列表查询用
select/查询、原始 SQL 用exec/执行是否认可? - §5.5 表单/校验:字段表、校验表、服务端必校、admin 共用是否认可?
- §5 槽位:仅由组件导出名推断,是否足够?
- §8 废弃:是否确认全部推倒重来、不兼容旧实现?
评审通过后:冻结本文为 Accepted → 清空旧 web 扩展代码 → 按本文从零实现(骨架 → db CRUD/select → form/validate → 页面装配 → app listen → 规范示例 → gold)。