深入解析 Koa 官方 FAQ：Koa 的设计定位与 Context 对象属性设计规则

本文以 Koa 官方 FAQ（docs/faq.md）为主线，逐条回答社区最常提出的五个问题：Koa 与 Express、Connect 的定位关系、为何不内置路由、为什么 Koa 不是“Express 4.0”，以及 ctx/ctx.request/ctx.response 上自定义属性的设计规则。同时结合当前仓库（v3.2.1）的 lib/application.js 与 lib/context.js 源码，验证这些设计决策的实现依据。读完本文，你可以准确说明 Koa 的功能边界，并理解 Context 属性委托（delegation）的底层机制。

一、Koa 会取代 Express 吗？

FAQ 给出的官方回答是：不会。Koa 更类似于 Connect，但 Express 中许多"便利功能"（goodies）在 Koa 中被下沉到了中间件层，从而为整个技术栈打下更坚实的基础——这使中间件的编写对整条链路（而不只是应用端代码）都更愉快、更不易出错。

FAQ 进一步解释了原因：在 Express 生态中，许多中间件会重复实现相似的功能，甚至实现得并不正确；而诸如签名 Cookie 密钥（signed cookie secrets）这类特性，本质上是**应用级（application-specific）**而非中间件级（middleware-specific）的关注点。

这一点可以从当前仓库的源码中得到印证：

• Koa 的核心 Application 类（lib/application.js）只包含中间件注册（use）、请求分发（callback）、上下文创建（createContext）与默认错误处理（onerror），并继承自 Node 的 EventEmitter。
• Readme.md 明确说明：只有几乎每个 HTTP 服务器都会用到的方法（内容协商、Node 不一致性的归一化、重定向等）才被直接整合进 Koa 约 570 行（SLOC）的小型代码库中，并且 "Koa 不捆绑任何中间件（Koa is not bundled with any middleware）"。
• 签名 Cookie 正是"应用级配置"的典型例子：lib/context.js 中的 ctx.cookies getter 会为每个请求上下文惰性创建一个 Cookies 实例，并把应用级的 this.app.keys（签名密钥）与 this.request.secure 传递进去。密钥归属于应用，中间件只是消费者——这正是 FAQ 所述"把 Express 的 goodies 移到更合理层级"的设计体现。

二、Koa 会取代 Connect 吗？

FAQ 的回答是：不会，只是对相似功能的不同实现取向。如今 async functions 让我们可以用更少的回调编写代码，这是 Koa 区别于 Connect 的背景；但 Connect 同样强大，有些人仍然偏好 Connect，取舍取决于个人。

从源码结构看，Koa 的核心差异在于中间件"栈式"（stack-like）的执行模型：lib/application.js 的 callback() 通过 koa-compose 将 use() 注册的所有中间件组合成一条 await 链——请求在下游执行动作，响应在上游被过滤与加工。Readme.md 中给出的 logger 中间件示例清晰地展示了这一差异：

// async function 风格（Koa v2+）
app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});

值得注意的是，Koa 对中间件签名的态度经历过一次重大演进：v1.x 的旧版签名（callback 风格）在 v2.x 中已被弃用，而 v3 已完全移除对旧签名中间件的支持（见 Readme.md 中 "Koa v1.x Middleware Signature" 一节的说明）。如果你从旧版本升级，可参考 docs/migration-v2-to-v3.md 与 docs/migration-v1-to-v2.md。

三、Koa 内置路由吗？

FAQ 的回答很直接：不内置。开箱即用的 Koa 没有任何形式的路由，但官方 wiki 列出了大量可选的路由中间件。

这一结论在源码层面可以得到严格验证：

• use() 方法（lib/application.js）的全部职责只是做类型检查并把函数推入 this.middleware 数组；
• callback() 方法中没有任何路由表、路径匹配或分发逻辑，它只完成两件事：用 this.compose(this.middleware)（默认即 koa-compose 的 compose）组合中间件，以及按请求创建上下文并执行；
• 构造函数（lib/application.js）中也没有任何与路由相关的配置项，可用选项只有 env、keys、proxy、subdomainOffset、proxyIpHeader、maxIpsCount、compose、asyncLocalStorage 等。

因此，路由能力只能通过第三方中间件引入：路由中间件以 app.use() 的方式注册，在自己的闭包中维护"路径 → 处理器"的映射，命中后执行对应处理器，未命中则 await next() 继续向下游传递。Koa 本身只保证中间件链的按序执行与异常冒泡（见 docs/error-handling.md）。

四、为什么 Koa 不是"Express 4.0"？

FAQ 的回答是：Koa 与人们对 Express 的认知是相当大的一次偏离，设计从根本上就不同。如果硬要从 Express 3.0 迁移到这个"Express 4.0"，实际上意味着重写整个应用，因此团队认为更合适的做法是创建一个全新的库。

这个"偏离"在仓库中有持续的佐证：

1. 中间件模型不同：Express 3.x 的回调式 next(err) 被 async/await 语义取代，且 v3 已移除旧签名兼容（见 Readme.md 与 docs/migration-v2-to-v3.md）。
2. 上下文模型不同：Express 中 req/res/next 三参数并行；Koa 则将请求与响应封装进单一对象 ctx，由每个请求独立持有（见下文第五节的 createContext 实现）。
3. API 边界不同：Koa 刻意保持核心极简，把路由、静态文件、会话等全部交给中间件生态，这使从 Express 迁移时需要逐个挑选中间件，而不是得到一个"全家桶"。

仓库内还提供了专门面向 Express 用户的对比文档 docs/koa-vs-express.md，可作为迁移时的延伸阅读。

五、Koa 对象上的自定义属性：两条设计规则与委托机制

这是 FAQ 中最具"规范"性质的一节。原文回答：Koa 使用三个自定义对象——ctx、ctx.request、ctx.response——它们通过便捷方法与 getter/setter 抽象了 Node 的 req 和 res。向这些对象添加属性，必须遵守以下规则：

• 它们必须非常常用，和/或必须能做一些有用的事；
• 如果某属性存在 setter，则它也必然存在 getter，但反之不成立（可以有只读 getter，但不能只有 setter 没有 getter）。

此外，ctx.request 和 ctx.response 的许多属性被**委托（delegated）**到了 ctx 上：如果它是一个 getter/setter 对，那么 getter 和 setter 会严格对应到 ctx.request 或 ctx.response 二者之一。FAQ 最后提醒：在建议新增属性之前，请先思考上述规则。

5.1 委托机制的源码实现

委托的实现位于 lib/context.js，使用 delegates 包对 Context 原型批量生成访问器：

// Response delegation（lib/context.js#L195-L213 节选）
delegate(proto, 'response')
  .method('attachment')
  .method('redirect')
  .method('remove')
  .method('vary')
  .method('has')
  .method('set')
  .method('append')
  .method('flushHeaders')
  .method('back')
  .access('status')      // getter + setter
  .access('message')
  .access('body')
  .access('length')
  .access('type')
  .access('lastModified')
  .access('etag')
  .getter('headerSent')  // 只读 getter
  .getter('writable')

// Request delegation（lib/context.js#L219-L248 节选）
delegate(proto, 'request')
  .method('acceptsLanguages')
  .method('acceptsEncodings')
  .method('acceptsCharsets')
  .method('accepts')
  .method('get')
  .method('is')
  .access('querystring')
  .access('idempotent')
  .access('socket')
  .access('search')
  .access('method')
  .access('query')
  .access('path')
  .access('url')
  .access('accept')
  .getter('origin')
  .getter('href')
  .getter('subdomains')
  .getter('protocol')
  .getter('host')
  .getter('hostname')
  .getter('URL')
  .getter('header')
  .getter('headers')
  .getter('secure')
  .getter('stale')
  .getter('fresh')
  .getter('ips')
  .getter('ip')

从这段源码可以读出三层信息：

1. .access() 生成 getter + setter 对，例如 ctx.status、ctx.body、ctx.type、ctx.path、ctx.method——读写都穿透到 ctx.response 或 ctx.request；
2. .getter() 生成只读属性，例如 ctx.host、ctx.href、ctx.ip、ctx.fresh、ctx.subdomains——它们只有 getter 没有 setter，恰好满足"有 setter 必有 getter，反之不成立"的规则；
3. .method() 委托方法调用，例如 ctx.redirect() 实际调用 ctx.response.redirect()，ctx.accepts() 实际调用 ctx.request.accepts()。

5.2 规则在实现中的验证

"有 setter 必有 getter"这一规则可以在底层对象上逐条核验：

• lib/request.js 中，header/headers（L35-L68）、url（L77-L89）、method（L122-L135）、path（L144-L163）、query（L172-L187）、querystring（L196-L215）、search（L225-L240）、ip 等属性都是成对定义的 getter + setter；而 host（L251）、hostname（L281）、href（L109）等只有 getter。
• lib/response.js 中，status 的 getter/setter 成对出现，且 setter 内做严格校验（status code must be a number、范围 100–999）；message（L102-L115）、body（L124 起）、type、etag、length、lastModified 同样成对定义。

这种成对结构保证了 ctx.status = 204 与 ctx.status 的读取总是读写同一份底层状态（Node 的 res.statusCode），不会出现"可写不可读"的不对称陷阱。

5.3 上下文的创建方式与 app.context 扩展点

理解了"哪些属性被委托"，还需要理解"这些对象是如何按请求创建的"。lib/application.js 的 createContext 展示了完整的装配过程：

createContext (req, res) {
  const context = Object.create(this.context)                    // 原型链挂在 app.context 上
  const request = (context.request = Object.create(this.request))
  const response = (context.response = Object.create(this.response))
  context.app = request.app = response.app = this
  context.req = request.req = response.req = req
  context.res = request.res = response.res = res
  request.ctx = response.ctx = context
  request.response = response
  response.request = request
  context.originalUrl = request.originalUrl = req.url
  context.state = {}
  return context
}

要点：

• 每个请求都会 Object.create 出全新的 context/request/response 实例，共享同一套应用级原型；
• 构造函数中（lib/application.js）this.context = Object.create(context)、this.request = Object.create(request)、this.response = Object.create(response)——这意味着在 app.context 上添加的自定义属性会被所有请求的 ctx 继承。测试 tests/application/context.test.js 验证了两点：app.context.msg = 'hello' 后，中间件中 ctx.msg 可读到 'hello'；且这种扩展不会影响另一个应用实例（原型对象未被污染）；
• context.state = {} 是每请求独立的空对象，docs/api/context.md 将其定义为"在中间件之间和向视图传递信息的推荐命名空间"（如 ctx.state.user = await User.find(id)）。

5.4 为什么强调"添加前先想清楚"

FAQ 末尾的提醒"Please think about these rules before suggesting additional properties"指向的正是源码层面的约束：委托清单（lib/context.js）是显式声明的白名单，新增一个 ctx.xxx 属性需要同时修改底层 request/response 定义与委托声明，并保持 getter/setter 的成对性与读写一致性。这也解释了为什么 Koa 坚持"只整合几乎所有 HTTP 服务器通用的方法"——属性面越小，中间件之间命名冲突与行为歧义的风险越低。

六、FAQ 结论速查表

问题	官方结论	仓库中的源码依据
Koa 取代 Express 吗？	否，更近于 Connect，Express 的便利功能被移到中间件层	lib/context.js#L164-L176（app.keys 应用级签名密钥）
Koa 取代 Connect 吗？	否，是相似功能的另一种实现取向	lib/application.js#L167-L183（compose 式中间件栈）
Koa 内置路由吗？	否，路由由第三方中间件提供	lib/application.js#L152-L157（use 无路由逻辑）
为什么不是 Express 4.0？	设计根本不同，迁移等于重写，故另起新库	Readme.md（v3 移除 v1.x 旧签名）
自定义属性规则	必须常用/有用；有 setter 必有 getter	lib/context.js#L195-L248（delegates 委托清单）

小结

Koa 官方 FAQ 的核心信息可以概括为三句话：Koa 的功能边界刻意收窄到"几乎所有 HTTP 服务器都需要的能力"，路由、静态文件等能力交给中间件生态；Koa 相对 Express/Connect 的差异是设计取向而非能力替代；而 ctx/ctx.request/ctx.response 的属性扩展遵循"常用且有用、setter 必配 getter、委托严格单向"的严格规则。这些决策在 lib/application.js、lib/context.js、lib/request.js 与 lib/response.js 中都有清晰、可核验的对应实现，是理解 Koa 设计哲学的最佳入口。