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
3.2 KiB
3.2 KiB
变更记录: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. 怎么保证没改坏
迁移采用快照比对:
- 先在旧实现上导出全部 203 项的
(id, name, required, optional)到 TSV - 合并成表后,用同一段代码再导出一份
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 |
本文件 |