Monarch 🦋

最小化、可管理、迁移

在您的应用中运行迁移从未如此简单：灵感来自迁徙的帝王蝶。

有关 Monarch 的更详细介绍，请查看我的博客文章Monarch 介绍。

您不一定第一次就能做对。这就是为什么铅笔有橡皮擦——以及为什么应用程序需要迁移。

简单迁移：定义独立的迁移，无需担心状态管理，从而轻松地随着时间的推移演变您的应用程序。
为 Swift 和 SwiftUI 构建：Monarch 的迁移在任何 Swift 应用中都感觉很自然，拥有简洁的 SwiftUI API。
依赖注入：无论您的迁移是简单还是复杂，Monarch 易于使用的依赖注入都提供了结构，以防止与数据相关的问题。

入门

在您的应用中设置迁移很简单

使用 Migration 协议定义您的迁移。
将您的迁移添加到 MigrationGroup。
使用 runMigrations 视图修饰符运行您的迁移。

// 1. Define a migration
struct MigrateUserDataToAppGroup: Migration {
    @MigrationDependency private var userDefaultsAppState
    @MigrationDependency private var sharedAppState

    static let id: MigrationID = "MigrateUserDataToAppGroup"

    func run() async throws {
        // Migrate the user data from UserDefaults to an app group, so you can share data across targets
        sharedAppState.userData = userDefaultsAppState.userData

        userDefaultsAppState.userData = nil
    }
}

// 2. Group your migrations and add dependencies
let migrations = MigrationGroup {
    MigrateUserDataToAppGroup()
    // Add more migrations here
}
.migrationDependency(self.userDefaultsAppState)
.migrationDependency(self.sharedAppState)

// 3. Run migrations in your SwiftUI app
struct ContentView: View {
    var body: some View {
        Text("Hello, Monarch! 🦋")
            .runMigrations {
                migrations
            }
    }
}

这就是开始使用 Monarch 所需的一切！根据需要添加任意数量的迁移和依赖项，以帮助您的应用随着时间的推移不断发展。

高级用法

Monarch 提供了多种方法来定制和控制您的迁移过程

手动运行迁移

如果迁移的时机在您的应用中至关重要，您可以使用 MigrationRunner 进行完全控制。以下是一个利用 Monarch 功能手动运行迁移的应用示例

struct ButterflyTrackerApp: App {
    @State var appState = AppState()
    @State var preferences = Preferences()
    
    var body: some Scene {
        WindowGroup {
            ContentView()
                .task { 
                    try await self.runMigrations()
                }
        }
    }
    
    func runMigrations() async throws {
        MigrationRunner.removeAllMigrations()

        MigrationRunner.markMigrationAsCompleted(withID: ResetButterflyListMigration.id)
        
        let migrationGroup = MigrationGroup {
            ProvideButterlyFansPremiumAccountAccessMigration()
            RemoveAccidentallyAddedMothMigration()
        }
        .migrationDependency(self.appState)
        .migrationDependency(self.preferences)

        try await MigrationRunner.runMigrations({ migrationGroup })
    }
}

MigrationRunner API

// Run the migrations in a MigrationGroup.
public static func runMigrations(_ migrationGroup: MigrationGroup) async throws

// Mark a migration as completed, without actually running it. This is useful when transitioning to Monarch from another migration system.
public static func markMigrationAsCompleted(withID id: MigrationID)

// Remove a specific migration that has previously run, allowing it to be re-run.
public static func removeMigration(withID id: MigrationID)

// Remove all previously run migrations.
public static func removeAllMigrations()

注意

Monarch 将已完成迁移的列表存储在 UserDefaults 中，这可能需要长达 7 秒的时间才能同步。如果用户在此 7 秒的时间窗口内重新运行这些迁移（例如，通过重新启动应用程序），则可能会重新运行迁移。

要求

iOS 17.0+
macOS 14.0+
Xcode 14+
Swift 5.10+

安装

Swift 包管理器

在您的 Package.swift 文件中添加 Monarch 作为依赖项

dependencies: [
    .package(url: "https://github.com/yourusername/Monarch.git", .upToNextMajor(from: "1.0.0"))
]

然后，将 Monarch 添加到您的目标依赖项

targets: [
    .target(
        name: "YourTarget",
        dependencies: ["Monarch"]
    )
]

手动

如果您不想使用 SPM，可以通过复制 Sources/Monarch 目录中的文件将 Monarch 手动集成到您的项目中。

关于我

嗨，我在网络上到处都叫 Joe，尤其是在 Threads 上。

许可证

有关如何使用 Monarch 的更多信息，请参阅许可证。

赞助

Monarch 是一项爱的劳动，旨在帮助开发人员构建更好的应用程序，使您更容易释放您的创造力，并为您自己和您的用户创造一些令人惊叹的东西。如果您发现 Monarch 有价值，如果您能考虑帮助赞助我的开源工作，我将非常感谢，这样我就可以继续从事像 Monarch 这样的项目来帮助像您这样的开发人员。