API 设计 / 系统课时
设计 Mutation 输入与返回值
设计 Mutation 输入与返回值
Mutation 的难点不在于把字段放进 type Mutation,而在于让写入契约长期稳定。本节用创建、更新、删除三类操作说明如何设计 input 与 payload,让参数边界、业务错误和后续字段扩展都保持清晰。
学习目标
- 能为创建、更新和删除操作设计专用
input,避免参数散落在 Mutation 字段上。 - 能用 payload 同时承载业务对象与可处理的业务错误。
- 能识别更新输入中“字段未提供”和“显式传入 null”的语义差异。
用 input 固化写入边界
写入操作通常把参数收拢为一个非空 input 参数,而不是给 Mutation 字段不断追加顶层参数。这样客户端变量结构稳定,服务端也能按业务动作定义不同输入类型。
创建输入只放客户端有权提供的字段。数据库主键、创建时间、审计字段等由服务端生成,不应要求客户端提交。更新和删除则应使用独立输入类型,不要为了“复用”把所有动作塞进一个巨型输入对象。
下面的 SDL 展示一组可扩展的写入契约。它是片段示例,需要放入现有 GraphQL Schema,并由对应 Resolver 实现。
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 可能不同。
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"}}}'预期输出
{"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。输入和返回值都围绕具体业务动作命名,后续增加字段时就能保持向后兼容,而不必频繁破坏已有客户端。