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

Shallows序列化能力清单JSON、Plist与String存储映射全覆盖指南【免费下载链接】Shallows Your lightweight persistence toolbox项目地址: https://gitcode.com/gh_mirrors/sh/ShallowsShallows 是一个轻量级的 Swift 持久化工具箱persistence toolbox它的核心类型StorageKey, Value可以通过 7 个便捷的 map 序列化方法把磁盘上原始的Data直接映射成 JSON、Plist 或 String 等类型安全的存储——本文为你整理这份 JSON、Plist 与 String 存储映射的完整能力清单帮你快速选对序列化方案。一、3 秒看懂 Shallows 的序列化模型Shallows 的设计思路非常简洁所有序列化都建立在一个统一模型之上Data 存储DiskStorage │ mapString / mapJSON / mapPlist ▼ 类型安全存储 StorageKey, 你的类型底层DiskStorage 负责把Data读写到磁盘文件序列化层DiskExtensions.swift 在Value Data的存储上提供 7 个 map 方法读取时反序列化、写入时序列化全程自动完成上层你只需要用强类型的值比如一个Codable结构体直接set/retrieve再也不用手写编码解码逻辑。let diskStorage DiskStorage.main.folder(cities, in: .cachesDirectory) .mapJSONObject(City.self) // StorageFilename, City自动 JSON 序列化/反序列化 这 7 个方法定义在extension StorageProtocol where Value Data上见 DiskExtensions.swift所以任何产出Data的存储磁盘、文件、自定义后端都可以直接挂上这些序列化能力。二、Shallows 序列化方法完整清单一张表看懂方法映射结果底层技术默认参数mapString(withEncoding:)StorageKey, StringString.Encoding.utf8mapJSON(readingOptions:writingOptions:)StorageKey, AnyJSONSerialization空选项mapJSONDictionary(...)StorageKey, [String: Any]JSONSerialization空选项mapJSONObject(_:decoder:encoder:)StorageKey, CodableJSONDecoder/JSONEncoder默认实例mapPlist(format:readOptions:writeOptions:)StorageKey, AnyPropertyListSerializationXML 格式mapPlistDictionary(...)StorageKey, [String: Any]PropertyListSerializationXML 格式mapPlistObject(_:decoder:encoder:)StorageKey, CodablePropertyListDecoder/PropertyListEncoder默认实例每个格式家族都提供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 的singleKeylet settings DiskStorage.main.folder(settings, in: .applicationSupportDirectory) .mapJSONDictionary() .singleKey(settings) // StorageVoid, [String : Any]3. 通用任意 JSONmapJSON最宽松的版本值可以是任意 JSON 结构数组、数字、字典均可代价是返回类型为Any需要自行类型转换。三个方法均支持传入readingOptions/writingOptions如JSONSerialization.WritingOptions.prettyPrinted输出格式化 JSON。四、Plist 序列化苹果生态的原生选择1. 存 Codable 模型mapPlistObject与mapJSONObject完全对等只是底层换成PropertyListEncoder/PropertyListDecoder适合与苹果生态工具如 Xcode 工程文件、UserDefaults风格配置互通的场景。2. 存键值配置mapPlistDictionary映射结果为[String: Any]字典适合.plist风格的设置文件。3. 通用任意 PlistmapPlist⚠️新手注意format参数默认是.xml格式见 DiskExtensions.swift 的默认值如果需要二进制 plist 请显式传.binarylet plistStorage DiskStorage.main.folder(config, in: .applicationSupportDirectory) .mapPlist(format: .binary) // 显式指定二进制格式五、String 序列化最轻量的一档一行代码搞定文本存储mapString适合存纯文本、日志片段、小配置字符串等。默认编码为UTF-8也可换成.ascii、.utf16等任意String.Encodinglet strings DiskStorage.main.folder(strings, in: .cachesDirectory) .mapString(withEncoding: .utf8) .makeSyncStorage() // SyncStorageString, String同步读写 try strings.set(hello.uppercased(), forKey: hello) 序列化 组合是 Shallows 的王牌组合先把磁盘存储映射成 String/JSON 类型再与MemoryStorage组合成内存 磁盘两级缓存既类型安全又高效。六、3 步选型哪种序列化方法最适合你有Codable模型→ 首选mapJSONObject跨平台通用或mapPlistObject苹果生态存的是配置字典→ 用mapJSONDictionary/mapPlistDictionary还能配合singleKey做单文件配置只是纯文本→ 直接mapString一行代码最轻量。不确定时记住一个原则类型越具体越好——优先选ObjectCodable版本 Dictionary版本 Any版本编译期就能帮你挡掉大量错误。七、源码位置速查功能文件位置7 个序列化 map 方法DiskExtensions.swift磁盘存储实现DiskStorage.swiftStorage 核心类型与 singleKeyStorage.swift内存存储MemoryStorage.swift存储组合combined / backed / pushingComposition.swift序列化用法示例XCTest.swift八、常见问题FAQQ1map 方法只能在 DiskStorage 上用吗不是。这些方法定义在所有Value Data的存储扩展上任何基于Data的后端含自定义实现都能直接使用。Q2mapPlist 默认输出什么格式默认是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考