Strapi 5 采用了新的扁平化 REST API 响应格式

页面摘要： Strapi 5 通过移除 attributes 包装并使用 documentId 替代 id，将 REST API 响应扁平化。在迁移期间可使用 Strapi-Response-Format: v4 请求头以实现向后兼容。

在 Strapi 5 中，REST API 响应格式已被简化并扁平化。你可以设置 Strapi-Response-Format: v4 请求头来使用旧的 v4 格式，同时逐步转换你的代码以充分考虑新的 Strapi 5 响应格式。

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

破坏性变更说明

在 Strapi v4 中

内容 API 将所请求内容的所有属性包裹在 attributes 参数内返回：

{
  "data": {
    // 系统字段
    "id": 14,
    "attributes": {
      // 用户字段
      "title": "Article A"
      "relation": {
        "data": {
          "id": "clkgylw7d000108lc4rw1bb6s"
          "name": "Category A"
        }
      }
    }
  }
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10
    }
  }
}

在 Strapi 5 中

内容 API 返回所请求内容的属性时不再将其包裹在 attributes 对象中，并且使用 documentId 替代 id：

{
  "data": {
    // 系统字段
    "documentId": "clkgylmcc000008lcdd868feh",
    "locale": "en",
    // 用户字段
    "title": "Article A"
    "relation": {
      // 系统字段
      "documentId": "clkgylw7d000108lc4rw1bb6s"
      // 用户字段
      "name": "Category A"
    }
  }
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10
    }
  }
}

迁移

说明

Strapi-Response-Format: v4 请求头会临时恢复 Strapi v4 的包裹结构（data.attributes.*）。你可以在更新每个消费方时保留该请求头，待每个客户端都能读取扁平化格式后再移除它。该请求头影响 REST 调用（包括关联的联表加载），但不会回退 documentId 的引入。

要在迁移期间使用兼容请求头：

1. 在开启请求头之前，先采集一些基线响应样本。一旦 attributes 恢复返回，这些样本可帮助你比较负载，并确保关联、组件和嵌套联表加载都按预期响应。
2. 将 Strapi-Response-Format: v4 请求头添加到遗留客户端发出的每个 REST 请求中。只有在更新并测试完每个端点后再移除它。
3. 请注意，当请求头缺失时，documentId 仍然是 REST API 返回的唯一标识符。启用请求头后，REST 响应会同时包含 id（用于向后兼容）和 documentId（规范标识符）。请计划迁移任何仍依赖数字 id 的下游系统。

示例

curl \
  -H 'Authorization: Bearer <token>' \
  -H 'Strapi-Response-Format: v4' \
  'https://api.example.com/api/articles?populate=category'

await fetch('https://api.example.com/api/articles', {
  headers: {
    Authorization: `Bearer ${token}`,
    'Strapi-Response-Format': 'v4',
  },
});

const client = axios.create({
  baseURL: 'https://api.example.com/api',
  headers: {
    Authorization: `Bearer ${token}`,
    'Strapi-Response-Format': 'v4',
  },
});

const articles = await client.get('/articles', { params: { populate: '*'} });

手动操作步骤

确保你的 API 调用已考虑新的响应格式，或者设置可选请求头以继续使用 Strapi v4 的响应格式（请参阅 说明）。