全书目录

第三十六篇：Koa 完全指南 —— 洋葱关卡巡防宇宙

第七章：路由生态 —— Koa 自己不带路牌，但它的路牌系统很成熟

2 分钟 465 字 第 690 / 962 个阅读单元

这是 Koa 初学者最容易误会的地方之一：

Koa core 不自带路由。

它是一个极薄的 HTTP middleware foundation。
所以到了真实项目里，你通常会自己拼出一套常见组合：

text
Koa Core
├── @koa/router      -> 路由分发
├── @koa/bodyparser  -> JSON / form / text 请求体
├── @koa/cors        -> CORS
├── koa-static       -> 静态资源
└── koa-body         -> multipart / 上传等更重请求体场景

到 2026-03-28，主流路线里最常见的路由器依然是 @koa/router。

先看最小实战形状：

bash
npm i koa @koa/router @koa/bodyparser
js
import Koa from 'koa'
import Router from '@koa/router'
import { bodyParser } from '@koa/bodyparser'

const app = new Koa()
const router = new Router({ prefix: '/api' })

router.get('/patrols/:id', async (ctx) => {
  ctx.body = {
    id: ctx.params.id,
    status: '巡防中',
  }
})

router.post('/alerts', async (ctx) => {
  const payload = ctx.request.body

  ctx.status = 201
  ctx.body = {
    id: 'alert_001',
    received: payload,
  }
})

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

app.listen(3000)

这段代码背后的巡防图是：

text
请求进入 Koa
   │
   ▼
bodyParser 先解析请求体
   │
   ▼
router.routes() 按路径和方法分流
   │
   ▼
具体 handler 执行业务
   │
   ▼
allowedMethods() 处理 OPTIONS / 405 / 501 这类方法语义

这里有几个必须讲透的点：

#1. ctx.params 不是 Koa core 自带的

它通常来自 @koa/router。

#2. router.allowedMethods() 很实用

它能自动处理：

  • OPTIONS
  • 405 Method Not Allowed
  • 501 Not Implemented

这比你自己手写方法判断稳得多。

#3. @koa/bodyparser 不处理 multipart

如果你要文件上传、复杂 multipart 表单，常见路线是 koa-body 或 @koa/multer 这类方案，不是继续指望 @koa/bodyparser。

所以你要建立的认知不是：

text
Koa = 一个完整大框架

而是：

text
Koa = 核心巡防塔
生态模块 = 各种外挂关卡和分流器