GraphQL API 已更新

🌐 The GraphQL API has been updated

在 Strapi 5 中，GraphQL API 已经更新。它可以处理新的扁平化响应格式（参见相关重大变更），现在也可以接受 Relay-style 查询。

扁平查询仍然返回一个简单的文档数组。你也可以使用 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.

此页面是重大更改数据库的一部分，提供关于重大更改的信息以及从 Strapi v4 迁移到 Strapi 5 的附加说明。

🌐 This page is part of the breaking changes database 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 | 主题 | 更改说明 ||------------------------------|-----------------------------------------------------------------------------------------------------|| 文件上传支持 |

移除了 uploadFile uploadFiles 变更
移除了 updateFileInfo 变更，改为使用 updateUploadFile 变更
移除了 removeFile 变更，改为使用 deleteUploadFile 变更
移除了 folder 查询和变更
移除了 createUploadFile 变更

|| 国际化支持 | 移除了 createXXLocalization 变更，改为可通过主 updateXXX 变更更新任何语言环境 || 草稿与发布支持 | 移除了 publicationState，改为 status 以符合新的草稿与发布行为 || 架构更改 |

简化了基础查询，无 meta/pagination
引入 Connection 以添加分页

有关新的 Strapi 5 GraphQL API 的详细描述，请参阅 GraphQL API 参考文档。

🌐 For an extensive description of the new Strapi 5 GraphQL API, please refer to the GraphQL API reference documentation.

迁移

🌐 Migration

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

🌐 To gradually convert to the new GraphQL API format, follow these steps:

启用 v4CompatibilityMode 旧兼容性头，以便在重构客户端时查询仍可依赖 data.attributes.*。在 config/plugins.{js,ts} 中配置它。启用该标志后，服务器将继续返回 Strapi v4 结构。

config/plugins.js
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 分页元数据。

{
  # 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
      }
    }
  }
}

一旦集合查询和单个查询使用 *_connection，就停止在 attributes 中封装用户字段。这适用于查询和变更响应。

{
  # 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
      }
    }
  }
}

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

{
  # 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
    }
  }
}

{
  # 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
    }
  }
}

禁用 v4CompatibilityMode 兼容性头，以便服务器原生输出 Strapi 5 格式。

更改列表​

迁移​

更改列表

迁移