第 1 章 洋葱之门：Koa 全景与上手
第 1 章 · 洋葱之门：Koa 全景与上手
章节摘要：本章跟着一条线走——一个被回调风格拖垮的老服务，如何在团队手里换上 Koa 的洋葱内核。历史从哪里来、和 Express 怎么选、第一颗洋葱怎么跑起来，都在这条线上。
一条主线：给老服务换一颗内核
我们虚构但不虚构地讲一个场景：一家做内容管理系统的团队，手里有个跑了多年的 Node.js 服务，接口散落在回调嵌套里，错误处理东一处西一处，每次改需求都像在拆盲盒。技术负责人决定迁移到 Koa，但直接换框架等于把整栋楼的地基掀了——所以本章先不写代码迁移，而是先回答三件事：Koa 从哪来（1.1）、它和 Express 的边界在哪（1.2）、最小可跑的一颗洋葱长什么样（1.3）。这三站走完，你会明白迁移不是换库，而是换一种组织异步逻辑的方式：请求进一层、出一步，每层只做一件事。
沿途站点
- 1.1 十年剥层：Koa 的演进脉络——从 Connect 与 Express 的源头讲起，经过 generator 与 co 的过渡带，落到 async/await 语义定型的 Koa 2。这一站解决"为什么会有洋葱模型"的问题：不是炫技，而是回调与 generator 都没能同时解决异步编排和错误传播。
- 1.2 Koa 与 Express：对比与选型——把两个框架放在内核设计、生态约定、错误模型三个维度上对照，给出一张可以直接用于技术评审的选型判断表，并交代迁移的真实成本。
- 1.3 环境准备与最小可跑应用——装好 Node.js 与 Koa，写出一个不到二十行的最小应用，用命令行完成首次请求穿透，并把新手最常见的启动报错排一遍。
拐点与结论
本章最重要的认知转折在第 1.1 节的后半段：洋葱模型不是为了优雅而优雅的设计，它是对"异步代码需要对称结构"这个需求的直接回应——中间件进层时申请资源、出层时释放资源，next() 前后天然形成进入与返回两个阶段。结论也在这里：选 Koa 选的不是"更少的代码"，而是"可推理的控制流"。如果你读完本章只记住一句话，记住这句：框架的形态决定了错误和资源在代码里的流动方式。
本章的全景结构如下。
上手前的三个常见误区
动笔之前先排雷，这三个误区会浪费新手整整一个周末。误区一：拿 Express 的肌肉记忆写 Koa——res.send 与 ctx.body 的差别不在名字，在发送时机，1.2 与 1.3 节会反复对齐这组差异。误区二：跳过历史直接背 API——不知道洋葱模型为什么长成这样，第 2 章的每个机制都会变成需要死记的条目；1.1 节那条时间线是给后面八章省力的投资，值得慢慢读。误区三：环境口径随缘——Node 版本过低、依赖没装全、端口被占，这类问题的报错信息与新手第一直觉的排查方向常常南辕北辙，1.3 节把高频启动报错与固定排查路径列成了清单，遇到时先对单查、再动手改。
图 1-0：本章三站与主线的关系
读完你应该
- 能用五分钟向同事讲清 Koa 诞生的时间线与动因，说出 generator 过渡带存在的原因；
- 能对照团队场景填写选型判断表，说清什么情况留在 Express、什么情况换 Koa、代价各是什么；
- 能从空目录开始搭出最小 Koa 应用并跑通请求，理解每一行代码在洋葱里的位置；
- 能独立排查端口占用、Node 版本不匹配这两类最常见的启动失败；
- 能说出"中间件、洋葱模型、进层出层"这几个词在本册语境下的准确含义。
下一章的接力
1.3 跑起来的那个最小应用，内核里发生了什么？app.use 塞进去的函数为何必须 await next()？Context 对象从哪来、到哪去？第 2 章把洋葱剥到芯，逐个拆解 Application、Context 与错误处理的内部机制——那是全书技术含量最密集的一章，也是后面所有章节的地基。