Mutation

Mutation 负责写操作：创建、更新、删除。与 Query 不同，Mutation 通常 串行执行（同一请求内按顺序），并常返回 payload（新对象 + 错误信息）。

学习目标

• 定义 Mutation 与 Input 类型
• 理解返回 payload 的设计模式
• 对照 REST 动词的映射关系

核心内容

Schema 定义

input CreateTrackInput {
  slug: String!
  title: String!
  level: String
}

type CreateTrackPayload {
  track: Track
  errors: [String!]
}

type Mutation {
  createTrack(input: CreateTrackInput!): CreateTrackPayload!
  updateTrack(slug: String!, title: String): Track
  deleteTrack(slug: String!): Boolean!
}

Input 类型不可有字段 Resolver 嵌套查询；复杂校验在服务端完成（类似 spring-boot-essentials 的 @Valid）。

客户端调用

mutation CreateTrack($input: CreateTrackInput!) {
  createTrack(input: $input) {
    track { slug title }
    errors
  }
}

{
  "variables": {
    "input": { "slug": "lab-gql", "title": "GraphQL 实验", "level": "intermediate" }
  }
}

与 REST 对照

操作	REST（本站 TrackController）	GraphQL
创建	POST /tracks + body	mutation createTrack
更新	PUT /tracks/{id}	mutation updateTrack
删除	DELETE /tracks/{id}	mutation deleteTrack

CodeRoadMap 管理端与主 API 走 REST；Mutation 课用于理解 GitHub、Shopify 等 GraphQL-first 平台。不要在未授权实验环境外对生产 /tracks 写接口做破坏性测试。

乐观 UI 提示

react-essentials 表单提交后可乐观更新列表；Apollo update 函数写缓存。REST 则 invalidate SWR/React Query 缓存——模式不同，UX 目标相同。

练习

• 为 createLesson 设计 Input 与 Payload 类型
• 写 Mutation：更新 track 的 title，返回完整