您可能已经注意到,我们的几个查询和变更的参数变得非常冗长。有一种更好的方法可以使用输入类型来组织这些参数。输入类型类似于 GraphQL 对象类型,只是它仅用于输入参数。
让我们使用参数的输入类型来改进 postPhoto 突变:
input PostPhotoInput {
name: String!
description: String
category: PhotoCategory = PORTRAIT
}
type Mutation {
postPhoto(input: PostPhotoInput!): Photo!
}
PostPhotoInput 类型类似于对象类型,但它仅为输入参数创建。它需要名称和描述,但类别字段仍然是可选的。现在发送 postPhoto 突变时,新照片的详细信息需要包含在一个对象中:
mutation newPhoto($input: PostPhotoInput!) {
postPhoto(input: $input) {
id
url
created
}
}
当我们创建这个突变时,我们设置 $input 查询变量的类型来匹配我们的 PostPhotoInput! 输入类型。它是不可空的,因为至少我们需要访问 input.name 字段来添加新照片。当我们发送突变时,我们需要在嵌套在输入字段下的查询变量中提供新的照片数据:
{
"input": {
"name": "Hanging at the Arc",
"description": "Sunny on the deck of the Arc",
"category": "LANDSCAPE"
}
}
我们的输入被组合在一个 JSON 对象中,并与“输入”键下的查询变量中的突变一起发送。由于查询变量的格式为 JSON,因此类别需要是与 PhotoCategory 类型中的类别之一相匹配的字符串。
输入类型是组织和编写清晰的 GraphQL 模式的关键。您可以将输入类型用作任何字段的参数。您可以使用它们来改进应用程序中的数据分页和数据过滤。
让我们来看看如何通过使用输入类型来组织和重用我们所有的排序和过滤字段:
input PhotoFilter {
category: PhotoCategory
createdBetween: DateRange
taggedUsers: [ID!]
searchText: String
}
input DateRange {
start: DateTime!
end: DateTime!
}
input DataPage {
first: Int = 25
start: Int = 0
}
input DataSort {
sort: SortDirection = DESCENDING
sortBy: SortablePhotoField = created
}
type User {
...
postedPhotos(filter:PhotoFilter paging:DataPage sorting:DataSort): [Photo!]!
inPhotos(filter:PhotoFilter paging:DataPage sorting:DataSort): [Photo!]!
}
type Photo {
...
taggedUsers(sorting:DataSort): [User!]!
}
type Query {
...
allUsers(paging:DataPage sorting:DataSort): [User!]!
allPhotos(filter:PhotoFilter paging:DataPage sorting:DataSort): [Photo!]!
}
我们在输入类型下组织了许多字段,并在我们的模式中重复使用这些字段作为参数。
PhotoFilter 输入类型包含可选的输入字段,允许客户端过滤照片列表。PhotoFilter 类型在字段 createdBetween 下包含一个嵌套的输入类型 DateRange。DateRange 必须包括开始日期和结束日期。使用 PhotoFilter,我们还可以按类别、搜索字符串或标记用户过滤照片。我们将所有这些过滤器选项添加到返回照片列表的每个字段。这使客户端可以很好地控制从每个列表返回哪些照片。
还为分页和排序创建了输入类型。DataPage 输入类型包含请求数据页所需的字段,DataSort 输入类型包含我们的排序字段。这些输入类型已添加到我们的架构中返回数据列表的每个字段。
我们可以使用可用的输入类型编写一个接受一些非常复杂的输入数据的查询:
query getPhotos($filter: PhotoFilter, $page: DataPage, $sort: DataSort) {
allPhotos(filter: $filter, paging: $page, sorting: $sort) {
id
name
url
}
}
此查询可选择接受三种输入类型的参数:$filter、$page 和 $sort。使用查询变量,我们可以发送一些关于我们想要返回的照片的具体细节:
{
"filter": {
"category": "ACTION",
"taggedUsers": ["MoonTahoe", "EvePorcello"],
"createdBetween": {
"start": "2018-11-6",
"end": "2018-5-31"
}
},
"page": {
"first": 100
}
}
此查询将查找 GitHub 用户 MoonTahoe 和 EvePorcello 在 11 月 6 日至 5 月 31 日期间标记的所有 ACTION 照片,这恰好是滑雪季节。我们还要求使用此查询提供前 100 张照片。
输入类型帮助我们组织模式和重用参数。他们还改进了 GraphiQL 或 GraphQL Playground 自动生成的模式文档。这将使您的 API 更易于理解,更易于学习和消化。最后,您可以使用输入类型为客户端提供强大的功能来执行有组织的查询。
👈 上一节 | 下一节 👉 |
---|