data-persistence

数据持久化 / 存储层

存储方案选型

方案	适用场景	线程安全	数据量
UserDefaults	轻量配置、用户偏好	✅ 主线程安全	< 1MB
Keychain	Token、密钥、敏感凭证	✅	极小
CoreData	结构化关系数据、离线缓存	需配置	大
SwiftData	新项目结构化数据（iOS 17+）	✅	大
FileManager	文件、图片、导出数据	需加锁	任意

选择原则：

• 能用 UserDefaults 解决的不上 CoreData
• 敏感数据（Token、密码）必须存 Keychain，禁止存 UserDefaults
• 新项目且最低支持 iOS 17+ 可选 SwiftData，否则用 CoreData
• 文件类数据（导出 PDF、录音文件）用 FileManager

---

UserDefaults

规范

• 封装为 UserDefaultsStorage，禁止在业务代码中直接调用 UserDefaults.standard
• Key 统一管理，禁止散落字符串：

struct UserDefaultsStorage {
    private let defaults = UserDefaults.standard

    enum Key: String {
        case hasCompletedOnboarding
        case selectedTheme
        case lastSyncTimestamp
        case launchCount
    }

    var hasCompletedOnboarding: Bool {
        get { defaults.bool(forKey: Key.hasCompletedOnboarding.rawValue) }
        set { defaults.set(newValue, forKey: Key.hasCompletedOnboarding.rawValue) }
    }
}

已知陷阱

• bool(forKey:) 在 key 不存在时返回 false，无法区分"未设置"和"设置为 false"。需要区分时用 object(forKey:) != nil 判断
• UserDefaults.standard 写入是异步的，synchronize() 在 iOS 12+ 已无必要（系统自动处理）
• 禁止存储大数据（图片 Base64、JSON 数组等），会导致启动变慢
• App Group 共享：必须用 UserDefaults(suiteName: "group.com.app.shared")

---

Keychain

封装

final class KeychainStorage {
    static let shared = KeychainStorage()

    private let service = Bundle.main.bundleIdentifier ?? "com.app.default"

    func save(_ data: Data, for key: String) throws {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: key,
        ]
        SecItemDelete(query as CFDictionary)

        var addQuery = query
        addQuery[kSecValueData as String] = data
        addQuery[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock
        let status = SecItemAdd(addQuery as CFDictionary, nil)
        guard status == errSecSuccess else {
            throw KeychainError.saveFailed(status)
        }
    }

    func load(for key: String) -> Data? {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: key,
            kSecReturnData as String: true,
            kSecMatchLimit as String: kSecMatchLimitOne,
        ]
        var result: AnyObject?
        let status = SecItemCopyMatching(query as CFDictionary, &result)
        return status == errSecSuccess ? result as? Data : nil
    }

    func delete(for key: String) {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: key,
        ]
        SecItemDelete(query as CFDictionary)
    }
}