Body parser 中间件

请求数据是使用注册在 start/kernel.ts 文件中的 BodyParser 中间件来解析的。

中间件的配置存放在 config/bodyparser.ts 文件中。在该文件中，你可以为解析 JSON 负载、包含文件上传的 multipart 表单 以及 URL 编码的表单 配置解析器。

import { defineConfig } from '@adonisjs/core/bodyparser'

export const defineConfig({
  allowedMethods: ['POST', 'PUT', 'PATCH', 'DELETE'],

  form: {
    // 解析 HTML 表单的设置
  },

  json: {
    // 解析 JSON 体的设置
  },

  multipart: {
    // multipart 解析器的设置
  },

  raw: {
    // 原始文本解析器的设置
  },
})

允许的方法

你可以定义一个 allowedMethods 数组，指定 bodyparser 中间件应该尝试解析请求体的 HTTP 方法。默认情况下，配置了以下方法。不过，欢迎你移除或添加新方法。

{
  allowedMethods: ['POST', 'PUT', 'PATCH', 'DELETE']
}

将空字符串转换为 null

当输入字段没有值时，HTML 表单会在请求体中发送一个空字符串。HTML 表单的这种行为使得在数据库层进行数据规范化变得更加困难。

例如，如果你有一个设置为可空的数据库列 country，你希望在用户没有选择国家时，在该列中存储 null 值。

然而，使用 HTML 表单时，后端会收到一个空字符串，你可能会将一个空字符串插入数据库，而不是让该列保持为 null。

BodyParser 中间件可以处理这种不一致：当配置中启用了 convertEmptyStringsToNull 标志时，它会将所有空字符串值转换为 null。

{
  form: {
    // ... 配置其余部分
    convertEmptyStringsToNull: true
  },

  json: {
    // ... 配置其余部分
    convertEmptyStringsToNull: true
  },

  multipart: {
    // ... 配置其余部分
    convertEmptyStringsToNull: true
  }
}

JSON 解析器

JSON 解析器用于解析定义为 JSON 编码字符串、且 Content-type 头匹配预定义 types 值之一的请求体。

json: {
  encoding: 'utf-8',
  limit: '1mb',
  strict: true,
  types: [
    'application/json',
    'application/json-patch+json',
    'application/vnd.api+json',
    'application/csp-report',
  ],
  convertEmptyStringsToNull: true,
}

encoding: 将请求体 Buffer 转换为字符串时使用的编码。很可能你会想要使用 utf-8。不过，你可以使用 iconv-lite 包支持的任何编码。
limit: 解析器允许的请求体数据最大限制。如果请求体超过了配置的限制，将返回一个 413 错误。
strict: 严格解析只允许在 JSON 编码字符串的顶层出现 objects（对象）和 arrays（数组）。
types: 一个 Content-type 头的值数组，这些值应该使用 JSON 解析器来解析。

URL 编码表单解析器

form 解析器用于解析 Content-type 头设置为 application/x-www-form-urlencoded 的 URL 编码字符串。换句话说，HTML 表单数据是使用 form 解析器来解析的。

form: {
  encoding: 'utf-8',
  limit: '1mb',
  queryString: {},
  types: ['application/x-www-form-urlencoded'],
  convertEmptyStringsToNull: true,
}

encoding

将请求体 Buffer 转换为字符串时使用的编码。很可能你会想要使用 utf-8。不过，你可以使用 iconv-lite 包支持的任何编码。

limit

解析器允许的请求体数据最大限制。如果请求体超过了配置的限制，将返回一个 413 错误。

queryString

URL 编码的请求体使用 qs 包进行解析。你可以使用 queryString 属性为该包定义选项。

  form: {
    queryString: {
      allowDots: true,
      allowSparse: true,
    },
  }

Multipart 解析器

multipart 解析器用于解析带有文件上传的 HTML 表单请求。

另请参阅：文件上传

multipart: {
  autoProcess: true,
  processManually: [],
  encoding: 'utf-8',
  fieldsLimit: '2mb',
  limit: '20mb',
  types: ['multipart/form-data'],
  convertEmptyStringsToNull: true,
}

autoProcess

启用 autoProcess 会将所有用户上传的文件移动到你的操作系统的 tmp 目录。

之后，在控制器中，你可以校验这些文件，并将它们移动到持久化位置或某个云服务。

如果你禁用了 autoProcess 标志，则必须手动处理流，并从请求体中读取文件/字段。另请参阅：自行处理 multipart 流。

你可以定义一个要自动处理文件的路由数组。这些值必须是路由模式，而不是 URL。

{
  autoProcess: [
    '/uploads',
    '/post/:id'
  ]
}

processManually

processManually 数组允许你为选定的路由关闭文件的自动处理。这些值必须是路由模式，而不是 URL。

multipart: {
  autoProcess: true,
  processManually: [
    '/file_manager',
    '/projects/:id/assets'
  ],
}

encoding

将请求体 Buffer 转换为字符串时使用的编码。很可能你会想要使用 utf-8。不过，你可以使用 iconv-lite 包支持的任何编码。

limit

处理所有文件时允许的字节最大限制。你可以使用 request.file 方法定义单个文件的大小限制。

fieldsLimit

处理 multipart 请求时，允许的非文件字段的字节最大限制。如果字段大小超过了配置的限制，将返回一个 413 错误。

基础

中间件

基础

请求