Firebase iOS SDK Firestore 模块全版本演进解析从 API 里程碑到 Pipeline 与性能优化【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdkFirestore 是 Firebase iOS SDK 中功能最丰富、演进最快的模块之一本文以仓库 Firestore/CHANGELOG.md 为骨架系统梳理 Cloud Firestore iOS SDK 从 0.8.0 初版到当前开发版的核心功能迭代、破坏性变更与底层工程优化并结合 Firestore/Swift 与 Firestore/Source 的源码实现进行印证。读完本文你将掌握 Firestore iOS SDK 的能力全景、关键 API 的用法与迁移路径以及这些演进背后的架构决策。版本体系概览Firestore 模块的发布历史可分为两个阶段早期版本号沿用了独立的 0.x / 1.x 序列0.8.0 至 1.19.0自 7.0.0 起与 Firebase iOS SDK 主版本号对齐7.x、8.x、9.x、10.x、11.x、12.x当前开发版Unreleased已进入 12.19.0 之后的迭代。版本号对齐意味着 Firestore 的更新节奏与整个 SDK 保持一致开发者升级 Firebase 版本时即可同步获得 Firestore 的新能力。从变更类型看CHANGELOG 中的条目统一使用[feature]、[fixed]、[changed]、[removed]、[added]五类标签其中[removed]和部分[changed]标注为Breaking change是需要开发者重点关注并执行迁移的节点。查询能力演进从基础过滤到 OR 查询与多字段不等式数组类查询操作符1.7.0 / 0.13.0查询 API 的能力扩张始于数组操作0.13.0 引入whereField(_:arrayContains:)用于匹配数组字段包含特定元素的文档1.7.0 引入whereField(_:in:)与whereField(_:arrayContainsAny:)前者匹配字段值属于给定数组的文档后者匹配数组字段与给定数组有任意交集。不等与排除类操作符1.18.01.18.0 新增whereField(_:notIn:)与whereField(_:isNotEqualTo:)。值得注意的是这两个操作符都不会匹配字段不存在的文档——这与普通字段比较的语义存在差异容易在迁移旧代码时引入隐性 bug。1.0.0 与 7.1.0 中的修复说明SDK 对查询过滤中null和NaN的校验经历了先收紧、后放宽的过程最终与 Firestore 后端保持一致所有操作符都接受null与NaN。多字段范围与不等式过滤10.24.010.24.0 解锁了在同一查询中对多个字段使用 range 与 inequality范围与不等式过滤的能力这打破了此前仅单个字段可使用范围/不等式条件的限制是复杂业务查询的关键能力。集合组查询与分页限制1.3.0 / 1.9.01.3.0 通过Firestore.collectionGroup()支持跨集合查询collection group query对应的持久化层 schema 变更在 1.1.0 即已就位1.9.0 新增limit(toLast:)返回匹配文档中的最后 N 条。OR 查询与快照同步10.7.0 / 1.6.010.7.0 为查询加入析取disjunction能力即OR查询更早的 1.6.0 则提供了addSnapshotsInSyncListener()在所有快照监听器与后端同步完成时获得统一通知便于协调多个监听结果的一致性展示。聚合能力count、sum、average 与 aggregate 聚合聚合查询是 Firestore 近年的重点投入方向10.0.0新增Query.count()只返回结果集文档数量而不下载文档本身显著节省带宽与费用10.17.0新增 sum 与 average 聚合查询至此三大基础聚合count/sum/average齐备在 Swift 源码中聚合通过AggregateFunction抽象暴露见 ExpressionImplementation.swift 中的sum()与average()实现在 Pipeline 模式下聚合通过aggregate(_:)组合多个别名聚合字段执行见 Pipeline.swift。这些聚合全部由服务端执行客户端只接收汇总结果是降低移动端耗电与传输量的有效手段。事务与写入增强事务能力迭代事务相关的能力贯穿多个版本1.4.3 / 1.5.0事务操作序列更灵活如读不存在的文档后可多次 set失败重试引入指数退避高竞争文档下的成功率显著提升1.10.0取消事务中读到的每个文档必须被写的旧限制9.2.0新增TransactionOptions可配置提交重试次数9.0.0Breaking change移除FirebaseFirestore模块中自动生成的 async/throw 事务方法使用该形态需引入FirebaseFirestoreSwift模块依赖同时修复了 update 闭包返回nil导致崩溃的问题12.8.0修复 Swift 6 下事务块返回对象无法跨越 actor 边界的问题。FieldValue 变换操作1.1.0引入FieldValue.increment()可在updateData(_:)与setData(_:merge:)中安全地对数值字段做增减无需事务0.13.0引入FieldValue.arrayUnion()与FieldValue.arrayRemove()原子地向数组字段添加/移除元素7.5.0优化了包含 FieldValue 变换的写入路径不再拆分为两次操作每个 WriteBatch 可承载 500 条写入与是否携带变换无关0.12.4 / 0.9.2允许FieldValue.delete()与setData(merge:)、mergeFields:组合使用实现字段级删除最新 12.19.0为FieldValue增加minimum(_:)与maximum(_:)操作可将字段设置为当前值与给定值中的较小者/较大者。对应 Objective-C 实现见 FIRFieldValue.h包含fieldValueForDoubleMinimum:、fieldValueForIntegerMinimum:、fieldValueForDoubleMaximum:、fieldValueForIntegerMaximum:四组工厂方法Swift 侧统一映射为FieldValue.minimum(_:)与FieldValue.maximum(_:)同时支持整数与浮点两种重载。批量写入与原子操作1.1.0 与 0.10.0 分别增强了WriteBatch无 completion 的 commit 方法与写入的原子性7.5.0 的批处理优化配合 0.13.0 对大型写入批次数百条变更的性能修复保证了批量写入场景的稳定性。本地持久化与缓存体系缓存配置与 LRU 垃圾回收本地缓存是 Firestore 离线能力的基础其演进脉络清晰0.16.0磁盘持久化引入自动垃圾回收默认缓存阈值 100 MB可通过FIRFirestoreSettings.cacheSizeBytes调整最小 1 MB设为kFIRFirestoreCacheSizeUnlimited可完全关闭10.9.0新增缓存配置 API并为内存缓存提供 LRU 垃圾回收选项10.11.0允许以无上限大小初始化FIRLocalCacheSettings11.0.0Breaking changeLRU 垃圾回收成为内存缓存的默认策略eager GC 改为显式启用通过MemoryCacheSettings(garbageCollectorSettings: MemoryEagerGCSettings())11.3.0提升内存持久化在处理大量写入时的效率。客户端自动索引9.6.0 / 10.15.09.6.0通过FIRFirestore.setIndexConfigurationFromJSON与FIRFirestore.setIndexConfigurationFromStream暴露客户端侧索引配置声明位于 FIRFirestore.h10.15.0进一步允许 SDK 自动创建缓存索引以改进本地查询执行该能力由FIRPersistentCacheIndexManager统一管理前述两个 setter 在新 API 下已被标记为 deprecated见 FIRPersistentCacheIndexManager.h。快照来源控制与离线语义10.23.0支持快照监听器仅从本地缓存读取数据的选项0.12.0重构了读取来源控制getDocument()/getDocuments()可指定仅服务器仅缓存先服务器后回退缓存三种模式其中第三种为默认行为早期版本0.13.4、0.10.4优化了离线时的get()行为只尝试一次后端、超时 10 秒判定离线并回退缓存避免离线时的长时间阻塞。Pipeline 数据处理管线10.x–12.x 重点投入Pipeline数据处理管线是 12.x 版本的功能核心从 12.8.0 起以Enterprise edition 公开预览形式可用并持续扩充表达式能力。其 Swift 实现位于 Firestore/Swift/Source/SwiftAPI/Pipeline核心类型包括Pipeline、PipelineSource、PipelineResult、RealtimePipeline与表达式目录Expressions/。数据源与 forceIndexPipeline 的数据源包括collection(_:forceIndex:)与collectionGroup(_:forceIndex:)可显式指定要使用的索引名称实现见 PipelineSource.swift。12.15.0 修复了forceIndex使用 designated initializer 的问题12.13.0 为collection/collectionGroup阶段正式加入该选项。表达式家族演进时间线CHANGELOG 记录了 Pipeline 表达式的持续扩充12.10.0regexFind、regexFindAll12.11.0first、last、arrayAgg、arrayAggDistinct、trunc、rand以及arrayFirst、arrayFirstN、arrayLast、arrayLastN、arrayMinimumN、arrayMaximumN、arrayIndexOf、arrayLastIndexOf、arrayIndexOfAll等数组表达式同版本移除了BooleanExpression的 Beta APIthen(_:else:)Breaking change统一改用ConditionalExpression12.12.0parent、timestampTruncate/timestampDiff/timestampExtract时间表达式、ltrim/rtrim/stringIndexOf/stringReplaceOne/stringReplaceAll/stringRepeat字符串表达式、nor/switchOn、ifNull/coalesce、isType、mapSet/mapKeys/mapEntries/mapValues映射表达式并引入子查询与作用域桥接Subcollection、define()、toArrayExpression()、toScalarExpression()、Variable、CurrentDocument12.13.0arraySlice、arrayFilter、arrayTransform、arrayTransformWithIndex数组管线表达式以及搜索阶段对languageCode、offset、limit、retrievalDepth的支持12.12.0同时提供了全文搜索与地理位置搜索的预览支持。表达式定义位置各表达式的 Swift 声明集中在 Expression.swift常量如CurrentDocument与变量绑定位于Expressions/目录下的Constant.swift、Variable.swift、CurrentDocument.swift、Field.swift、AliasedExpression.swift等文件中体现了表达式即数据的设计Pipeline 表达式以结构化类型描述查询意图便于服务端执行与优化。数据类型Timestamp、ServerTimestamp 与 VectorValueTimestamp 与快照时间戳行为0.11.0引入Timestamp类支持微秒精度可替代系统Date传入 API同时提供areTimestampsInSnapshotsEnabled设置避免浮点Date的精度舍入误差1.0.0将该设置默认开启Breaking change快照中的时间戳字段一律返回FIRTimestamp需要NSDate的代码须显式转换7.0.0Breaking change彻底移除该设置FIRDocumentSnapshot读出的时间戳固定为FIRTimestamp转换用FIRTimestamp.dateValue11.0.0Breaking change将Timestamp类迁入FirebaseCore模块FirebaseFirestore.Timestamp改为FirebaseCore.Timestamp服务端时间戳语义由ServerTimestampT承载11.6.0为其增加条件Sendable一致性T为Sendable时该类型亦为Sendable并在 10.7.0 修复了深层嵌套服务端时间戳导致的栈溢出。VectorValue 向量类型11.1.011.1.0 新增VectorValue类型用于语义搜索等场景的向量字段。Objective-C 声明见 FIRVectorValue.h它持有NSArrayNSNumber * *数组并标记为NS_SWIFT_SENDABLESwift 侧以VectorValue名称暴露Codable 支持位于 VectorValueCodable.swift。测试覆盖见 FIRVectorValueTests.mm。网络层与依赖工程演进gRPC 与网络监测0.15.0从 Objective-C gRPC 迁移到 gRPC C手动依赖管理用户需以gRPC-C替换gRPC、gRPC-ProtoRPC、gRPC-RxLibrary1.8.0移除ProtobufCocoaPod 依赖、新增abseil依赖1.8.1 起不再从 bundle 加载 TLS 证书10.16.0CocoaPods 的 gRPC 依赖回退到 1.44.0修复 iOS 12 设备上 10.10.0 引入的崩溃11.8.0 / 12.1.0 / UnreleasedgRPC 依次升级至 1.69、1.83.1并更新 Abseil 至 1.20250512.2Unreleased 版本同时要求C17移除 C14 支持12.16.0Apple 平台的网络连通性监测从旧版SCNetworkReachabilityAPI 迁移到现代NWPathMonitorAPI。大文档与消息限制12.17.0将 gRPC 消息大小上限提升至 17 MB从而支持16 MB 文档0.10.4定义了 10 秒连接判定阈值超时视为离线并回退缓存早期修复1.3.2、1.4.5、1.11.1、1.16.1持续优化断网、后台切换、总丢包等场景下的重连与恢复速度。Swift Concurrency 与模块拆分Swift 并发一致性Firestore 对 Swift 6 并发模型的支持分步推进11.2.0将所有只含只读属性的公开类标记为Sendable消除 Swift Concurrency Check 警告11.6.0ServerTimestampT条件Sendable一致化12.8.0修复事务返回值跨越 actor 边界的问题10.2.0修复凭据提供器中的数据竞争。FirebaseFirestoreSwift 合并与模块移除10.17.0FirebaseFirestore模块开始包含原本仅由FirebaseFirestoreSwift扩展 SDK 提供的 Swift-only API11.0.0Breaking change正式移除已废弃的FirebaseFirestoreSwift模块迁移指引见 Firebase 官方 Swift 迁移文档CHANGELOG 原文附有迁移链接本文不再重复外部地址9.0.0async/throw 事务方法迁入FirebaseFirestoreSwift是模块拆分过程中的一个过渡节点。数据模型与 CodableCodable 支持在Firestore/Swift/Source/Codable中实现包括CodablePassThroughTypes.swift含 VectorValue 的透传与VectorValueCodable.swift。DocumentID属性包装器在 10.25.0 中放宽了非 nil 赋值的警告认可文档创建后再更新 ID的合法模式。其他值得关注的能力与修复数据迁移与本地存储位置1.10.0 将本地存储从 Documents 目录迁至Library/Application Support避免在 iOS 文件 App 中暴露给用户文档明确警告迁移后降级到旧版 SDK 会导致数据丢失的假象旧版无法读取新位置数据。生命周期与网络管理1.5.0新增waitForPendingWrites()等待所有待处理写入被后端确认与terminate()终止实例并释放资源之后可调用clearPersistence()清空磁盘数据0.10.0新增disableNetwork()/enableNetwork()显式网络管理0.10.2删除 FirebaseApp 时级联删除关联 Firestore 实例1.4.0新增clearPersistence()便于编写可靠测试。多数据库与 App Check10.3.0加入 MultiDb 支持10.11.0将其作为公开预览暴露8.9.0加入 Firebase App Check 支持8.9.1 修复其响应无关通知的问题12.4.0修复了 CVE-2025-0838 相关问题内部 workaround。Bundles 数据包7.9.07.9.0 通过FIRFirestore.loadBundle、loadBundleStream与getQueryNamed支持 Firestore Bundles用服务端预打包的数据填充本地缓存无需从后端逐文档读取适合冷启动加速与离线内容投递。分发方式与构建适配10.8.0Swift Package Manager 分发从源码切换为二进制显著缩短集成与构建时间并修复 SSL 符号冲突10.23.0 起二进制分发使用带代码签名的 XCFramework10.12.0 / 10.21.0visionOS 需通过open --env FIREBASE_SOURCE_FIRESTORE /path/to/project.xcodeproj强制使用源码版 Firestore避免使用默认二进制分发10.16.0修复二进制 SwiftPM 在测试目标下的链接问题影响 Xcode 15 Beta 5。破坏性变更速查表版本变更内容迁移要点0.12.0DocumentListenOptions/QueryListenOptions/SetOptions/SnapshotOptions对象改为布尔参数setData(..., merge: true)、addSnapshotListener(includeMetadataChanges: true)1.0.0时间戳默认返回FIRTimestampgetDocument()对不存在文档返回exists false的快照代码从if (snapshot)改为if (snapshot.exists)7.0.0移除areTimestampsInSnapshotsEnabled时间戳固定为FIRTimestamp用dateValue转NSDate9.0.0移除模块内 async/throw 事务方法使用 async 事务需引入FirebaseFirestoreSwift11.0.0移除FirebaseFirestoreSwift模块内存缓存默认 LRU GCTimestamp迁入FirebaseCore迁移FirebaseFirestore.Timestamp→FirebaseCore.Timestamp显式启用 eager GC12.11.0移除BooleanExpression.then(_:else:)Beta API改用ConditionalExpressionUnreleased要求 C17移除 C14 支持涉及 C 构建链的工程需升级编译器标准结语从 Firestore/CHANGELOG.md 可以看到Cloud Firestore iOS SDK 的演进遵循清晰的节奏早期0.x–1.x打牢查询、事务、持久化与数据模型地基7.x–9.x 补齐聚合、索引、Bundles 与平台能力10.x–12.x 则集中投入 Pipeline 管线、向量检索、大文档与 Swift 并发一致性。对于开发者而言版本升级时应优先对照本文破坏性变更速查表检查受影响 API并关注 PipelineEnterprise 预览、FieldValue.minimum/maximum、16 MB 文档等新能力在实际业务中的落地机会。所有新 API 的具体用法均可进一步查阅 Firestore/Swift/Source 与 Firestore/Source/Public/FirebaseFirestore 中的头文件与测试用例如 FIRVectorValueTests.mm、FIRFieldValueTests.mm以获得第一手的签名与语义参考。【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
