说个真实经历前几年我做电商 App 的订单列表数据一刷新就掉帧偶尔还因为 indexPath 错位闪退光是处理“删除某一行后接下来的 cell 全部乱掉”这种 bug 就花了好几个版本。直到 iOS 13 苹果推出了 UITableViewDiffableDataSource这类问题才算有了官方解法。它不是简单替换 UITableViewDataSource 里的几个方法而是一套真正以数据为驱动的列表刷新思路你负责把列表状态描述清楚系统负责对比新旧状态、自动计算要插入、删除、移动哪些行连动画都帮你生成好了。这篇文章我会从 Diffable 的底层机制讲起手把手写一个完整列表再讲怎么把老项目里那些“祖传 dataSource”重构过来最后把我实际项目里踩过的坑和排查技巧全部整理出来。适合正准备切入现代 UI 开发、或者面试想聊清楚“UITableViewDiffableDataSource 到底是什么、跟 reloadData 的区别在哪”的 iOS 开发者。1. 为什么说传统 UITableView 数据源让人又爱又恨1.1 三件套的痛每个 iOS 开发都懂用 UIKit 写过列表的人基本都绕不开这三个方法numberOfRowsInSection、cellForRowAt、didSelectRowAt。前两个是 UITableViewDataSource 的标配第三个是 UITableViewDelegate 的标配。这套“三件套”用了十几年能解决的问题很多但代价是你要自己维护一套“数组和界面同步”的心智模型。举个最常见的例子页面上有一个数组var items: [Item]当前 UI 显示的是数组的第 0、1、2 行。这时候用户左滑删除了第 1 行你需要先更新数组再手动调用deleteRows(at:with:)而且传入的 IndexPath 必须和数组更新后的位置一一对应。听起来不复杂可一旦页面支持多分区、折叠、拖拽排序、增量加载这个“手动同步”就变成了灾难现场。我见过好几个项目里删除一个 cell 后相邻 cell 状态错乱、展开收起时 section 数量对不上、下拉刷新后动画卡成狗都是因为这个模式下数据源和 UI 永远是两份需要手工保持一致的东西。更麻烦的是传统数据源模式下任何对数组的增删改都会直接暴露到 controller 里。业务代码和 UI 刷新逻辑耦合在一起单元测试也没法做——你总不能在测试里真的去创建 UITableView 吧所以很多老项目到最后列表页的代码越来越长动一个地方就崩三个地方根本不敢重构。1.2 reloadData 的代价被严重低估有同学会说“我不手动算 IndexPath每次都调用 reloadData 不就行了”确实reloadData 是省事但它是一套“核武器”会把整个表格全部重绘代价比大多数人想象得要大丢失动画。即使数据只改了一行整张表的 cell 都会重新创建视觉上就是“闪一下”没有局部刷新的丝滑感。滚动位置重置。如果用户在列表中间一下拉刷新就回到顶部体验非常糟糕。无谓的 cell 重建。所有可见 cell 都会重新走一遍cellForRowAt哪怕它的数据根本没变。键盘和焦点问题。在搜索页里输入关键字过滤列表时用 reloadData键盘经常跳动甚至被 dismiss。类似这种问题老手一般会手动用beginUpdates/endUpdates包一层局部刷新然后手动计算 insert/delete/move 的 IndexPath 集合。这条路不是不能走但非常容易出错尤其是复杂业务下你很难保证计算出来的 IndexPath 一定是对的。Diffable DataSource 就是苹果为了解决这堆问题给出的官方答案。1.3 苹果为什么重新发明数据源iOS 13 发布时苹果一口气给 UITableView 和 UICollectionView 都引入了 Diffable DataSource。它的核心思想是开发者不再告诉系统“第几行需要刷新”而是告诉系统“现在的完整数据长什么样”。系统通过对比新旧数据之间的差异自己生成操作项自己决定动画自己处理 IndexPath 的变化。这套设计思路其实来自 Apple 内部的 SwiftUI 团队所以你会发现 Diffable 的处理逻辑和 SwiftUI 的State驱动 update 非常像数据变了UI 跟着变中间过程交给框架。对开发者来说心智负担一下子小了很多。2. 理解 Diffable Data Source 的核心Snapshot2.1 Snapshot 是列表的一次“完整快照”Diffable DataSource 不像传统 dataSource 那样直接面对 cell而是面向一个叫NSDiffableDataSourceSnapshot的东西。你可以把它理解为某一时刻列表数据的完整状态。比如一个订单列表当前有 3 个分区“待付款”“待发货”“已完成”。每个分区下面有若干订单。那么一个 snapshot 就是Section 数组[待付款, 待发货, 已完成]每个 section 对应的 item ID 数组[order_001, order_002], [order_003], [order_004, order_005]发起刷新时你不需要做任何增删计算只需要构建一个“理想状态”的 snapshot然后调用dataSource.apply(snapshot, animatingDifferences: true)系统会自动和当前的快照做对比差异化之后再执行增删移动和对应动画。2.2 为什么模型必须遵循 HashableDiffable 对比新旧数据时靠的是 item 的哈希值来判断“这是不是同一个元素”。所以SectionIdentifierType和ItemIdentifierType都必须遵循Hashable协议。在 Swift 里一个结构体如果所有属性都遵循 Hashable可以直接声明struct Item: Hashable自动获得实现。它内部的 hash 值就是区分 item 的唯一凭据。这里我一开始踩过坑如果两个 item 的属性完全一样系统会认为它们是同一个 item刷新时会直接把两个都当成同一个轻则动画异常重则触发断言崩溃。所以真实项目里model 里一定要带上唯一 ID比如服务端返回的 id、订单号、URL 等别偷懒。注意Diffable 对 item 的唯一性要求比传统 dataSource 严格得多。传统写法里重复数据顶多显示两行一样的 cellDiffable 里直接会崩。排查接口返回数据时第一个想到的就是“ID 是否重复”。2.3 apply 时系统做了什么当你调用apply后Diffable 底层会做一次 diff 计算把当前 snapshot 和目标 snapshot 之间的差异拆成插入、删除、移动、更新四类操作并交给 UITableView 去执行。整个过程是带事务性的要么全部成功要么界面不变。这里有一个关键点apply并不会“毫秒级”完成。如果列表很复杂diff 计算会占用一些时间。所以苹果要求apply最好在主线程调用避免 UI 更新和计算之间出现竞争。你可以在后台线程先构建好 snapshot比如解析网络 JSON 后组装 model然后在主线程上调用 apply这是官方推荐的做法。3. 从零接入UITableViewDiffableDataSource 基础实战3.1 准备模型与 Section先用一个最小例子走通流程。假设我们要做一个待办事项列表每条待办有标题和完成状态。定义如下enum TodoSection: Int, Hashable, CaseIterable { case unfinished case finished } struct TodoItem: Hashable { let id: UUID var title: String var isDone: Bool }TodoItem里有一个id: UUID这是 Diffable 唯一标识的关键。就算 title 一样的两条待办只要 id 不同也互不干扰。3.2 创建 DataSource在 UITableViewController 的 viewDidLoad 里创建数据源private var dataSource: UITableViewDiffableDataSourceTodoSection, TodoItem! private var tableView: UITableView! override func viewDidLoad() { super.viewDidLoad() tableView UITableView(frame: view.bounds, style: .insetGrouped) tableView.register(UITableViewCell.self, forCellReuseIdentifier: cell) view.addSubview(tableView) dataSource UITableViewDiffableDataSourceTodoSection, TodoItem( tableView: tableView, cellProvider: { tableView, indexPath, item in let cell tableView.dequeueReusableCell(withIdentifier: cell, for: indexPath) cell.textLabel?.text item.title cell.accessoryType item.isDone ? .checkmark : .none return cell } ) tableView.dataSource dataSource }注意dataSource必须强持有。它不像老的 dataSource 那样可以直接用一个 VC 类型去遵守协议而是作为一个对象赋给tableView.dataSource。一旦局部变量被释放列表就崩了。3.3 应用初始快照并渲染数据准备好后把 items 填进对应的 section构建 snapshotfunc applyInitialData() { let unfinishedItems [ TodoItem(id: UUID(), title: 写周报, isDone: false), TodoItem(id: UUID(), title: 买咖啡豆, isDone: false) ] let finishedItems [ TodoItem(id: UUID(), title: 跑五公里, isDone: true) ] var snapshot NSDiffableDataSourceSnapshotTodoSection, TodoItem() snapshot.appendSections(TodoSection.allCases) snapshot.appendItems(unfinishedItems, toSection: .unfinished) snapshot.appendItems(finishedItems, toSection: .finished) dataSource.apply(snapshot, animatingDifferences: false) }到这里列表渲染基本完成。你可以看到两个分区未完成区两条已完成区一条每个 cell 的右侧完成状态也有显示。3.4 第一个小测试删除一行传统写法里删一行要手动计算 IndexPath。现在呢只需要把数组里对应的 item 从 snapshot 里删掉再 applyfunc markAsDone(item: TodoItem) { var snapshot dataSource.snapshot() // 从当前快照里移除该 item snapshot.deleteItems([item]) // 再新建一个已完成状态的新 item或直接修改属性后重新 append var doneItem item doneItem.isDone true snapshot.appendItems([doneItem], toSection: .finished) dataSource.apply(snapshot, animatingDifferences: true) }这里有一个非常重要的细节dataSource.snapshot()返回的是当前快照的副本。你需要在这个副本上修改而不是直接操作原来的 snapshot。Diffable 会用它做差集计算但不会实时同步到 UI必须等apply之后再提交。我第一次写的时候习惯性在同一个 snapshot 变量上连续改结果应用了两次旧状态差点以为是自己记错了 API。4. 多分区与动态更新现代列表开发的核心操作4.1 多 Section 管理实际业务里单 section 的列表太少见了。常见的有“首页推荐”“购物车分组”“订单状态”等至少三四个分区。多分区只需要在 snapshot 里按顺序 append section并保证 item 挂到正确的 section 上enum HomeSection: Int, Hashable, CaseIterable { case banner case category case recommend } var snapshot NSDiffableDataSourceSnapshotHomeSection, HomeItem() snapshot.appendSections(HomeSection.allCases) snapshot.appendItems(banners, toSection: .banner) snapshot.appendItems(categories, toSection: .category) snapshot.appendItems(recommendations, toSection: .recommend) dataSource.apply(snapshot, animatingDifferences: true)注意section 的顺序由 appendSections 的顺序决定。如果需要调整分区顺序不要改动 enum 的 case 顺序而是调整 appendSections 的传参顺序。这和传统 dataSource 里每个 section index 的物理含义解耦了非常舒服。另外section 支持insertSections、deleteSections、moveSection等操作。比如某个活动入口要临时从列表里隐藏直接删除对应 sectionUI 会自动收起这一整块并附带动画。4.2 局部刷新reloadItems 与 reconfigureItems 怎么选很多项目里列表数据的某个 item 会实时变化比如点赞数、进度条、开关状态。Diffable 提供了两个常用的局部刷新 APIreloadItems(_:)删除该 item 对应的 cell再重新生成一个新的 cell 并配置。reconfigureItems(_:)从 iOS 15 开始提供只会对已存在的 cell 做重新配置不会销毁重建。两者都能刷新 UI但性能差异明显。reloadItems会先删后建如果 cell 里持有图片、视频播放器等重量级对象代价就很高。reconfigureItems则是原地 update耗能更小体验也更流畅。func updateLikeCount(for item: FeedItem) { var snapshot dataSource.snapshot() guard let updatedItem findUpdatedItem(item) else { return } snapshot.reconfigureItems([updatedItem]) dataSource.apply(snapshot, animatingDifferences: true) }如果只追求 iOS 15我建议优先用reconfigureItems。需要兼容老系统的话再降级到reloadItems。这里还有个容易踩的坑reloadItems或reconfigureItems要求 item 必须是当前 snapshot 中已经存在的同一个标识。如果你把 item 换成一个新 idDiffable 会认为它是另一个元素结果变成“新增一行”而不是刷新原行。4.3 搜索过滤与异步数据加载Diffable 处理搜索过滤特别顺手因为不需要算 indexPath直接构建一个新的过滤后的 snapshotfunc search(with keyword: String, allItems: [TodoItem]) { let filtered keyword.isEmpty ? allItems : allItems.filter { $0.title.localizedCaseInsensitiveContains(keyword) } var snapshot NSDiffableDataSourceSnapshotTodoSection, TodoItem() snapshot.appendSections(TodoSection.allCases) let unfinished filtered.filter { !$0.isDone } let finished filtered.filter { $0.isDone } snapshot.appendItems(unfinished, toSection: .unfinished) snapshot.appendItems(finished, toSection: .finished) dataSource.apply(snapshot, animatingDifferences: true) }搜索时键盘一般不会抖动因为系统只更新差异行不会整表重绘。异步场景也很简单。比如网络请求返回后先在后台线程解析 Json 生成 model再回到主线程 applyDispatchQueue.global(qos: .userInitiated).async { let result try? JSONDecoder().decode(Response.self, from: data) var snapshot NSDiffableDataSourceSnapshotHomeSection, HomeItem() // 构建快照... DispatchQueue.main.async { self.dataSource.apply(snapshot, animatingDifferences: true) } }5. 迁移重构把老项目里的 dataSource 去掉5.1 迁移前的评估很多老项目里UITableViewDataSource的实现直接写在了 Controller 里动辄上千行。迁移到 Diffable 之前先做一遍“清点”当前用到几个 sectionsection 的类型是 Int 还是 String每个 cell 对应 model 是否具备唯一标识没有的话要补。有没有用heightForRowAt、viewForHeaderInSection、viewForFooterInSection这类 delegate 方法这些与 Diffable 不冲突可以保留。是否依赖willDisplay做曝光埋点Diffable 没有改变这些回调所以不影响。清点完再动手。如果 model 是 class 而不是 struct建议先换成 struct或至少加一个稳定 ID因为 class 的 hash 默认是地址不能作为唯一标识。5.2 五步迁移法实操下来我推荐按下面五步迁移每一步都能单独验证避免一次改动太大定义 section 枚举。把原来的 section 序号换成有语义的枚举比如OrderSection.pending不要继续用0、1、2。让所有 cell 对应的 model 遵循 Hashable并确认唯一 ID 字段存在。创建UITableViewDiffableDataSource把原本cellForRowAt里创建 cell 的逻辑搬进 cellProvider。删除旧numberOfRowsInSection、numberOfSections等 dataSource 方法给tableView.dataSource赋值为新的 dataSource 对象。把所有“手动刷新数据”的地方从reloadData或insertRows/deleteRows改成“先更新数据模型再构建 snapshot最后 apply”。第五步是大头。项目里可能有增删改查、上下拉刷新、点击 cell 修改状态等逻辑每个都要搬到 snapshot 操作上。我的建议是不要一次性全改先选一个最核心的列表页面做改造跑通后再推广。5.3 传统数据源与 Diffable 对比对比维度传统 UITableViewDataSourceUITableViewDiffableDataSource刷新方式reloadData / 手动 IndexPath 集合apply snapshot自动 diff数据与 UI 同步手动维护容易错位数据快照驱动天然同步动画基本靠系统默认手动控制繁琐自动匹配增删移动动画唯一标识不强制重复数据也能显示必须 HashableID 必须唯一多分区管理基于 section index顺序敏感基于枚举类型更语义化性能大规模刷新时全表重绘差量更新性能更优心智负担高尤其复杂列表低构建快照即可5.4 迁移后要注意的细节迁移完还要检查几个隐蔽点。第一个是 header/footer。Diffable 接管的是 dataSource 方法但 delegate 里的viewForHeaderInSection、titleForHeaderInSection仍然生效。我见过有人把 delegate 方法也删了结果 section header 全部消失。第二个是 cell 复用。Diffable 只负责告诉系统哪个 item 对应哪个 cell不会改变dequeueReusableCell的机制。如果 cell 重用了旧数据一定要在prepareForReuse或 cellProvider 里把属性重置干净。第三个是didSelectRowAt。Diffable 不会改变 delegate 回调所以点击事件拿到 indexPath 后依然需要在当前 snapshot 里找到对应 item。用 iOS 15 可以直接itemIdentifier(for:)func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) { guard let item dataSource.itemIdentifier(for: indexPath) else { return } // 处理点击 }这个比原来从数组里取items[indexPath.row]安全得多。因为 snapshot 可能和数组不完全一致比如你还有排序、过滤操作用 itemIdentifier 拿到的就是当前 UI 状态下的真实数据。6. 实战中的坑Diffable DataSource 与真实业务6.1 崩溃相同 ID 的问题Diffable 最经典的崩溃就是“重复 item identifier”。有些接口返回的数据里同一个 ID 会出现两次比如分页接口底层排序错了或者后端把推荐内容和固定位内容放在同一个流里没做去重。传统 dataSource 会原样显示两行Diffable 直接在 apply 时断言失败提示你 item identifier 重复。排查思路接到崩溃日志后先看崩溃堆栈多半会指向_collapseOrInsert或NSDiffableDataSourceSnapshot相关方法。这时候去复查接口数据把列表所有数据的 ID 打出来看是否有重复。实在查不到可以加一个去重逻辑extension Array where Element: Hashable { func diffableUnique() - [Element] { var seen SetElement() return filter { seen.insert($0).inserted } } }不过要注意去重是兜底手段不能掩盖后端的数据问题。最好还是反馈给服务端让接口保证返回数据的唯一性。6.2 动画不动背后的线程与快照丢失问题有时候你会发现明明调用了 apply界面却没有任何变化。排除掉数据确实没变的情况最常见的原因有两个第一个是“同一个快照被重复修改”。很多人会这么做var snapshot dataSource.snapshot() snapshot.appendItems(newItems) snapshot.appendItems(moreItems) // 这里想在新快照基础上继续加 dataSource.apply(snapshot, animatingDifferences: true)如果你在第一次 append 后调用了 apply再继续对同一个 snapshot 修改第二次 apply 时那个 snapshot 已经是“旧”的了系统比对后发现没有变化所以什么都不做。正确的做法是每次想刷新 UI都从dataSource.snapshot()获取当前快照的副本在副本上修改后再 apply。第二个是线程问题。官方要求 apply 必须在主线程调用如果你在后台线程 applyUIKit 有可能忽略动画甚至产生不可预期的 UI 状态。我的做法是封装一个applySnapshot(_:animating:)方法内部用DispatchQueue.main.async兜底。6.3 调试技巧开发者模式与抓包结合调试列表问题光靠看代码效率太低。我自己的习惯是三层配合。第一层Xcode 的视图层级调试。点击 Debug View Hierarchy能看到当前 tableView 的 cell 是否多余或缺失配合 Diffable 的场景能直观看出哪些 cell 被系统认为“相同”。第二层Debug 控制台打印 snapshot。可以写一个扩展把当前 dataSource 里的所有 section 和 item 数量打出来业务排查时会省很多时间func printSnapshot() { let current dataSource.snapshot() print(Sections: \(current.sectionIdentifiers)) for section in current.sectionIdentifiers { print(\(section): \(current.numberOfItems(inSection: section)) items) } }第三层用 Charles 抓包看接口返回。列表数据是 Diffable 的源头ID 是否重复、字段是否缺失往往一眼就能在抓包工具里看出来。特别是分页加载场景多抓几页数据对比一下很多“莫名多了一行”的问题都是接口返回重复导致的。这套组合拳基本能解决列表开发 90% 的数据类疑难杂症。开启 iOS 开发者模式也是排查问题的一个基础条件尤其是真机测试和日志导出的时候没有开发者模式很多调试工具用不了。6.4 面试高频问题速查整理了几个别人面试时最常问到也是我自己面试常被问的问题问题回答要点UITableViewDiffableDataSource 和传统 dataSource 区别数据驱动、自动 diff、自动动画、Hashable 唯一性要求Snapshot 是什么为什么要每次生成新的列表某一时刻的完整状态系统靠新旧对比计算结果apply 是同步还是异步同步计算差异UI 更新带事务性建议主线程调用Hashable 为什么必须系统靠 hash 判断 item 是否相同重复 ID 会崩溃reloadItems 和 reconfigureItems 区别reload 先删后建reconfigure 原地更新后者性能更好多分区怎么实现用 Hashable 枚举定义 sectionsnapshot 里 appendSections最后再分享一个小技巧实际项目里我一般把“构建 snapshot”的代码从 Controller 里抽出来放到 ViewModel 或专门的数据源 Builder 里。这样做的好处是 Controller 只负责调用 apply列表规则可以单独写单元测试。测试时不需要真的创建 UITableView只需要构建不同类型的 snapshot断言 section 数量、每个 section 的 item 数量以及 item 顺序是否符合预期。这比老数据源模式好测太多也是我最终敢在老项目里大刀阔斧重构的原因。如果你正在做一个列表复杂度越来越高的 App早点切到 Diffable DataSource 不亏。它不能解决所有问题但绝对能帮你的列表代码减负不少。
