Shallows序列化能力清单：JSON、Plist与String存储映射全覆盖指南

Shallows序列化能力清单：JSON、Plist与String存储映射全覆盖指南

【免费下载链接】Shallows🛶 Your lightweight persistence toolbox项目地址: https://gitcode.com/gh_mirrors/sh/Shallows

Shallows 是一个轻量级的 Swift 持久化工具箱（persistence toolbox），它的核心类型Storage<Key, Value>可以通过 7 个便捷的 map 序列化方法，把磁盘上原始的Data直接映射成 JSON、Plist 或 String 等类型安全的存储——本文为你整理这份 JSON、Plist 与 String 存储映射的完整能力清单，帮你快速选对序列化方案。

一、3 秒看懂 Shallows 的序列化模型

Shallows 的设计思路非常简洁，所有序列化都建立在一个统一模型之上：

Data 存储（DiskStorage） │ mapString / mapJSON / mapPlist ▼ 类型安全存储 Storage<Key, 你的类型>

• 底层：DiskStorage 负责把Data读写到磁盘文件；
• 序列化层：DiskExtensions.swift 在Value == Data的存储上提供 7 个 map 方法，读取时反序列化、写入时序列化，全程自动完成；
• 上层：你只需要用强类型的值（比如一个Codable结构体）直接set/retrieve，再也不用手写编码解码逻辑。

let diskStorage = DiskStorage.main.folder("cities", in: .cachesDirectory) .mapJSONObject(City.self) // Storage<Filename, City>，自动 JSON 序列化/反序列化

💡 这 7 个方法定义在extension StorageProtocol where Value == Data上（见 DiskExtensions.swift），所以任何产出Data的存储（磁盘、文件、自定义后端）都可以直接挂上这些序列化能力。

二、Shallows 序列化方法完整清单（一张表看懂）

每个格式家族都提供3 个粒度级别：

• Any版本（mapJSON/mapPlist）：最宽松，拿到的是字典/数组等通用对象；
• 字典版本（mapJSONDictionary/mapPlistDictionary）：保证值是[String: Any]字典，适合配置项场景；
• Codable 对象版本（mapJSONObject/mapPlistObject）：类型最安全，直接映射到你自己的结构体或类。

三、JSON 序列化：3 个方法怎么选

1. 存 Codable 模型：mapJSONObject

适合存储业务模型（如用户信息、城市数据等Codable结构体），可自定义JSONDecoder/JSONEncoder（例如修改日期编码策略）：

diskStorage = DiskStorage.main.folder("cities", in: .cachesDirectory) .mapJSONObject(City.self) // 直接存取 City 结构体 diskStorage.set(kharkiv, forKey: "kharkiv") let city = try await diskStorage.retrieve(forKey: "kharkiv")

2. 存键值配置：mapJSONDictionary

适合存 JSON 对象形式的配置（字典）。配合.singleKey还能变成"单键存储"——整个存储只保存一份配置（见 Storage.swift 的singleKey）：

let settings = DiskStorage.main.folder("settings", in: .applicationSupportDirectory) .mapJSONDictionary() .singleKey("settings") // Storage<Void, [String : Any]>

3. 通用任意 JSON：mapJSON

最宽松的版本，值可以是任意 JSON 结构（数组、数字、字典均可），代价是返回类型为Any，需要自行类型转换。三个方法均支持传入readingOptions/writingOptions（如JSONSerialization.WritingOptions.prettyPrinted输出格式化 JSON）。

四、Plist 序列化：苹果生态的原生选择

1. 存 Codable 模型：mapPlistObject

与mapJSONObject完全对等，只是底层换成PropertyListEncoder/PropertyListDecoder，适合与苹果生态工具（如 Xcode 工程文件、UserDefaults风格配置）互通的场景。

2. 存键值配置：mapPlistDictionary

映射结果为[String: Any]字典，适合.plist风格的设置文件。

3. 通用任意 Plist：mapPlist

⚠️新手注意：format参数默认是.xml格式（见 DiskExtensions.swift 的默认值），如果需要二进制 plist 请显式传.binary：

let plistStorage = DiskStorage.main.folder("config", in: .applicationSupportDirectory) .mapPlist(format: .binary) // 显式指定二进制格式

五、String 序列化：最轻量的一档

一行代码搞定文本存储：mapString

适合存纯文本、日志片段、小配置字符串等。默认编码为UTF-8，也可换成.ascii、.utf16等任意String.Encoding：

let strings = DiskStorage.main.folder("strings", in: .cachesDirectory) .mapString(withEncoding: .utf8) .makeSyncStorage() // SyncStorage<String, String>，同步读写 try strings.set("hello".uppercased(), forKey: "hello")

💡 序列化 + 组合是 Shallows 的王牌组合：先把磁盘存储映射成 String/JSON 类型，再与MemoryStorage组合成"内存 + 磁盘"两级缓存，既类型安全又高效。

六、3 步选型：哪种序列化方法最适合你？

1. 有Codable模型？→ 首选mapJSONObject（跨平台通用）或mapPlistObject（苹果生态）；
2. 存的是配置字典？→ 用mapJSONDictionary/mapPlistDictionary，还能配合singleKey做单文件配置；
3. 只是纯文本？→ 直接mapString，一行代码，最轻量。

不确定时记住一个原则：类型越具体越好——优先选Object（Codable）版本 >Dictionary版本 >Any版本，编译期就能帮你挡掉大量错误。

七、源码位置速查

八、常见问题（FAQ）

Q1：map 方法只能在 DiskStorage 上用吗？不是。这些方法定义在所有Value == Data的存储扩展上，任何基于Data的后端（含自定义实现）都能直接使用。

Q2：mapPlist 默认输出什么格式？默认是 XML 格式 plist。想要二进制格式请显式传format: .binary。

Q3：序列化失败会怎样？读取时会抛出带原始数据的DecodingError（见 DiskExtensions.swift），你可以用.fallback(with:)或.defaulting(to:)给存储加上容错回退，避免单条坏数据导致整个功能不可用。

按这份清单选对序列化方法，Shallows 就能帮你把"磁盘字节 ↔ 强类型值"的繁琐工作全部自动化，让你专注于业务逻辑本身。🛶

【免费下载链接】Shallows🛶 Your lightweight persistence toolbox项目地址: https://gitcode.com/gh_mirrors/sh/Shallows