Mutation

这一课你将能做到

1. 用 input + payload 范式为本站「提交代码」「标记课时完成」设计 Mutation
2. 在 Mutation 的返回里直接查询变更后的数据，让前端免发第二次请求
3. 说清楚 Mutation 与 Query 在执行语义上的关键差异（串行 vs 并行）

为什么要学

读操作写错，最坏是页面渲染错；写操作设计错，是脏数据、是重复提交、是用户点了三次按钮创建了三条记录。GraphQL 的 Mutation 语法上和 Query 几乎一样，但工程含义完全不同：它要有幂等设计、要有业务错误通道、要让客户端拿到「变更后的世界」。这一课学的不是语法，是写操作的纪律。

人话：Query 是「问」，Mutation 是「办」——办就要给回执，回执上写清办成了没有、办成了什么样。

先建立图像

本站「提交代码」的完整数据流：

客户端                          服务端
  │  mutation SubmitCode($input: SubmitCodeInput!)  │
  │ ──────────────────────────────────────────────> │
  │                                                 │ 校验 → 幂等检查 → 落库 → 触发判题
  │  <────────────────────────────────────────────── │
  │  payload: { submission { id status }            │
  │             progress { percent }   ← 顺带回新变化 │
  │             userErrors []          ← 业务错误通道 │
  │           }                                     │

Payload 三段式是社区事实标准：

type SubmitCodePayload {
  submission: Submission      # 1. 变更的核心对象
  progress: Progress          # 2. 受影响的关联对象（按需）
  userErrors: [UserError!]!   # 3. 业务错误（区别于 transport 层 errors）
}

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

跟着做

步骤 1：第一个 Mutation——标记课时完成

# Schema
input MarkLessonDoneInput {
  lessonId: ID!
  clientMutationId: String        # 幂等键，Relay 惯例
}

type MarkLessonDonePayload {
  progress: Progress
  userErrors: [UserError!]!
}

type Mutation {
  markLessonDone(input: MarkLessonDoneInput!): MarkLessonDonePayload!
}

调用：

mutation MarkDone($input: MarkLessonDoneInput!) {
  markLessonDone(input: $input) {
    progress { status percent }
    userErrors { message code }
  }
}

// variables
{ "input": { "lessonId": "101", "clientMutationId": "uuid-abc" } }

步骤 2：提交代码——回读变更后状态

提交记录创建后状态是 PENDING，同时我的进度条可能变化。一次 Mutation 全带回：

mutation SubmitCode($input: SubmitCodeInput!) {
  submitCode(input: $input) {
    submission {
      id
      status          # PENDING / ACCEPTED / REJECTED
      submittedAt
    }
    progress {        # 同一个 Mutation 顺带回查进度
      status
      percent
    }
    userErrors { field message }
  }
}