MooTool 网络工具与系统服务:Electron vitest 与 Compose 实现的对照研究与移植验证指南
MooTool 网络工具与系统服务:Electron vitest 与 Compose 实现的对照研究与移植验证指南
导读
本文以 MooTool 开源仓库中 next-compose/docs/fixtures/electron-next-netTools-vitest.md 这份对照文档为核心,深入解析 Electron 端 netTools.test.ts / systemService.test.ts 的网络工具与系统服务测试,以及 Compose(Kotlin Multiplatform)端的对应实现 NetEngine / NetHistoryMetadata / NetHistoryRestore / EnvEngine。通过逐一比对其中的三个关键 caseId(IPv4 与无符号长整型互转、端口扫描历史持久化与恢复、环境变量文件安全更新),说明两套实现如何在算法、边界处理、wire 协议与错误码语义上保持一致,可作为跨技术栈移植时的逐项对照清单与验收依据。
一、对照文档概述:一条可追溯的双端 parity 链路
该文档是一张"案例级"对照表,记录了 Electron vitest 与 Compose 实现之间三条已经对齐的功能点。它的价值不在于篇幅,而在于每行都指向真实的源码与测试文件:
| caseId | Electron vitest | Compose 实现 |
|---|---|---|
ipv4-long |
next/src/features/net/netTools.test.ts 中 127.0.0.1 ↔ 2130706433 |
NetEngineTest.convertsIpv4AndUnsignedLongFixtures(NetEngineTest.kt) |
port-scan-history |
命令 port-scan + 端口规格持久化 |
NetHistoryMetadataTest / NetHistoryRestoreTest(以 wire operation + options 端口 JSON 序列化) |
env-file |
systemService.test.ts 环境文件更新 |
EnvEngineTest.updatesEnvironmentFileLikeElectronSystemServiceFixture |
该文档登记于 DIFF-533:F11 历史恢复闭环 + F20 历史回填 + MCP 时间 round-trip。从 DIFF-533 的"背景"可知,这三条对齐的目标是补齐 F11 通用历史恢复:此前 operation/options 只写入本地化摘要、端口扫描未保存 portSpec,恢复时无法对齐 Electron 的 NetworkAction 字符串;本文对应的三条 caseId 正是这一补丁中最核心的网络侧成果。
下文将依次拆解三个 caseId 在 Electron 与 Compose 两侧的具体实现、测试证据与设计差异。
二、caseId ipv4-long:IPv4 与无符号 32 位整型的双向转换
2.1 Electron 侧:纯函数 + 极简 vitest
Electron 侧的转换逻辑位于 next/src/features/net/netTools.ts,提供两个纯函数:
ipv4ToLong(value: string): number:拆分四个十进制段,逐段校验后按result * 256 + part累加,并通过>>> 0将结果强制为无符号 32 位整数。longToIpv4(value: string | number): string:要求数值为安全整数且落在[0, 0xffffffff]区间,再按 24/16/8/0 位位移逐段取低 8 位拼回点分十进制。
对应的测试在 next/src/features/net/netTools.test.ts,核心断言正是文档登记的那组往返:
expect(ipv4ToLong('127.0.0.1')).toBe(2130706433)
expect(longToIpv4('2130706433')).toBe('127.0.0.1')
同一套测试在 next/src/shared/systemService.test.ts 中被扩展为更完整的用例:192.168.1.1 ↔ 3232235777 往返、非法输入(如 300.1.1.1、超出 32 位范围的整数)必须抛错。也就是说,转换函数同时被网络工具 UI 与系统服务模块复用,这也是它在仓库中被拆为 netTools.ts 纯函数模块、再被 systemService.ts 导出的原因——见 systemService.ts 中的同源实现。
2.2 Compose 侧:Long 语义 + 更完整的边界测试
Compose 端 NetEngine 位于 NetEngine.kt,其 ipv4ToLong 返回 Long 而非无符号 Int,底层用 acc * 256 + part 折叠计算;longToIpv4 用 value shr shift and 0xffL 提取每段。相比 Electron 的 Number,Kotlin 侧直接以 64 位 Long 承载 32 位无符号值,天然避免 JS Number 在边界上的精度隐患。
对照测试 NetEngineTest.convertsIpv4AndUnsignedLongFixtures(NetEngineTest.kt)在文档登记的基础上显著扩充了边界覆盖:
- 极值往返:
0.0.0.0↔0L、255.255.255.255↔4294967295L; - 前导零宽容:
127.0.0.01解析为2130706433L(与 Electron 侧对\d{1,3}的容忍一致); - 非法输入全部抛
NetConvertException:256.0.0.1、1.2.3、1.2.3.4.5、::1(IPv6)、127.0.0.、负整数-1、越界整数4294967296、非整数1.5。
这组测试同时给出了转换函数的边界契约:四段十进制、每段 1~3 位且 ≤ 255、整数必须落在 <a href="https://link.gitcode.com/i/e133aaae7399b41cbd805f3d807844dd" target="_blank">0, 0xffffffff]。Electron 侧 [systemService.test.ts 的 >>> 0 与 0x1_0000_0000 上界检查与其完全同语义。
2.3 两个转换点的实际调用位置
在 NetTool.tsx 中,convertFromIp / convertFromLong 两个按钮处理函数分别调用 ipv4ToLong / longToIpv4 并写入界面上的两个输入框;默认值即 127.0.0.1 与 2130706433,与测试夹具完全一致。这说明该 caseId 不仅是"测试对齐",更是 UI 功能与测试数据的严格同源。
三、caseId port-scan-history:端口扫描动作与端口规格的历史持久化
3.1 端口规格的解析规则(两端的公共契约)
端口扫描核心是 systemService.ts 的 parsePortSpec 与 scanPorts,以及 Compose 侧 NetEngine.parsePortSpec。两端保持一致的规则:
- 空输入:回退到内置常用端口表
commonPorts(约 50 个知名端口,如 22/ssh、3306/mysql、6379/redis、9092/kafka、27017/mongodb),两端的端口表内容完全一致; - 逗号分隔:
22,80,3306展开为三个端口; - 区间语法:
80-82展开为80,81,82,且要求start <= end、跨度不超过 4096(MAX_CUSTOM_PORTS); - 合法性:端口必须为 1~65535,非数字、
0、65536、跨度超限(如1-4097)一律抛INVALID_TARGET。
测试证据分别见 systemService.test.ts 与 NetEngineTest.parsesIpv4RangeAndPortSpec。
3.2 为什么历史需要 wire id + options JSON
Electron 的 NetworkAction 是字符串联合类型(interfaces、connections、ping、ping-range、port-scan、flush-dns、resolve、whois),而 Compose 的 NetworkAction 是 Kotlin 枚举(Interfaces、Connections、Ping、PingRange、PortScan、FlushDns、Resolve、Whois)。历史恢复时若直接存枚举名,跨端对齐就会失败。因此 Compose 侧引入 NetHistoryMetadata(NetHistoryMetadata.kt)作为 wire 协议层:
actionWireId(action)将枚举映射为 Electron 风格字符串(PingRange -> "ping-range"、PortScan -> "port-scan"等);parseAction(operation, options)同时兼容两种输入:优先按 wire id 反解,失败后再尝试按枚举名反解(enumValueOrNull),从而兼容历史中旧记录options=NetworkAction枚举名的情况;encodePortSpec将端口规格(如22,80-82)编码为{"ports":"22,80-82"}形式的 options JSON;decodePortSpec反向解码,遇到损坏数据时安全降级返回空字符串(runCatching { ... }.getOrDefault(""))。
3.3 恢复逻辑:从历史记录回填整个网络会话
NetHistoryRestore.apply(session, item)(NetHistoryRestore.kt)负责把一条 HistoryRecord 应用到 NetSession:
- 通用处理:先恢复输出区并清空错误;若
operation为ipv4-to-long/long-to-ipv4,则分别回填 IPv4 与 Long 输入框; - 命令动作:根据
parseAction的解析结果,将item.input分别写回pingTarget/ipRange/portScanTarget/hostTarget/whoisTarget;其中PortScan额外通过decodePortSpec(item.options)恢复端口规格portSpec。
这一设计对应 DIFF-533 中"F11 网络/IP 历史恢复:恢复输出区、IPv4↔Long、各命令目标与 portSpec"的验收项。测试由 NetHistoryMetadataTest.kt 覆盖:actionWireId 输出与 Electron 字符串完全一致、encodePortSpec / decodePortSpec 往返无损、parseAction 对 wire id 与旧枚举名双路径均能正确解析。
3.4 扫描行为本身:可取消的并发扫描
作为历史持久化的底层支撑,两端扫描行为也保持一致:IP 段扫描并发度 32、端口扫描并发度 96,输出上限 2 MB;Electron 侧对应 systemService.ts 的 ipRangeConcurrency = 32、portScanConcurrency = 96,Compose 侧对应 NetEngine.IP_RANGE_CONCURRENCY = 32、PORT_SCAN_CONCURRENCY = 96。端口探测采用 Socket 连接超时判断(默认每端口 ≤ 500ms),并通过 AbortController / NetCommandHandle 支持用户主动取消(取消语义为 ABORTED)。Compose 侧 NetEngineTest 用一个真实监听的 ServerSocket 验证了"本机开放端口可被扫描到",同时验证了 Ping 的取消路径返回 ABORTED。
四、caseId env-file:环境变量文件的安全更新
4.1 Electron 侧:正则驱动的行级更新器
env-file 案例对应的 Electron 实现是 systemService.ts 中的 updateEnvironmentContent 与 parseEnvironmentContent。更新器遵守以下约束:
- 变量名必须匹配
[A-Za-z_][A-Za-z0-9_]*; - 值长度不超过 65535、不允许包含
\0、\r、\n; - 通过
environmentAssignment正则^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$识别行,仅替换同名键的首次出现,其余行(含注释)原样保留,删除时移除该行并清理尾部空行。
序列化遵循 shell 风格:shellExport=true 时输出 export KEY='value' 并转义单引号(' → '\'');false 时输出 KEY="value" 并转义双引号与反斜杠。测试夹具见 systemService.test.ts:更新 JAVA_HOME 为含单引号的值 /opt/jdk's 后,文件里出现 export JAVA_HOME='/opt/jdk'\''s',再解析回来恰好还原为 /opt/jdk's;删除同一变量后注释与 OTHER 行原样保留。
4.2 Compose 侧:逐字节对齐的 fixture 测试
Compose 端对应的 EnvEngine 提供同签名接口 EnvEngine.updateContent(source, key, value, shellExport) / EnvEngine.parseContent(content)(EnvEngine.kt)。验证其与 Electron 对齐的正是文档登记的那个测试名:EnvEngineTest.updatesEnvironmentFileLikeElectronSystemServiceFixture(EnvEngineTest.kt)。
该测试使用了与 Electron vitest 完全相同的输入输出夹具:
val source = """
# keep this comment
export JAVA_HOME='/old jdk'
OTHER="value"
""".trimIndent() + "\n"
val updated = EnvEngine.updateContent(source, "JAVA_HOME", "/opt/jdk's", shellExport = true)
// 期望:# keep this comment\n export JAVA_HOME='/opt/jdk'\''s'\n OTHER="value"\n
再通过 EnvEngine.parseContent 断言解析出 EnvEntry("JAVA_HOME", "/opt/jdk's")、EnvEntry("OTHER", "value"),并验证删除操作只移除目标行。这说明 caseId env-file 的"对齐"是字节级的:从输入源文件到转义后的输出文本逐字符一致,属于跨端移植中最强的一类契约保障。
4.3 扩展:环境持久化的完整链路
作为上下文补充,Electron 端环境持久化不止单文件更新:systemService.ts 还包含 listPersistentEnvironment / writeUnixEnvironment / syncCurrentProcessEnvironment。Unix 下用户级环境写入 ~/.MooTool/environment(权限 0o600),并在 ~/.zshenv 或 ~/.profile 中追加 # >>> MooTool environment >>> 标记块以 source 该文件;macOS 额外通过 launchctl setenv/unsetenv 同步;Windows 侧则经 PowerShell [Environment]::SetEnvironmentVariable(..., [EnvironmentVariableTarget]::User/Machine) 写入,系统级写入自动提升权限。无权限时(如系统级)两端均走临时文件 + 提权复制(macOS osascript 管理员权限、Linux pkexec)的路径。这部分属于 Electron 端更完整的系统服务能力,Compose 端 EnvEngine 聚焦于文本层的一致性,二者共同构成"env-file"case 的可验证全集。
五、对照价值:为什么这种逐案例登记有意义
5.1 作为移植验收清单
该对照文档最直接的用途是移植验收。以 port-scan-history 为例,验收时只需依次检查:actionWireId 输出的八个 wire id 是否与 Electron 字符串一致、encodePortSpec 是否能用 {"ports":"..."} JSON 无损往返、NetHistoryRestore 是否能同时恢复目标与端口规格、以及旧记录枚举名是否仍可解析——四个检查点分别由 NetHistoryMetadataTest 与 NetHistoryRestoreTest 覆盖。
5.2 作为测试命名与代码结构的统一约定
文档强调"Electron vitest ↔ Compose"一一对应的命名方式(convertsIpv4AndUnsignedLongFixtures、updatesEnvironmentFileLikeElectronSystemServiceFixture)。这类"Fixture 命名约定"让两端的回归测试天然互为镜像:改动任一端的转换算法、端口解析或环境序列化规则,都能立即在另一端同名测试中暴露差异。
5.3 与 DIFF-533 的闭环关系
三个 caseId 均登记于 DIFF-533。该补丁同时验证了历史恢复闭环(NetHistoryMetadataTest / NetHistoryRestoreTest / TranslationHistoryRestoreTest / MooToolMcpToolsTest),并声明 Compose 桌面测试全量通过(文档记录为 837/837 通过、2 个默认跳过的公网 smoke 用例)。本文三个 caseId 正是其中 F11 网络/IP 历史部分的具体落地证据。
六、实践建议:如何复用本对照进行双端维护
- 以 wire id 为唯一跨端标识:所有进入历史记录的
operation字段一律使用 Electron 风格字符串(如port-scan、ping-range),Compose 端只做"枚举 → wire id → 枚举"的映射,不要在两端各自发明字符串; - 历史
options统一为可 JSON 解码的字段:端口规格用NetHistoryMetadata.encodePortSpec序列化,读取时用decodePortSpec并容忍损坏数据,避免旧记录导致恢复失败; - 转换与文本更新坚持纯函数:
ipv4ToLong/longToIpv4/updateEnvironmentContent/parseEnvironmentContent在两端都是无副作用的纯函数,便于用同一组 fixture 做逐字节断言; - 新增 caseId 时同步维护对照文档:参照本文引用的文档格式,将"Electron 测试文件 + 具体断言 + Compose 测试方法 + DIFF 编号"四要素登记在 next-compose/docs/fixtures/electron-next-netTools-vitest.md 中,保证 parity 链路可追溯。
参考资料(仓库内)
- 对照文档:next-compose/docs/fixtures/electron-next-netTools-vitest.md
- 相关补丁:next-compose/docs/diff/533-f11-f20-net-history-mcp-timestamp-slice.md
- Electron 测试:netTools.test.ts、systemService.test.ts
- Electron 实现:netTools.ts、systemService.ts、NetTool.tsx
- Compose 实现与测试:NetEngine.kt、NetHistoryMetadata.kt、NetHistoryRestore.kt、EnvEngine.kt
- Compose 测试:NetEngineTest.kt、NetHistoryMetadataTest.kt、EnvEngineTest.kt