v4 插件迁移：迁移后端

¥v4 plugin migration: Migrating the back end

本指南是 v4 插件迁移指南 的一部分，旨在帮助你将插件从 Strapi v3.6.x 迁移到 v4.0.x。

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

将插件后端迁移到 Strapi v4 需要：

¥Migrating the back end of a plugin to Strapi v4 requires:

• 更新 绑带包

  ¥updating Strapi packages

• 更新内容类型 getters 和可选的 relations

  ¥updating content-types getters and, optionally, relations

• 更新 插件配置

  ¥updating the plugin configuration

根据这些步骤，某些操作只能手动完成，而其他操作则可以通过修改代码的脚本（称为 codemod）自动执行。下表列出了迁移每个步骤的可用选项：

¥Depending on these steps, some actions can only be done manually while others can be performed automatically by scripts that modify the code, which are called codemods. The following table lists available options for each step of the migration:

行动	迁移类型
更新 Strapi 包	Automatic 或 manual
更新内容类型 getter	Automatic 或 manual
更新内容类型关系	手动的
更新配置	手动的

更新 Strapi 软件包

¥Updating Strapi packages

🤓 v3/v4 比较

Strapi v3 中的软件包名称以 strapi- 为前缀。

¥Package names in Strapi v3 are prefixed by strapi-.

Strapi v4 使用范围包。

¥Strapi v4 uses scoped packages.

要迁移到 Strapi v4，请将所有 Strapi 软件包从 strapi-package-name 重命名为 @strapi/package-name。这需要在 package.json 依赖以及导入包的任何地方完成。

¥To migrate to Strapi v4, rename all Strapi packages from strapi-package-name to @strapi/package-name. This needs to be done in the package.json dependencies and anywhere the package is imported.

Strapi 范围包可以更新 automatically 或 manually。

¥Strapi scoped packages can be updated automatically or manually.

自动 Strapi 套件更新

¥Automatic Strapi packages update

✋ 提醒

Codemods 修改插件源代码。在运行命令之前，请确保你已初始化 git 存储库、工作树是干净的、你已推送 v3 插件并且位于新分支上。

¥Codemods modify the plugin source code. Before running a command, make sure you have initialized a git repo, the working tree is clean, you've pushed your v3 plugin, and you are on a new branch.

要自动更新 Strapi 范围内的包：

¥To update Strapi scoped packages automatically:

1. 通过运行以下命令来使用 update-package-dependencies 代码模式：

   ¥Use the update-package-dependencies codemod by running the following command:

   npx @strapi/codemods migrate:dependencies [path-to-strapi-plugin]

2. 通过运行以下命令来使用 update-strapi-scoped-imports 代码模式：

   ¥Use the update-strapi-scoped-imports codemod by running the following command:

   npx @strapi/codemods transform update-strapi-scoped-imports [path-to-file | folder]

手动 Strapi 套件更新

¥Manual Strapi packages update

要手动更新 Strapi 范围内的包：

¥To update Strapi scoped packages manually:

1. 将 package.json 中的所有 Strapi 包（例如 strapi-package-name）重命名为 @strapi/package-name

   ¥Rename all Strapi packages (e.g. strapi-package-name) in package.json to @strapi/package-name

2. 对导入包的所有实例重复此操作。

   ¥Repeat for all instances where the package is imported.

更新内容类型 getter

¥Updating content-types getters

🤓 v3/v4 比较

Strapi v3 型号在 Strapi v4 中已重命名为 content-types。

¥Strapi v3 models have been renamed to content-types in Strapi v4.

如果插件声明模型，请更新从 strapi.models 到 strapi.contentTypes 的所有 getter 的语法。语法可以更新 automatically 或 manually。

¥If the plugin declares models, update the syntax for all getters from strapi.models to strapi.contentTypes. The syntax can be updated automatically or manually.

自动内容类型 getter 更新

¥Automatic content-types getters update

✋ 提醒

Codemods 修改插件源代码。在运行命令之前，请确保你已初始化 git 存储库、工作树是干净的、你已推送 v3 插件并且位于新分支上。

¥Codemods modify the plugin source code. Before running a command, make sure you have initialized a git repo, the working tree is clean, you've pushed your v3 plugin, and you are on a new branch.

要自动更新内容类型 getter 的语法，请使用 change-model-getters-to-content-types 代码模式。codemod 将指定文件或文件夹中的所有 strapi.models 实例替换为 strapi.contentTypes。

¥To update the syntax for content-types getters automatically, use the change-model-getters-to-content-types codemod. The codemod replaces all instances of strapi.models with strapi.contentTypes in the indicated file or folder.

要使用 codemod，请在终端中运行以下命令：

¥To use the codemod, run the following command in a terminal:

npx @strapi/codemods transform change-model-getters-to-content-types [path-to-file | folder]

手动内容类型 getter 更新

¥Manual content-types getters update

要手动更新内容类型 getter 的语法，请将 strapi.models 的任何实例替换为 strapi.contentTypes。

¥To update the syntax for content-types getters manually, replace any instance of strapi.models with strapi.contentTypes.

💡 提示

Strapi v4 引入了新的 getter，可用于进一步重构插件代码（请参阅 服务器 API 使用文档）。

¥Strapi v4 introduced new getters that can be used to refactor the plugin code further (see Server API usage documentation).

更新内容类型关系

¥Updating content-types relations

☑️ Prerequisites

将内容类型关系更新到 Strapi v4 需要将 v3 模型转换为 Strapi v4 内容类型（请参阅 将模型转换为内容类型文档）。

¥Updating content-types relations to Strapi v4 requires that the v3 models have been converted to Strapi v4 content-types (see converting models to content-types documentation).

🤓 v3/v4 比较

Strapi v3 使用模型设置中的 via、model 和 collection 属性定义内容类型之间的关系。

¥Strapi v3 defines relations between content-types with the via, model and collection properties in the model settings.

在 Strapi v4 中，关系应在内容类型的 schema.json 文件中明确描述（参见 关系文档）。

¥In Strapi v4, relations should be explicitly described in the schema.json file of the content-types (see relations documentation).

如果插件声明内容类型及其之间的关系，则应在内容类型的 schema 中手动将关系迁移到 Strapi v4。

¥If the plugin declares content-types with relations between them, migrating relations to Strapi v4 should be done manually in the schema of the content-types.

要更新内容类型关系，请使用以下过程更新每个内容类型的 server/content-types/<content-type-name>/schema.json 文件：

¥To update content-type relations, update the server/content-types/<content-type-name>/schema.json file for each content-type with the following procedure:

1. 通过将 type 属性值设置为 "relation" 来显式声明关系。

   ¥Declare the relation explicitly by setting the type attribute value to "relation".

2. 使用 relation 属性定义关系类型。
   该值应该是以下可能选项中的字符串："oneToOne"、"oneToMany"、"manyToOne" 或 "manyToMany"。

   ¥Define the type of relation with the relation property.
   The value should be a string among the following possible options: "oneToOne", "oneToMany", "manyToOne" or "manyToMany".

3. 使用 target 属性定义内容类型目标。
   该值应该是遵循 api::api-name.content-type-name 或 plugin::plugin-name.content-type-name 语法约定的字符串。

   ¥Define the content-type target with the target property.
   The value should be a string following the api::api-name.content-type-name or plugin::plugin-name.content-type-name syntax convention.

4. （可选）在 双向关系 中，为每个内容类型定义 mappedBy 和 inversedBy 属性。

   ¥(optional) In bidirectional relations, define mappedBy and inversedBy properties on each content-type.

Example of all possible relations between an article and an author content-types

./src/plugins/my-plugin/server/content-types/article/schema.json

// Attributes for the Article content-type
"articleHasOneAuthor": {
  "type": "relation",
  "relation": "oneToOne",
  "target": "api::author.author"
},
"articleHasAndBelongsToOneAuthor": {
  "type": "relation",
  "relation": "oneToOne",
  "target": "api::author.author",
  "inversedBy": "article"
},
"articleBelongsToManyAuthors": {
  "type": "relation",
  "relation": "oneToMany",
  "target": "api::author.author",
  "mappedBy": "article"
},
"authorHasManyArticles": {
  "type": "relation",
  "relation": "manyToOne",
  "target": "api::author.author",
  "inversedBy": "articles"
},
"articlesHasAndBelongsToManyAuthors": {
  "type": "relation",
  "relation": "manyToMany",
  "target": "api::author.author",
  "inversedBy": "articles"
},
"articleHasManyAuthors": {
  "type": "relation",
  "relation": "oneToMany",
  "target": "api::author.author"
}

./src/plugins/my-plugin/server/content-types/author/schema.json

// Attributes for the Author content-type
"article": {
  "type": "relation",
  "relation": "manyToOne",
  "target": "api::article.article",
  "inversedBy": "articleBelongsToManyAuthors"
},
"articles": {
  "type": "relation",
  "relation": "manyToMany",
  "target": "api::article.article",
  "inversedBy": "articlesHasAndBelongsToManyAuthors"
}

更新插件配置

¥Updating plugin configuration

🤓 v3/v4 比较

Strapi v3 在 config 文件夹中定义插件配置。

¥Strapi v3 defines plugin configurations in a config folder.

在 Strapi v4 中，插件的默认配置被定义为在 config.js 文件或 config/index.js 文件中找到的对象。然后从入口文件中调用它们（参见 默认插件配置文档）。

¥In Strapi v4, the default configuration of a plugin is defined as an object found in the config.js file or in the config/index.js file. These are then called from the entry file (see default plugin configuration documentation).

要按照推荐的方式处理 Strapi v4 中的默认插件配置：

¥To handle default plugin configurations in Strapi v4 the recommended way:

1. 创建包含导出对象的 server/config/index.js 文件。

   ¥Create the server/config/index.js file containing an exported object.

2. 在 config 对象内：

   ¥Within the config object:

   • 定义一个 default 键，它采用一个对象来存储默认配置。

     ¥Define a default key that takes an object to store the default configuration.

   • （可选）添加一个 validator 键，这是一个以 config 作为参数的函数。

     ¥(optional) Add a validator key, which is a function taking the config as an argument.

Example of a default plugin configuration

  ```jsx title="./src/plugins/my-plugin/server/config/index.js"

  module.exports = {
    default: { optionA: true },
    validator: (config) => {
      if (typeof config.optionA !== 'boolean') {
        throw new Error('optionA has to be a boolean');
      }
    },
  }
  ```

3. 在 server/index.js 文件中，导入配置并导出。

   ¥In the server/index.js file, import the configuration and export it.

Example of a default entry file

  ```jsx title="./src/plugins/my-plugin/server/index.js"

  // ...
  const config = require('./config');
  // ...

  module.exports = {
    // ...
    config,
    // ...
  };
  ```

4. 通过将以下行添加到 <plugin-name>/strapi-server.js 条目文件中，确保 Strapi 知道从 server/index.js 导出的插件后端接口：

   ¥Make sure that Strapi is aware of the plugin's back-end interface exported from server/index.js by adding the following line to the <plugin-name>/strapi-server.js entry file:

   ./src/plugins/my-plugin/strapi-server.js

   
   module.exports = require('./server');