v4 代码迁移：更新控制器

¥v4 code migration: Updating controllers

本指南是 v4 代码迁移指南 的一部分，旨在帮助你将 Strapi 应用的代码从 v3.6.x 迁移到 v4.0.x

¥This guide is part of the v4 code migration guide designed to help you migrate the code of a Strapi application from v3.6.x to v4.0.x

🤓 v3/v4 比较

在 Strapi v3 和 v4 中，创建内容类型会自动生成核心 API 控制器。控制器是包含一系列方法（称为操作）的 JavaScript 文件。

¥In both Strapi v3 and v4, creating content-types automatically generates core API controllers. Controllers are JavaScript files that contain a list of methods, called actions.

在 Strapi v3 中，控制器导出一个包含操作的对象，这些操作与核心 API 控制器的现有操作合并，从而允许自定义。

¥In Strapi v3, controllers export an object containing actions that are merged with the existing actions of core API controllers, allowing customization.

在 Strapi v4 中，控制器将调用结果导出到 createCoreController 工厂功能，无论是否进一步定制。

¥In Strapi v4, controllers export the result of a call to the createCoreController factory function, with or without further customization.

将 controllers 迁移到 Strapi v4 包括确保每个控制器位于正确的文件夹中并使用 v4 中引入的 createCoreController 工厂功能。

¥Migrating controllers to Strapi v4 consists in making sure that each controller is located in the proper folder and uses the createCoreController factory function introduced in v4.

由于 Strapi v3 和 v4 中控制器实现之间的差异，建议创建一个新的控制器文件，然后选择将现有的 v3 自定义项引入新文件并在必要时进行调整。

¥Due to the differences between controllers implementation in Strapi v3 and v4, it's recommended to create a new controller file, then optionally bring existing v3 customizations into the new file and adapt them when necessary.

✏️ 注意

控制器文件可以使用 交互式 CLI 命令 strapi generate.txt 自动创建。

¥The controller file can be created automatically with the interactive CLI command strapi generate.

创建 v4 控制器：

¥To create a v4 controller:

1. 在 ./src 文件夹内创建 api/<api-name>/controllers/<controller-name>.js 文件（请参阅 项目结构）。

   ¥Create a api/<api-name>/controllers/<controller-name>.js file inside the ./src folder (see project structure).

2. 将以下代码复制并粘贴到 ./src/api/<api-name>/controllers/<controller-name>.js 文件的顶部。该代码从 Strapi 核心包含的工厂导入 createCoreController 工厂函数：

   ¥Copy and paste the following code at the top of the ./src/api/<api-name>/controllers/<controller-name>.js file. The code imports the createCoreController factory function from the factories included with the core of Strapi:

   const { createCoreController } = require('@strapi/strapi').factories;

3. 复制并粘贴以下代码，将 api-name 和 content-type-name 替换为适当的名称。该代码导出对 createCoreController 工厂函数的调用结果，并将内容类型的唯一标识符（例如 api::api-name.content-type-name）作为参数传递：

   ¥Copy and paste the following code, replacing api-name and content-type-name with appropriate names. The code exports the result of a call to the createCoreController factory function, passing the unique identifier of the content-type (e.g. api::api-name.content-type-name) as an argument:

   module.exports = createCoreController('api::api-name.content-type-name')

4. （可选）要自定义控制器操作，请将第二个参数传递给 createCoreController 工厂函数。该参数可以是一个对象，也可以是一个返回对象的函数。该对象包含方法，这些方法可以是全新的操作，也可以替换或扩展核心 API 控制器的现有操作（参见 控制器实现文档）。

   ¥(optional) To customize controller actions, pass a second argument to the createCoreController factory function. This argument can be either an object or a function returning an object. The object contains methods, which can either be entirely new actions or replace or extend existing actions of core API controllers (see controllers implementation documentation).

Example of a v4 controller without customization:

./src/api/<content-type-name>/controllers/<controller-name>.js

const { createCoreController } = require('@strapi/strapi').factories;

module.exports = createCoreController('api::api-name.content-type-name');

Example of a v4 controller with customization:

./src/api/<content-type-name>/controllers/<controller-name>.js

const { createCoreController } = require('@strapi/strapi').factories;

module.exports = createCoreController('api::api-name.content-type-name', ({ strapi }) => ({
  // wrap a core action, leaving core logic in place
  async find(ctx) {
    // some custom logic here
    ctx.query = { ...ctx.query, local: 'en' }

    // calling the default core action with super
    const { data, meta } = await super.find(ctx);

    // some more custom logic
    meta.date = Date.now()

    return { data, meta };
  },
}));

💡 定制技巧

• 可以使用 super（例如 super.find()）调用原始控制器的 CRUD 操作。

  ¥The original controller’s CRUD actions can be called using super (e.g. super.find()).

• sanitizeInput 和 sanitizeOutput 实用程序可在 Strapi v4 中使用，并替换 v3 中的 sanitizeEntity 实用程序。

  ¥The sanitizeInput and sanitizeOutput utilities can be used in Strapi v4 and replace the sanitizeEntity utility from v3.

更多示例可以在 控制器实现文档 中找到。

¥More examples can be found in the controllers implementation documentation.

🤓 下一步

Strapi 的 迁移后端代码 到 v4 还需要至少迁移 Strapi 服务器的核心功能，例如 configuration、dependencies、routes、services 和 内容类型模式。

¥Migrating the backend code of Strapi to v4 also requires to at least migrate the core features of the Strapi server, such as the configuration, dependencies, routes, services, and content-type schemas.