SwiftyUserDefaults 从 3.x 迁移到 4.x 完全指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00684/article/details/148508324

SwiftyUserDefaults 从 3.x 迁移到 4.x 完全指南

SwiftyUserDefaults Modern Swift API for NSUserDefaults 项目地址: https://gitcode.com/gh_mirrors/sw/SwiftyUserDefaults

前言

SwiftyUserDefaults 是一个优秀的 Swift 语言用户偏好设置(UserDefaults)封装库，它通过类型安全的方式简化了 UserDefaults 的使用。在 4.x 版本中，该库进行了一些重大改进和 API 调整，本文将详细介绍如何从 3.x 版本平滑迁移到 4.x 版本。

主要变更概述

4.x 版本主要包含以下重大变更：

移除了基于字符串键的遗留 API
移除了某些类型的默认值
改进了自定义类型的支持方式

详细迁移指南

1. 从字符串键迁移到 DefaultsKey

3.x 版本写法：

let value = Defaults["key"].intValue

4.x 版本推荐写法：

let key = DefaultsKey<Int>("key")
let value = Defaults[key]

变更说明：新版本强制使用类型化的 DefaultsKey，这带来了以下优势：

编译时类型检查
更好的代码自动补全
减少运行时错误
更清晰的代码意图表达

如果不想迁移，也可以直接使用原生的 UserDefaults API。

2. 默认值处理的变化

3.x 版本行为：某些类型（如 String）会自动提供默认值（如空字符串）。

4.x 版本变化：移除了这些隐式默认值，需要显式指定。

迁移方案：

// 旧代码
let key = DefaultsKey<String>("test1")

// 新代码 - 显式提供默认值
let key = DefaultsKey<String>("test1", defaultValue: "")

设计考量：这一变化是为了：

避免隐式行为导致的混淆
简化代码库结构
让默认值的选择权完全交给开发者

3. 自定义类型的支持改进

4.x 版本引入了更优雅的自定义类型支持方式。

3.1 支持 NSCoding 的类型

旧版实现方式：

final class Froggy: NSObject, NSCoding { ... }

extension UserDefaults {
    subscript(key: DefaultsKey<Froggy?>) -> NSColor? {
        get { return unarchive(key) }
        set { archive(key, newValue) }
    }
}

新版实现方式：

final class Froggy: NSObject, NSCoding, DefaultsSerializable { ... }

只需让类型符合 DefaultsSerializable 协议即可，无需额外实现下标方法。

3.2 支持 RawRepresentable 的类型（如枚举）

同样只需让枚举类型符合 DefaultsSerializable 协议：

enum Direction: Int, DefaultsSerializable {
    case north, south, east, west
}

3.3 自定义桥接实现

对于更复杂的自定义类型，可以实现自定义的 DefaultsBridge。

基础示例：

struct FrogCustomSerializable: DefaultsSerializable {
    static var _defaults: DefaultsBridge<FrogCustomSerializable> { 
        return DefaultsKeyedArchiverBridge() 
    }
    static var _defaultsArray: DefaultsBridge<[FrogCustomSerializable]> { 
        return DefaultsKeyedArchiverBridge() 
    }
    let name: String
}

高级自定义桥接示例：

final class DefaultsFrogBridge: DefaultsBridge<FrogCustomSerializable> {
    override func get(key: String, userDefaults: UserDefaults) -> FrogCustomSerializable? {
        let name = userDefaults.string(forKey: key)
        return name.map(FrogCustomSerializable.init)
    }

    override func save(key: String, value: FrogCustomSerializable?, userDefaults: UserDefaults) {
        userDefaults.set(value?.name, forKey: key)
    }
    
    // 其他必要方法实现...
}

struct FrogCustomSerializable: DefaultsSerializable, Equatable {
    static var _defaults: DefaultsBridge<FrogCustomSerializable> { 
        return DefaultsFrogBridge() 
    }
    static var _defaultsArray: DefaultsBridge<[FrogCustomSerializable]> { 
        return DefaultsFrogArrayBridge() 
    }
    let name: String
}

3.4 扩展现有类型

还可以为现有类型添加支持：

extension Data: DefaultsSerializable {
    public static var _defaults: DefaultsBridge<Data> { return DefaultsDataBridge() }
    public static var _defaultsArray: DefaultsBridge<[Data]> { return DefaultsArrayBridge() }
}