koa-router

在 Koa 中，koa-router 是一个轻量级的路由中间件，它可以帮助你定义路由、处理 HTTP 请求并解析请求参数。通过使用 koa-router，你可以创建一个灵活的路由系统，轻松地组织和管理 Koa 应用的各个部分。

1. 安装 koa-router

首先，你需要安装 koa-router：

npm install koa-router

2. 基本使用

koa-router 提供了一个简单的 API 来定义路由和请求处理。

示例：基本路由定义

const Koa = require('koa');
const Router = require('koa-router');

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

// 定义一个 GET 路由
router.get('/', (ctx) => {
  ctx.body = 'Hello, Koa Router!';
});

// 使用路由
app.use(router.routes()).use(router.allowedMethods());

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

在这个示例中，我们通过 router.get() 定义了一个简单的 GET 路由，处理根路径（/）的请求。当请求根路径时，服务器返回 Hello, Koa Router!。

3. 路由方法

koa-router 提供了多种 HTTP 请求方法，用于定义不同类型的路由。

常用的路由方法：

• router.get(path, callback)：处理 GET 请求
• router.post(path, callback)：处理 POST 请求
• router.put(path, callback)：处理 PUT 请求
• router.delete(path, callback)：处理 DELETE 请求
• router.patch(path, callback)：处理 PATCH 请求
• router.head(path, callback)：处理 HEAD 请求
• router.all(path, callback)：处理所有类型的请求

示例：不同的请求方法

router.get('/get', (ctx) => {
  ctx.body = 'GET request received';
});

router.post('/post', (ctx) => {
  ctx.body = 'POST request received';
});

4. 路由参数

koa-router 支持路由参数，允许你从请求的 URL 中提取动态参数。你可以通过在路由路径中使用 : 来定义参数。

示例：路由参数

router.get('/user/:id', (ctx) => {
  const userId = ctx.params.id; // 获取路由参数 id
  ctx.body = `User ID: ${userId}`;
});

在这个示例中，路由 /user/:id 会匹配类似 /user/123 的请求，并且将 123 提取为参数 id。

支持多个参数

router.get('/user/:id/:name', (ctx) => {
  const { id, name } = ctx.params;
  ctx.body = `User ID: ${id}, Name: ${name}`;
});

5. 查询字符串

koa-router 支持从请求的查询字符串中提取参数。这些参数可以通过 ctx.request.query 访问。

示例：查询字符串

router.get('/search', (ctx) => {
  const { query, page } = ctx.request.query;
  ctx.body = `Search query: ${query}, Page: ${page}`;
});

访问 /search?query=koa&page=1 将返回 Search query: koa, Page: 1。

6. 中间件与路由

在 Koa 中，中间件用于处理请求和响应。koa-router 也可以与其他中间件一起使用。你可以将中间件应用到特定的路由、路由组，或者全局处理请求。

示例：为特定路由添加中间件

router.get('/admin', (ctx, next) => {
  if (!ctx.state.user) {
    ctx.status = 401;
    ctx.body = 'Unauthorized';
  } else {
    return next(); // 继续执行后续中间件
  }
}, (ctx) => {
  ctx.body = 'Welcome to Admin!';
});

在这个示例中，我们为 /admin 路由添加了一个中间件来检查用户是否已认证。如果未认证，则返回 401 Unauthorized，否则继续执行后续的中间件。

7. 路由组（Router Prefix）

你可以使用 koa-router 的路由组功能来为一组路由添加公共的路径前缀。这样可以让你的路由更加结构化。

示例：路由组

const apiRouter = new Router({
  prefix: '/api'
});

apiRouter.get('/users', (ctx) => {
  ctx.body = 'Get Users';
});

apiRouter.get('/posts', (ctx) => {
  ctx.body = 'Get Posts';
});

app.use(apiRouter.routes());

在这个示例中，所有的路由都自动带上了 /api 前缀。访问 /api/users 和 /api/posts 会分别返回 Get Users 和 Get Posts。

8. 路由方法的使用限制

koa-router 支持链式调用，你可以在同一路由上同时使用多个 HTTP 方法。

示例：链式路由定义

router
  .get('/test', (ctx) => {
    ctx.body = 'GET request';
  })
  .post('/test', (ctx) => {
    ctx.body = 'POST request';
  });

9. 其他功能

路由重定向

koa-router 提供了 redirect 方法来实现 URL 重定向。

router.get('/redirect', (ctx) => {
  ctx.redirect('/new-url');
});

路由的异常处理

你可以在 Koa 路由中使用 try...catch 来捕获并处理异常。

router.get('/error', async (ctx) => {
  try {
    // 模拟错误
    throw new Error('Something went wrong!');
  } catch (err) {
    ctx.status = 500;
    ctx.body = 'Internal Server Error';
  }
});

10. 总结

koa-router 是 Koa 中非常重要的一个工具，它使得路由定义和请求处理变得非常简单和高效。通过使用 koa-router，你可以轻松地创建和管理路由，处理动态路由参数、查询字符串、以及请求方法等。此外，它还支持中间件功能、路由组等扩展，帮助你更好地组织和管理 Koa 应用。

无论是创建简单的 API 还是复杂的 Web 应用，koa-router 都是一个非常强大且灵活的工具。