Files
marqdo/doc/design/change-hostfn-table.md
cflmy b196a44685 refactor(host): HostFn 五张表合一 — HOST_FN_TABLE 单一来源(−404 行)
202 个宿主函数的元数据原本分散在 from_u16 / from_name / name /
required_params / optional_params 五个手写 match 里,必须同步维护,
审计已记录过 from_name 与 name() 的漂移。

改动:
- 新增 HostFnDef + HOST_FN_TABLE(203 项:id, 变体, 规范名, 必填, 可选)
- from_u16 按 id 查表;name / required_params / optional_params 按判别值查表
- call_host 的 202 个一行臂保持不变(只集中元数据,不动分派逻辑)
- from_name 保留:它是别名注册表(http_get/中文别名…),语义与规范名不同

等价性证明(快照比对):
1. 先在旧实现导出全部 203 项的 (id,name,required,optional) 到 TSV
2. 合并后用同一段代码再导出
3. diff 两份 → 完全一致;快照测试用后即删

长期守护(4 个不变量测试,上一轮已加):
id↔as_u16 往返、name→from_name 往返、规范名唯一、required/optional 不重叠。

验证:cargo build 零警告;cargo test --release 609 passed / 0 failed。
行数:dispatch.rs 2052 → 1648;src 合计 53,040 → 52,668。

文档:doc/design/change-hostfn-table.md
2026-10-22 15:51:26 +08:00

3.2 KiB
Raw Permalink Blame History

变更记录:HostFn 五张表合一(HOST_FN_TABLE 单一来源)

状态 Implemented
日期 2026-10-22
来源 code-volume-audit.md §4 第 4 项
改动 src/host/dispatch.rs:−404 行(639 删 / 235 增)
行为 零变化(203 项逐字节一致)

1. 原来有五张并行表

202 个宿主函数的元数据分散在五个手写 match 里:

表 行数 作用
from_u16 ~215 id → 变体
from_name ~215 名字/别名 → 变体(保留,见 §4)
name ~210 变体 → 规范名
required_params ~145 变体 → 必填参数
optional_params ~90 变体 → 可选参数

五张表必须同步维护,而 code-volume-audit.md 记录过 from_name 接受 http_get 而 name() 只输出 host_http_get 的一类漂移。

2. 现在只有一张

pub struct HostFnDef {
    pub id: u16,
    pub f: HostFn,
    pub name: &'static str,
    pub required: &'static [&'static str],
    pub optional: &'static [&'static str],
}

pub const HOST_FN_TABLE: &[HostFnDef] = &[
    HostFnDef { id: 1, f: HostFn::ReadText, name: "host_read_text",
                required: &["path"], optional: &[] },
    …
];

四个函数改为查表(from_u16 按 id 查,其余按判别值查); call_host 保留它那 202 个一行臂——分派逻辑不动,只把元数据集中。

3. 怎么保证没改坏

迁移采用快照比对:

  1. 先在旧实现上导出全部 203 项的 (id, name, required, optional) 到 TSV
  2. 合并成表后,用同一段代码再导出一份
  3. diff 两份文件 → 完全一致
$ diff /tmp/host_fns_baseline.tsv /tmp/host_fns_new.tsv && echo IDENTICAL
IDENTICAL

快照测试是一次性的,比对通过后删除;长期守护交给四个不变量测试:

测试 内容
every_assigned_id_round_trips 每个已分配 id → as_u16() 往返(id 空间稀疏是退役 id,不复用)
every_id_has_a_name_that_round_trips name() → from_name() 回到同一变体
names_are_unique 规范名唯一
required_and_optional_params_are_disjoint 必填/可选不重叠、all_params 无重复

4. 为什么 from_name 没有并进表

它是别名注册表(http_get、get、中文别名…),语义与"规范名"不同; 并进表会让 name() 与 from_name 又变成一对映射。 现在它保留原样,由上面的往返测试保证不与表漂移。

5. 收益

指标 前 后
dispatch.rs 2,052 行 1,648 行
src/ 合计 53,040 52,668
需同步维护的表 5 1

6. 验证

项 结果
cargo build --release 零警告
cargo test --release 609 passed / 0 failed
快照 diff 203 项逐字节一致
四个不变量测试 全绿

7. 变更清单

文件 变更
src/host/dispatch.rs 新增 HostFnDef / HOST_FN_TABLE(203 项);from_u16 / name / required_params / optional_params 改为查表;删除对应四个 match
doc/design/change-hostfn-table.md 本文件