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:
-
在 GraphQL 插件的配置中使用
v4CompatibilityMode标志启用 v4 兼容模式（参见 插件配置）：¥Enable v4 compatibility mode with the
v4CompatibilityModeflag in the configuration of the GraphQL plugin (see plugins configuration):{
restaurants {
data {
id
attributes {
title
image {
data {
id
attributes {
url
}
}
}
images {
data {
id
attributes {
url
}
}
}
xToOneRelation {
data {
id
attributes {
}
}
xToManyRelation {
data {
id
attributes {
field
}
}
}
}
}
meta {
pagination {
page
pageSize
}
}
}
} -
使用
documentId代替id进行 contentType 查询和修改：¥Use
documentIdinstead ofidfor contentType queries & mutations:Strapi 5 引入了
documentId作为主要标识符 用于文档，确保跨数据库的唯一性。为了向后兼容，REST API 仍然返回数字id，但在 GraphQL 中不可用。¥Strapi 5 introduces
documentIdas the main identifier for documents, ensuring uniqueness across databases. The numericidis still returned by the REST API for backward compatibility but is not available in GraphQL.{
restaurants {
data {
documentId
attributes {
title
image {
data {
documentId
attributes {
url
}
}
}
images {
data {
documentId
attributes {
url
}
}
}
xToOneRelation {
data {
documentId
attributes {
}
}
xToManyRelation {
data {
documentId
attributes {
field
}
}
}
}
}
meta {
pagination {
page
pageSize
}
}
}
}{
mutation {
updateRestaurant(
documentId: "some-doc-id",
data: { title: "My great restaurant" }
) {
data {
documentId
attributes {
title
image {
data {
documentId
attributes {
url
}
}
}
}
}
}
}
} -
移动到
_connection而不改变响应格式（仅适用于查询）：¥Move to
_connectionwithout changing response format (only applies to queries):{
# 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
}
}
}
} -
依赖数据库层上的任何输入填充值都不 可靠，因此如果自定义代码库中需要，生命周期应始终获取必要的数据。
¥Remove attributes (applies to queries & 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
}
}
}
} -
使用新命名或更简单的查询：
¥Use new naming or the simpler queries:
{
# Rename data to nodes & meta.pagination to pageInfo
restaurants_connection {
nodes {
id
title
# can remove data in single Images
image {
id
url
}
# collection fields can be renamed to _connection to get a v4 compat response
images_connection {
nodes {
id
url
}
}
# can remove data in xToOne
xToOneRelation {
id
field
}
# collection fields can be renamed to _connection to get a v4 compat response
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
}
# remove _connection & data
images {
id
url
}
xToOneRelation {
id
field
}
# remove _connection & data
xToManyRelation {
id
field
}
}
}