GraphQL API

要使用 GraphQL API，请安装 GraphQL 插件。

GraphQL API 允许执行查询和变异，以通过 Strapi 的 GraphQL 插件与 content-types 进行交互。结果可以过滤、排序和分页。

统一响应格式

响应与 GraphQL API 统一，具体如下：

返回单个条目信息的查询和突变主要使用 XxxEntityResponse 类型
返回多个条目信息的查询和突变主要使用 XxxEntityResponseCollection 类型，除了数据本身外，还包含 meta 信息（带 pagination）

响应还可以包含 error（请参阅错误处理文档）。

示例：查询和突变的响应格式，以“文章”内容类型为例

graphql

type ArticleEntityResponse {
    data: ArticleEntity
}

type ArticleEntityResponseCollection {
    data: [ArticleEntityResponse!]!
    meta: ResponseCollectionMeta!
}

query {
    article(...): ArticleEntityResponse # find one
    articles(...): ArticleEntityResponseCollection # find many
}

mutation {
    createArticle(...): ArticleEntityResponse # create
    updateArticle(...): ArticleEntityResponse # update
    deleteArticle(...): ArticleEntityResponse # delete
}

Queries

GraphQL 中的查询用于获取数据而不对其进行修改。

我们假设已启用 Shadow CRUD 功能。对于每个模型，GraphQL 插件都会自动生成查询和突变，以模仿基本的 CRUD 操作（findMany、findOne、create、update、delete）。

获取单个条目

可以通过其“id”找到单个条目。

示例查询：查找 ID 为 1 的条目

graphql

query {
  document(id: 1) {
    data {
      id
      attributes {
        title
        categories {
          data {
            id
            attributes {
              name
            }
          }
        }
      }
    }
  }
}

获取多个条目

示例查询：查找所有文档并使用“名称”属性填充“类别”关系

graphql

query {
  documents {
    data {
      id
      attributes {
        title
        categories {
          data {
            id
            attributes {
                name
            }
          }
        }
      }
    }
    meta {
      pagination {
        page
        pageSize
        total
        pageCount
      }
    }
  }
}

获取动态区域数据

动态区域是 graphql 中的联合类型，因此您需要使用片段来查询字段。

graphql

query {
  restaurants {
    data {
      attributes {
        dynamiczone {
          __typename
          ...on ComponentDefaultClosingperiod {
            label
          }
        }
      }
    }
  }
}

突变 Mutations

GraphQL 中的变异用于修改数据（例如创建、更新、删除数据）。

创建新条目

graphql

mutation createArticle {
  createArticle(data: { title: "Hello"}) {
    data {
      id
      attributes {
        title
      }
    }
  }
}

突变的实现还支持关系属性。例如，您可以创建一个新的“用户”，并通过编写查询将许多“餐厅”附加到它：

graphql

mutation {
  createUser(
    data: {
      username: "John"
      email: "john@doe.com"
      restaurants: ["1", "2"]
    }
  ) {
    data {
      id
      attributes {
        username
        email
        restaurants {
          data {
            id
            attributes {
              name
              description
              price
            }
          }
        }
      }
    }
  }
}

更新现有条目

graphql

mutation updateArticle {
  updateArticle(id: "1", data: { title: "Hello" }) {
    data {
      id
      attributes {
        title
      }
    }
  }
}

您还可以通过传递 ID 或 ID 数组（取决于关系）来更新关系属性。

graphql

mutation {
  updateRestaurant(
    id: "5b5b27f8164f75c29c728110"
    data: {
      chef: "1" // User ID
    }
  }) {
    data {
      id
      attributes {
        chef {
          data {
            attributes {
              username
              email
            }
          }
        }
      }
    }
  }
}

删除条目

graphql

mutation deleteArticle {
  deleteArticle(id: 1) {
    data {
      id
      attributes {
        title
      }
    }
  }
}

Filters

查询可以接受具有以下语法的 filters 参数：

filters: { field: { operator: value } }

还可以使用逻辑运算符（and、or、not）并接受对象数组。

可用的运算符如下：

运算符	说明
`eq`	等于
`ne`	不等于
`lt`	小于
`lte`	小于或等于
`gt`	大于
`gte`	大于或等于
`in`	包含在数组中
`notIn`	不包含在数组中
`contains`	包含，区分大小写
`notContains`	不包含，区分大小写
`containsi`	包含，不区分大小写
`notContainsi`	不包含，不区分大小写
`null`	为空
`notNull`	不为空
`between`	介于之间
`startsWith`	以...开头
`endsWith`	以...结尾
`and`	逻辑 `and`
`or`	逻辑 `或`
`非`	逻辑 `非`

带过滤器的示例查询

graphql

{
  documents(filters: { name: { eq: "test" }, or: [{ price: { gt: 10 }}, { title: { startsWith: "Book" }}] }) {
    data {
      id
    }
  }
}

Sorting

查询可以接受 sort 参数，语法如下：

根据单个值排序：sort: "value"
根据多个值排序：sort: ["value1", "value2"]

排序顺序可以用 :asc（升序，默认，可以省略）或 :desc（降序）定义。

示例请求：按标题升序排序

graphql

{
  documents(sort: "title") {
    data {
      id
    }
  }
}

示例请求：按标题降序排序

graphql

{
  documents(sort: "title:desc") {
    data {
      id
    }
  }
}

示例请求：按标题升序排序，然后按价格降序排序

graphql

{
  documents(sort: ["title:asc", "price:desc"]) {
    data {
      id
    }
  }
}

Pagination

查询可以接受 pagination 参数。结果可以按页面或偏移量分页。

分页方法不能混合使用。始终使用 page 和 pageSize 或 start 和 limit。

按页分页

参数	描述	默认
`pagination[page]`	页码	1
`pagination[pageSize]`	页面大小	10

示例查询：按页分页

graphql

{
  documents(pagination: { page: 1, pageSize: 10 }) {
    data {
      id
    }
    meta {
      pagination {
        page
        pageSize
        pageCount
        total
      }
    }
  }
}

按偏移量分页

参数	说明	默认	最大值
`pagination[start]`	起始值	0	-
`pagination[limit]`	要返回的实体数	10	-1

示例查询：按偏移量分页

graphql

{
  documents(pagination: { start: 20, limit: 30 }) {
    data {
      id
    }
    meta {
      pagination {
        start
        limit
      }
    }
  }
}

可以使用 graphql.config.defaultLimit 和 graphql.config.maxLimit 键在 ./config/plugins.js 文件中配置 pagination[limit] 的默认值和最大值。