GraphQL API 已更新

页面摘要： Strapi 5 的 GraphQL API 支持新的扁平化响应格式以及用于分页的 Relay 风格 *_connection 查询。请使用 v4CompatibilityMode 逐步迁移，采用 documentId，将字段重命名为 *_connection，并最终去掉 attributes 包装。

在 Strapi 5 中，GraphQL API 已更新。它处理新的扁平化响应格式（请参阅相关破坏性变更），并且现在也可以接受 Relay 风格的查询。

扁平查询仍然返回简单的文档数组。你也可以使用 Relay 风格的 *_connection 查询，它返回 nodes 和一个 pageInfo 对象来处理分页。当你需要有关页面或总数的元数据时，请使用这些查询。

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

变更列表

主题	变更说明
文件上传支持

移除了 uploadFile、uploadFiles 变更（mutation）
移除了 updateFileInfo 变更，改用 updateUploadFile 变更
移除了 removeFile 变更，改用 deleteUploadFile 变更
移除了 folder 查询与变更
移除了 createUploadFile 变更 | | 国际化支持 | 移除了 createXXLocalization 变更，改为可以在主 updateXXX 变更中更新任何语言版本 | | 草稿与发布支持 | 移除了 publicationState，改用 status，以与新的草稿与发布行为保持一致 | | 模式变更 |
简化了基础查询，不再包含 meta/pagination
引入了 Connection 来添加分页 |

有关新的 Strapi 5 GraphQL API 的详尽说明，请参阅 GraphQL API 参考文档。

迁移

要逐步转换为新的 GraphQL API 格式，请按照以下步骤操作：

启用 v4CompatibilityMode 向后兼容请求头，这样在重构客户端期间，查询可以继续依赖 data.attributes.*。在 config/plugins.{js,ts} 中配置它。开启该标志后，服务器会继续返回 Strapi v4 的结构。

module.exports = {
  graphql: {
    config: {
      v4CompatibilityMode: true,
    },
  },
};

{
  restaurants {
    data {
      id
      attributes {
        title
        image {
          data {
            id
            attributes {
              url
            }
          }
        }
        images {
          data {
            id
            attributes {
              url
            }
          }
        }
        xToOneRelation {
          data {
            id
            attributes {
              field
            }
          }
        }
        xToManyRelation {
          data {
            id
            attributes {
              field
            }
          }
        }
      }
    }
    meta {
      pagination {
        page
        pageSize
      }
    }
  }
}

采用 documentId，它在 GraphQL 中取代数字 id。即使兼容模式处于开启状态，也要更新查询和变更以读取和发送 documentId。

{
  restaurants {
    data {
      documentId
      attributes {
        title
        image {
          data {
            documentId
            attributes {
              url
            }
          }
        }
        images {
          data {
            documentId
            attributes {
              url
            }
          }
        }
        xToOneRelation {
          data {
            documentId
            attributes {
              field
            }
          }
        }
        xToManyRelation {
          data {
            documentId
            attributes {
              field
            }
          }
        }
      }
    }
  }
}

mutation UpdateRestaurant {
  updateRestaurant(
    documentId: "some-doc-id",
    data: { title: "My great restaurant" }
  ) {
    data {
      documentId
      attributes {
        title
        image {
          data {
            documentId
            attributes {
              url
            }
          }
        }
      }
    }
  }
}

将集合字段重命名为其 _connection 变体。这样可以在仍保留 v4 风格的 data 和 attributes 结构的同时，解锁 Relay 分页元数据。

{
  # 集合字段可重命名为 _connection 以获得 v4 兼容响应
  restaurants_connection {
    data {
      id
      attributes {
        title
        image {
          data {
            id
            attributes {
              url
            }
          }
        }
        # 集合字段可重命名为 _connection 以获得 v4 兼容响应
        images_connection {
          data {
            id
            attributes {
              url
            }
          }
        }
        xToOneRelation {
          data {
            id
            attributes {
              field
            }
          }
        }
        # 集合字段可重命名为 _connection 以获得 v4 兼容响应
        xToManyRelation_connection {
          data {
            id
            attributes {
              field
            }
          }
        }
      }
    }
    meta {
      pagination {
        page
        pageSize
      }
    }
  }
}

一旦集合查询和单一查询都使用了 *_connection，就停止将用户字段包裹在 attributes 中。这适用于查询和变更响应。

{
  # 集合字段可重命名为 _connection 以获得 v4 兼容响应
  restaurants_connection {
    data {
      id
      title
      image {
        data {
          id
          url
        }
      }
      # 集合字段可重命名为 _connection 以获得 v4 兼容响应
      images_connection {
        data {
          id
          url
        }
      }
      xToOneRelation {
        data {
          id
          field
        }
      }
      # 集合字段可重命名为 _connection 以获得 v4 兼容响应
      xToManyRelation_connection {
        data {
          id
          field
        }
      }
    }
    meta {
      pagination {
        page
        pageSize
      }
    }
  }
}

(可选) 如果你需要符合 Relay 规范的分页，请将 data 重命名为 nodes，将 meta.pagination 重命名为 pageInfo。当客户端不需要分页元数据时，你也可以完全去掉 _connection。

{
  # 将 data 重命名为 nodes，将 meta.pagination 重命名为 pageInfo
  restaurants_connection {
    nodes {
      id
      title
      image {
        id
        url
      }
      images_connection {
        nodes {
          id
          url
        }
      }
      xToOneRelation {
        id
        field
      }
      xToManyRelation_connection {
        nodes {
          id
          field
        }
      }
    }
    pageInfo {
      page
      pageSize
    }
  }
}

{
  # 如果完全不需要分页，可移除 _connection 和 data
  restaurants {
    id
    title
    image {
      id
      url
    }
    images {
      id
      url
    }
    xToOneRelation {
      id
      field
    }
    xToManyRelation {
      id
      field
    }
  }
}

禁用 v4CompatibilityMode 兼容请求头，这样服务器就会原生输出 Strapi 5 格式。