《互联网产品的客户端架构·内容、社交与实时互动》前言

为什么单独写一篇前言

技术书的前言通常有两个用途：告诉读者这本书讲什么，以及告诉读者怎么读。本卷的前言还想多做一件事：把「卷二与卷一、卷三的关系」讲清楚。

原因是一本四卷本的中间卷最容易被误读。只读卷二的读者，可能以为客户端架构就是「信息流加 WebSocket」；只读卷一的读者，可能以为状态归属与分层已经解决了所有问题。两种误读都会在真实项目里付出代价。

这篇前言会把四卷的分工、卷二的位置、实验工程的用法一次讲完。如果你时间有限，至少读「卷二的结构」与「卷二的边界」两节。

四卷规划与卷二的位置

《互联网产品的客户端架构》共四卷：

卷二处在「静态结构」与「高约束业务」之间。卷一给出的分层、状态归属、错误边界，在卷二会被放进持续变化的数据里检验；卷二建立的断点、去重、降级判断，会在卷三被交易与增长场景进一步收紧。

一个具体的例子：卷二讲点赞的乐观更新，回滚成本低，失败就回滚。卷三讲下单的乐观更新，回滚成本高，默认不能乐观，必须先确认再改 UI。同一个模式，在不同的约束下得出相反的结论。这正是四卷分卷的意义：模式本身不复杂，难的是判断在什么约束下适用。

卷二的结构

十三章分四段，前面已经说过，这里给出更具体的章节依赖：

• 第 1 章是坐标系，后面所有章节都引用它的四条面划分与三级验证。
• 第 2 章依赖第 1 章的容器；第 3、4 章依赖第 1 章的内容模型，但不依赖第 2 章。
• 第 5 章依赖第 1 章的互动面；第 6、7、8 章形成一条连接链，建议按顺序读。
• 第 9、10 章依赖第 7 章的重连与补拉；第 11、12 章相对独立。
• 第 13 章依赖前面所有章节，但每一节的场景可以单独运行。

依赖关系不是硬约束。每章开头会用一段话复述必要前提，读者从中间进入也能跟上。真正的硬约束只有一条：第 6 到 8 章建议连读，因为连接生命周期、重连退避、presence 衰减是一个连续的设计。

贯穿案例「回声」的内容面

「回声」在卷一里是一个有发现页、详情页、下单页的产品。卷二只使用它的内容面：

• 信息流：推荐流与关注流，支持下拉刷新与无限滚动。
• 详情：单条内容的完整正文、评论、互动。
• 发布：文字、图片、视频的上传与草稿。
• 私信：一对一会话，实时消息与在线状态。
• 通知：点赞、评论、关注的未读汇总。
• 审核：发布前预检与发布后的审核态。

这些面共享同一份内容模型，但各自有独立的状态容器。书中不会给出完整的页面代码，只给出每一面的关键判断与可运行片段。

案例中的产品决策也是假设的：信息流上限 200 条、评论按时间正序、私信不做端到端加密、审核采用「先发后审」。这些决策会影响架构，书中会在用到时说明它们的影响，读者可以替换成自己的决策重新推导。

实验工程 social-client-lab

实验工程与卷一平行，目录按章组织：

social-client-lab/
  src/core/       内容模型、信息流容器、分级判定
  src/feed/       游标、窗口、刷新策略
  src/render/     块模型、sanitize、占位
  src/upload/     上传编排、续传、格式策略
  ...
  test/           与 src 一一对应的测试

运行方式：

cd .local/checks/social-client-lab
node --test test/core/content-model.test.ts

不需要安装依赖。Node 26 原生支持 TypeScript 类型剥离，代码里没有装饰器、没有 enum、没有需要编译的语法。导入路径带 .ts 后缀，这是 Node 原生 ESM 的要求。

工程只用于验证书中逻辑，不是生产脚手架。它没有路由、没有 UI 框架、没有构建配置。读者要把它接进自己的项目，需要补的是适配层，不是核心判断。

与卷一实验工程的关系

卷一有 echo-client-lab，卷二有 social-client-lab。两个工程刻意分开，理由是它们的依赖方向不同。

卷一工程的模块围绕「一个页面如何组织」：分层、状态、路由、渲染、构建。它们大多只依赖核心类型，适合做结构验证。卷二工程的模块围绕「数据如何流动」：游标、窗口、连接、补拉。它们需要事件循环、假时钟与本地端口，验证方式更接近集成测试。

两者不共享代码，但共享概念。卷一的「事实源」「回滚成本」在卷二被反复引用；卷二的「断点」「去重集合」会在卷三被交易流程复用。如果读者想合并两个工程，建议保留 core 的类型定义，其余模块按需引入，不要强行统一抽象。

工程分开还有一个现实原因：卷二的部分模块需要真实端口，跑起来的资源占用比卷一高。把它们混在一起，会让只想跑纯函数用例的读者被迫等待网络用例。

错误处理的一致口径

本卷所有模块对错误采取同一套口径，方便读者横向比较：

1. 错误必须被分类：网络错误、服务端拒绝、客户端校验失败、用户取消，四类的处理不同。
2. 可恢复错误不抛到 UI：进入重试队列或降级路径，UI 只看到「进行中」或「已完成」。
3. 不可恢复错误必须可行动：告诉用户发生了什么、能做什么，而不是只显示「出错了」。
4. 错误不吞：即使降级成功，也要记录一次可观测事件，否则线上无法知道降级在发生。

这套口径不是行业唯一解，但它能让书中各章的代码保持一致。读者替换成自己团队的口径时，至少要保证「分类」与「可观测」两点，否则降级会变成静默失败。

三级可运行性

与卷一相同，本卷的验证分三级：

三级不是质量等级，而是「能证明什么」的范围。L1 通过不代表流程正确，L3 通过也不代表真机没问题。每一节会明确标注它的结论覆盖到哪一级。

本卷不承诺真机验证。iOS 与 Android 只讲架构建模，小程序只讲包体与生命周期的约束，不做平台实测。这是写作边界，不是对平台的轻视。

一次 L2 才抓到的错误

卷一的前言讲过一次 L2 抓错的案例，这里讲一个卷二特有的。

上传模块的第一版，orchestrator 的单元测试全绿：分片切分正确、进度计算正确、完成判定正确。但整条链路在手工测试时失败：上传完成后，服务端收到的文件比原文件少了最后一个分片。

原因是 Promise.all 在最后一个分片确认之前就返回了。单测只测了「分片函数」与「进度函数」，没有测「所有分片确认之后才 resolve」这个时序。这个错误属于 L2：它需要真实的 Promise 调度才能暴露。

修复后补了一条 L2 用例：用假时钟与可控的 resolve 顺序，断言「最后一个分片未确认时，整体状态仍是 uploading」。这条用例后来在重构时又抓住了一次回归。

这类错误说明为什么本卷坚持三级标注：不是所有 bug 都能在纯函数层被发现，也不是所有结论都需要真实端口。标注级别，是为了让读者知道「这段代码在什么环境下被验证过」。

代码块的三行头

正文里标了文件来源的代码块，开头固定三行：

// file: src/feed/cursor.ts
// tier: L1
// verify: node --test test/feed/cursor.test.ts

• file 是相对实验工程的路径。
• tier 是这段代码的验证级别。
• verify 是复现它的命令。

这三行不是注释装饰。书稿的校验脚本会按 file 找到工程文件，逐字节比较；不一致就报错。这样能防止「书里的代码」与「能跑的代码」慢慢分叉。

没有标 file 的代码块是说明性的，可能不完整，读者不应直接复制运行。

数字与版本的口径

版本口径：Node v26.5.0，TypeScript 以 Node 原生类型剥离为准，不使用 tsc。浏览器行为以 2026 年 10 月的稳定版 Chromium 与 Safari 为参考，但书中不依赖具体浏览器 API 的差异。

数字口径分三类：

1. 真实输出：测试耗时、用例数量、通过数量，逐字来自本机运行。
2. 案例假设：容器上限、退避间隔、合并窗口，用于演示判断，不是标准。
3. 推导值：由前两类数字计算得出，文中会给出算式。

读者如果要把某个数字用于生产，请先确认它属于哪一类。把案例假设当成实测，是把书读坏的最快方式。

卷二的边界

本卷明确不覆盖：

• 推荐算法与排序策略。信息流只讲「如何稳定消费」，不讲「如何决定顺序」。
• 富文本编辑器的实现。只讲内容的块模型与渲染边界，不讲编辑器内核。
• 音视频编解码与播放器内核。只讲上传、格式选择与占位，不讲解码。
• 实时协议的底层实现。只讲连接管理、重连、补拉与去重，不讲帧格式与拥塞控制。
• 安全攻防的完整体系。只讲端上渲染边界与预检，不讲服务端风控。
• 真机性能与平台适配。只讲架构建模，不做实测。

这些主题中的每一个都值得单独成书。本卷的选择标准是：它与端上架构判断直接相关，且能在 Node 环境里被验证或建模。

需要特别说明「不做真机验证」这条边界。它不代表平台差异不重要，而是因为真机性能受设备、系统版本、后台策略、网络制式影响，无法在书稿里给出可复现的结论。书中会把平台差异作为「架构输入」来讲：例如 iOS 会挂起后台连接，因此重连必须假定中断随时发生；小程序包体受限，因此首屏模块必须能裁剪。这些是设计约束，不是性能数字。

同样，书中不会给出「某框架更好」的判断。框架会变，判断方法不会。读者应该用书中的方法评估自己正在用的框架，而不是找一个可以照搬的答案。

怎么读这一卷

三种读法在前言里再强调一次：

• 顺序读：第 1 章建立坐标系，第 2 到 12 章按主题展开,第 13 章收口。
• 按问题读：从目录找到对应章节，每章开头有前提复述。
• 按代码读：先跑实验工程，再看正文解释。适合已经熟悉业务、只想确认实现细节的读者。

无论哪种读法，建议至少完整读第 1 章与第 13 章。前者定义所有术语，后者验证所有判断组合起来是否成立。

关于代码质量的自检

书中的每个代码片段都经过三类自检，读者也可以用同样的方式检查自己的实现。

第一类：格式自检。 每个标了 file 的代码块与工程文件逐字节比对。若有空白差异、顺序差异，校验脚本会报错。这保证了「书里看到的」与「实际能跑的」是同一份代码。

第二类：行为自检。 每个模块都有对应测试，且测试必须真实通过。文中出现的测试输出是运行结果，不是手工编写的示例。耗时数字可能随机器变化，但用例数量与通过数量不会。

第三类：边界自检。 每节末尾列出常见错误与边界，覆盖三类边界：输入边界（空值、超长、异常字符）、时序边界（并发、乱序、超时）、产品边界（权限、审核、降级）。这些条目不是凑数，而是写作时真的踩过的坑。

三类自检之外，还有一条人工检查：叙事是否连贯。代码正确但解释跳跃，对读者同样是失败的。这条只能靠通读，没有脚本能替代。

写作顺序与章节编号

本卷按「先面、再流、后连接」的顺序写作，章节编号也按这个顺序排列。但编号不代表阅读必须严格顺序，读者可以按前面的三种路径进入。

需要说明的是，章节内部的三个小节通常有这样的关系：第一节定义问题与判断，第二节给出实现与代码，第三节处理边界与失败。这个结构不是强制的，但大多数章节遵循它，读者可以据此快速定位。

小节编号的格式是「章.节」，例如 7.2 表示第 7 章第 2 节。正文中的交叉引用都使用这个格式，方便读者跳转。

每章末尾的练习

大多数章节末尾的「常见错误与边界」不是练习，而是检查清单。真正的练习在正文里：每节都会给出一个可运行的片段，读者可以把它改坏，再看测试是否失败。

推荐的练习方式有三步：

1. 先运行原代码，确认测试全绿。
2. 修改一个前提，例如把容器上限改成 3、把重连退避改成固定间隔、把 sanitize 白名单放宽一项。
3. 预测哪些用例会失败，再运行验证。

第三步是关键。如果预测与实际一致，说明你理解了这段代码的约束；如果不一致，正文里通常有一段解释能补上认知差。这比抄一遍代码有效得多。

有读者可能会问：为什么不直接给课后题。因为架构判断没有标准答案，只有「在你的约束下是否成立」。改造已有代码并观察失败，比做一道有标准答案的题更接近真实工作。

如果读者把某段代码改坏后，测试仍然全绿，那可能暴露了两件事之一：测试覆盖不足，或者这段代码的行为没有被任何测试锁定。两种情况都值得记录，它们会提醒你在自己的项目里补上对应的用例。

练习不要求提交，也没有参考答案。真正的参考是你自己的产品：同一段代码放进不同的业务约束里，正确的改法可能完全不同。

致谢与反馈

这套书的写法受益于很多次真实的故障复盘。案例中的事故都经过改写，但判断与教训来自实际项目。

如果读者发现代码无法运行、结论与自己的场景冲突、或者某个数字明显不合理，欢迎指出。技术书的价值不在于「说得都对」，而在于「说清楚在什么条件下成立」。

开始之前

在进入第 1 章之前，建议先做一件事：打开你正在做的产品，找出它的信息流、详情、互动、实时四条面，分别写下「这条数据的事实源在哪里」「失败时退到哪里」。

写不出来也没关系，第 1 章会给出模板。带着这四个空白进入正文，比空手读一遍更有收获。