附录B · 技术栈对照：换个栈，哪些变了、哪些没变

📖 不写 Python 的人从这里进；写 Python 的人拿它确认「哪些是概念、哪些只是 FastAPI 的叫法」。

01–15 章末尾各有一张「换个栈怎么对应」小表，一共 15 张。这里把它们按概念族重排成一份总对照，并补上原表缺的两块：Java / Spring（企业里最常见的那个后端栈，原表一次没出现过）和前端的 React / Vue（原表只在 09、10 两章出现过）。

⚠️ 每一格背后的「为什么」留在各章，这里不重讲 —— 每一族都标了它出自哪一章，看不懂某一格就回去看那一章。

🗓️ 先声明一次，后面不再重复

这份表里的库名会过期，判据不会。

⭐ 发现名字对不上时，拿最左边那一列去搜 —— 那一列是概念，它不动；右边四列是叫法，它们每年都在动。

所以这里刻意不写版本号、不写性能对比、不写「现在大家都在用 X」。那三样是全表里唯一必然会腐、而且删掉完全不影响价值的部分。会过期的具体东西单独标 🗓️。

🎯 一句话

四个栈都得干同一件事，区别只在「它把哪一半藏起来了」—— 藏起来不等于替你做完，而且藏得越深，你越晚发现它其实没做。

🧭 零、这份表和「一行 API 都不写」那条立场怎么共处

站里 智能体工程教程 16b 写过一句很硬的话：「因为框架会过期而原理不会，这章只写映射和坑，一行 API 都不写。」

⚠️ 那说的是 Agent 框架（LangChain 那一类），立场是对的 —— 那层封装薄、换得快、封的还是你本来就该懂的机制。但全栈不给代码没法学。 00 章第五节已经拍板过折中，原话三条：

⭐ 这份附录就是第二条的产物，只是把 16 处分散的对照收成一处、并补了两个栈。它和 16b 不矛盾：16b 拒绝写的是「怎么调这个 API」，这里写的是「这个概念在你那个栈里叫什么」。 后者恰恰是 16b 自己在做的事 —— 它管那叫「一张对回机制的地图」。

💡 怎么用：不写 Python 的人，先在这里确认概念对得上，再回正文读原理，把代码当伪码看。

🧱 一、起一个 HTTP 服务

📍 出自 03 章（另见 02 章）

⭐ 不变的是什么：「每个请求都要做、却不属于任何一个业务函数的事，得有一个统一的地方挂」 —— 鉴权、限流、拿连接、生成 trace_id、识别租户。这个概念不会过期，Depends 这个名字会。四个栈里只有 FastAPI 把它叫「依赖注入」，另外三个都用中间件干同一件事。

⚠️ Spring 这一列有个名字陷阱：Spring 确实有一个真正的依赖注入容器，但它注的是启动期的单例 bean，和 FastAPI 的 Depends（每个请求跑一遍）不是同一件事。「每请求要做的事」在 Spring 里仍然走 Filter / Interceptor —— 名字撞了，位置没撞。

⭐ 「等待不占线程」那一行值得多看两眼：Python 用 async def、Node 天生如此、Go 交给运行时 —— 这三个都是语言层就定死的。只有 Java 把它做成了一个你要自己选的部署形态（阻塞的 MVC 还是反应式的 WebFlux），🗓️ 而虚拟线程又让「阻塞写法」重新变得便宜。⭐ 所以 03 章那条判据在 Java 里换了个形态但没消失：你仍然要知道自己写的这段代码，等待的时候占不占着一条执行流。

🌊 二、分批往外写响应

📍 出自 05 章（另见 01 章）

⭐⭐ 不变的是什么：「分批往外写」在每个栈里都要显式表达，没有一个栈是「你只管 yield，剩下的它替你办」。 区别只在它把哪一半藏起来了：FastAPI 藏进 StreamingResponse 这个名字里、Go 明写成 Flusher.Flush()、Spring 藏进一个你从没设过的超时配置里。

⚠️ Spring 那个默认超时是这一族最容易咬人的格子：它不是「不流式」，是流到一半被框架自己掐断，而本地开发时你的回答都短，一次都不会触发。⭐ 判据和 04 章的读取超时完全同源：这个数要大于「一次合法的静默能有多长」，不是由手感决定。

⭐ 有一件事四列写的是同一个词：⚠️ 反向代理的缓冲。Nginx 的 proxy_buffering off、云平台入口网关的默认值 —— 那一层和你用什么语言毫无关系（05 章 · 14 章）。换栈重写时，人们通常记得搬业务逻辑，忘了搬这一件。

🗄️ 三、数据库与连接池

📍 出自 06 章（向量那一层见 07 章）

⭐ 不变的是什么：四个生态的迁移工具都长成「一串有序脚本 + 一张记录跑到哪了的表」，连接池都有一个「最大连接数」旋钮，执行计划都是同一句 EXPLAIN ANALYZE（那是数据库的能力，跟语言无关）。换栈要重学的只有语法。

⭐ 最后一行是这份附录里最值得单独记的一格。 06 章那条判据是「事务里只放数据库自己的操作，任何网络调用都在事务之外」，而它在 Spring 里最危险 ——

另外三个栈里，事务是一段你能用眼睛框出来的代码，你把 LLM 调用写进去，with 块或 Begin/Commit 之间会明显变长。@Transactional 把边界变成了「这个方法的全部」：你在这个方法里加一行调模型，事务就默默从几毫秒变成几秒到几十秒，代码的形状上什么都没变，评审时也看不出来。

⚠️ 连接池默认值这一行别照抄数字。 每个池的默认值都不一样，而且都在变（🗓️ 用前查你那个池的文档）。⭐ 06 章给的判据才是不动的那个：pool_size 是一道除法 —— 数据库能承受的连接总数 ÷ 应用进程数 ÷ 还有谁在连同一个库。四个栈里这道除法一模一样。

⭐ 向量那一层几乎不受栈影响：建表、<=> 运算符、索引选型、先过滤还是先检索 —— 全是 SQL 层和数据建模的事。各栈都有一个把向量类型接进驱动的小库（🗓️ 名字和各家 ORM 的支持程度都在变，用前先查包管理器里的真实包名）。⭐ 这是选 pgvector 的一个附带好处：你的知识不绑定在某个 SDK 上。

⏳ 四、后台任务与队列

📍 出自 11 章

⭐ 不变的是什么：名字全不一样，四件事完全一样 —— 一张带状态的表、一条原子认领语句、一个由输入算出的幂等键、一套带抖动和上限的重试。这四件事不过期，上面那些包名会。

⭐ 一个好例子：Java 生态里那些「把任务存进数据库」的调度库，打开一看就是一张带状态的表 + 一条原子认领语句 —— 11 章那四件事，一件不少。它不是「Java 的做法」，它就是那四件事换了个包装。

⚠️ @Scheduled 是这一族最会骗人的一格：它写起来像一行注解，看上去比另外三个栈都省事 —— 但多副本部署时每一台都会到点触发，于是「每小时结一次账」变成了每小时结 N 次。修法是加一把分布式锁（🗓️ 有现成的库），⭐ 而判据还是 11 章那条：一个由输入算出的幂等键。 另外三个栈的定时任务也有同一个问题，只是它们的写法不会让你误以为框架管了。

🔑 五、配置与密钥

📍 出自 13 章

⭐ 不变的是什么：四个栈形状完全一样 —— 一处声明全部配置 → 启动时校验 → 校验不过就别启动 → 打印时永远不吐密钥。 会过期的是包名，不会过期的是这四步。

⭐ 第三步「校验不过就别启动」在 Spring 里是最彻底的：配置校验失败发生在容器装配期，进程直接起不来，根本没有「先跑起来、跑到那行代码才发现少个 Key」的中间状态。⚠️ 但这不是 Spring 独有的能力，是它默认帮你做了 —— 另外三个栈要你自己把校验放在启动路径上，放晚了就退化成运行期才炸。

⚠️ Spring 这一列有个 grep 陷阱值得单独说：它会把环境变量名和配置项名当成同一个命名空间来匹配（把分隔符和大小写的差异抹平），好处是同一份配置既能写在文件里也能用环境变量盖掉；⚠️ 代价是你在代码里搜那个环境变量名会一无所获 —— 代码里出现的是配置项的名字，环境变量名是推算出来的。🗓️ 具体的匹配规则查文档，⭐ 但排查思路不变：从配置项名反推，不要指望全文搜索能找到那根线。

📈 六、日志与指标

📍 出自 15 章

⭐⭐ 不变的是什么：三个栈用隐式上下文（写起来舒服），一个栈用显式传递（写起来啰嗦）。隐式的那三个都有同一个 bug：换执行载体时上下文断掉，而且不报错。

⭐ 15 章那个 run_in_executor 的坑不是 Python 的毛病，是隐式上下文这个设计的固有代价：

⭐⭐ 三边的症状一模一样：日志里的 id 悄悄变成默认值，不抛异常、不打警告、本地单人开发时也看不出来。修法的形状也一模一样：在跳转的那一刻，把上下文整个拷过去。 Go 那种「什么都要手传」的啰嗦，买的就是这一条 —— 15 章的原话是「永远不会出现『第三层忘了传』」。

⚠️ 还有一个断点四个栈全都躲不掉：⭐⭐ 进了队列就必须写进 payload。 队列里的任务是另一个进程、可能另一台机器、可能几分钟之后才跑，任何进程内的上下文机制都帮不上忙（15 章第三节）。这一格没有语言差异，只有做没做。

🧪 七、把上游换成假的

📍 出自 03 章（dependency_overrides）和 04 章（FakeLLM）

⭐ 不变的是什么：这四行都不是测试技巧，是设计的结果。它们能成立的唯一前提是 03 章那条规矩：api/ 里不许直接出现模型 SDK 的名字。 业务代码对着你自己的接口写，「换成假的」才是一行的事；对着某个 SDK 写，换什么栈都换不掉。

⭐ 04 章说 FakeLLM 值钱不在于省钱，在于它能故意抛 429、故意超时、故意返回半截 JSON —— ⭐ 重试和降级路径只有这样才测得到。 这一点四个栈完全一样。

⚠️ 第二行 Go 是唯一把「假上游」放进标准库的，⭐ 但那只省了一次安装：形状四家一模一样 —— 起一个真的 HTTP 服务，让被测代码真的走一遍网络栈，而不是 mock 掉客户端对象。⭐ 这个区别很重要：mock 客户端测不出超时怎么分、重试白名单对不对，而那两件恰恰是 04 章整章在讲的东西。

📦 八、容器与部署

📍 出自 14 章

⭐ 不变的是什么：层缓存的排序法则、多阶段构建、.dockerignore、两个健康检查端点问的是两个问题、关机四步 —— 一条都不属于 Python。会过期的只是基础镜像的版本号和包管理器的名字。

⭐ Spring 是四个栈里替你做得最多的一个：优雅关闭一个开关、两个健康检查端点开箱就有。⚠️ 但它替你做的是端点，不是语义 —— 14 章那四步里最关键的是 ①先摘流量、②再停止接受新连接，顺序反了就永远等不完；而框架不知道负载均衡器什么时候把你摘下去，也不知道你正在流式的那个请求还要跑两分钟。

⭐⭐ 所以这一族的真正判据和栈无关，一共两条： ① 宽限期必须 ≥ 你最长的一次请求（⚠️ 各层默认值都在几十秒量级 🗓️，而一次长回答跑两分钟很正常 —— 不改的话每次发版都切断一批正在流式的用户）； ② /readyz 要反映真实状态，并给「摘流量」这个动作留几秒。 框架给你端点，不会替你决定这两个数。

⭐ 另外「一个容器跑一个进程」和反向代理那一层，四列写的是同一句话 —— 那是容器和 HTTP 的规矩，不是某个语言的。

🎨 九、前端：原生 JS / React / Vue

📍 出自 09 章 和 10 章

⚠️ 这一族的三列不是「三个后端栈」，是同一个浏览器上的三种写法 —— 所以判据也不同：不是「哪个更好」，是 ⭐ 「哪几行框架真能帮上忙」。

⭐⭐ 不变的是什么：八行里只有三行是框架真能帮上忙的（状态、渲染、只更新最后一条），另外五行换成任何框架都还在。 收流、拼帧、AbortController、滚动跟随、净化 —— 这些是浏览器和 HTTP 层的问题，以及「模型输出是不可信输入」这件事，不是框架能替你解决的。

⭐ 这也正是 10 章值得单独一章的原因：AI 应用前端的难点不在 UI 层，在流式协议和不可信内容上。⚠️ 别把这张表读成「所以不用框架」—— 09 章不用框架是因为它的读者是后端（目标是「做出不丢人的界面」）；本来就写前端的人，00 章的路线 C 让你直接从 10 章开始。

🧷 十、横着看这九张表，四条规律

前面每一族的「⭐ 不变的是什么」都只管那一族。把九族横过来看，会浮出四条更大的：

① ⭐⭐ 每个栈都得干同一件事，区别只在「它把哪一半藏起来了」

FastAPI 把 flush 藏进 StreamingResponse 这个名字里、Go 把它明写成 Flusher.Flush()、Spring 把流式的超时藏进一个你从没设过的配置项里。藏起来不等于替你做完 —— ⚠️ 藏得越深，你越晚发现它其实没做，而且往往是在生产环境、在最长的那个回答上才发现。

② ⭐⭐ 隐式的东西写起来舒服，代价永远是同一个：换执行载体时它悄悄断掉，而且不报错

contextvars 断在线程池、MDC 断在异步注解、@Transactional 让事务边界从代码里消失。三个例子的共同点是「不报错」 —— 它们不会在 CI 里红，只会让你的日志少一根线、让你的连接池在并发上来时耗尽。Go 那种什么都要手传的啰嗦，买的就是这一条。

③ ⭐ 框架能替你做的是端点和语法，替不了的是顺序和判据

Spring 自带两个健康检查端点，但「先摘流量再停止接受新连接」还是你的事；四家的迁移工具都是「有序脚本 + 一张记录表」，但扩展—收缩五步法是你的事；四家都有队列库，但幂等键怎么算是你的事。⭐ 凡是「顺序」和「阈值」，翻遍文档也找不到 —— 因为它取决于你的业务。

④ ⭐ 越靠近数据库和浏览器，栈的差别越小

EXPLAIN ANALYZE、SKIP LOCKED、<=>、Nginx 的 proxy_buffering、fetch + getReader()、AbortController、SSE 的帧格式 —— 这些格子里，四列（或三列）写的是同一个词。⭐ 换栈要重学的东西，比你以为的少得多：真正要重学的是最上面那一层（路由怎么写、依赖怎么注），越往下越通用。

⭐⭐ 这份表最终想让你得到的一句话： 看到一个陌生的栈时，别问「它的 API 怎么写」，问「这九件事它做了哪些、藏起来了哪些、一件没做的是哪些」。 前一个问题的答案半年就过期，后一个问题的答案跟着你换栈。

🔗 这一页连到哪里

✅ 检查点

1. 这份表最左边那一列和右边四列，哪一列会过期？发现名字对不上时该怎么办？
2. ⭐ 「分批往外写响应」这件事，四个栈里有没有哪个是「你只管产出，剩下的它替你办」的？
3. FastAPI 的 Depends 和 Spring 的依赖注入，是不是同一件事？
4. ⭐⭐ contextvars 扔进线程池会断、Java 的 MDC 换线程会断、Go 不会断 —— 这三件事说明了什么共同的东西？代价各是什么？
5. 「别把 LLM 调用包在事务里」这个坑，为什么在 Spring 里比另外三个栈更危险？
6. 前端那张表八行里，换成 React 或 Vue 能真正省掉的是哪几行？剩下的为什么省不掉？
7. Spring 自带两个健康检查端点，是不是就不用管 14 章那四步关机顺序了？
8. ⭐ 为什么说「越靠近数据库和浏览器，栈的差别越小」？举两个四列写同一个词的例子。