内容 API 调用中应使用 documentId 而非 id

页面摘要： 在 Strapi 5 中，作为文档服务 API 迁移的一部分，documentId 字段取代了 id，用于在内容 API 调用（REST API 和 GraphQL）中标识文档。

在 Strapi 5 中，处理内容的底层 API 是 文档服务 API，在内容 API 调用（REST API 和 GraphQL）中应通过文档的 documentId 来调用文档。

本页面是破坏性变更数据库的一部分，提供有关该破坏性变更的信息，以及从 Strapi v4 迁移到 Strapi 5 的附加说明。

代码迁移工具： entity-service-document-service

破坏性变更说明

在 Strapi v4 中

条目通过它们的 id 标识：

{
  "data": {
    // 系统字段
    "id": 14,
    "attributes": {
      // 用户字段
      "title": "Article A"
      "relation": {
        "data": {
          "id": 15
          "name": "Category A"
        }
      }
    }
  }
  "meta": {
    // …
  }
}

在 Strapi 5 中

文档通过它们的 documentId 标识：

{
  "data": {
    // 系统字段
    "documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
    "locale": "en",
    // 用户字段
    "title": "Article A"
    "relation": {
      // 系统字段
      "documentId": "j9k8l7m6n5o4p3q2r1s0tuvw"
      // 用户字段
      "name": "Category A"
    }
  }
  "meta": {
    // …
  }
}

迁移

本节汇总了关于该破坏性变更的有用说明和操作步骤。

说明

  • 此破坏性变更影响路由和关联。
  • 为简化从 v4 到 Strapi 5 的过渡，对条目的 API 调用在响应中可能仍包含 id 字段，尤其是在 文档服务 API 中。但建议你养成使用 documentId 而非 id 的习惯，因为这将有助于过渡到未来的 Strapi 版本。

迁移步骤

codemod 会部分处理此变更，但很可能会在你的代码中添加 __TODO__ 项，因为 codemod 无法自动猜测你内容的新的 documentId。

更多信息，请参阅以下资源：