# koa-router

URL: https://caijiao.org/koa/middleware/router
Source: docs/koa/middleware/router.md
Description: 了解如何在 Koa 中使用 'koa-router'，包括路由定义、请求处理、参数解析等基本功能。

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

## 1. 安装 koa-router

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

```bash
npm install koa-router
````

## 2. 基本使用

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

### 示例：基本路由定义

```js
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)`**：处理所有类型的请求

### 示例：不同的请求方法

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

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

## 4. 路由参数

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

### 示例：路由参数

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

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

### 支持多个参数

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

## 5. 查询字符串

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

### 示例：查询字符串

```js
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` 也可以与其他中间件一起使用。你可以将中间件应用到特定的路由、路由组，或者全局处理请求。

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

```js
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` 的路由组功能来为一组路由添加公共的路径前缀。这样可以让你的路由更加结构化。

### 示例：路由组

```js
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 方法。

### 示例：链式路由定义

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

## 9. 其他功能

### 路由重定向

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

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

### 路由的异常处理

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

```js
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` 都是一个非常强大且灵活的工具。