CarrieYung刚切换 Diffable Data Source 那天，我把手头一个老项目的列表页从头到尾翻了一遍，第一反应是：之前写的那堆 reloadData、indexPath.row、还有藏在 numberOfRows 里的各种 if 分判，到底是怎么扛过这么多版本的。并不是传统写法完全不能跑，而是每次来个新功能、调个删改排序，我就得像排雷一样检查 cell 复用、动画状态和数组索引，动不动就白屏、闪屏、崩溃三连。后来团队里有人提议试试 UITableViewDiffableDataSource，一开始我挺抗拒，觉得不就是多了个快照嘛，能有多大差别。真正改完一个复杂列表之后，我记得很清楚，那天下午我把原来的 dataSource 实现整个删掉了，心里只有一个词：清爽。
如果你现在还在用传统的 UITableViewDataSource 写列表，尤其是那种数据模型复杂、增删排序频繁的页面，我强烈建议你花点时间把这套东西学明白。这篇文章我打算从“为什么必须换”讲起，然后深入 diffable 的快照机制，最后用真实的重构过程带你走一遍从传统写法到现代写法的完整迁移，顺便把那些文档里不写的坑都给你踩一遍。
1. 为什么要换掉传统的 UITableViewDataSource
1.1 传统列表写法里那些每天都在踩的坑
先别急着上代码，我们回想一下用传统 UITableViewDataSource 维护列表时最让人头疼的几个场景。
第一，dataSource 回调强制要 indexPath。你的数据是一维数组还好，一旦列表变成分区列表、多 section 混合内容，numberOfSections、numberOfRowsInSection、cellForRowAt、didSelectRowAt 四个回调里同时维护一个二维数据结构，每次增删都要手动计算正确的 section、row，写错一个就等着“Index out of range”吧。我见过一个老项目，Add 一条记录要在 array.insert 后手动 tableView.insertRows(at:)，结果因为数组和 UI 不是同步更新，偶发崩溃，线上反馈了好几次才定位到漏了处理空 section 的场景。
第二，reloadData 是最省事但也是最粗暴的方案。很多时候我们根本不想处理精确的增删改，于是直接 self.tableView.reloadData()。问题是 reloadData 会重建所有可见 cell，不仅打断用户当前滚动，还会导致图片闪烁、输入框失焦、展开状态丢失。如果页面里还有轮播图、视频播放器这类重量级组件，每次刷新卡顿感非常明显。而且 reloadData 完全没有动画，用户看到列表“跳”一下，体验很廉价。
第三，手动 diff 非常难写且容易出 bug。为了优化交互体验，一些同学会尝试自己写 diff 逻辑，也就是比对新旧两组数据，找出新增、删除、更新、移动的项，再去调 performBatchUpdates / beginUpdates。理论上可行，但现实是做出来一个勉强能用的 diff 工具就要花不少精力，还要处理“同一个 item 同时被删除又插入”“两个相同 item 移动到不同位置”这种边界情况。稍有不慎 batch update 就会抛异常：“Invalid update: invalid number of rows in section”。说实话，这不是算法能力的问题，而是这个方案本身的容错率太低了。
1.2 Diffable 的诞生背景与定位
UITableViewDiffableDataSource 是 iOS 13 推出的，同期还有 UICollectionViewDiffableDataSource。它的定位不是单纯帮你少写几行代码，而是从架构层面改变了列表数据的刷新方式。
传统模式是“你告诉我 UI 该怎么变”，你得手动计算哪个 cell 该插入、该删除、该更新，UI 是数据模型的下游，而且中间隔着大量样板代码。Diffable 模式是“你告诉我数据现在长什么样”，框架自己比较新旧数据的差异，然后自动处理 UI 更新。
你没看错，苹果把 diff 的能力直接做进了系统框架。这意味着你不需要再维护老一套的批量刷新逻辑，也不需要祈祷每个 indexPath 都对得上，框架在底层会安全地帮你完成精确的动画更新。这个转变对列表开发的工程意义，不亚于 Auto Layout 之于手写 frame。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Diffable Data Source 的核心原理与设计逻辑
2.1 快照（Snapshot）：唯一数据源
要理解 UITableViewDiffableDataSource，你只需要抓住一个核心概念：Snapshot。
你可以把它理解为当前列表状态的“一张完整照片”，也就是某一个时刻，所有 section 和 item 的数据结构到底是什么样。你每次想更新列表，不需要去改动 tableView，而是先构建一个新的 snapshot，然后把新 snapshot apply 给 dataSource，剩下的差异计算、动画更新统统交给框架。
swift复制var snapshot = NSDiffableDataSourceSnapshot<Section, Item>()
snapshot.appendSections([.main])
snapshot.appendItems(items)
dataSource.apply(snapshot, animatingDifferences: true)
这段代码几乎是 diffable 使用的“最小骨架”。但推敲一下，它背后的设计思路很值得琢磨：
- Section 和 Item 都必须实现
Hashable，原因在于 diff 的过程依赖哈希值来判断“两个 item 是否相等”。 - Snapshot 是值类型，对它的任何修改都是独立的，不用担心外部数组被隐式改动。
- Apply 之后，框架拿旧 snapshot 和新 snapshot 做对比，再生成一批精确的 UI 操作。
2.2 Hashable 驱动的差异计算
Diffable 之所以能实现精细动画，核心依赖 Hashable。你声明的 Item 类型，必须能稳定地哈希自身，框架才能判断“这个 item 是新加的”“那个 item 被删了”“这两个 item 只是内容变了位置没变”。
这里我踩过一个非常典型的坑：一开始图省事，直接拿类对象当 Item 用。类对象的哈希值默认跟内存地址相关，同一份数据如果重新从服务器 fetch了一遍，即便内容一模一样，在框架眼里也是两个不同的 item。结果每次下拉刷新，列表都认为旧 item 全被删了、新 item 全插进来了，动画就是从“空列表”过渡到“全新列表”，完全没有 diff 的效果，还会出现 cell 闪烁。
正确的做法是让 Item 使用结构体，并尽量基于一个稳定不变的标识符（比如 ID）来参与哈希运算，而不是把整个对象的所有字段都拿来做哈希。
swift复制struct ProductItem: Hashable {
let id: Int
let name: String
let price: Double
let imageURL: URL?
// 只以 id 判断“是不是同一个产品”
// name/price/imageURL 变化时，framework 会认为是同一个 item 的数据发生了更新
}
注意这里的微妙之处：Hashable 的 hash 结果决定“是不是同一个 item”，而 framework 一旦确认是同一个 item 之后，只要其他属性（比如 name 变了），它就会更新 cell。所以你要想清楚：哪些字段是稳定标识，哪些字段是可变数据。这跟数据库主键的设计思路完全一致。
2.3 为什么这个设计比手动 reloadData 更正确
我觉得 diffable 最厉害的一点，是把“UI 更新策略”从“数据变更之后手动同步”提升到了“每次提供完整数据快照，系统自动 diff”的维度。这背后的心智转变其实是很深的：
- 你再也不用关心 indexPath 计算，因为数据源只认标识符，不认位置。
- 你再也不用关心批量更新的顺序问题，系统会保证 apply 完整性。
- 你再也不用考虑“数据模型和 UI 不同步”导致的越界崩溃，因为它每次拿到的都是一份完整一致的快照。
举个类比，传统方式就像一个厨师在厨房里盯着每道菜，哪个顾客加了菜，他就自己去灶台上“增删菜”，一旦忘记哪个桌号对应哪个菜就乱套了。Diffable 的方式则是每