# 网络能力调研:从「能跑」到「完整项目」 | | | |---|---| | 状态 | **Historical capability matrix** — 作者面以 **[ext-web-artifact.md](ext-web-artifact.md)** / ADR [0007](../adr/0007-web-document-endpoint.md) 为准(2026-09-28) | | 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核)· 2026-09-28(Artifact 标注) | | 相关 | [ext-web-artifact.md](ext-web-artifact.md) · [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) | | 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状;**下文 API 名多为 W0–W7 历史面**(`compose_*` / `configure` 已废止) | > **2026-09-28**:作者面迁移到 Document / Endpoint / Resource。 > - Document/Endpoint:`type: web|endpoint` + `web.serve` / `web.render` / `web.inspect` > - DB/cache/storage → `ext/data`;auth/oidc/rbac → `ext/security`;ws → `ext/net` > - 统一 View:`|type|slot|value|attrs|style|`;中间件:`web.use` > 本文件保留为**原生能力矩阵**对照,勿再按 `compose_*` / `app.configure` 写作。 --- ## 0. 一句话结论 **能力层(plugins/web)**:中间件/JSON API、数据层、安全、内容站点、上传下载、sitemap、WebSocket 等仍在原生实现中。 **作者面(2026-09-28)**:改为 Artifact Metadata + facade;`compose_*` / `configure` **已删除**。边界不变:**纯解析进 `lib/net`,HTTP 服务器进 `plugins/web`,作者 API 进 `ext/web` + `ext/data` + `ext/security` + `ext/net`**。 **宿主集成下一刀**(同域 LLM SSE 中继、HTTP→用户 `##`、与 MCP Server 协作)不在本 W 表内,见 [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-hosting.md](../roadmap/ext-hosting.md)。 --- ## 1. 现状盘点(2026-08-26 实测) ### 1.1 `lib/net`(标准库,L0.5 宿主原语薄包装) | 能力 | 归属 | 现状 | |---|---|---| | `http_get` / `获取` | host `net.rs` (ureq) | ✅ GET,返回 `{status, body}` | | `http_post` / `提交` | host `net.rs` | ✅ POST,默认 JSON CT | | `http_request` / `请求` | host `net.rs` | ✅ 通用 method+body+headers | | `http_post_sse` / `提交流式` | host `net.rs` | ✅ OpenAI 兼容 SSE 流式消费 | | `openai_sse_parse` / `解析流式` | host `net.rs` | ✅ 离线 SSE 解析 | | `url_encode` / `编码地址` | host `net.rs` | ✅ URL 编码 | | `cookie_parse` / `解析Cookie` | host `net.rs` | ✅ RFC6265 子集(请求头/响应头) | | `multipart_parse` / `解析多部分` | host `net.rs` | ✅ multipart/form-data 解析 | | `markdown_parse` / `解析Markdown` | host `net.rs` | ✅ GFM/Markdown → HTML(纯解析,W4c) | **标准库网络原语已齐备**:客户端 GET/POST/SSE、URL 编码、cookie、multipart、Markdown 解析。服务器侧上传/下载/ETag 在 `plugins/web`(A5/P3)。 ### 1.2 `plugins/web`(ABI v2,领域能力) **服务器侧已实现:** | 域 | ABI | 能力 | |---|---|---| | 页面 | `web_page_new` · `web_compose_components` · `web_compose_main` · `web_page_query` · `web_page_order` · `web_page_link_prefix` · `web_page_css` · `web_page_detail` | 页面装配、列表/排序、CSS、详情页 | | 样式 | `web_style` | GFM 表 → CSS(`make_style`/`样式装配`) | | 表单 | `web_form_new/fields/rules/validate/render/submit/from_schema` · `web_compose_form` | 字段表、校验表、渲染、提交、schema→form | | 数据库 | `web_db_new/init/insert/select/get/update/delete/exec/table_info/list_tables` | SQLite CRUD + where + order + limit | | 应用 | `web_app_new/route/mount_form/static/auth` · `web_app_route_ws` | 路由、静态目录、admin、鉴权、WS 端点 | | 会话 | `web_session_new/set/get/del/destroy` | 内存 TTL 会话 | | 鉴权 | `web_auth_login/check/logout/new` · `web_app_auth` | `/admin` 登录门禁 | | WebSocket | `web_ws_connect`(客户端)· `web_app_route_ws`(服务器) | 单请求-响应式客户端 + echo 服务器 | **关键实现事实(2026-08-28 W7+P3 后):** - **中间件 + JSON API**(W1):`app.configure` 装配 CORS、安全头、gzip、请求体上限、JSON 端点。 - **数据层**(W2/W6/W7/P3):连接池、事务、分页、OR/IN/BETWEEN、`db.count`、迁移、FTS5 搜索、init 唯一/索引/外键、审计时间戳。 - **安全**(W3s/P3):argon2、CSRF、SQLite 会话、CSPRNG session id、登录限速、RBAC(`app.gate` + 用户 `role`)。 - **内容站点**(W4c/W7):SEO `page.meta`、RSS、Markdown 正文、`page.paginate`、sitemap/robots。 - **媒体**(W5/P3):multipart 上传、下载、`app.gallery`、ETag/Cache-Control。 - **运维向**(W6/W7):访问日志、自定义 404/500、301/307 重定向、WS 广播;HTTPS 由反代终止 + `cookie_secure`。 - **仍属应用层约定**:标签聚合页模板(D6)、评论反垃圾、草稿/定时发布(表+where 即可)。 --- ## 2. 主流网络栈对照(联网调研 2026-08) ### 2.1 分层共识(决定「标准库 vs 扩展」边界) | 语言 | 标准库网络能力 | 扩展/框架能力 | 边界准则 | |---|---|---|---| | Python | `urllib`(HTTP 客户端)、`http.cookies`(cookie 解析器)、`http.server`(简易服务器)、`email` 多部分解析 | `requests`/`httpx`(连接池/session)、`FastAPI`/`Flask`(中间件/校验/模板) | 解析器进标准库;便利层/框架层在第三方 | | Node.js | `node:http`(低层流式,**不解析 body**)、`node:https` | express、fastify、ws、formidable | 低层原语进核心;fancy 功能 userland 验证后再进 core | | Go | `net/http`(服务器+客户端**都在标准库**)、`net/http/cookiejar`(RFC6265)、`net/smtp` | `golang.org/x/net`(演进性)、gin/echo | HTTP 与 stdin 同级的核心能力;cookie 解析进标准库 | | Rust | 极小 std(无 HTTP) | `hyper`→`reqwest`→`axum` | 分层;HTTP 生态多样不进 std | **对本项目的三处判定(与 [ext-web-net.md](ext-web-net.md) 一致并延伸):** 1. **纯解析原语**(cookie / multipart / url)→ `lib/net` 标准库。✅ 已达成。 2. **HTTP 服务器结构能力**(JSON / 中间件 / 上传下载 / HTTPS / 缓存头)→ `plugins/web`(ABI)。这是 axum 本身就在依赖链里的,不需要新增核心依赖。 3. **领域能力**(session / auth / 分页 / 搜索 / RSS / SEO / 限流)→ `plugins/web` + `ext/web` 作者面。 ### 2.2 「完整 Web 框架」能力清单(FastAPI / Express / Flask / axum 共通项) > **marqdo 列**反映 **2026-08-28 W7+P3 完结** 后状态(见 §3 差距表)。 | 能力 | FastAPI | Express | Flask | axum | marqdo | |---|---|---|---|---|---| | 路由(含动态参数) | ✅ | ✅ | ✅ | ✅ | ✅ 动态路由 `/post/{slug}` | | 中间件管道 | ✅ | ✅ | ✅ | ✅(tower) | ✅ W1 `app.configure` | | CORS | ✅ 内置 | ✅ 中间件 | ✅ flask-cors | ✅ tower-http | ✅ W1 | | JSON 请求/响应 | ✅ 原生 | ✅ | ✅ | ✅ | ✅ W1 JSON API 表 | | 校验(schema/字段) | ✅ Pydantic | 手动(zod) | 手动 | ✅ extractor | ✅ form 校验表 | | 静态文件 | ✅ Starlette | ✅ | ✅ | ✅ | ✅ `app.static` | | 模板/渲染 | ✅ Jinja | ✅ | ✅ | ✅ | ✅ GFM 表装配 | | 会话 | ✅ | ✅ express-session | ✅ | ✅ | ✅ SQLite 持久化(W3s) | | 鉴权 | ✅ OAuth2/APIKey | ✅ | ✅ | ✅ | ✅ admin + RBAC(P3) | | 文件上传 | ✅ | ✅ multer | ✅ | ✅ | ✅ W5 upload | | WebSocket | ✅ | ✅ ws | ✅ Flask-SocketIO | ✅ | ✅ echo + 广播(W6) | | 安全头 | ✅ | ✅ helmet | ✅ | ✅ tower-http | ✅ W1 | | 限流 | ✅ | ✅ | ✅ | ✅ | ✅ 登录限速(W3s) | | 日志 | ✅ | ✅ morgan | ✅ | ✅ | ✅ access_log(W6) | | gzip 压缩 | ✅ | ✅ | ✅ | ✅ | ✅ W1 | | 分页 | 手动 | 手动 | ✅ paginate | ✅ | ✅ db + page UI(W2/W4c) | | 迁移 | ✅ alembic | ✅ | ✅ | ✅ sqlx | ✅ W6 `db.migrate` | | 测试工具 | ✅ TestClient | ✅ supertest | ✅ | ✅ | gold 测试(`tests/ext/web-*`) | | HTTPS/TLS | 反代 | 反代 | 反代 | ✅ rustls | 反代 + `cookie_secure`(W7 文档锁定) | --- ## 3. 差距分析:按「完整项目」四类需求 ### 3.1 类 A:结构化 HTTP 基础设施(做 API / 前后端分离 / SPA 支撑) | # | 缺失能力 | 影响 | 归属 | 优先级 | |---|---|---|---|---| | A1 | **JSON 请求/响应**(`Json` extractor、`application/json` 响应、body 大小限制) | ✅ **已实现(W1)**:`接口` 表声明 JSON API 端点;`请求体上限` 配置 body 限制 | `plugins/web` | **P0 ✅** | | A2 | **中间件管道**(`app.configure` / `应用.装配`:CORS、安全头、压缩、请求体限制统一挂载) | ✅ **已实现(W1)**:`middleware.rs` 装配 GFM 表并 `app.layer` 挂到 axum | `plugins/web` | **P0 ✅** | | A3 | **CORS 支持**(`Access-Control-Allow-Origin` 可配) | ✅ **已实现(W1)**:`跨域` 表 `|允许来源|方法|头|暴露头|凭证|` | `plugins/web` | P1 ✅ | | A4 | **安全响应头**(CSP / X-Frame-Options / X-Content-Type-Options / HSTS / Referrer-Policy / 去 `X-Powered-By`) | ✅ **已实现(W1)**:`安全` 表 `|头|值|` | `plugins/web` | P1 ✅ | | A5 | **文件上传接收**(multipart extractor → 校验类型/大小 → 落盘)与**下载**(`Content-Disposition`) | ✅ **已实现(W5)**:`app.upload` / `app.download`;`file:` storage;离线 + curl live 金样 | `plugins/web` | P1 ✅ | | A6 | **HTTPS / TLS**(rustls 终止或反代提示) | ✅ **文档锁定(W7)**:进程内 TLS 不启用;反代终止 HTTPS,并设 `cookie_secure=True` | 文档 + `cookie_secure` | P2 ✅ | | A7 | **gzip / br 压缩** + **ETag / Cache-Control 缓存头** | gzip ✅(W1);Cache-Control ✅(W7);ETag ✅ **已实现(P3,下载/相册 + If-None-Match→304)** | `plugins/web` | P2 ✅ | | A8 | **访问日志**(请求方法/路径/状态/耗时) | ✅ **已实现(W6b)**:`configure access_log=True` → stderr | `plugins/web` | P2 ✅ | | A9 | **自定义 404/500 错误页** | ✅ **已实现(W7)**:`app.error_page` / `应用.错误页`;404 fallback + 500 页袋 | `plugins/web` | P2 ✅ | | A10 | **重定向增强**(permanent/自定义状态码) | ✅ **已实现(W7)**:`app.redirect` → 301/307 | `plugins/web` | P3 ✅ | ### 3.2 类 B:数据层深化(内容站点/社区的根基) | # | 缺失能力 | 影响 | 归属 | 优先级 | |---|---|---|---|---| | B1 | **连接池 / busy_timeout / WAL** | 高并发下 `database is locked`、每请求重连开销 | `plugins/web`(db.rs) | **P0 ✅** | | B2 | **事务 API**(`begin` / `commit` / `rollback`,或 `with_transaction` 包装) | 批量/多表写无原子性 | `plugins/web` | **P0 ✅** | | B3 | **结果集型裸查询**(exec 返回 rows) | count / join / group / 子查询完全不可用 | `plugins/web` | P1 ✅ | | B4 | **分页**(db 层 `limit`+`offset`;页面层上一页/下一页) | 列表页只能限量 | `plugins/web` + `ext/web` | P1 ✅(db 层;页面 UI 属 D4) | | B5 | **查询表达力**:OR / IN / BETWEEN / IS NULL / LIKE 转义 / 括号组合 | where 只能 AND | `plugins/web` | P1 ✅ | | B6 | **迁移机制**(schema 版本表 + 迁移脚本) | ✅ **已实现(W6)**:`db.migrate` + `_marqdo_migrations`(SQLite) | `plugins/web` + `ext/web` | P2 ✅ | | B7 | **索引 / 唯一 / 外键声明**(init 表增强) | ✅ **已实现(W7+P3)**:`唯一`/`索引`/`外键`(`posts.id` / `posts`) | `plugins/web` | P2 ✅ | | B8 | **聚合辅助**:count / group 便捷 API | 统计面板、标签计数 | `plugins/web` | P2 ✅(`db.count`) | | B9 | **全文搜索**(SQLite FTS5) | ✅ **已实现(W6)**:`db.fts` + `db.search`(bm25) | `plugins/web`(FTS5 现成) | P2 ✅ | | B10 | **时间戳 / 审计字段自动维护** | ✅ **已实现(P3)**:表含 `created_at`/`updated_at` 时 insert/update 自动写入 | `plugins/web` | P3 ✅ | ### 3.3 类 C:安全硬化(能上线的前提) | # | 缺失能力 | 影响 | 归属 | 优先级 | |---|---|---|---|---| | C1 | **密码哈希**(argon2/bcrypt/sha+盐,替代明文) | ✅ **已实现(W3s)**:argon2 | `plugins/web` | **P0 ✅** | | C2 | **CSRF 防护**(session-bound token,写操作校验) | ✅ **已实现(W3s)** | `plugins/web` | **P0 ✅** | | C3 | **登录限速/失败锁定**(每 IP/用户名 5 次/15min) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ | | C4 | **会话持久化**(SQLite/文件,替代内存) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ | | C5 | **加密安全 session id**(CSPRNG + 碰撞重试) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ | | C6 | **cookie 增强**:`Secure` 标志、签名、滑动过期 | ✅ **已实现**:`cookie_secure` + 滑动 TTL(touch);cookie 签名未单独做 | `plugins/web` | P2 ✅ | | C7 | **防暴力破解 / 会话上限 / 后台过期清理** | ✅ 限速 + prune;会话条数硬上限可后续 | `plugins/web` | P2 ✅ | | C8 | **RBAC / 多角色**(作者/管理员/访客) | ✅ **已实现(P3)**:用户表 `role`/`角色`;`app.gate`;`/admin*` 默认需 `admin` | `plugins/web` + `ext/web` | P3 ✅ | ### 3.4 类 D:内容站点标配(博客/CMS 特有) | # | 缺失能力 | 影响 | 归属 | 优先级 | |---|---|---|---|---| | D1 | **SEO**:每页 `