API 配置

🌐 API configuration

Page summary:
/config/api 集中管理响应隐私、REST 默认设置（前缀、分页限制、最大请求大小）以及对 REST 内容 API 和文档服务的严格参数验证。

API 调用的一般设置可以在 ./config/api.js（或 ./config/api.ts）文件中设置。rest 和 documents 选项都在这个单一的配置文件中。

🌐 General settings for API calls can be set in the ./config/api.js (or ./config/api.ts) file. Both rest and documents options live in this single config file.

属性	描述	类型	默认
`responses`	全局 API 响应配置	对象	-
`responses.privateAttributes`	一组全局定义的属性，应被视为私有。	字符串数组	`[]`
`rest`	REST API 配置	对象	-
`rest.prefix`	API 前缀	字符串	`/api`
`rest.defaultLimit`	API 调用中使用的默认 `limit` 参数（参见 REST API 文档）。将其设置为 `-1` 可以移除限制（见下方说明）。	整数	`25`
`rest.maxLimit`	可以作为 `limit` 请求的最大允许数量（参见 REST API 文档）。	整数	`100`
`rest.withCount`	列表响应是否默认包含 `meta.pagination` 中条目总数和页数。可以通过 `pagination[withCount]` 参数在每次请求中覆盖。	布尔值	`true`
`rest.strictParams`	当 `true` 时，Content API 路径上只接受允许的查询和主体参数；未知的顶层键将被拒绝。在 `register` 中通过自定义 Content API 参数添加允许的参数。	布尔值	-
`documents`	文档服务配置	对象	-
`documents.strictParams`	当 `true` 时，文档服务方法会拒绝具有未识别根级键的参数（例如，无效的 `status`、`locale`）。当 `false` 或未设置时，未知参数将被忽略。请参阅文档服务 API。	布尔值	-

Note

rest.defaultLimit 和 rest.maxLimit 有两种互动方式：

如果 rest.maxLimit 的值小于 rest.defaultLimit 的值，maxLimit 将是使用的限制。
将 rest.defaultLimit 设置为 -1 会取消对未明确传入 pagination 参数的请求的限制：每个匹配的条目都会在单次响应中返回，并且 rest.maxLimit 不会对其进行限制。这与在请求中显式传入 pagination[limit]=-1 不同，后者仍会受到 rest.maxLimit 的限制（详见 REST API 文档）。

Tip

rest.strictParams 适用于传入的 REST 内容 API 请求（查询和正文）。documents.strictParams 适用于传递给服务器端代码中 strapi.documents() 的参数。你可以在同一个配置文件中启用其中之一或两者。

使用 create-strapi-app 搭建的应用在生成的 config/api.* 文件中，默认情况下 rest.strictParams 和 documents.strictParams 都设置为 true。

🌐 Apps scaffolded with create-strapi-app have both rest.strictParams and documents.strictParams set to true by default in the generated config/api.* file.

示例：

JavaScript
TypeScript

./config/api.js

module.exports = ({ env }) => ({
  responses: {
    privateAttributes: ['_v', 'id', 'created_at'],
  },
  rest: {
    prefix: '/v1',
    defaultLimit: 100,
    maxLimit: 250,
    strictParams: true, // only allow parameters defined on routes or added via contentAPI.addQueryParams/addInputParams
  },
  documents: {
    strictParams: true, // reject unrecognized root-level parameters in strapi.documents() calls
  },
});

./config/api.ts
import type { Core } from '@strapi/strapi';

export default ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Api => ({
  responses: {
    privateAttributes: ['_v', 'id', 'created_at'],
  },
  rest: {
    prefix: '/v1',
    defaultLimit: 100,
    maxLimit: 250,
    strictParams: true, // only allow parameters defined on routes or added via contentAPI.addQueryParams/addInputParams
  },
  documents: {
    strictParams: true, // reject unrecognized root-level parameters in strapi.documents() calls
  },
});