《互联网产品的客户端架构·规模化与架构演进》目录与学习路径

这一卷要解决的问题

前三卷分别把结构、流动与事实做对了。卷四要回答的是另一个问题：当同一件事要在五个端、五个团队、五个发布节奏里同时成立，前面的「做对」还剩下多少。

这个问题没有一次性答案。它会在不同阶段以不同面貌出现：

• 刚扩到第二个端时，问题是「要不要复制代码」。
• 扩到第四个端时，问题是「组件库为什么每个端都改过」。
• 团队超过三个时，问题是「谁有权决定这处不一致可以接受」。
• 版本发了两年后，问题是「旧架构还能不能安全替换」。

卷四把这些阶段问题拆成十三章，每章给一组判断、一份可运行代码与一套验收方式。

全卷结构

十三章分四段：定义边界、建设能力、建立治理、完成演进。

前六章偏「建平台」，中间五章偏「管平台」，最后两章把建设与治理合起来验收。

详细目录

第 1 章 多端一致性与平台边界

• 1.1 五类端形态与一致性承诺
• 1.2 共享内核与端上适配层
• 1.3 能力探测与渐进增强

定义 identical / equivalent / allowed-diff 三级承诺，用矩阵计算端缺口；给出 core / protocol / adapter / ui 四层依赖规则；把端能力抽象为 native / polyfill / absent 与四种处理策略。这是全卷的地基。

第 2 章 设计系统与组件平台

• 2.1 设计 token 与主题化
• 2.2 组件契约与版本化
• 2.3 多品牌与多业务复用

从 token 的三层结构讲到组件契约的兼容规则，再讨论多品牌复用时的主题隔离。核心判据是「可预期」：同样的输入得到同样的行为，同样的版本得到同样的兼容性。

第 3 章 插件化与动态化

• 3.1 插件协议与宿主边界
• 3.2 沙箱、权限与失败隔离
• 3.3 动态配置与热更新的停止条件

插件化不是「把代码搬到线上」，而是「把变更权交给另一端」。本节组给出协议、权限与失败隔离的最小实现，并明确什么情况下必须停止热更新。

第 4 章 性能治理体系

• 4.1 性能预算与分端指标
• 4.2 归因：从慢到哪一行
• 4.3 优化闭环与回归防护

性能治理的关键不是优化一次，而是让「变慢」在合并前被发现。预算按端分配，归因按阶段拆解，回归靠基线对比。

第 5 章 稳定性与容错架构

• 5.1 故障域与爆炸半径
• 5.2 降级、开关与兜底
• 5.3 故障演练与恢复验证

端上的稳定性不是「不崩」，而是「坏了只坏一部分」。故障域决定爆炸半径，降级与开关决定用户看到什么，演练决定这些机制是否真的生效。

第 6 章 构建与交付工程

• 6.1 Monorepo 与包边界
• 6.2 产物治理与缓存
• 6.3 发布流水线与灰度回滚

多端共享构建的收益来自复用，风险来自耦合。包边界、产物缓存与发布流水线三节，把「共享」限制在可控范围内。

第 7 章 端上可观测性

• 7.1 日志、指标与追踪的最小契约
• 7.2 采样、脱敏与成本
• 7.3 从告警到定位的闭环

可观测性不是「多打日志」，而是「用最少的字段回答最多的问题」。最小契约定义必填字段，采样与脱敏控制成本，告警闭环保证问题有人接。

第 8 章 安全、隐私与合规

• 8.1 数据分级与最小权限
• 8.2 第三方 SDK 治理
• 8.3 隐私合规的工程落地

端是数据离开用户设备前的最后一道关口。数据分级决定什么能采、SDK 治理决定谁能采、同意管理决定何时能采。

第 9 章 国际化与本地化

• 9.1 文案、时区与货币
• 9.2 RTL、排版与本地内容
• 9.3 区域能力差异与降级

国际化的失败往往不是翻译错，而是格式错、时区错、货币舍入错。这三类错误与金额错误同级，必须纳入一致性承诺。

第 10 章 无障碍与包容性

• 10.1 语义结构与焦点顺序
• 10.2 读屏、键盘与动效偏好
• 10.3 无障碍测试与验收

无障碍不是附加功能，而是可用性的一部分。语义结构决定读屏能否理解页面，偏好映射决定交互是否可调，验收决定它会不会在迭代中退化。

第 11 章 团队协作与架构治理

• 11.1 架构决策记录与契约
• 11.2 代码所有权与评审
• 11.3 技术债台账与治理节奏

治理要轻，但必须可执行。ADR 记录判断，所有权表落实责任，技术债台账控制节奏。三者合起来，才能让「谁来决定」有答案。

第 12 章 架构演进与迁移

• 12.1 绞杀者与渐进式替换
• 12.2 双写双读与兼容窗口
• 12.3 迁移的退出条件与回滚

迁移的难点不是技术，而是「什么时候算完成」。绞杀者负责替换路径，双写负责数据过渡，退出条件负责结束。

第 13 章 卷四收口：从应用到平台

• 13.1 端到端：多端同一笔交易的体验一致性
• 13.2 平台化验收：能力矩阵与治理清单
• 13.3 全书收官：四卷回顾与下一站

把前十二章的模型合起来，跑一次多端端到端，再用能力矩阵与治理清单验收平台，最后回顾四卷的方法与边界。

前置与附录

• 序 ：为什么写这一卷，以及前三卷留下的三笔债。
• 前言 ：四段写法、模块地图、代码约定与团队用法。
• 附录 A：术语与判据速查（承诺、边界、能力、预算、治理）。
• 附录 B：多端问题排查手册（按症状组织）。
• 附录 C：架构评审清单（可直接投影使用）。

章与章之间的依赖

第 1 章（承诺与边界）
  ├─→ 第 2 章（设计系统）─→ 第 9、10 章（国际化、无障碍）
  ├─→ 第 3 章（插件化）
  ├─→ 第 4、5 章（性能、稳定性）─→ 第 7 章（可观测性）
  ├─→ 第 6 章（构建交付）
  └─→ 第 8 章（安全隐私）

第 11 章（治理）依赖 1、2、6
第 12 章（迁移）依赖 1、11
第 13 章（收口）依赖全部

依赖是概念前置，不是阅读顺序。第 9、10 章之所以放在治理段，是因为它们需要承诺与组件契约作为参照；单独读也能成立。

三条阅读路径

路径一：第一次做多端。 第 1 → 2 → 4 → 5 → 6 章。先定承诺，再做组件，然后解决性能与稳定性，最后统一构建发布。其余章节在第一版平台上线后补。

路径二：已有平台，治理失效。 第 11 → 1 → 12 章。先看治理方法，再回填承诺矩阵，最后规划迁移。第 7、8 章用于排查「问题总是上线后才发现」。

路径三：按风险选读。 性能看第 4 章，稳定性看第 5 章，安全合规看第 8 章，国际化与无障碍看第 9、10 章。每章独立，章末会指回相关承诺。

读完应能回答的六个问题

1. 你的产品在五个端上，哪三个行为必须逐字一致？哪些允许等价、哪些允许不同？
2. 共享代码的最底层依赖了哪些模块？有没有反向依赖或环？
3. 某个功能在某个端不可用时，系统给出的策略是降级、阻塞还是隐藏？依据是什么？
4. 性能预算按端怎么分？超限时谁负责、在哪个环节拦下？
5. 最近一次架构决策记录在哪？它记录了哪些被放弃的选项？
6. 下一次迁移的退出条件是什么？谁有权宣布迁移结束？

能回答四个以上，说明这一卷的方法已经进入团队；只能回答一两个，建议从第 1 章重新填一遍矩阵。

各章实验速查

每章对应一个实验目录与一个可运行测试文件，方便只挑感兴趣的章：

所有测试都通过 node --test test/<目录>/*.test.ts 运行。若只想验证某一章，把目录换成对应名称即可，不需要跑整本。

实验代码不追求覆盖所有工程细节，而是把每章的核心判断写成可断言的形式。读到某条判据不确定时，先看对应测试的断言，通常比读正文更快。

版本与配套

• 运行环境：Node v26.5.0，原生类型剥离，零第三方依赖。
• 站点构建：Hugo v0.163.3+extended。
• 实验工程：evolve-lab，目录结构与前言一致。
• 三级验证：L1 纯判断、L2 进程内模拟、L3 本地真实依赖。

每篇正文的代码块带 // file:、// tier:、// verify: 三行头，分别表示目标文件、验证级别与验证命令。三行头也是书稿与工程保持一致的校验依据。

如果只想带走一份材料，选附录 C 的评审清单；如果想理解方法，按路径一读前六章。

怎么使用这份目录

目录不只是索引，也是检查表。每读完一章，回到这里确认三件事：这一章的产出物是否留下、判据是否能用自己的话复述、反例是否能对应到本团队的一个真实问题。

如果某一章读完后只记得代码，不记得判据，说明读法偏了。代码是判据的证明，不是判据本身。

从1.1 五类端形态与一致性承诺 开始读正文。

如果读完之后仍然觉得「每个端都很特殊」，不必急着否定这套方法。多端不一致很少是技术问题，更多是责任没有被写下来。承诺矩阵的第一版可以很粗糙，粗糙的矩阵也比没有矩阵更容易被修正。