当前位置：首页 > news >正文

SimpleKeychain完全指南：iOS/macOS/tvOS/watchOS通用的钥匙串封装库

news 2026/7/28 23:03:26

SimpleKeychain完全指南：iOS/macOS/tvOS/watchOS通用的钥匙串封装库

【免费下载链接】SimpleKeychainA simple Keychain wrapper for iOS, macOS, tvOS, and watchOS项目地址: https://gitcode.com/gh_mirrors/si/SimpleKeychain

SimpleKeychain是一款适用于iOS、macOS、tvOS和watchOS平台的钥匙串封装库，它提供了简洁易用的API来安全地存储和管理敏感数据。无论是用户凭证、API令牌还是其他私密信息，SimpleKeychain都能帮助开发者轻松实现安全存储，而无需深入了解复杂的钥匙串框架细节。

为什么选择SimpleKeychain？

在移动应用开发中，安全存储用户数据是至关重要的一环。苹果的钥匙串服务提供了安全可靠的数据存储机制，但原生API使用起来较为繁琐。SimpleKeychain应运而生，它封装了复杂的钥匙串操作，提供了直观的接口，让开发者能够快速集成安全存储功能。

主要优势包括：

跨平台支持：一套代码适用于iOS、macOS、tvOS和watchOS
简洁API：通过简单的方法调用来存储、读取和删除数据
安全可靠：基于苹果钥匙串服务，确保数据安全
错误处理：完善的错误处理机制，便于调试和问题解决
Swift原生：使用Swift编写，充分利用Swift的特性和优势

快速开始：安装与配置

SimpleKeychain提供多种安装方式，满足不同项目的需求：

使用CocoaPods安装

在项目的Podfile中添加以下行：
```
pod 'SimpleKeychain', '~> 1.0'
```
运行以下命令安装依赖：
```
pod install
```

使用Carthage安装

在项目的Cartfile中添加以下行：
```
github "auth0/SimpleKeychain" ~> 1.0
```
运行以下命令构建框架：
```
carthage update
```

使用Swift Package Manager安装

在Xcode中，通过菜单选择File > Swift Packages > Add Package Dependency，然后输入仓库URL：

https://gitcode.com/gh_mirrors/si/SimpleKeychain

基础用法：SimpleKeychain核心功能

初始化SimpleKeychain实例

创建SimpleKeychain实例非常简单，默认配置即可满足大多数需求：

let simpleKeychain = SimpleKeychain()

如果需要自定义配置，可以在初始化时指定参数：

// 指定服务名称 let simpleKeychain = SimpleKeychain(service: "Auth0") // 指定访问组（用于应用间共享数据） let simpleKeychain = SimpleKeychain(accessGroup: "ABCDEFGH.com.example.myaccessgroup") // 启用iCloud同步 let simpleKeychain = SimpleKeychain(synchronizable: true)

存储数据

SimpleKeychain支持存储字符串和数据类型：

// 存储字符串 try simpleKeychain.set("user@example.com", forKey: "username") // 存储数据 let data = "secret".data(using: .utf8)! try simpleKeychain.set(data, forKey: "secretData")

读取数据

从钥匙串中读取数据同样简单：

// 读取字符串 if let username = try simpleKeychain.string(forKey: "username") { print("Username: \(username)") } // 读取数据 if let data = try simpleKeychain.data(forKey: "secretData") { let secret = String(data: data, encoding: .utf8) print("Secret: \(secret ?? "")") }

检查数据是否存在

可以检查特定键是否存在于钥匙串中：

if try simpleKeychain.hasItem(forKey: "username") { print("Username exists in keychain") } else { print("Username not found") }

删除数据

删除单个数据项或清空整个钥匙串：

// 删除单个数据项 try simpleKeychain.deleteItem(forKey: "username") // 清空整个钥匙串 try simpleKeychain.deleteAll()

高级功能：提升安全性和灵活性

访问控制与生物识别

SimpleKeychain支持访问控制标志，可与生物识别（如Touch ID或Face ID）结合使用：

let context = LAContext() context.localizedReason = "需要验证身份以访问安全数据" let simpleKeychain = SimpleKeychain(accessControlFlags: .biometryCurrentSet, context: context)

自定义可访问性

可以指定钥匙串项的可访问性级别，控制数据何时可以被访问：

// 仅在设备解锁时可访问 let simpleKeychain = SimpleKeychain(accessibility: .whenUnlocked) // 即使设备已锁定也可访问（适用于后台任务） let simpleKeychain = SimpleKeychain(accessibility: .afterFirstUnlock)

错误处理

SimpleKeychain使用SimpleKeychainError枚举来表示各种可能的错误：

do { let username = try simpleKeychain.string(forKey: "username") } catch let error as SimpleKeychainError { switch error { case .itemNotFound: print("用户名不存在") case .authFailed: print("身份验证失败") default: print("发生错误: \(error.localizedDescription)") } }

迁移指南：从v0到v1

如果您正在从SimpleKeychain v0迁移到v1，需要注意以下主要变化：

类到结构体的转变：A0SimpleKeychain类已重命名为SimpleKeychain结构体
方法抛出错误：所有方法现在通过抛出SimpleKeychainError来报告错误，而不是使用错误参数
枚举重命名：A0SimpleKeychainError重命名为SimpleKeychainError，A0SimpleKeychainItemAccessible重命名为Accessibility
Objective-C支持移除：v1不再支持Objective-C，仅支持Swift

迁移示例：

// v0 代码 let keychain = A0SimpleKeychain() var error: NSError? let username = keychain.stringForKey("username", error: &error) // v1 代码 let keychain = SimpleKeychain() do { let username = try keychain.string(forKey: "username") } catch { print("错误: \(error)") }