# 请求体解析

URL: https://caijiao.org/koa/middleware/body
Source: docs/koa/middleware/body.md
Description: 了解如何在 Koa 中解析请求体，包括解析 JSON、表单数据、文件上传等不同类型的请求体。

在 Koa 中，处理请求体是一个常见的任务，尤其是在处理 POST 或 PUT 请求时。[Koa](/koa/) 没有内建的请求体解析功能，但可以通过中间件来实现。常用的解析请求体的中间件有 `koa-bodyparser` 和 `koa-multer`。

## 1. 安装请求体解析中间件

首先，你需要安装合适的请求体解析中间件。这里我们使用 `koa-bodyparser` 来解析 JSON 和表单数据。

```bash
npm install koa-bodyparser
````

### 示例：安装并使用 `koa-bodyparser`

```js
const Koa = require('koa');
const bodyParser = require('koa-bodyparser');
const app = new Koa();

// 使用 koa-bodyparser 中间件来解析请求体
app.use(bodyParser());

app.use((ctx) => {
  // 访问解析后的请求体
  ctx.body = ctx.request.body;
});

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

在这个示例中，`koa-bodyparser` 中间件会自动解析请求中的 JSON 和表单数据，并将其放入 `ctx.request.body` 中。

## 2. JSON 请求体解析

`koa-bodyparser` 默认支持解析 JSON 格式的请求体。当收到 `Content-Type` 为 `application/json` 的请求时，Koa 会将请求体中的 JSON 数据自动解析为 JavaScript 对象。

### 示例：解析 JSON 请求体

```js
app.use((ctx) => {
  const { name, age } = ctx.request.body; // 获取 JSON 请求体中的字段
  ctx.body = `Hello ${name}, you are ${age} years old!`;
});
```

发送以下 JSON 请求体：

```json
{
  "name": "John",
  "age": 30
}
```

返回的响应将是：

```text
Hello John, you are 30 years old!
```

## 3. 表单数据解析

`koa-bodyparser` 也支持解析 `application/x-www-form-urlencoded` 类型的表单数据。当请求的 `Content-Type` 是表单格式时，它会将数据解析为 [JavaScript](/javascript/) 对象。

### 示例：解析表单数据

```js
app.use((ctx) => {
  const { username, password } = ctx.request.body; // 获取表单数据中的字段
  ctx.body = `Username: ${username}, Password: ${password}`;
});
```

通过发送以下表单请求：

```
username=admin&password=1234
```

返回的响应将是：

```text
Username: admin, Password: 1234
```

## 4. 文件上传解析

如果你需要处理文件上传，可以使用 `koa-multer` 中间件。`koa-multer` 可以处理 `multipart/form-data` 格式的请求体，这是文件上传请求的标准格式。

首先安装 `koa-multer`：

```bash
npm install koa-multer
```

### 示例：处理文件上传

```js
const multer = require('koa-multer');

const upload = multer({ dest: 'uploads/' });

app.use(upload.single('file')); // 处理单个文件上传，字段名为 'file'

app.use((ctx) => {
  const file = ctx.file; // 获取上传的文件
  ctx.body = `File uploaded: ${file.originalname}`;
});
```

在这个示例中，我们使用 `koa-multer` 处理上传的文件，文件将存储在 `uploads/` 目录下。

## 5. 请求体解析的配置

`koa-bodyparser` 提供了多种配置选项来控制请求体解析的行为：

* **`jsonLimit`**：设置 JSON 请求体的大小限制。
* **`formLimit`**：设置表单请求体的大小限制。
* **`textLimit`**：设置文本请求体的大小限制。
* **`enableTypes`**：指定要解析的请求体类型（如：`json`、`form`、`text`）。

### 示例：配置请求体解析器

```js
app.use(bodyParser({
  jsonLimit: '1mb',  // 限制 JSON 请求体大小为 1MB
  formLimit: '56kb',  // 限制表单请求体大小为 56KB
  enableTypes: ['json', 'form'],  // 只启用 JSON 和表单数据解析
}));
```

## 6. 错误处理

如果请求体格式不正确，`koa-bodyparser` 会抛出错误。你可以通过 Koa 的错误处理机制来捕获并处理这些错误。

### 示例：请求体解析错误处理

```js
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    if (err.status === 400) {
      ctx.status = 400;
      ctx.body = 'Invalid request body';
    } else {
      throw err;
    }
  }
});
```

在这个示例中，我们捕获了 400 错误并返回了自定义的错误消息。

## 7. 总结

请求体解析是 Koa 中非常重要的功能，尤其在处理 API 请求时。通过使用中间件如 `koa-bodyparser` 和 `koa-multer`，你可以轻松地解析 JSON、表单数据、文件上传等不同类型的请求体。合理配置和处理请求体大小限制和错误，有助于提高应用的稳定性和安全性。

在 Koa 中，使用这些中间件不仅简化了请求体处理过程，还能让你专注于业务逻辑的实现。