API 设计 / 系统课时

设计 Mutation 输入与返回值

设计 Mutation 输入与返回值

Mutation 的难点不在于把字段放进 type Mutation,而在于让写入契约长期稳定。本节用创建、更新、删除三类操作说明如何设计 input 与 payload,让参数边界、业务错误和后续字段扩展都保持清晰。

学习目标

  • 能为创建、更新和删除操作设计专用 input,避免参数散落在 Mutation 字段上。
  • 能用 payload 同时承载业务对象与可处理的业务错误。
  • 能识别更新输入中“字段未提供”和“显式传入 null”的语义差异。

用 input 固化写入边界

写入操作通常把参数收拢为一个非空 input 参数,而不是给 Mutation 字段不断追加顶层参数。这样客户端变量结构稳定,服务端也能按业务动作定义不同输入类型。

创建输入只放客户端有权提供的字段。数据库主键、创建时间、审计字段等由服务端生成,不应要求客户端提交。更新和删除则应使用独立输入类型,不要为了“复用”把所有动作塞进一个巨型输入对象。

下面的 SDL 展示一组可扩展的写入契约。它是片段示例,需要放入现有 GraphQL Schema,并由对应 Resolver 实现。

graphql
type Mutation {
  createProject(input: CreateProjectInput!): ProjectPayload!
  updateProject(input: UpdateProjectInput!): ProjectPayload!
  deleteProject(input: DeleteProjectInput!): DeleteProjectPayload!
}

input CreateProjectInput {
  name: String!
  ownerId: ID!
}

input UpdateProjectInput {
  id: ID!
  name: String
}

input DeleteProjectInput {
  id: ID!
}

type Project {
  id: ID!
  name: String!
  ownerId: ID!
}

type UserError {
  code: String!
  field: String
  message: String!
}

type ProjectPayload {
  project: Project
  userErrors: [UserError!]!
}

type DeleteProjectPayload {
  deletedId: ID
  userErrors: [UserError!]!
}

这组设计的生效行为是:三个 Mutation 字段都只有一个 input 参数;成功时 payload 返回业务结果;可预期的校验失败或业务冲突放进 userErrors,客户端不必从自然语言异常中猜原因。

用 payload 给返回值留出扩展空间

直接返回 Project! 看似简单,但一旦需要增加业务错误、审计信息或异步任务状态,就会迫使客户端与服务端同时调整返回结构。使用 payload 可以从一开始就保留稳定的扩展位置。

对于“名称重复”“对象已被删除”“当前状态不允许更新”等领域错误,建议返回稳定的 code,并把 field 作为可选定位信息。解析失败、Resolver 抛出的未处理异常等执行层问题仍可能出现在 GraphQL 顶层 errors 中,不要把所有故障都强行包装成业务错误。

下面发送一次创建请求。示例假定服务已在 http://localhost:<PORT>/graphql 暴露上述 Schema,实际端口和返回 ID 可能不同。

bash
curl -s http://localhost:<PORT>/graphql \
  -H 'content-type: application/json' \
  --data-binary '{"query":"mutation CreateProject($input: CreateProjectInput!) { createProject(input: $input) { project { id name ownerId } userErrors { code field message } } }","variables":{"input":{"name":"Docs","ownerId":"u-1"}}}'

预期输出

json
{"data":{"createProject":{"project":{"id":"<ID>","name":"Docs","ownerId":"u-1"},"userErrors":[]}}}

处理更新时的缺省与 null

GraphQL 输入对象会区分“字段没有出现”和“字段显式传入 null”。例如 name: String 允许客户端省略 name,也允许传入 null;这两个值是否代表“保持原值”和“清空字段”,必须由业务契约明确规定。

如果某字段在业务上不允许清空,Resolver 应拒绝显式 null,或改用更明确的输入结构。不要在映射到数据库更新语句时无条件把缺失字段转换为 null,否则一次局部更新可能误清空原数据。

让三类 Mutation 各自表达结果

创建操作通常返回新对象;更新操作返回更新后的对象,便于客户端直接刷新缓存;删除操作可以返回 deletedId,避免客户端只能依赖布尔值判断成功。

不要为了统一外形而让所有 Mutation 返回完全相同的字段。真正值得统一的是 payload 的基本约定,例如业务对象字段加 userErrors。输入和返回值都围绕具体业务动作命名,后续增加字段时就能保持向后兼容,而不必频繁破坏已有客户端。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计 Mutation 输入与返回值

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

登录哪都通