learnapollo iOS Track(5/6):用 GraphQL Mutation 添加新 Pokemon,并通过 Apollo 缓存实现 UI 自动刷新
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 更新机制。
练习目标与项目现状
本练习的 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)
}
逐步拆解这段代码:
- 实例化由
apollo-codegen生成的CreatePokemonMutation,传入从文本框取到的name、imageURL以及 segue 传来的trainerId作为变量; - 调用
activityIndicator.startAnimating()显示加载状态; - 通过
ApolloClient实例调用perform(mutation:)——注意这里执行的是 mutation,而不是基于 query 的fetch; - 依旧使用 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,这次表格视图会立即更新,新条目直接出现。
其原理可以概括为三点:
- Apollo 最初把
trainer及其关联的ownedPokemons存入ApolloStore,存储采用扁平化结构:trainer对象只是引用ownedPokemons条目,而不是把列表嵌套存储在其内部; trainerQueryWatcher一直在观察这份数据,任何变化都会触发当初调用watch时传入的闭包(即fetchTrainer()中设置的那个 handler,它会经setTrainerData(trainer:)走ownedPokemons的didSet触发tableView.reloadData());- 由于
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__等占位符)。
