GraphQL API 已更新
🌐 The GraphQL API has been updated
Page summary:Strapi 5 GraphQL API 支持新的扁平化响应格式和用于分页的 Relay 风格
*_connection查询。使用v4CompatibilityMode逐步迁移，采用documentId，将字段重命名为*_connection，并最终删除attributes封装器。🌐 The Strapi 5 GraphQL API supports a new flattened response format and Relay-style
*_connectionqueries for pagination. Migrate gradually usingv4CompatibilityMode, adoptdocumentId, rename fields to*_connection, and eventually drop theattributeswrapper.
在 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.
更改列表
🌐 List of changes
| 主题 | 更改说明 |
|---|---|
| 文件上传支持 |
|
| 国际化支持 | 移除了 createXXLocalization 变更，改为可通过主 updateXXX 变更更新任何语言环境 |
| 草稿与发布支持 | 移除了 publicationState，改为 status 以符合新的草稿与发布行为 |
| 架构更改 |
|
有关新的 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.jsmodule.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 格式。