# 实体服务已弃用

> Source: https://strapi.nodejs.cn/cms/migration/v4-to-v5/breaking-changes/entity-service-deprecated

🌐 Entity Service deprecated

在 Strapi 5 中，实体服务 API 已被弃用，并由文档服务 API 取代，该 API 使用 `documentId`，对所有查询返回数组，并引入了用于草稿和发布工作流程的新方法。

🌐 The Entity Service API is deprecated in Strapi 5 and replaced by the Document Service API, which uses `documentId`, returns arrays for all queries, and introduces new methods for draft and publish workflows.

在 Strapi v4 中使用的实体服务已被弃用，并在 Strapi 5 中被新的 [文档服务 API](/cms/api/document-service) 所取代。 

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

🌐 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
  - Codemod: [entity-service-document-service](https://github.com/strapi/strapi/blob/develop/packages/utils/upgrade/resources/codemods/5.0.0/entity-service-document-service.code.ts)

## 重大变更描述 {#breaking-change-description}

🌐 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](/cms/api/document-service) 取代了 Strapi v4 的实体服务 API。

🌐 The [Document Service API](/cms/api/document-service) replaces the Entity Service API from Strapi v4.

## 迁移 {#migration}

🌐 Migration

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

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

### 注意 {#notes}

🌐 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` 属性。<br/>这一重大变更同样影响 REST 和 GraphQL API（👉 请参见 [相关的重大变更条目](/cms/migration/v4-to-v5/breaking-changes/use-document-id)）。

  :::info

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

  :::

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

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

  **在 Strapi 5 中：**

  [`findMany()` 函数来自文档服务 API](/cms/api/document-service#findmany) 总是返回数组。<br/><br/>要获取单个项目，请从返回的数组中提取第一个项目，或使用 [ `findFirst()` 函数](/cms/api/document-service#findfirst)。

* 在 Strapi 5 中不再存在 `findPage()` 方法。<br/>👉 查看 [相关的重大变更条目](/cms/migration/v4-to-v5/breaking-changes/no-find-page-in-document-service)。
* Strapi 5 中的 [Draft & Publish](/cms/features/draft-and-publish) 功能已更新，这在文档服务 API 中有所体现：
  - `publicationState` 被 `status` <br/> 替换 👉 查看 [相关的重大变更条目](/cms/migration/v4-to-v5/breaking-changes/publication-state-removed)。
  - 引入了新方法来处理更新的 [Draft & Publish](/cms/features/draft-and-publish) 功能：
    - [`publish()`](/cms/api/document-service#publish),
    - [`unpublish()`](/cms/api/document-service#unpublish),
    - 和 [`discardDraft()`](/cms/api/document-service#discarddraft)。
  - `published_at` 属性不能再用于触发内容发布。
* 文档服务 API 的 [`delete()` 函数](/cms/api/document-service#delete) 返回受影响条目的列表（多个语言环境可以一次性删除），而 Strapi v4 的 `delete()` 函数只返回被删除的条目。
* 实体服务装饰器不能再使用，必须改用[文档服务中间件](/cms/api/document-service/middlewares)。
* 文档服务 API 不支持文件上传。

### 迁移程序 {#migration-procedure}

🌐 Migration procedure

在使用 [升级工具](/cms/upgrade-tool) 时，迁移部分由 codemod 处理。

🌐 The migration is partially handled by a codemod when using the [upgrade tool](/cms/upgrade-tool).

👉 [从实体服务 API 到文档服务 API 的迁移参考](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service) 提供了有关哪些方面由 codemod 处理以及哪些用例需要手动迁移的附加信息。