Shallows核心概念完整图解StorageKey, Value与三大协议如何重塑Swift缓存设计【免费下载链接】Shallows Your lightweight persistence toolbox项目地址: https://gitcode.com/gh_mirrors/sh/ShallowsShallows 浅滩是一个 Swift 轻量级持久化工具箱lightweight persistence toolbox它的核心是泛型类型StorageKey, Value与三大存储协议让开发者用统一的接口组合出内存缓存、磁盘缓存等多级缓存方案。本文以图解方式带你 10 分钟看懂 Shallows 的核心概念为什么一个空壳结构体 三个协议就能重塑 Swift 缓存设计。一、Shallows 是什么一个可组合的 Swift 缓存工具箱Shallows 本身不实现任何存储逻辑它是一个抽象层特性说明核心类型StorageKey, Value类型擦除的泛型存储容器设计风格组件化、可组合composition典型用途多级缓存、持久化、跨存储层的数据管道安装方式Swift Package Manager或git clone https://gitcode.com/gh_mirrors/sh/Shallows一句话概括Shallows 给你一套乐高积木——每个存储层都是积木块协议是接口组合操作是拼接方式。二、核心类型 StorageKey, Value一个无逻辑的空容器很多新手会以为Storage里藏着一堆读写逻辑其实恰恰相反——它只是一个持有闭包的空壳源码Sources/Shallows/Storage.swift┌──────────────────────────────┐ │ StorageKey, Value │ │ │ │ storageName: String │ │ _retrieve ──→ ReadOnlyStorage只读闭包 │ _set ────────→ WriteOnlyStorage只写闭包 │ │ │ retrieve(forKey:completion:)│ │ set(_:forKey:completion:) │ └──────────────────────────────┘三个关键设计点全异步retrieve和set都通过 completion 回调返回结果可失败fallible返回值统一包装在ShallowsResult中成功.success/ 失败.failure(error)缓存未命中也是失败由你自己决定兜底策略逻辑可注入你可以传任意读写闭包构造它因此它能包住内存、磁盘、网络、NSCache 任何实现。let storage MemoryStorageString, Int().asStorage() // StorageString, Int storage.retrieve(forKey: some-key) { result in /* ... */ }这里的.asStorage()就是类型擦除入口任何遵循StorageProtocol的实现都能归一化成统一的StorageKey, Value。三、三大协议读、写、全功能的分层抽象Shallows 的协议体系是一棵小树理解它就理解了整个库源码Sources/Shallows/Storage.swift、ReadOnlyStorage.swift、WriteOnlyStorage.swiftReadableStorageProtocol ──┐ (retrieve Key/Value 关联类型) ├──→ StorageProtocol (retrieve set) WritableStorageProtocol ──┘ │ 类型擦除包装器 ReadOnlyStorageKey, Value ← asReadOnlyStorage() WriteOnlyStorageKey, Value ← asWriteOnlyStorage() StorageKey, Value ← asStorage()协议必须实现的方法包装成适用场景ReadableStorageProtocolretrieve(forKey:completion:)ReadOnlyStorage只读数据源如不可变配置WritableStorageProtocolset(_:forKey:completion:)WriteOnlyStorage只写管道如埋点落盘StorageProtocol继承前两者retrievesetStorage完整读写存储这种分层的妙处在于读写能力是独立维度。你不需要暴露写权限就调用asReadOnlyStorage()调用方拿到的ReadOnlyStorage在类型层面根本没有set方法——用编译器而不是运行时来保护数据安全。 内置实现也遵循同一套协议MemoryStorageSources/Shallows/MemoryStorage.swift、DiskStorageSources/Shallows/DiskStorage/DiskStorage.swift、NSCacheStorageSources/Shallows/NSCacheStorage.swift它们都只是协议的一种落地。四、三大组合模式combined / backed / pushingShallows 最核心的概念是组合composition把两个存储层拼成多级缓存。三种组合对应不同的数据流向源码Sources/Shallows/Composition.swift组合方法读retrieve写set典型场景.combined(with:)先查前层未命中查后层并拉回前层同时写入前层和后层内存 磁盘的 L1/L2 缓存.backed(by:)先查前层未命中查后层只写前层不推后层临时缓存磁盘只作只读后备.pushing(to:)只查前层写入前层并推到后层前层可重建后层负责持久化以最常见的combined(with:)为例一次完整的读 未命中流程用户请求 key │ ▼ MemoryStorage ──命中──是──→ 直接返回 │否 ▼ DiskStorage ──命中──是──→ 写入 MemoryStorage回填→ 返回 │否 ▼ 返回 failure可接 fallback 兜底写操作的流程先写MemoryStorage成功后再推到DiskStorage任一层失败即中止。一个真实的组合写法摘自官方 READMElet efficient MemoryStorageFilename, UIImage() .combined(with: imageStorage) // 内存 磁盘二级缓存细节彩蛋️组合后的storageName会自带动画式命名——双向拉取推送是A-B仅从后层拉取是A-B仅推送是A-B互不影响是A-B。调试日志里一眼就能看出缓存流向。五、变换能力mapKeys / mapValues / singleKeyStorage实例还能变形类型系统会跟着精确变化mapValues(to:transformIn:transformOut:)值类型双向转换。例如磁盘存Data读出转UIImage写入再转回Data得到StorageFilename, UIImagemapKeys键类型转换配合RawRepresentable可用字符串枚举直接当 keysingleKey(_:)把键固定为Void变成一个只存一条记录的单例存储——配置项的理想形态let settings DiskStorage.main.folder(settings, in: .applicationSupportDirectory) .mapJSONDictionary() .singleKey(settings) // StorageVoid, [String : Any]此外还有fallback(with:)/defaulting(to:)做错误兜底、zip()把两个存储横向配对、makeSyncStorage()得到同步版本适合脚本与测试。六、自己动手只需两个方法就能扩展 Shallows因为一切归于协议自定义存储的门槛极低遵循StorageProtocol实现retrieve和set两个方法注意自行保证线程安全然后.asStorage()即可接入整套组合、变换体系。只读数据源甚至只需实现retrieve遵循ReadOnlyStorageProtocol即可。库很小、组件化官方也鼓励你直接读源码自己搭核心文件都在Sources/Shallows/下——协议与Storage在 Storage.swift组合逻辑在 Composition.swift磁盘层在 DiskStorage/DiskStorage.swift测试用例含组合行为的完整断言在Tests/ShallowsTests/CompositionSpec.swift。七、总结一张表看懂 Shallows 设计哲学概念关键词记住一句话StorageKey, Value类型擦除它不存储它只是读闭包 写闭包的外壳三大协议能力分层读、写是独立维度编译器帮你守住只读边界combined/backed/pushing组合数据流向不同缓存行为不同mapKeys/mapValues变换每层变换都精确改变泛型参数自定义存储扩展点实现两个方法即插即用Shallows 的哲学可以浓缩为一句话把缓存在哪和怎么用彻底解耦——存储位置可替换、可叠加而你的业务代码始终面对同一个StorageKey, Value接口。这正是它轻量却能重塑 Swift 缓存设计的原因。⛵【免费下载链接】Shallows Your lightweight persistence toolbox项目地址: https://gitcode.com/gh_mirrors/sh/Shallows创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考