# GraphQL API 已更新
> Source: https://strapi.nodejs.cn/cms/migration/v4-to-v5/breaking-changes/graphql-api-updated
🌐 The GraphQL API has been updated
Strapi 5 GraphQL API 支持新的扁平化响应格式和用于分页的 Relay 风格 `*_connection` 查询。使用 `v4CompatibilityMode` 逐步迁移，采用 `documentId`，将字段重命名为 `*_connection`，并最终删除 `attributes` 封装器。
🌐 The Strapi 5 GraphQL API supports a new flattened response format and Relay-style `*_connection` queries for pagination. Migrate gradually using `v4CompatibilityMode`, adopt `documentId`, rename fields to `*_connection`, and eventually drop the `attributes` wrapper.
在 Strapi 5 中，GraphQL API 已经更新。它可以处理新的扁平化响应格式（参见 [相关重大变更](/cms/migration/v4-to-v5/breaking-changes/new-response-format.md)），现在也可以接受 [Relay-style](https://www.apollographql.com/docs/technotes/TN0029-relay-style-connections/) 查询。
扁平查询仍然返回一个简单的文档数组。你也可以使用 Relay 风格的 `*_connection` 查询，它们返回 `nodes` 和一个 `pageInfo` 对象来处理分页。当你需要关于页面或总数的元数据时使用这些查询。
🌐 Flat queries still return a simple array of documents. You can also use Relay-style `*_connection` queries, which return `nodes` and a `pageInfo` object to handle pagination. Use these when you need metadata about pages or total counts.
此页面是[重大更改数据库](/cms/migration/v4-to-v5/breaking-changes)的一部分，提供关于重大更改的信息以及从 Strapi v4 迁移到 Strapi 5 的附加说明。
🌐 This page is part of the [breaking changes database](/cms/migration/v4-to-v5/breaking-changes) and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.
- Is this breaking change affecting plugins? Yes
- Is this breaking change automatically handled by a codemod? No
## 更改列表 {#list-of-changes}
🌐 List of changes
| 主题 | 更改说明 |
|------------------------------|-----------------------------------------------------------------------------------------------------|
| 文件上传支持 | - 移除了 `uploadFile` `uploadFiles` 变更
- 移除了 `updateFileInfo` 变更，改为使用 `updateUploadFile` 变更
- 移除了 `removeFile` 变更，改为使用 `deleteUploadFile` 变更
- 移除了 `folder` 查询和变更
- 移除了 `createUploadFile` 变更
|
| 国际化支持 | 移除了 `createXXLocalization` 变更，改为可通过主 `updateXXX` 变更更新任何语言环境 |
| 草稿与发布支持 | 移除了 `publicationState`，改为 `status` 以符合新的草稿与发布行为 |
| 架构更改 | - 简化了基础查询，无 `meta`/`pagination`
- 引入 `Connection` 以添加分页
|
有关新的 Strapi 5 GraphQL API 的详细描述，请参阅 [GraphQL API](/cms/api/graphql) 参考文档。
🌐 For an extensive description of the new Strapi 5 GraphQL API, please refer to the [GraphQL API](/cms/api/graphql) reference documentation.
## 迁移 {#migration}
🌐 Migration
要逐步转换为新的 GraphQL API 格式，请按照以下步骤操作：
🌐 To gradually convert to the new GraphQL API format, follow these steps:
1. 启用 `v4CompatibilityMode` 旧兼容性头，以便在重构客户端时查询仍可依赖 `data.attributes.*`。在 `config/plugins.{js,ts}` 中配置它。启用该标志后，服务器将继续返回 Strapi v4 结构。
```js title="config/plugins.js"
module.exports = {
graphql: {
config: {
v4CompatibilityMode: true,
},
},
};
```
```graphql
{
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
}
}
}
}
```
2. 采用 [`documentId`](/cms/migration/v4-to-v5/breaking-changes/use-document-id) 来替换 GraphQL 中的数字 `id`。即使在兼容模式下，也要更新查询和变更以读取和发送 `documentId`。
```graphql
{
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
}
}
}
}
}
}
}
```
```graphql
mutation UpdateRestaurant {
updateRestaurant(
documentId: "some-doc-id",
data: { title: "My great restaurant" }
) {
data {
documentId
attributes {
title
image {
data {
documentId
attributes {
url
}
}
}
}
}
}
}
```
3. 将集合字段重命名为它们的 `_connection` 变体。这可以在保持 v4 风格的 `data` 和 `attributes` 结构的同时，解锁 Relay 分页元数据。
```graphql
{
# collection fields can be renamed to _connection to get a v4 compat response
restaurants_connection {
data {
id
attributes {
title
image {
data {
id
attributes {
url
}
}
}
# collection fields can be renamed to _connection to get a v4 compat response
images_connection {
data {
id
attributes {
url
}
}
}
xToOneRelation {
data {
id
attributes {
field
}
}
}
# collection fields can be renamed to _connection to get a v4 compat response
xToManyRelation_connection {
data {
id
attributes {
field
}
}
}
}
}
meta {
pagination {
page
pageSize
}
}
}
}
```
4. 一旦集合查询和单个查询使用 `*_connection`，就停止在 `attributes` 中封装用户字段。这适用于查询和变更响应。
```graphql
{
# collection fields can be renamed to _connection to get a v4 compat response
restaurants_connection {
data {
id
title
image {
data {
id
url
}
}
# collection fields can be renamed to _connection to get a v4 compat response
images_connection {
data {
id
url
}
}
xToOneRelation {
data {
id
field
}
}
# collection fields can be renamed to _connection to get a v4 compat response
xToManyRelation_connection {
data {
id
field
}
}
}
meta {
pagination {
page
pageSize
}
}
}
}
```
5. *(可选)* 如果你需要符合 Relay 标准的分页，请将 `data` 重命名为 `nodes`，将 `meta.pagination` 重命名为 `pageInfo`。当客户端不需要分页元数据时，你也可以完全删除 `_connection`。
```graphql
{
# Rename data to nodes & meta.pagination to 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
}
}
}
```
```graphql
{
# remove _connection & data if you don't need pagination att all
restaurants {
id
title
image {
id
url
}
images {
id
url
}
xToOneRelation {
id
field
}
xToManyRelation {
id
field
}
}
}
```
6. 禁用 `v4CompatibilityMode` 兼容性头，以便服务器原生输出 Strapi 5 格式。