Skip to main content

实体服务已弃用

🌐 Entity Service deprecated

在 Strapi v4 中使用的实体服务已被弃用，并在 Strapi 5 中被新的 文档服务 API 所取代。

本节重新组合了有关引入的重大更改的有用说明和程序。

🌐 This section regroups useful notes and procedures about the introduced breaking change.

 Is this breaking change affecting plugins?Yes
 Is this breaking change automatically handled by a codemod?Partly
(see entity-service-document-service)

重大变更描述​

🌐 Breaking change description

在 Strapi v4 中

实体服务 API 是用于与你的内容类型交互的首选 API。

🌐 The Entity Service API is the go-to API to use to interact with your content-types.

在 Strapi 5 中

文档服务 API 取代了 Strapi v4 的实体服务 API。

🌐 The Document Service API replaces the Entity Service API from Strapi v4.

迁移​

🌐 Migration

本节重新组合了有关引入的重大更改的有用说明和程序。

🌐 This section regroups useful notes and procedures about the introduced breaking change.

注意​

🌐 Notes

以下是使用文档服务 API 而不是 Strapi v4 中的实体服务 API 时需要考虑的主要主题：

🌐 The following are the main topics to take into account when using the Document Service API instead of the Entity Service API from Strapi v4:

  • 文档服务 API 期望一个 documentId 属性。
    这一重大变更同样影响 REST 和 GraphQL API（👉 请参见 相关的重大变更条目）。

    Info

    为了简化向 Strapi 5 的过渡，文档服务 API 响应除了包含新的 documentId 字段外，仍然包含 id 字段。

  • findMany() 函数返回的响应在 Strapi v4 和 Strapi 5 中不同：

    在 Strapi v4 中：

    实体服务 API 中的 findMany() 函数会为单一类型返回单个项目。

    在 Strapi 5 中：

    findMany() 函数来自文档服务 API 总是返回数组。

    要获取单个项目，请从返回的数组中提取第一个项目，或使用 findFirst() 函数。

  • 在 Strapi 5 中不再存在 findPage() 方法。
    👉 查看 相关的重大变更条目。

  • Strapi 5 中的 Draft & Publish 功能已更新，这在文档服务 API 中有所体现：

  • 文档服务 API 的 delete() 函数 返回受影响条目的列表（多个语言环境可以一次性删除），而 Strapi v4 的 delete() 函数只返回被删除的条目。

  • 实体服务装饰器不能再使用，必须改用文档服务中间件。

  • 文档服务 API 不支持文件上传。

迁移程序​

🌐 Migration procedure

在使用 升级工具 时，迁移部分由 codemod 处理。

🌐 The migration is partially handled by a codemod when using the upgrade tool.

👉 从实体服务 API 到文档服务 API 的迁移参考 提供了有关哪些方面由 codemod 处理以及哪些用例需要手动迁移的附加信息。