API 设计 / 系统课时

设计参数与 Input

设计参数与 Input

GraphQL 字段参数适合表达一次字段调用所需的条件,Input Object 则把一组会共同演进的输入组织成稳定结构。本篇用商品查询与创建命令说明筛选、排序、分页和写入参数应如何分层。

学习目标

  • 判断何时直接使用字段参数,何时抽成 Input Object
  • 用输入对象组织筛选、排序、分页与 Mutation 命令参数
  • 通过变量传递结构化输入,并识别常见演进风险

从字段参数到输入对象

少量且稳定的参数可以直接声明在字段上,例如 product(id: ID!): Product。当筛选条件不断增加,继续平铺 keyword、categoryId、minPrice、maxPrice 会让字段签名膨胀,也不利于在多个字段之间复用规则。

Input Object 适合把“属于同一个概念”的输入聚合起来。它只能用于输入位置,不能作为字段返回类型。查询条件、排序规则、分页参数和 Mutation 命令通常应各自建模,不要把所有参数塞进一个巨大的通用 OptionsInput。

建模筛选、排序与分页

下面的 SDL 把三类查询参数拆开,同时让创建商品使用独立的命令输入:

graphql
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 文本。查询文档保持稳定,变量则独立承载筛选和分页状态:

graphql
query Products(
  $filter: ProductFilter
  $orderBy: [ProductOrder!]
  $page: ProductPage
) {
  products(filter: $filter, orderBy: $orderBy, page: $page) {
    nodes {
      id
      name
      price
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

变量示例:

json
{
  "filter": {
    "keyword": "keyboard",
    "minPrice": 50
  },
  "orderBy": [
    {
      "field": "PRICE",
      "direction": "ASC"
    }
  ],
  "page": {
    "first": 2,
    "after": null
  }
}

预期结果

json
{
  "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 决定“这组输入如何被组织和演进”。把筛选、排序、分页与命令参数按职责拆开,既能让客户端变量结构更清晰,也能降低后续扩展时破坏现有调用方的概率。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计参数与 Input

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通