Koa Router教程

在Node.js生态的轻量级Web框架选型中，Koa凭借洋葱模型的中间件机制、极简的核心设计与对异步语法的原生支持，成为很多开发者构建高性能接口服务、小型Web应用与BFF中间层服务的首选框架，但Koa核心库只封装了基础的请求响应处理逻辑，并未内置路由分发功能，因此专门承接URL路径匹配与请求方法分发的koa-router模块，就成了Koa生态中使用频率最高的核心扩展插件之一。

要使用koa-router，首先需要在项目中安装依赖，对于基于npm包管理的项目，可以通过`npm install koa-router`命令完成安装，使用yarn或pnpm的项目则可以对应替换为`yarn add koa-router`或`pnpm add koa-router`。安装完成后，就可以在Koa应用中引入并实例化路由对象，最基础的使用示例只需要几步：首先引入Koa和koa-router构造函数，分别实例化app和router对象，接着通过router.get()、router.post()等方法注册对应请求方法和路径的处理函数，最后调用app.use(router.routes())将路由中间件挂载到Koa应用上，同时别忘记挂载router.allowedMethods()中间件——这一步很多新手开发者容易忽略，它的作用是处理那些路径匹配但请求方法不匹配的请求，自动返回405 Method Not Allowed状态码，对于服务器不支持的请求方法则返回501 Not Implemented，能很大程度上补全路由的标准HTTP响应逻辑。

koa-router支持所有标准的HTTP请求方法，包括get、post、put、delete、patch、head、options等，还提供了all方法用于匹配某个路径下的所有请求方法。除了最简单的静态路径匹配，koa-router还支持动态路径参数，比如我们可以定义`router.get('/user/:id', async (ctx) => { ctx.body = { userId: ctx.params.id } })`这样的路由，当用户访问/user/123时，路径中的123会被解析为id参数，挂载到ctx.params对象上，开发者可以直接获取使用。对于URL中的查询参数，比如/user?page=1&size=10，koa本身已经将其解析到ctx.query对象中，不需要额外的路由配置就能直接读取。如果是post、put等请求携带的请求体参数，则需要配合koa-bodyparser这类请求体解析中间件使用，解析后的数据会挂载到ctx.request.body上，这也是新手常踩的坑之一——直接在ctx.body上找请求参数，实际上ctx.body是用来设置响应体的属性。

基于Koa的洋葱模型，koa-router天然支持路由级别的中间件，我们可以为单个路由绑定多个处理函数，按顺序执行，非常适合做权限校验、参数校验这类前置逻辑。比如给管理员接口加权限校验，就可以写成`router.get('/admin/user/list', checkAuth, checkAdmin, async (ctx) => { // 业务逻辑 })`，其中checkAuth和checkAdmin都是独立的中间件函数，分别负责验证用户登录状态和管理员权限，只要任意一个中间件调用了ctx.throw抛出错误，后续的中间件就不会执行，完全符合Koa的中间件执行规则。除了单个路由的中间件，我们还可以通过router.use()为某一类前缀的路由批量挂载中间件，比如`router.use('/admin', checkAdmin)`就能让所有以/admin开头的路由都经过管理员权限校验，不需要每个路由单独添加。说到前缀，koa-router还支持在实例化时直接传入prefix参数，比如`const userRouter = new Router({ prefix: '/api/user' })`，这样后续在userRouter上注册的所有路由都会自动加上/api/user前缀，这一特性在模块化拆分路由时格外实用。

当项目规模逐渐变大，把所有路由都写在入口文件里显然不利于维护，这时我们可以按业务模块拆分路由文件，结合嵌套路由实现清晰的层级管理。比如我们可以在项目中新建routes目录，分别创建user.js、post.js、index.js三个文件，user.js中定义用户相关的登录、注册、信息查询等路由，post.js中定义文章的增删改查路由，每个文件都导出自己的router实例，最后在index.js中引入这些子路由，通过`apiRouter.use('/user', userRouter.routes(), userRouter.allowedMethods())`和`apiRouter.use('/post', postRouter.routes(), postRouter.allowedMethods())`将子路由挂载到父级的apiRouter上，最后在应用入口文件中只需要引入apiRouter并挂载即可，这样的结构不仅逻辑清晰，后续维护某一模块的路由时也不需要改动其他模块的代码。除了模块化拆分，koa-router还提供了很多实用的进阶功能，比如路由重定向，可以通过`router.redirect('/old-path', '/new-path', 301)`快速实现旧路径到新路径的301重定向，也可以在路由处理函数中通过ctx.redirect()方法实现动态重定向；还有路由命名功能，可以给路由设置别名，通过`router.url('路由名', 参数对象)`动态生成对应的URL路径，避免硬编码路径带来的维护问题；对于有严格参数格式要求的路由，还可以用正则表达式限制动态参数的格式，比如`router.get('/user/:id(\\d+)', handler)`就只会匹配id为数字的路径，大大提升了路由匹配的精准度，也减少了后续参数校验的工作量。

在使用koa-router的过程中，还有几个常见的坑需要注意。首先是路由的匹配顺序，koa-router会按照路由注册的顺序依次匹配，只要找到第一个匹配的路由就会执行对应的处理函数，因此如果同时存在静态路径和动态路径的路由，比如`/user/info`和`/user/:id`，一定要把静态路径的路由写在动态路径的前面，否则静态路径会被动态路径拦截，导致逻辑出错。其次是allowedMethods中间件的挂载顺序，必须要在router.routes()之后挂载，否则无法正常工作，因为它需要依赖routes()中间件匹配到的路由信息来判断请求方法是否支持。在使用嵌套路由时，子路由的prefix会和父路由的prefix自动拼接，比如父路由前缀是/api，子路由前缀是/user，那么最终的路径就是/api/user，不需要重复编写前缀。

整体来看，koa-router虽然代码量不大，却提供了足够灵活且全面的路由能力，既可以满足小型项目快速搭建接口的需求，也能通过模块化拆分、嵌套路由等特性支撑中大型项目的路由管理。作为Koa生态中最核心的扩展插件之一，掌握koa-router的核心用法、进阶特性与最佳实践，不仅能提升Koa应用的开发效率，也能让项目的路由结构更加清晰易维护，为后续的功能迭代打下良好的基础。