API 设计 / 系统课时
设计参数与 Input
设计参数与 Input
GraphQL 字段参数适合表达一次字段调用所需的条件,Input Object 则把一组会共同演进的输入组织成稳定结构。本篇用商品查询与创建命令说明筛选、排序、分页和写入参数应如何分层。
学习目标
- 判断何时直接使用字段参数,何时抽成 Input Object
- 用输入对象组织筛选、排序、分页与 Mutation 命令参数
- 通过变量传递结构化输入,并识别常见演进风险
从字段参数到输入对象
少量且稳定的参数可以直接声明在字段上,例如 product(id: ID!): Product。当筛选条件不断增加,继续平铺 keyword、categoryId、minPrice、maxPrice 会让字段签名膨胀,也不利于在多个字段之间复用规则。
Input Object 适合把“属于同一个概念”的输入聚合起来。它只能用于输入位置,不能作为字段返回类型。查询条件、排序规则、分页参数和 Mutation 命令通常应各自建模,不要把所有参数塞进一个巨大的通用 OptionsInput。
建模筛选、排序与分页
下面的 SDL 把三类查询参数拆开,同时让创建商品使用独立的命令输入:
enum ProductSortField {
CREATED_AT
PRICE
}
enum SortDirection {
ASC
DESC
}
input ProductFilter {
keyword: String
categoryId: ID
minPrice: Float
maxPrice: Float
}
input ProductOrder {
field: ProductSortField!
direction: SortDirection!
}
input ProductPage {
first: Int = 20
after: String
}
input CreateProductInput {
name: String!
price: Float!
categoryId: ID
}
type PageInfo {
endCursor: String
hasNextPage: Boolean!
}
type Product {
id: ID!
name: String!
price: Float!
}
type ProductConnection {
nodes: [Product!]!
pageInfo: PageInfo!
}
type Query {
products(
filter: ProductFilter
orderBy: [ProductOrder!]
page: ProductPage
): ProductConnection!
}
type Mutation {
createProduct(input: CreateProductInput!): Product!
}这是接口定义示例。filter、orderBy、page 都是可选参数;CreateProductInput 本身必须提供,且 name、price 是必填字段。first 的默认值只能提供默认数量,像“必须大于 0 且不超过 100”这样的范围约束仍需在服务端校验。
用变量发送结构化参数
客户端应优先通过 variables 传递动态值,而不是把用户输入直接拼进 GraphQL 文本。查询文档保持稳定,变量则独立承载筛选和分页状态:
query Products(
$filter: ProductFilter
$orderBy: [ProductOrder!]
$page: ProductPage
) {
products(filter: $filter, orderBy: $orderBy, page: $page) {
nodes {
id
name
price
}
pageInfo {
endCursor
hasNextPage
}
}
}变量示例:
{
"filter": {
"keyword": "keyboard",
"minPrice": 50
},
"orderBy": [
{
"field": "PRICE",
"direction": "ASC"
}
],
"page": {
"first": 2,
"after": null
}
}预期结果
{
"data": {
"products": {
"nodes": [
{
"id": "p1",
"name": "Compact Keyboard",
"price": 69
},
{
"id": "p2",
"name": "Mechanical Keyboard",
"price": 89
}
],
"pageInfo": {
"endCursor": "<ID>",
"hasNextPage": true
}
}
}
}商品内容和游标由实际数据决定,因此示例用 <ID> 表示动态游标值。请求是否真正返回这两条商品,还取决于服务端 resolver、数据集与排序实现。
为 Mutation 设计命令输入
Mutation 往往比查询参数更需要 Input Object,因为写操作会随着业务增长增加字段、校验和审计信息。createProduct(input: CreateProductInput!) 比把 name、price、categoryId 全部平铺在字段参数上更容易演进,也能让客户端把一个命令作为整体变量传入。
输入对象仍应保持单一职责。查询用的 ProductFilter 不应直接复用为创建或更新输入,因为“可用于筛选”与“允许被写入”是两套不同权限和业务规则。对于更新操作,还要区分字段“未提供”和“显式传 null”的语义;若两者代表不同动作,resolver 必须保留这个差异。
控制 Schema 演进风险
新增一个可选字段到 Input Object,通常不会强迫已有客户端修改请求;但新增一个没有默认值的非空输入字段,会让原来合法的请求因为缺少该字段而失败。因此,必填输入应该只用于真正不可缺少、且能长期稳定承诺的业务条件。
排序字段优先用 enum,而不是任意字符串,这样 Schema 可以公开允许的集合并在执行前完成类型校验。分页参数也应采用稳定模型;若数据会频繁插入或删除,基于 cursor 的 first/after 通常比裸 offset 更容易保持翻页边界稳定。
字段参数决定“这个字段接受什么”,Input Object 决定“这组输入如何被组织和演进”。把筛选、排序、分页与命令参数按职责拆开,既能让客户端变量结构更清晰,也能降低后续扩展时破坏现有调用方的概率。