Appearance
resource-package-verifier
1. 实验目标与工程要点
这个样板把 download_service.dart 案例里的“校验阶段”单独拎出来，验证三个最常漏掉的闸门：
- 文件大小是否匹配元信息
- SHA-256 是否匹配
- manifest 里的资源版本是否与远端声明一致
它解决的问题不是“如何下载”，而是下载后的候选资源包能不能被宣布为可晋升版本。
2. 深入原理与生活浅显比喻
2.1 生活浅显比喻
资源包校验像仓库收货验收入库：
- 先看箱子重量对不对（size）
- 再看防伪码对不对（hash）
- 最后开箱确认货号和清单对不对（manifest）
前两步只证明“箱子像是对的”，最后一步才证明“业务真的能用”。
2.2 底层原理分析
典型端上更新至少要分三层验证：
- 传输完整性：size 是否一致
- 内容完整性：sha256 是否一致
- 业务可用性：manifest / 入口文件 / 版本兼容性是否一致
如果只做前两层，不做 manifest 校验，仍然可能出现：
- ZIP 能解压，但入口文件名不对
- 资源版本与客户端策略不兼容
- CDN 缓存了旧包，却配了新版本号
2.3 方案对比矩阵
| 方案 | 通俗比喻 | 底层原理 | 保证特性 | 吞吐性能 | 运行开销 | 适用场景 |
|---|---|---|---|---|---|---|
| 只看 HTTP 200 | 快递签收就算成功 | 只证明响应完成 | 最弱 | 高 | 低 | Demo、非关键缓存 |
| size + hash | 重量 + 防伪码 | 证明传输和字节一致 | 中 | 中 | 中 | 大部分资源包下载 |
| size + hash + manifest | 收货后再核对货单 | 加业务可用性校验 | 强 | 中 | 中高 | 离线包、模型、配置更新 |
3. Android / 移动端实战场景与误配事故
3.1 实战场景
- Flutter 离线包下载后准备切换 active 目录
- Android WebView 资源包更新
- 端上模型 / 配置包升级
3.2 常见误配与事故注意事项
- 只校验 hash，不校验 manifest，结果业务入口文件缺失
- 远端 version 已升级，但本地还拿旧 manifest，误把坏包当可用包
- 校验失败后不分类，后续无法判断要不要自动重试
3.3 排障思路
先看失败属于哪一类：
- sizeMismatch
- hashMismatch
- manifestInvalid
- versionMismatch
只有分清层次，才能决定是删 staging、重下，还是暂停自动重试等待服务端修包。
4. 实验源码与运行验证
关键源码
关键参数 / 开关
expectedVersion：远端声明版本manifest.version：解压后 manifest 版本expectedSha256/actualSha256：模拟 hash 校验
运行方式
bash
cd labs/shared/backend-data/resource-package-verifier
node resource_package_verifier.mjs预期控制台运行输出
text
[verify:size] ok
[verify:sha256] ok
[verify:manifest] version mismatch: expected=42 actual=41
[result] package rejected, keep activeVersion=v41