# Realm 到 SwiftData 迁移 — 参考指南 **目的**：从 Realm 到 SwiftData 的完整迁移路径 **Swift 版本**：Swift 5.9+（建议使用严格并发的 Swift 6） **iOS 版本**：iOS 17+（建议使用 iOS 26+） **背景**：Realm 设备同步将于 2025 年 9 月 30 日日落。本指南对于在截止日期前迁移的 Realm 用户至关重要。 ** ** ## 关键时间线 **Realm Device Sync** 弃用截止日期 = 2025 年 9 月 30 日如果您的应用程序使用领域同步： * ⚠️ 您必须在 2025 年 9 月 30 日之前迁移 * ✅ SwiftData 是推荐的替代品 * ⏰ 剩余时间：取决于当前日期，但生产应用程序的迁移需要 2-8 周 **本指南**提供成功迁移所需的一切。 ** ** ## 迁移策略概述第 1 阶段（第 1-2 周）：准备和规划 ├─ 审核当前 Realm 使用情况 ├─ 理解模型关系 ├─ 规划数据迁移路径 └─ 搭建测试环境第 2 阶段（第 2-3 周）：开发 ├─ 从 Realm 模式创建 SwiftData 模型 ├─ 实现数据迁移逻辑 ├─ 将线程模型转换为 async/await └─ 用真实数据测试第 3 阶段（第 3-4 周）：迁移 ├─ 迁移现有应用程序用户的数据 ├─ 并行运行（Realm + SwiftData） ├─ 验证 CloudKit 同步是否有效 └─ 监控问题第 4 阶段（第 4 周以上）：生产 ├─ 并行持久化部署更新 ├─ 从 Realm 逐步切换到 SwiftData ├─ 弃用 Realm 代码 └─ 监控CloudKit同步运行状况 ** ** ## 第 1 部分：模式等效项 ### 模型定义转换 #### Realm → SwiftData：基本模型 // 领域类 RealmTrack: 对象 { @Persisted(primaryKey: true) var id: 字符串 @Persisted var 标题：字符串 @Persisted var 艺术家：字符串 @Persisted var 持续时间：TimeInterval @Persisted var 类型：字符串？ } // SWIFT 数据 @模型期末班曲目{ @Attribute(.unique) var id: 字符串 var 标题：字符串变种艺术家：String var 持续时间：TimeInterval var 类型：字符串？ init(id: 字符串, 标题: 字符串, 艺术家: 字符串, 持续时间: TimeInterval, 流派: 字符串? = nil) { self.id = id self.title = 标题 self.艺术家=艺术家 self.duration = 持续时间 self.流派 = 流派 } } **主要区别**： * 领域：`@Persisted(primaryKey: true)` → SwiftData：`@Attribute(.unique)` * Realm：隐式初始化 → SwiftData：需要显式初始化 * Realm: `Object` 基类 → SwiftData: `final class` 上的 `@Model` 宏 #### 领域 → SwiftData：关系 // 领域：一对多类 RealmAbum: 对象 { @Persisted(primaryKey: true) var id: 字符串 @Persisted var 标题：字符串 @Persisted var 轨道：RealmSwiftCollection } // SWIFTDATA：一对多 @模型期末班相册{ @Attribute(.unique) var id: 字符串 var 标题：字符串 @Relationship(deleteRule: .cascade, inverse: \Track.album) var 轨道：[轨道] = [] } @模型期末班曲目{ @Attribute(.unique) var id: 字符串 var 标题：字符串 var 专辑：专辑？ // 逆自动维护 } **主要区别**： * Realm：显式 `RealmSwiftCollection` 类型 → SwiftData：本机 `[Track]` 数组 * Realm：手动关系管理 → SwiftData：自动逆关系 * Realm: 无删除规则 → SwiftData: `deleteRule: .cascade / .nullify / .deny` #### 领域 → SwiftData：索引 // 领域类 RealmTrack: 对象 { @Persisted(primaryKey: true) var id: 字符串 @Persisted(indexed: true) var 流派：字符串 @Persisted(indexed: true) var releaseDate: 日期 } // SWIFT 数据 @模型期末班曲目{ @Attribute(.unique) var id: 字符串 @Attribute(.indexed) var 类型: String = "" @Attribute(.indexed) var releaseDate: Date = Date() } ** ** ## 第 2 部分：线程模型转换 ### 领域线程 → Swift 并发 #### 领域：手动线程处理类 RealmDataManager { 函数 fetchTracksOnBackground() { DispatchQueue.global().async { 让领域=尝试！ Realm() // 必须在每个线程上获取 Realm 让轨迹=realm.objects(RealmTrack.self) DispatchQueue.main.async { self.updateUI（曲目：数组（曲目）） } } } func saveTrackOnBackground(_ track: RealmTrack) { DispatchQueue.global().async { 让领域=尝试！领域() 试试吧！领域. 写入 { 领域.添加（轨道） } } } } **问题**： * 手动DispatchQueue线程处理容易出错 * 容易访问错误线程上的对象 * 没有编译时保证 #### SwiftData：基于 Actor 的并发演员 SwiftDataManager { 让 modelContainer: ModelContainer func fetchTracks() 异步 -> [Track] { 让上下文 = ModelContext(modelContainer) 让描述符 = FetchDescriptor() 返回（尝试？context.fetch（描述符））？ [] } func saveTrack(_ track: Track) 异步 { 让上下文 = ModelContext(modelContainer) 上下文.插入（轨道）试试？上下文.save() } } // 用法（自动线程处理） @主要演员类 ViewController: UIViewController { @State private var track: [Track] = [] 私有让管理器：SwiftDataManager func loadTracks() 异步 { 曲目=等待经理.fetchTracks() } } **优点**： * 无需手动DispatchQueue * 编译时线程安全 * 自动演员隔离 * Swift 6 严格并发兼容 #### 常见线程模式境界格局| Swift 数据模式 ---|--- `DispatchQueue.global().async` |后台演员中的“async/await” `realm.write { }` | `context.insert()` \+ `context.save()` 手动线程本地 Realm 实例 |共享 `ModelContainer` \+ 背景 `ModelContext` `Thread.isMainThread` 检查 | `@MainActor` 注释 ** ** ## 第 3 部分：架构迁移策略 ### 简单架构迁移（直接转换）对于具有简单架构（< 5 个表，< 10 个字段）的应用程序，直接迁移非常简单：演员 SchemaImporter { 让realmPath：字符串让 modelContainer: ModelContainer func migrateFromRealm() 异步抛出 { // 1.打开Realm数据库让realmConfig = Realm.Configuration（fileURL：URL（fileURLWithPath：realmPath））让领域=尝试等待领域（配置：realmConfig） // 2. 创建 SwiftData 上下文让上下文 = ModelContext(modelContainer) // 3. 迁移各个模型类型尝试 migrateAllTracks(从: 领域, 到: 上下文) 尝试 migrateAllAlbums(从: 领域, 到: 上下文) 尝试 migrateAllPlaylists(从: 领域, 到: 上下文) // 4. 一次性保存尝试 context.save() print("迁移完成！") } private func migrateAllTracks(从领域：Realm，到上下文：ModelContext) throws { 让realmTracks=realm.objects(RealmTrack.self) 对于realmTracks 中的realmTrack { 让 sdTrack = 轨迹（ id：realmTrack.id，标题：realmTrack.title，艺术家：realmTrack.artist，持续时间：realmTrack.duration，流派：realmTrack.流派）上下文.插入(sdTrack) } } private func migrateAllAlbums(从领域：Realm，到上下文：ModelContext) throws { 让realmAlbums=realm.objects(RealmAlbum.self) 对于realmAlbum in realAlbums { 让 sdAlbum = 专辑( id：realmAlbum.id，标题：realmAlbum.title ）上下文.插入(sdAlbum) // 创建所有记录后连接关系对于realmAlbum.tracks 中的realmTrack { if let sdTrack = findTrack(id:realmTrack.id, in:context) { sdAlbum.tracks.append(sdTrack) } } } } private func findTrack(id: String, in context: ModelContext) -> 跟踪？ { 让描述符 = FetchDescriptor( 谓词：#Predicate { $0.id == id } ）返回试试？ context.fetch(描述符).first } } ### 复杂模式迁移（转换层）对于具有复杂架构、许多计算属性或数据转换的应用程序： // 步骤1：定义转换层结构体 TrackDTO { 让realmTrack：RealmTrack var id：字符串{realmTrack.id} var title: String {realmTrack.title } var cleanTitle: String {realmTrack.title.trimmingCharacters(in: .whitespaces) } var 持续时间格式：字符串 { 让分钟 = Int(realmTrack.duration) / 60 让秒 = Int(realmTrack.duration) % 60 返回字符串（格式：“％d：％02d”，分钟，秒） } } // 步骤2：通过转换层迁移演员 ComplexMigrator { 让 modelContainer: ModelContainer func migrateWithTransformation（来自领域：领域）抛出{ 让上下文 = ModelContext(modelContainer) 让realmTracks=realm.objects(RealmTrack.self) 对于realmTracks 中的realmTrack { 让 dto = TrackDTO(realmTrack:realmTrack) // 迁移过程中转换数据让 sdTrack = 轨迹（ id: dto.id, title: dto.cleanTitle, // 清理后的版本艺术家：realmTrack.artist，持续时间：realmTrack.duration ）上下文.插入(sdTrack) } 尝试 context.save() } } ** ** ## 第 4 部分：CloudKit 同步过渡 ### 领域同步 → SwiftData CloudKit Realm Sync（现已弃用）提供自动同步。 SwiftData 直接使用 CloudKit： // REALM SYNC：自动但已弃用让 config = Realm.Configuration( 同步配置：同步配置（用户：app.currentUser！）） // SWIFTDATA：CloudKit（推荐替换）让 schema = Schema([Track.self, Album.self]) 让配置=模型配置（架构：架构， cloudKitDatabase: .private("iCloud.com.example.MusicApp") ）让容器=尝试ModelContainer（用于：模式，配置：配置） ### 同步状态监控 @主要演员 CloudKitSyncMonitor 类：ObservableObject { @Published var isSyncing = false @Published var lastSyncDate：日期？ @Published varsyncError：错误？让 modelContainer: ModelContainer 函数开始监控（）{ // 监控CloudKit同步通知通知中心.default.addObserver( forName: NSNotification.Name("CloudKitSyncDidComplete"), 对象：无，队列：.main ) { [弱自我] _ in self?.isSyncing = false self?.lastSyncDate = 日期() } } funcsyncNow() 异步 { 正在同步 = true 做{ 让上下文 = ModelContext(modelContainer) // SwiftData 同步自动发生 // 手动获取触发同步让描述符 = FetchDescriptor() _ = 尝试 context.fetch(描述符) } 抓住 { 同步错误=错误 } 正在同步 = false } } ### 迁移时机：Realm Sync → CloudKit 时间表：第 1-2 周：开发与测试 ├─ 创建 SwiftData 模型 ├─ 在非CloudKit模式下测试迁移 └─ 准备CloudKit配置第 3 周：CloudKit 同步测试 ├─ 在测试版本中启用CloudKit ├─ 验证同步是否适用于小型数据集 ├─ 测试多设备同步 └─ 测试冲突解决第 4 周以上：生产部署 ├─ 使用 SwiftData + CloudKit 部署应用程序 ├─ 最初并行运行（Realm Sync + SwiftData CloudKit） ├─ 监控两种同步机制 ├─ 逐渐弃用 Realm Sync └─ 2025年9月30日前最终截止 ** ** ## 第 5 部分：现实世界的迁移场景 ### 场景 A：小型应用程序（< 10,000 条记录） **时间轴**：1-2 周 **数据大小**：< 10 MB // 1.导出Realm数据让realmPath = Realm.Configuration.defaultConfiguration.fileURL！ // 2. 在后台任务中迁移演员 SmallAppMigration { 让 modelContainer: ModelContainer func migrateSmallApp() 异步抛出 { 让realmConfig = Realm.Configuration（文件URL：realmPath）让领域=尝试等待领域（配置：realmConfig）让上下文 = ModelContext(modelContainer) // 一次性迁移（对于 < 10k 条记录是安全的）让 allTracks = Realm.objects(RealmTrack.self) for allTracks 中的realmTrack { 让track = Track（来自：realmTrack）上下文.插入（轨道） } 尝试 context.save() print("✅ 已迁移 \(allTracks.count) 个曲目") } } // 3. 部署 // 选项 1：首次启动时迁移（离线） // 选项2：提供手动“迁移数据”按钮 // 选项3：后台自动迁移 ### 场景 B：中型应用程序（100,000 - 1,000,000 条记录） **时间轴**：3-4 周 **数据大小**：100 MB - 1 GB **挑战**：进度报告、内存管理演员 MediumAppMigration { 让 modelContainer: ModelContainer 让realmPath：字符串类型别名 ProgressCallback = (Int, Int) -> Void func migrateMediumApp(onProgress: @MainActor ProgressCallback) 异步抛出 { 让realmConfig = Realm.Configuration（fileURL：URL（fileURLWithPath：realmPath））让领域=尝试等待领域（配置：realmConfig）让上下文 = ModelContext(modelContainer) 让 allTracks = Realm.objects(RealmTrack.self) 让totalCount = allTracks.count // 基于块的迁移以提高内存效率变量计数 = 0 for chunk in Array(allTracks).chunked(into: 5000) { 块中的realmTrack { 让track = Track（来自：realmTrack）上下文.插入（轨道） } // 定期保存尝试 context.save() 计数 += 块.计数等待 onProgress(计数, 总计数) // 检查是否取消如果任务已取消 { 抛出取消错误() } } } } // 4. 显示进度UI @主要演员类 MigrationViewController: UIViewController { @IBOutlet 弱变量progressView：UIProgressView！ @IBOutlet 弱变量 statusLabel：UILabel！函数开始迁移() { 任务{ 做{ 尝试等待 migrator.migrateMediumApp { 当前，总计 self.progressView.progress = Float(当前) / Float(总计) self.statusLabel.text = "已迁移\(当前)\(总计)..." } self.statusLabel.text = "✅ 迁移完成！" } 抓住 { self.statusLabel.text = "❌ 迁移失败: \(错误)" } } } } ### 场景 C：大型应用程序（企业，> 100 万条记录） **时间表**：6-8 周 **数据大小**：> 1 GB **挑战**：最短的停机时间、数据完整性、回滚计划类 EnterpriseGradualMigration { let coreDataStack: CoreDataStack // 现有领域让 modelContainer: ModelContainer 让batchSize = 10000 // 第 1 阶段：并行迁移 func startGradualMigration() 异步 { 变量偏移量 = 0 让totalRecords = countAllRecords() 而偏移量 < 总记录数 { 让batch = fetchRealmBatch（限制：batchSize，offset：offset）试试？等待 migrateBatch(batch) 偏移量 += 批量大小等待报告进度（偏移量，总记录数） } } private func migrateBatch(_ batch: [RealmTrack]) 异步抛出 { 让上下文 = ModelContext(modelContainer) 对于批处理中的realmTrack { 让track = Track（来自：realmTrack）上下文.插入（轨道） track.migrationStatus = .completedPhase1 } 尝试 context.save() // 给主线程喘息的时间尝试等待 Task.sleep(纳秒: 100_000_000) // 100ms } // 第 2 阶段：验证所有已迁移的内容 func verifyMigrationComplete() 异步抛出 { 让 sdContext = ModelContext(modelContainer) 让 sdCount = 尝试 sdContext.fetch(FetchDescriptor()) 让realmCount = countAllRealmRecords() 守卫 sdCount.count == 领域计数其他 { 抛出 MigrationError.countMismatch（sd：sdCount.count，领域：realmCount） } print("✅ 已验证：\(sdCount.count) 条记录已迁移") } // 第三阶段：回滚计划 func rollbackToRealm() { // 保持 Realm 数据库完整直到 100% 置信 // 仅在 SwiftData 上稳定运行 2 周以上后删除 Realm } } ** ** ## 第 6 部分：测试与验证 ### 数据完整性检查表在使用 SwiftData 之前： @主要演员类迁移验证器 { func verifyMigration() 异步抛出 { print("🔍 运行迁移验证...") // 1. 计数验证让 sdCount = 尝试等待 countSwiftDataRecords() 让 RealmCount = countRealmRecords() print("✓ 记录数：SD=\(sdCount), Realm=\(realmCount)") 守卫 sdCount == 领域计数其他 { 抛出 VerificationError.countMismatch } // 2. 数据完整性采样（抽查）尝试等待 verifySampleRecords(count: min(100, sdCount / 10)) print("✓ 抽查 100 条记录 - 全部有效") // 3. 关系完整性尝试等待 verifyRelationships() print("✓ 所有关系完好无损") // 4.CloudKit同步测试尝试等待 verifyCloudKitSync() print("✓ CloudKit 同步工作正常") // 5. 性能测试尝试等待 verifyPerformance() print("✓ 查询性能可接受") print("✅ 所有验证都通过了！") } 私有 func verifySampleRecords(count: Int) 异步抛出 { 让 sdContext = ModelContext(modelContainer) 让描述符 = FetchDescriptor() 让 Tracks = 尝试 sdContext.fetch(描述符) 让样本 = 数组(tracks.prefix(count)) 对于样本中的轨道{ // 验证字段已填充 assert(!track.id.isEmpty, "轨道 ID 为空") assert(!track.title.isEmpty, "曲目标题为空") assert(track.duration > 0, "曲目的持续时间无效") } } private func verifyRelationships() 异步抛出 { 让 sdContext = ModelContext(modelContainer) 让 albumDescriptor = FetchDescriptor() 让相册=尝试 sdContext.fetch(albumDescriptor) 对于相册中的相册{ // 验证逆关系对于 album.tracks 中的曲目 { assert(track.album?.id == album.id, "关系破裂") } } } private func verifyCloudKitSync() 异步抛出 { 让 sdContext = ModelContext(modelContainer) // 插入测试记录让 testTrack = 跟踪（ id: "测试-" + UUID().uuidString, 标题：“测试跑道”，艺术家：“测试艺术家”，持续时间：240 ） sdContext.插入（testTrack）尝试 sdContext.save() // 验证 CloudKit 同步已启动 //（检查 iCloud → iPhone → 设置 → iCloud 的同步状态） print("ℹ️ 检查 iCloud 应用程序以验证已启动同步") } 私有 func verifyPerformance() 异步抛出 { 让 sdContext = ModelContext(modelContainer) 让开始=日期（）让描述符 = FetchDescriptor( 排序依据：[SortDescriptor(\.title)] ） _ = 尝试 sdContext.fetch(描述符) 让经过 = Date().timeIntervalSince(start) print("获取时间: \(String(format: "%.2f", elapsed))s") 守卫已过去 < 2.0 else { 抛出 VerificationError.performanceIssue } } } ** ** ## 第 7 部分：故障排除 ### 常见迁移问题问题 |原因 |解决方案 ---|---|--- “属性必须有默认值” | CloudKit 约束 |添加默认值：`var title: String = ""` 关系未同步 |缺少逆 |添加“逆：\Track.album” 同步卡住| CloudKit 身份验证问题 |检查设置 → iCloud → CloudKit 导入期间内存膨胀 |没有分块 |实现批量导入（一次1000个）数据丢失|没有备份|迁移后将 Realm 副本保留 2 周 ** ** ## 第 8 部分：成功标准在以下情况下您的迁移成功： * 所有数据均已正确迁移（计数匹配） * 记录验证通过样本（抽查100+条记录） * 关系完好无损（反向关系有效） * CloudKit 同步已启用并正在运行 * 性能可接受（查询 < 1 秒） * 无数据竞争（Swift 6 严格并发） * 在真实设备上测试（不仅仅是模拟器） * 记录并测试回滚计划 * Realm数据库作为备份保存2周 * 1 周后生产中零崩溃 ** ** ## 快速参考：命令清单 # 1. 审核 Realm 使用情况 grep -r "RealmTrack\|RealmAlbum" 。 --include="*.swift" # 2. 统计 Realm 记录（在应用程序中）让领域=尝试！领域() 让 count = real.objects(RealmTrack.self).count # 3.导出Realm数据库 cp ~/Library/Developer/Realm/my_realm.realm ~/Downloads/backup.realm # 4. 测试 SwiftData 模型 // 创建内存测试容器让 config = ModelConfiguration(isStoredInMemoryOnly: true) 让容器=尝试ModelContainer（用于：Track.self，配置：config） # 5. 验证 CloudKit 设置 → [您的名字] → iCloud → 检查 CloudKit 状态 ** ** ## 资源 **全球开发者大会**：2024-10137 **文档**：/swiftdata **技能**：axiom-swiftdata、axiom-swift-concurrency、axiom-database-migration ** ** **创建**：2025 年 11 月 30 日 **状态**：生产就绪迁移指南 **紧急性**：Realm 设备同步将于 2025 年 9 月 30 日日落 **预计迁移时间**：2-8 周，具体取决于应用程序复杂性

Axiom Realm 迁移参考

包含技能