12.2 Koa - 人人都会AI编程

Koa 是由 Express 原班人马打造的新一代 Web 框架，旨在用更现代化、更精简的方式解决 Express 在设计上的一些遗留问题。Koa 的核心口号是“用更小、更具表现力的方式构建 Web 应用和 API”，它的出现不是对 Express 的简单重写，而是在 Node.js 异步编程模型演进到 async/await 之后，对中间件架构的一次重新思考。

12.2.1 Koa 的诞生背景与设计理念

Express 诞生于 Node.js 的 Callback 时代，其中间件机制依赖于 (req, res, next) 三元组，写起业务来需要大量地管理回调嵌套，而错误处理又分散在多个层次中，很容易被遗漏。随着 Node.js 对 Promise 和 async/await 的原生支持，Express 的遗留设计（如无法让中间件真正返回 Promise、错误处理需要手动 try/catch 搭配 next(err)）逐渐显得不够优雅。

Koa 团队决定抛弃历史包袱，不向下兼容 Express，设计了一个极简内核：

不内置任何中间件（甚至不带路由和模板引擎），让开发者根据需要自由组装。
核心只提供 Context（上下文） 对象和 洋葱模型中间件，并充分利用 async/await 让异步流程的编写像同步代码一样直观。
将请求和响应完全封装到 Context 上，而不是分开的 req / res。

正是因为 Koa 朝着“最小内核 + 强大扩展”的方向走，它很适合用来开发注重性能、或者需要高度自定义中间件链的轻量级服务。

12.2.2 洋葱模型中间件：Koa 最核心的精妙之处

Koa 把每一层中间件当作一个异步函数，这些函数按照洋葱的层级顺序执行：

const Koa = require('koa');
const app = new Koa();

app.use(async (ctx, next) => {
  console.log('1 - 进入中间件1');
  await next(); // 进入下一层
  console.log('1 - 离开中间件1');
});

app.use(async (ctx, next) => {
  console.log('2 - 进入中间件2');
  await next();
  console.log('2 - 离开中间件2');
});

app.use(async ctx => {
  console.log('3 - 进入最内层');
  ctx.body = 'Hello World';
});

app.listen(3000);

当一个请求进入时，控制台会输出：

1 - 进入中间件1
2 - 进入中间件2
3 - 进入最内层
2 - 离开中间件2
1 - 离开中间件1

这就像剥洋葱：在外层进入，由外向内执行到核心，然后返回时再由内向外逐层退出。每层中间件中的 await next() 就是把执行权交给下一层中间件的“分界线”，next() 返回的是一个 Promise，所以上游可以等待下游完全执行完后再恢复执行。这种机制天然支持：

请求前后处理逻辑分开：例如记录请求耗时，可以在进入时记时，在离开时计算差值。
统一错误捕获：最外层中间件可以 try/catch 包裹 await next()，捕获来自任意下游的异常。
响应后处理：例如压缩、设置缓存头等。

与 Express 相比，Koa 中间件的 next 不再是回调风格，而是返回 Promise，并且可以在 next() 之后继续写代码。Express 虽然也能通过 res.on('finish') 等方式实现类似效果，但远没有 Koa 这么直接和清晰。

12.2.3 与 Express 的核心差异

Koa 和 Express 的差别不只是换了一套语法，更在于架构的升级：

| 维度 | Express | Koa |
|------|---------|-----|
| 异步模型 | 传统 Callback，中间件缺陷较多 | 原生支持 async/await，中间件返回 Promise |
| 内置能力 | 自带路由、静态文件中间件、模板引擎等常见功能 | 极简核心，不捆绑任何功能，完全由中间件拼装 |
| 请求/响应封装 | req 和 res 保留原生 Node.js HTTP 对象，仅做些微扩展 | 封装为 ctx 对象，把所有常用操作收拢到一处，提供快捷方法 |
| 错误处理 | 需要 next(err) 将错误传到错误处理中间件，或 try/catch 插入异步捕获 | 最外层直接 try/catch 包裹 await next()，统一捕获所有异步错误 |
| 响应设置 | 通过 res.send(), res.json(), res.end() 等多种方法 | 统一通过 ctx.body 赋值，框架自动识别类型 |
| 生态 | 庞大且成熟，第三方中间件和教程极多 | 相对精简但质量高，核心功能依赖社区中间件（如 koa-router） |

例如，在 Express 中处理一个异步请求的可能写法：

app.get('/user', async (req, res, next) => {
  try {
    const data = await fetchUser();
    res.json(data);
  } catch (err) {
    next(err);
  }
});

在 Koa 中，同样的事情会更简洁优雅：

app.use(async ctx => {
  const data = await fetchUser();
  ctx.body = data;
});

无需每次都手动 try/catch，因为错误会冒泡到最外层的错误处理中间件（下面会具体讲解）。这种简洁性在中间件层叠套用的场景中尤其明显。

12.2.4 Koa 的核心用法与常见搭配

绝大多数的 Koa 项目都是“Koa 核心 + 若干中间件”拼起来的。典型的安装和启动流程：

npm install koa koa-router koa-body koa-static

一个包含路由、请求体解析和静态文件服务的 Koa 应用：

const Koa = require('koa');
const Router = require('koa-router');
const koaBody = require('koa-body');
const serve = require('koa-static');
const path = require('path');

const app = new Koa();
const router = new Router();

// 静态资源
app.use(serve(path.join(__dirname, 'public')));

// 解析请求体 (JSON / 表单 / 文件)
app.use(koaBody({ multipart: true }));

// 日志中间件（洋葱模型演示）
app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});

// 路由
router.get('/api/users', async ctx => {
  ctx.body = [{ name: 'Alice' }, { name: 'Bob' }];
});

router.post('/api/users', async ctx => {
  const { name } = ctx.request.body;
  ctx.body = { id: 3, name };
  ctx.status = 201;
});

app.use(router.routes());
app.use(router.allowedMethods());

app.listen(3000);

这种“自由组合”的风格给予了开发者极大的灵活性。如果想换个路由库（比如 @koa/router 代替 koa-router），或者加入参数校验、鉴权中间件，都非常容易，不会因为框架内置了太多东西而产生冲突。

12.2.5 错误处理：一次注册，全局兜底

Koa 的错误处理浑然一体。在所有中间件的外层添加一个错误处理中间件，就能捕获所有下游抛出的异常（包括 await 导致的异步错误）：

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = { error: err.message };
    // 可以将错误日志发送到监控系统
  }
});

这样，路由或更深层的中间件中抛出的任何未捕获错误，最终都会到达这里，避免了进程崩溃。ctx.throw(status, message) 也可以用来主动抛出带有状态码的 HTTP 错误，非常方便。

此外，Koa 在 Application 层面提供了 error 事件可以监听未在中间件中捕获的异常，用于最终的日志记录和告警：

app.on('error', (err, ctx) => {
  console.error('server error', err);
});

12.2.6 Koa 的版本选择与当前生态

Koa v1 使用 co 和 generator 函数实现异步，但随着 Node.js 全面支持 async/await，Koa v2 已经成为绝对主流，且 v3 已在规划中。新项目应直接使用 Koa v2 及以上。

当前 Koa 的生态虽然不是像 Express 那样铺天盖地，但其常用模块已经足够稳定：

路由：koa-router 或官方 @koa/router
请求体解析：koa-body（支持文件上传）、koa-bodyparser
静态文件：koa-static
参数校验：koa-joi-router 或直接在中间件中使用 Joi/Zod
认证：koa-jwt、koa-session
跨域：@koa/cors
视图渲染：koa-views 搭配模板引擎

这些中间件与 Koa 的洋葱模型天然适配，组合起来流畅且无侵入。

12.2.7 选型建议：什么时候用 Koa？

Koa 并非要取代 Express，而是在对异步处理和中间件链控制要求更高的场景中提供了更优解：

当你的团队已经习惯 async/await，且不愿意在异步错误处理上费力时，Koa 更安全、更清晰。
当你需要自己定制一套精简的中间件体系，或者开发一个网关、BFF 层，不需要 Express 内置的大量功能时，Koa 的极小体积和自由组装能力更合适。
如果是一个新项目且追求代码的现代性，Koa 是比 Express 更先进的选择。

不过，如果你的系统极度依赖 Express 生态中那些已经非常成熟的中间件，或者团队成员对 Koa 还很陌生，那么在熟悉的 Express 基础上搭配 TypeScript（确保类型安全）同样是可行的路线。而一旦项目规模大到需要模块化和依赖注入的架构时，NestJS（见第 12.3 节）可能是比 Koa 更好的企业级选择。

无论如何，理解 Koa 的洋葱模型对你使用任何 Node.js Web 框架都有帮助，因为这种思想已经渗透到包括 Redux 中间件在内的很多前端状态管理库中，掌握它让全栈思维更加统一。