7.1 Web 应用案例

7.1 Web 应用案例

本节摘要：本节以浏览器端媒体处理为背景，把一次完整的 Wasm 集成从头走到尾：需求拆解、三层架构、边界协议、加载策略、上线复盘。所有步骤配可直接对照的代码骨架，结尾给出迁移工程的避坑清单。

接手项目的场景再普通不过：一款在线图片编辑器，随着滤镜与降噪功能越加越多，纯 JavaScript 实现的处理延迟已经爬到秒级，移动端尤甚；团队决定把处理内核迁到 Wasm。本节按真实项目的推进顺序复盘这次集成，重点不在展示代码，而在展示每一步的决策依据。

需求拆解：先回答适配性问题

动手之前，第一章的场景三问先过一遍。计算热点显著吗——显著，滤镜是逐像素卷积，降噪是频域变换，都属计算密集。数据能批量过境吗——能，图像天然是连续字节缓冲，一次进一次出。有既有资产吗——有，卷积核与降噪算法在 C++ 图像库里躺了很多年。三问皆是，迁移成立。但要补一条约束：产品要求所有交互保持实时响应，处理过程进度可见——这条决定了架构必须把计算挪出主线程。

三层架构：界面、编排与内核

最终的架构分三层，边界清晰得可以用三条纪律概括。

界面层留在 JavaScript：画布渲染、控件交互、进度条。它持有 DOM，是唯一能直接操作页面的一层。编排层负责调度：决定何时加载模块、如何切分任务、怎样把进度事件转发给界面层，运行在 Worker 里。计算内核是 Wasm 模块：滤镜、降噪、色彩空间转换，全部字节化，同样驻留 Worker——与编排层同线程，互调零边界。

读图的关键在虚线：图像数据从不进消息通道。主线程把解码后的像素写进共享缓冲区（ArrayBuffer 递给 Wasm 当线性内存），编排层只传"地址加长度加滤镜参数"，内核在原地计算，界面层直接把结果区域交给渲染。数据零搬运，边界只过指令与信号——第五章的通道账本在这里兑现成架构。

核心协议与加载策略

边界协议是这次集成的成败点。初版接口按功能粒度设计——每个滤镜一个函数，参数走栈——结果单元测试全绿，集成测试却慢得离谱：一次"一键增强"要串行调用锐化、降噪、色彩三个函数，中间结果在宿主与模块间来回倒手。改造后的协议只保留一个粗粒度入口：

// 内核侧唯一入口：一次调用完成整条处理链
// pipeline 返回结果缓冲区在共享内存中的偏移
int pipeline(int src_offset, int width, int height,
             const char* ops_json, int ops_len);
​

// 编排层：把处理链描述为参数，一次过境
const ops = encoder.encode(JSON.stringify([
  { op: "denoise", strength: 2 },
  { op: "sharpen", radius: 1 },
  { op: "colorspace", target: "srgb" }
]));
const resultOffset = instance.exports.pipeline(
  srcOffset, width, height,
  opsOffset, ops.length
);
​

参数描述（处理链）很小，走字符串通道无伤大雅；像素数据很大，走共享内存零拷贝——大小数据各走各的通道，这是协议设计的通则。加载策略上，模块按功能拆包：基础滤镜随首屏加载（百 KB 级，流式编译边下边验），高级降噪按需拉取并缓存到 Cache Storage，Service Worker 拦截模块请求走缓存优先——弱网环境首屏不受高级功能拖累。

就绪时序也值得一笔：模块是异步进港的，用户却可能点击得比网络快。稳妥的做法是把"模块未就绪"设计成合法状态——点击先入队、界面标记加载进度，就绪后自动清空队列。这个细节上线前不易想到，却是感知性能与真实性能的分界线。

结果与复盘：数据说了什么

结果：像素处理路径整体耗时降到原来的四分之一上下；主线程帧率在处理期间保持满帧，进度条平滑推进；首屏因基础包轻量化反而略有提前。解读：收益的构成值得拆开看——算法本身从 JavaScript 换成编译后的 C++ 贡献了主要份额；Worker 挪窝贡献的是"处理期间不掉帧"的体验项；边界协议改造贡献的是多步处理链的合并收益，这一项恰恰是初版架构里最隐蔽的性能损失，若没有集成测试的对比数据，很可能被误判为"Wasm 也就这样"。变式：同一套架构可以平移到音频处理（数据换成 PCM 帧，处理链换成效果器串接）、视频转码（增加 Worker 池做分段并行，衔接第六章的多线程提案）以及前端密码学场景（密钥驻留内存、明文不出边界）。架构不变，协议随数据形态微调——这正是"案例"比"代码"更值钱的地方。

避坑清单：迁移工程的高发事故

最后把这次集成踩过或险些踩过的坑收拢成清单。其一，图元级互调：任何"每个像素、每条记录调一次"的接口设计都要在评审时拦下。其二，扩容后使用旧视图：线性内存扩容后 ArrayBuffer 脱钩，所有缓存的视图要在扩容后重建。其三，调试信息全剥离：发布包可以瘦身，但灰度阶段保留调试信息，出了问题再重编是来得及的。其四，缓存不设版本：Cache Storage 里的模块字节必须带版本键，回滚场景才能秒级切换。其五，把基准搬上真机：开发机上的性能数字对移动端没有代表性，低端安卓机才是验收的最终裁判。

本节要点回顾

• 适配性三问前置：计算热点、批量过境、既有资产，三问不过不迁移；
• 三层架构三条纪律：界面留 JavaScript、编排与内核同住 Worker、像素数据永不进消息通道；
• 粗粒度协议是成败点：处理链一次过境，中间结果不倒手，大小数据各走各的通道；
• 加载按功能拆包：基础随首屏、高级按需拉、Service Worker 缓存优先；
• 复盘靠数据拆解收益：算法、架构、协议各自的贡献分开度量，才能发现隐蔽损失。

Web 航线跑通，下一节看字节离港后的世界：服务端、边缘与更多非 Web 部署形态。