GraphQL API 已更新
¥The GraphQL API has been updated
在 Strapi 5 中，GraphQL API 已更新。它处理新的扁平响应格式（参见 相关重大更改更改），现在还可以接受 中继样式 查询。
¥In Strapi 5, the GraphQL API has been updated. It handles the new, flattened response format (see related breaking change), and can also now accept Relay-style queries.
扁平查询仍然返回一个简单的文档数组。你还可以使用 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 查询和突变 |
| 草稿和发布支持 | 删除模块配置选项并将其拆分为 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 格式。¥Enable the
v4CompatibilityModeretro-compatibility header so queries can continue to rely ondata.attributes.*while you refactor clients. Configure it inconfig/plugins.{js,ts}. With the flag on, the server keeps returning the Strapi v4 shape.
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，即使在启用兼容模式的情况下也是如此。¥Adopt
documentIdwhich replaces numericidin GraphQL. Update queries and mutations to read and senddocumentId, even while compatibility mode is on.{
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变体重命名集合字段。这可以解锁 Relay 分页元数据，同时保持 v4 风格的data和attributes格式。¥Rename collection fields with their
_connectionvariants. This unlocks Relay pagination metadata while still keeping the v4-styledataandattributesshape.{
# 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中。这适用于查询和变更响应。¥Once collection and single queries use
*_connection, stop wrapping user fields inattributes. This applies to queries and mutation responses.{
# 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。¥(Optional) If you need Relay-compliant pagination, rename
datatonodesandmeta.paginationtopageInfo. When a client does not need pagination metadata, you can also drop_connectionentirely.{
# 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 格式。¥Disable the
v4CompatibilityModecompatibility header so the server emits the Strapi 5 format natively.