learnapollo iOS Track(5/6):用 GraphQL Mutation 添加新 Pokemon,并通过 Apollo 缓存实现 UI 自动刷新

原创2026-10-12 09:28:131,689 阅读
文章标签:教程前端

learnapollo iOS Track(5/6):用 GraphQL Mutation 添加新 Pokemon,并通过 Apollo 缓存实现 UI 自动刷新

本篇是 learnapollo 教程 iOS 轨道第 5 练的完整实现指南:在 exercise-05 中通过定义 CreatePokemon mutation 向 Pokedex 写入新数据,并把 ApolloClient 的一次性 fetch 升级为 watch,配合 GraphQLQueryWatcher 与客户端缓存(ApolloStore),让表格在 mutation 成功后无需手动 reloadData() 即自动刷新。读完后你将掌握 GraphQL mutation 的完整定义-生成-执行链路,以及 Apollo iOS 客户端「归一化存储 + 查询观察」的自动 UI 更新机制。

目标状态:Pokedex 表格在原有 Mewtwo、Pikachu、Bulbasaur 之后显示了通过 mutation 新增的 Mewthree

练习目标与项目现状

本练习的 goal 是向 Pokedex 中添加新的 Pokemon,核心知识点是 GraphQL 的 mutation。

打开第 5 练目录(exercise-05),用 Xcode 打开 pokedex-apollo.xcworkspace。该工作区已包含前几课代码的可运行版本,并预置了一个新的视图控制器 CreatePokemonViewController,用于录入新 Pokemon 的数据。从 PokedexTableViewController segue 到 CreatePokemonViewController 时会把 trainer 的 ID 传过去,这样在提交 mutation 时可以把新 Pokemon 关联到对应的 trainer。

在写 mutation 之前,先回顾一下本教程始终使用的 GraphQL schema(完整定义见 ios-02.md):

type Trainer {
  id: String!
  name: String
  ownedPokemons: [Pokemon]
}

type Pokemon {
  id: String!
  url: String!
  name: String!
  trainer: Trainer
}

createPokemon 的写入目标就是 Pokemon 类型:name 与 url 是必填字段,trainerId 用于建立 Pokemon -> Trainer 的关联。后面定义 mutation 变量时,这个 schema 就是取值类型的依据。

GraphQL Mutation:从 query 到 mutation

mutation 与 query 的区别

此前的练习只涉及 query——从 API 拉取数据的操作。但大多数应用还需要修改后端数据:更新已有条目或创建全新条目。在 GraphQL 中,这件事由 mutation 完成。

mutation 与 query 的写法非常相似,唯一的区别是:在 .graphql 文件中定义时使用 mutation 关键字替代 query。Apollo iOS 客户端随后会像处理 query 一样,为每个 mutation 生成一个对应的 Swift 类。

定义 CreatePokemon mutation

下面是添加新 Pokemon 的 mutation(先不要急着复制,CreatePokemonViewController.graphql 稍后才会创建):

mutation CreatePokemon($name: String, $url: String!, $trainerId: ID) {
  createPokemon(name: $name, url: $url, trainerId: $trainerId) {
    id
    name
    url
  }
}

说明:与 query 一样,这段 mutation 可以直接粘贴到 GraphiQL playground 中执行测试。注意在 GraphiQL 左下角的 Query Variables 区域为 $name、$url 以及(如需要)$trainerId 添加变量值。

上面这段 mutation 会用给定数据创建一个新 Pokemon。关于 mutation 有一个重要特性:它和 query 一样,可以指定希望服务器返回的数据。也就是说,我们不仅在修改后端数据,还能同时要求服务器在执行完 mutation 后回传指定字段。用 REST 的术语类比,这相当于一次 POST 加一次 GET 的组合。

这里我们要求返回新建 Pokemon 的 id、name 和 url。这样做的好处是:可以直接用 mutation 的响应来更新 UI——这一点本练习后半部分会具体展开。

让 apollo-codegen 生成 CreatePokemonMutation

要在 App 中使用这段 mutation,新建一个空文件 CreatePokemonViewController.graphql,把上面的 mutation 复制进去,然后按 CMD + B 构建项目,再查看 API.swift 的内容。

可以看到 apollo-codegen 又生成了一个名为 CreatePokemonMutation 的新类。它的结构与 query 类似:内部有一个嵌套的 struct CreatePokemon,包含 id、name、url 三个属性,表示新建的 Pokemon。每个 mutation 都会生成一个类,mutation 变量则映射为该类的初始化参数(可选变量默认为 nil,这与 ios-03.md 中 query 变量的处理方式一致)。

在 Swift 代码中使用 CreatePokemonMutation

打开 CreatePokemonViewController.swift,把下面的代码片段复制到 addPokemon() 方法的 guard 语句之后:

let createPokemonMutation = CreatePokemonMutation(name: name, url: imageURL, trainerId: trainerId)
activityIndicator.startAnimating()
apollo.perform(mutation: createPokemonMutation) { (result: GraphQLResult?, error: Error?) in
    self.activityIndicator.stopAnimating()
    if let error = error {
        print(#function, "ERROR | An error occured while adding the new Pokemon: \(error)")
        return
    }
    guard let newPokemon = result?.data?.createPokemon else {
        print(#function, "ERROR | Could not get the new Pokemon")
        return
    }
    print("Created new pokemon: \(newPokemon)")
    self.presentingViewController?.dismiss(animated: true)
}

逐步拆解这段代码:

  1. 实例化由 apollo-codegen 生成的 CreatePokemonMutation,传入从文本框取到的 name、imageURL 以及 segue 传来的 trainerId 作为变量;
  2. 调用 activityIndicator.startAnimating() 显示加载状态;
  3. 通过 ApolloClient 实例调用 perform(mutation:)——注意这里执行的是 mutation,而不是基于 query 的 fetch;
  4. 依旧使用 Swift 尾随闭包(trailing closure)传入回调,在闭包中处理请求结果:出错则打印日志;成功则从 result?.data?.createPokemon 取出新 Pokemon 并打印,最后 dismiss 当前弹层。

运行验证:创建 Mewthree

运行 App,创建一个名为 Mewthree 的新 Pokemon,图片 URL 使用 Mewtwo 的地址:http://cdn.bulbagarden.net/upload/thumb/7/78/150Mewtwo.png/250px-150Mewtwo.png。

控制台应输出类似内容:

Created new pokemon: CreatePokemon(__typename: "Pokemon", id: "cixm4hazlitwt01693wg9mey5", name: Optional("Mewthree"), url: Optional("http://cdn.bulbagarden.net/upload/thumb/7/78/150Mewtwo.png/250px-150Mewtwo.png"))

说明新 Pokemon 已成功写入数据库,可以在 GraphiQL 中查询验证。但此时表格视图里还看不到这只新 Pokemon! 这正是下一节要解决的问题。

Apollo 的缓存能力与 GraphQLQueryWatcher

除了为 query 和 mutation 生成强类型 Swift 代码,Apollo 的第二大核心能力是 caching(数据缓存)。它能让我们在不做任何额外操作的情况下保持 UI 与数据同步:mutation 之后既不用手动更新视图属性,也不用调用 tableView.reloadData()。

核心组件:GraphQLQueryWatcher

实现自动 UI 更新最关键的是 GraphQLQueryWatcher。每个 watcher 实例只绑定一个 query。实际要做的改动很小:把 ApolloClient 上发起 query 的方式从 fetch 换成 watch,watch 的返回值就是这个 GraphQLQueryWatcher 实例。

此后该实例会持续观察客户端缓存中发生的变化:只要与 watcher 绑定的 query 相关的数据发生变化,它就会再次调用最初传入的 result handler。

把 fetch 换成 watch

目前 App 只发出一条 query。首先在 PokedexTableViewController 中添加一个属性(可以放在类的顶部、var trainerId: GraphQLId? 之前):

var trainerQueryWatcher: GraphQLQueryWatcher<TrainerQuery>?

然后更新 fetchTrainer() 方法:

        let trainerQuery = TrainerQuery(name: "__NAME__")
        trainerQueryWatcher = apollo.watch(query: trainerQuery) { (result: GraphQLResult?, error: Error?) in
            if let error = error {
                print(#function, "ERROR | An error occured: \(error)")
                return
            }
            guard let trainer = result?.data?.trainer else {
                print(#function, "ERROR | Could not retrieve trainer")
                return
            }
            self.setTrainerData(trainer: trainer)
        }

对比之前的实现,唯一的变化就是第二行:改用 watch 方法并把返回值存入新属性。

最后要做的是清理:当 PokedexTableViewController 被释放时,需要取消 watcher 的观察。在视图控制器中实现 deinit(在对象释放前调用):

    deinit {
        trainerQueryWatcher?.cancel()
    }

注意:此时运行 App,你会发现承诺的自动 UI 更新仍然不生效!还需要两处小改动。

完成自动 UI 更新的两块拼图

第一处:在 ApolloClient 上实现 cacheKeyForObject

在 AppDelegate 的 application(_:, didFinishLaunchingWithOptions:) 中、实例化 ApolloClient 之后,添加 cacheKeyForObject 的实现:

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        apollo.cacheKeyForObject = { $0["id"] }
        return true
    }

关于这里涉及到的缓存机制,原文档给出的说明是:ApolloClient 把从服务器收到的数据存储在 ApolloStore 实例中,但它不会按收到的原始形状(也就是所发 query 的形状)保存,而是把数据 normalize(归一化/flatten 扁平化)为一组更简单的对象,并为每个对象关联一个唯一 key,以便后续引用(例如被另一个 query 更新时)。cacheKeyForObject 就是定义这个唯一 key 如何生成的函数。上面 { $0["id"] } 的写法表示:用响应对象里的 id 字段作为缓存 key——这也要求 query/mutation 始终请求 id。

第二处:mutation 显式请求关联数据

修改 CreatePokemonViewController.graphql 中的 CreatePokemon mutation。不能只让 PokemonDetails 返回,还要显式请求 trainer 及其 ownedPokemons——只有这样,trainerQueryWatcher 才能察觉到它所观察的数据(即 ownedPokemons)发生了变化:

mutation CreatePokemon($name: String!, $url: String!, $trainerId: ID) {
  createPokemon(name: $name, url: $url, trainerId: $trainerId) {
    ...PokemonDetails
    trainer {
      id
      ownedPokemons {
        id
      }
    }
  }
}

这里的 ...PokemonDetails 复用的是 ios-04.md 中定义的 fragment,保证表格展示所需字段(id/name/url)不重复书写。

自动更新为什么会生效

构建并运行项目,再通过 CreatePokemonViewController 添加一只新 Pokemon,这次表格视图会立即更新,新条目直接出现。

其原理可以概括为三点:

  1. Apollo 最初把 trainer 及其关联的 ownedPokemons 存入 ApolloStore,存储采用扁平化结构:trainer 对象只是引用 ownedPokemons 条目,而不是把列表嵌套存储在其内部;
  2. trainerQueryWatcher 一直在观察这份数据,任何变化都会触发当初调用 watch 时传入的闭包(即 fetchTrainer() 中设置的那个 handler,它会经 setTrainerData(trainer:) 走 ownedPokemons 的 didSet 触发 tableView.reloadData());
  3. 由于 ApolloStore 中的数据独立于发出原始数据的 query 而存在,这次变更来自哪个操作并不重要——mutation 回传的 trainer { ownedPokemons { id } } 恰好命中缓存中被 watch 的条目,从而触发 UI 更新。

这也解释了上一节的关键约束:如果 mutation 不请求 trainer/ownedPokemons 这部分数据,缓存中就没有对应条目被写入/更新,watcher 也就不会感知到变化。ios-06.md 中的 UpdatePokemon、DeletePokemon mutation 同样显式请求这部分关联数据,遵循的是同一模式。

Recap

本练习为 App 增加了「添加新 Pokemon」能力,并利用了 Apollo iOS 客户端的缓存与自动 UI 更新。知识点回顾:

  • Mutation 用于在 GraphQL 中更新后端数据;
  • 语法上与 query 类似,只是关键字用 mutation 而非 query;
  • apollo-codegen 会为每个 mutation 生成一个类;
  • ApolloClient 的 perform() 方法用于真正执行 mutation;
  • query 可以通过 GraphQLQueryWatcher 被观察,从而实现自动 UI 更新。

延伸:同一功能在 React 轨道的实现对照

learnapollo 仓库同时维护了 React、React Native、iOS 等多条教程轨道。作为旁证,仓库中 React 轨道的 AddPokemonMutation.ts 同样实现了「添加 Pokemon」,但走的是 Relay 的 Mutation 模式:它在 getConfigs() 中显式声明了一条 RANGE_ADD 配置(第 36-46 行),指定向 viewer.allPokemons 连接追加新 edge,并额外提供了 getOptimisticResponse() 做乐观更新。这从侧面印证了本文的结论:客户端要在 mutation 后自动刷新列表,关键在于 mutation 回传的数据能否命中被观察/被连接的缓存条目——iOS 轨道靠 watch + 归一化 ApolloStore 自动完成,Relay 则要求通过 config 显式声明。

适用前提说明:本文内容以当前仓库文档为准,对应的是 Apollo iOS 客户端配合 apollo-codegen(Build Phase 在每次构建前生成 API.swift)的早期工作流,服务端为 Graph.cool 托管的 pokedex-apollo 项目(需先在教程第 1 练中创建项目并替换 __NAME__/__PROJECT_ID__ 等占位符)。

登录后查看全文
learnapollo