请求和响应

¥Requests and Responses

Strapi 后端服务器基于 相思木。当你通过 REST API 发送请求时，上下文对象 (ctx) 会传递到 Strapi 后端的每个元素（例如 policies、controllers、services）。

¥The Strapi back end server is based on Koa. When you send requests through the REST API, a context object (ctx) is passed to every element of the Strapi back end (e.g., policies, controllers, services).

ctx 包括 3 个主要对象：

¥ctx includes 3 main objects:

• ctx.request 有关客户端发出 API 请求所发送的请求的信息，

  ¥ctx.request for information about the request sent by the client making an API request,

• ctx.state 有关 Strapi 后端内请求状态的信息，

  ¥ctx.state for information about the state of the request within the Strapi back end,

• 和 ctx.response 有关服务器将返回的响应的信息。

  ¥and ctx.response for information about the response that the server will return.

💡 提示

还可以使用 strapi.requestContext function. 代码从代码中的任何位置访问请求的上下文。

¥The request's context can also be accessed from anywhere in the code with the strapi.requestContext function.

👀 信息

除了以下文档中描述的概念和参数之外，你还可以在 Koa 请求文档、Koa 路由文档 和 Koa 响应文档 中找到其他信息。

¥In addition to the concepts and parameters described in the following documentation, you might find additional information in the Koa request documentation, Koa Router documentation and Koa response documentation.

The diagram represents a simplified version of how a request travels through the Strapi back end, with requests and responses highlighted. The backend customization introduction page includes a complete, interactive diagram.

ctx.request

ctx.request 对象包含以下参数：

¥The ctx.request object contains the following parameters:

范围	描述	类型
ctx.request.body	正文的解析版本。	Object
ctx.request.files	随请求发送的文件。	Array
ctx.request.headers	随请求一起发送的标头。	Object
ctx.request.host	URL 的主机部分，包括端口。	String
ctx.request.hostname	URL 的主机部分，不包括端口。	String
ctx.request.href	所请求资源的完整 URL，包括协议、域、端口（如果指定）、路径和查询参数。	String
ctx.request.ip	发送请求者的 IP。	String
ctx.request.ips	当 X-Forwarded-For 存在且 app.proxy 启用时，将返回 IP 数组，按从上游到下游的顺序排列。 例如，如果值为 "客户端、代理 1、代理 2"，你将收到 ["client", "proxy1", "proxy2"] 数组。	Array
ctx.request.method	请求方法（例如，GET、POST）。	String
ctx.request.origin	第一个 / 之前的 URL 部分。	String
ctx.request.params	URL 中发送的参数。 例如，如果内部 URL 是 /restaurants/:id，那么你在实际请求中替换 :id 的任何内容都可以通过 ctx.request.params.id 访问。	Object
ctx.request.path	请求资源的路径，不包括查询参数。	String
ctx.request.protocol	正在使用的协议（例如，https 或 http）。	String
ctx.request.query	表带专用 查询参数。	Object
ctx.request.subdomains	URL 中包含的子域名。 例如域名为 tobi.ferrets.example.com，则值为以下数组：["ferrets", "tobi"]。	Array
ctx.request.url	所请求资源的路径和查询参数，不包括协议、域和端口。	String

Differences between protocol, origin, url, href, path, host, and hostname :

给定发送到 https://example.com:1337/api/restaurants?id=123 URL 的 API 请求，以下是 ctx.request 对象返回的不同参数：

¥Given an API request sent to the https://example.com:1337/api/restaurants?id=123 URL, here is what different parameters of the ctx.request object return:

范围	返回值
ctx.request.href	https://example.com:1337/api/restaurants?id=123
ctx.request.protocol	https
ctx.request.host	localhost:1337
ctx.request.hostname	localhost
ctx.request.origin	https://example.com:1337
ctx.request.url	/api/restaurants?id=123
ctx.request.path	/api/restaurants

ctx.request.query

ctx.request 提供了一个 query 对象，可以访问 Strapi 查询参数。下表列出了可用参数以及简短说明和相关 REST API 文档部分的链接（有关更多信息，请参阅 REST API 参数）：

¥ctx.request provides a query object that gives access to Strapi query parameters. The following table lists available parameters with a short description and a link to the relevant REST API documentation section (see REST API parameters for more information):

范围	描述	类型
ctx.request.query ctx.query	整个查询对象。	Object
ctx.request.query.sort	对响应进行排序 的参数	String 或 Array
ctx.request.query.filters	过滤响应 的参数	Object
ctx.request.query.populate	填充关系、组件或动态区域 的参数	String 或 Object
ctx.request.query.fields	仅选择与响应一起返回的特定字段 的参数	Array
ctx.request.query.pagination	参数 逐页浏览条目	Object
ctx.request.query.publicationState	参数 选择草稿和发布状态	String
ctx.request.query.locale	参数 选择一个或多个区域设置	String 或 Array

ctx.state

ctx.state 对象可以访问 Strapi 后端内的请求状态，包括有关 user、authentication、route 的特定值：

¥The ctx.state object gives access to the state of the request within the Strapi back end, including specific values about the user, authentication, route:

范围	描述	类型
ctx.state.isAuthenticated	返回当前用户是否以任何方式进行身份验证。	Boolean

ctx.state.user

ctx.state.user 对象允许访问有关执行请求的用户的信息，并包含以下参数：

¥The ctx.state.user object gives access to information about the user performing the request and includes the following parameters:

范围	描述	类型
ctx.state.user	用户的信息。仅填充一种关系。	Object
ctx.state.user.role	用户的角色	Object

ctx.state.auth

ctx.state.auth 对象提供对与身份验证相关的信息的访问，并包含以下参数：

¥The ctx.state.auth object gives access to information related to the authentication and includes the following parameters:

范围	描述	类型
ctx.state.auth.strategy	当前使用的认证策略信息（用户和权限插件 或 API 令牌）	Object
ctx.state.auth.strategy.name	当前使用的策略名称	String
ctx.state.auth.credentials	用户的凭据	String

ctx.state.route

ctx.state.route 对象可以访问与当前路由相关的信息，并包含以下参数：

¥The ctx.state.route object gives access to information related to the current route and includes the following parameters:

范围	描述	类型
ctx.state.route.method	用于访问当前路由的方法。	String
ctx.state.route.path	当前路由的路径。	String
ctx.state.route.config	当前路由的配置信息。	Object
ctx.state.route.handler	当前路由的处理程序（控制器）。	Object
ctx.state.route.info	有关当前路由的其他信息，例如 apiName 和 API 请求类型。	Object
ctx.state.route.info.apiName	使用的 API 的名称。	String
ctx.state.route.info.type	使用的 API 的类型。	String

ctx.response

ctx.response 对象允许访问与服务器将返回的响应相关的信息，并包含以下参数：

¥The ctx.response object gives access to information related to the response that the server will return and includes the following parameters:

范围	描述	类型
ctx.response.body	响应正文。	Any
ctx.response.status	响应的状态代码。	Integer
ctx.response.message	响应的状态消息。 默认情况下，response.message 与 response.status 关联。	String
ctx.response.header ctx.response.headers	随响应一起发送的标头。	Object
ctx.response.length	Content-Length 标头值在存在时作为数字，或者在可能的情况下从 ctx.body 推导出来；否则，返回 undefined。	Integer
ctx.response.redirect ctx.response.redirect(url, [alt])	对 URL 执行 302 重定向。字符串 "back" 是特殊大小写的，以提供 Referrer 支持；当 Referrer 不存在时，使用 alt 或 "/"。 示例：ctx.response.redirect('back', '/index.html');	Function
ctx.response.attachment ctx.response.attachment([filename], [options])	将 Content-Disposition 标头设置为 "attachment" 以指示客户端提示下载。可以选择指定下载的文件名和一些 options。	Function
ctx.response.type	Content-Type 标头，不含 "charset" 等参数。	String
ctx.response.lastModified	Last-Modified 标头作为日期（如果存在）。	DateTime
ctx.response.etag	设置包含封装的“s”的响应的 ETag。 没有相应的 response.etag getter。	String

在任何地方访问请求上下文

¥Accessing the request context anywhere

✨ v4.3.9 中的新功能

strapi.requestContext 可与 Strapi v4.3.9+ 配合使用。

¥The strapi.requestContext works with Strapi v4.3.9+.

Strapi 公开了一种从代码中的任何位置访问当前请求上下文的方法（例如生命周期函数）。

¥Strapi exposes a way to access the current request context from anywhere in the code (e.g. lifecycle functions).

你可以按如下方式访问该请求：

¥You can access the request as follows:

const ctx = strapi.requestContext.get();

你应该只在 HTTP 请求上下文中调用的函数内部使用它。

¥You should only use this inside of functions that will be called in the context of an HTTP request.

// correct



const service = {


  myFunction() {
    const ctx = strapi.requestContext.get();
    console.log(ctx.state.user);
  },
};

// incorrect


const ctx = strapi.requestContext.get();





const service = {


  myFunction() {
    console.log(ctx.state.user);
  },
};

示例：

¥Example:

./api/test/content-types/article/lifecycles.js

module.exports = {
  beforeUpdate() {
    const ctx = strapi.requestContext.get();

    console.log('User info in service: ', ctx.state.user);
  },
};

✏️ 注意

Strapi 使用名为 异步本地存储 的 Node.js 功能来使上下文在任何地方可用。

¥Strapi uses a Node.js feature called AsyncLocalStorage to make the context available anywhere.