协议概述 该协议族用于规范 iOS 应用中图片缓存与获取流程，统一组件间的图片读取、写入、预取、失效与解码策略，目标是：

• 两级缓存：优先命中内存缓存，其次命中磁盘缓存，未命中再走网络（由上层调用方实现）
• TTL 和容量控制：支持全局与条目级 TTL；按容量（字节）淘汰
• 统一键生成：可配置的 Key 生成规则，避免重复下载
• 并发安全：协议要求线程安全（Sendable），默认采用 async/await
• 占位与预取：提供占位图获取与滚动场景的预取 API
• 解码选项扩展点：支持下采样等解码策略的扩展

适用场景：Feed 流与详情页的图片加载，减少重复下载，并在快速滑动时确保高命中与主线程流畅。

协议定义 以下为一组互补的协议与配套类型，覆盖键生成、解码选项、缓存层与统一获取接口。

import UIKit

// MARK: - 基础类型

/// 磁盘/内存命中来源
public enum ImageSource {
    case memory
    case disk
    case network
}

/// 失效与清理的目标范围
public enum CacheScope {
    case memory
    case disk
    case all
}

/// 解码选项（可扩展）
public struct ImageDecodingOptions: Sendable, Equatable {
    public enum ContentMode: Sendable {
        case fill
        case fit
    }
    public var downsampleToPixelSize: CGSize? // 若提供，则进行下采样解码
    public var scale: CGFloat                 // 目标屏幕 scale
    public var contentMode: ContentMode       // 下采样适配策略

    public init(downsampleToPixelSize: CGSize? = nil,
                scale: CGFloat = UIScreen.main.scale,
                contentMode: ContentMode = .fit) {
        self.downsampleToPixelSize = downsampleToPixelSize
        self.scale = scale
        self.contentMode = contentMode
    }
}

/// 请求模型：统一承载缓存与解码所需参数
public struct ImageRequest: Sendable, Hashable {
    public var url: URL
    public var overrideKey: String?              // 若提供则使用此 Key
    public var decodingOptions: ImageDecodingOptions
    public var cachePolicy: CachePolicy          // 读取缓存的策略
    public var userInfo: [String: AnyHashable]?  // 业务透传

    public init(url: URL,
                overrideKey: String? = nil,
                decodingOptions: ImageDecodingOptions = .init(),
                cachePolicy: CachePolicy = .default,
                userInfo: [String: AnyHashable]? = nil) {
        self.url = url
        self.overrideKey = overrideKey
        self.decodingOptions = decodingOptions
        self.cachePolicy = cachePolicy
        self.userInfo = userInfo
    }
}

/// 读取策略（示例）
public enum CachePolicy: Sendable {
    case `default`                 // 先内存->磁盘；过期则跳过
    case reloadIgnoringMemory      // 忽略内存，查磁盘
    case reloadIgnoringCache       // 忽略缓存，走网络（交由上层处理）
    case returnCacheElseLoad       // 有就返回，无则上层走网络
}

/// 统一返回
public struct ImageLoadResult: Sendable {
    public let image: UIImage
    public let source: ImageSource
    public let key: String
}

// MARK: - 键生成

/// 图片缓存键生成
public protocol ImageKeyProviding: Sendable {
    /// 根据请求生成稳定且唯一的 Key。
    /// 注意：Key 应当包含影响像素内容的参数（如 URL、尺寸、解码选项等），避免“不同显示需求命中同一文件”的错误复用。
    func makeKey(for request: ImageRequest) -> String
}

// MARK: - 缓存协议（两级缓存）

/// 两级缓存（内存 + 磁盘），具备 TTL 与容量控制。
/// 线程安全要求：实现类型必须是并发安全的（推荐使用 actor/锁），并符合 Sendable。
public protocol ImageCache: Sendable {
    // 配置
    var memoryCapacityBytes: Int { get set }    // 内存容量上限（字节）
    var diskCapacityBytes: Int { get set }      // 磁盘容量上限（字节）
    var defaultTTL: TimeInterval { get set }    // 默认 TTL（秒）

    var keyProvider: ImageKeyProviding { get }

    // 读取
    func image(forKey key: String,
               decoding: ImageDecodingOptions?) async -> UIImage?

    // 写入
    /// - Parameters:
    ///   - image: 已解码图片，建议写入内存。
    ///   - originalData: 原始编码数据（若有则用于磁盘写入；无则根据 image 编码写入）。
    ///   - key: 缓存键
    ///   - ttl: 条目级 TTL（若 nil 则使用 defaultTTL）
    ///   - costHintBytes: 内存 cost 估算（可 nil，由实现方估算）
    func store(image: UIImage,
               originalData: Data?,
               forKey key: String,
               ttl: TimeInterval?,
               costHintBytes: Int?) async

    // 命中检查
    func contains(_ key: String, in scope: CacheScope) async -> Bool

    // 失效与清理
    func remove(_ key: String, in scope: CacheScope) async
    func removeAll(in scope: CacheScope) async

    // 维护（可选增强）
    func trimToCapacityIfNeeded() async
}

// MARK: - 占位与预取

/// 占位图提供
public protocol ImagePlaceholderProviding: Sendable {
    func placeholder(for request: ImageRequest) -> UIImage?
}

/// 预取协议：用于快速滑动场景提前将磁盘项提升到内存，或提前下载写入磁盘。
public protocol ImagePrefetching: Sendable {
    /// 提前调度请求，使随后的正式加载快速命中（内存或磁盘）。
    func prefetch(_ requests: [ImageRequest])
    func cancelPrefetch(for requests: [ImageRequest])
}

// MARK: - 统一获取接口（组合）

/// 面向业务的统一入口：先查缓存（内存->磁盘->解码），未命中则由实现方决定是否走网络并回写缓存。
public protocol ImageProvider: Sendable, ImagePrefetching {
    var cache: ImageCache { get }
    var keyProvider: ImageKeyProviding { get }
    var placeholderProvider: ImagePlaceholderProviding? { get }

    /// 统一获取图片。实现方可按 request.cachePolicy 决定是否/如何走网络。
    func loadImage(with request: ImageRequest) async throws -> ImageLoadResult

    /// 失效处理
    func invalidate(keys: [String], scope: CacheScope) async
}

方法说明

• ImageKeyProviding

  • makeKey(for:):
    • 用途：从请求生成稳定的缓存键
    • 参数：request（包含 URL、解码选项、尺寸等）
    • 返回：字符串 Key
    • 注意：Key 必须包含像素相关参数（例如下采样尺寸、scale），避免同 URL 不同显示需求错误复用

• ImageCache

  • image(forKey:decoding:):
    • 用途：按 Key 读取图片。应先查内存；内存未命中则查磁盘并按 decoding 选项解码，再回填内存
    • 参数：key（缓存键）、decoding（解码选项，可为 nil）
    • 返回：UIImage 或 nil
  • store(image:originalData:forKey:ttl:costHintBytes:):
    • 用途：写入内存与磁盘；TTL 控制过期时间；容量控制在写入后触发裁剪
    • 参数：
      • image：已解码图片（写内存）
      • originalData：原始数据（优先写磁盘），缺省时可基于 image 编码
      • key：缓存键
      • ttl：条目级 TTL（nil 使用 defaultTTL）
      • costHintBytes：内存 cost 估算（如像素数×4）
  • contains(_:in:):
    • 用途：判断指定范围内是否存在有效缓存（未过期）
  • remove(_:in:), removeAll(in:):
    • 用途：删除指定键或全清空；scope 决定目标层级
  • trimToCapacityIfNeeded():
    • 用途：按容量上限在后台裁剪（LRU/按访问时间等）

• ImagePlaceholderProviding

  • placeholder(for:):
    • 用途：提供 UI 立即可用的占位图
    • 注意：不应阻塞主线程（可返回预制图片）

• ImagePrefetching

  • prefetch(_:), cancelPrefetch(for:):
    • 用途：在快速滑动中提前调度读取/下载，提升命中率
    • 注意：实现方应去重、限并发与可取消

• ImageProvider

  • loadImage(with:):
    • 用途：统一入口：内存->磁盘->（可选）网络；网络成功后应回填缓存
    • 返回：ImageLoadResult（包含来源与最终 Key）
    • 错误：可抛出网络或解码错误
  • invalidate(keys:scope:):
    • 用途：对外暴露的失效操作，便于业务统一驱动清理

属性说明

• ImageCache.memoryCapacityBytes, diskCapacityBytes
  • 缓存容量上限（字节），用于触发淘汰策略（建议 LRU）
• ImageCache.defaultTTL
  • 默认过期时间（秒），条目级 TTL 优先级更高
• ImageCache.keyProvider / ImageProvider.keyProvider
  • Key 生成器，确保组件间统一
• ImageProvider.placeholderProvider
  • 占位图提供者，UI 层可在加载前同步获取

使用示例 以下示例包含：

• DefaultKeyProvider：默认 Key 规则
• DefaultImageCache：两级缓存实现（actor 并发安全，含 TTL 与容量裁剪）
• DefaultImageProvider：统一获取接口（包含简单的网络下载）
• 预取与占位示例

说明：示例为教学用途，聚焦核心路径与正确性，省略了部分健壮性（如错误域细分、磁盘 LRU 更精细的实现等），可直接编译运行于 iOS 15+。

import UIKit
import CryptoKit

// MARK: - Key Provider

public struct DefaultKeyProvider: ImageKeyProviding {
    public init() {}
    public func makeKey(for request: ImageRequest) -> String {
        if let override = request.overrideKey { return override }
        // 组合 URL + 解码关键参数，避免错误复用
        let base = [
            request.url.absoluteString,
            "dps=\(request.decodingOptions.downsampleToPixelSize?.debugDescription ?? "nil")",
            "sc=\(request.decodingOptions.scale)",
            "cm=\(request.decodingOptions.contentMode)"
        ].joined(separator: "|")
        // 哈希缩短长度
        let digest = Insecure.MD5.hash(data: Data(base.utf8))
        return digest.map { String(format: "%02hhx", $0) }.joined()
    }
}

// MARK: - 内存缓存（TTL + NSCache）

actor MemoryCacheBox {
    private let cache = NSCache<NSString, UIImage>()
    private var expiry: [String: Date] = [:]

    init(capacityBytes: Int) {
        cache.totalCostLimit = capacityBytes
    }

    func updateCapacity(_ bytes: Int) {
        cache.totalCostLimit = bytes
    }

    func image(forKey key: String, now: Date) -> UIImage? {
        if let exp = expiry[key], exp < now {
            cache.removeObject(forKey: key as NSString)
            expiry.removeValue(forKey: key)
            return nil
        }
        return cache.object(forKey: key as NSString)
    }

    func set(image: UIImage, forKey key: String, ttl: TimeInterval, cost: Int) {
        let expireAt = Date().addingTimeInterval(ttl)
        expiry[key] = expireAt
        cache.setObject(image, forKey: key as NSString, cost: cost)
    }

    func contains(_ key: String, now: Date) -> Bool {
        if let _ = image(forKey: key, now: now) { return true }
        return false
    }

    func remove(_ key: String) {
        cache.removeObject(forKey: key as NSString)
        expiry.removeValue(forKey: key)
    }

    func removeAll() {
        cache.removeAllObjects()
        expiry.removeAll()
    }
}

// MARK: - 磁盘缓存（TTL + 容量）

actor DiskCacheBox {
    private let fm = FileManager()
    private let directory: URL
    private var diskCapacityBytes: Int
    private let metaExt = "meta" // sidecar 元数据文件后缀

    struct Meta: Codable {
        let expireAt: Date
        let length: Int
        let lastAccessAt: Date
    }

    init(directoryName: String = "DefaultImageDiskCache", diskCapacityBytes: Int) throws {
        let base = try fm.url(for: .cachesDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
        directory = base.appendingPathComponent(directoryName, isDirectory: true)
        if !fm.fileExists(atPath: directory.path) {
            try fm.createDirectory(at: directory, withIntermediateDirectories: true)
        }
        self.diskCapacityBytes = diskCapacityBytes
    }

    func updateCapacity(_ bytes: Int) {
        self.diskCapacityBytes = bytes
    }

    private func dataURL(for key: String) -> URL { directory.appendingPathComponent(key) }
    private func metaURL(for key: String) -> URL { directory.appendingPathComponent(key).appendingPathExtension(metaExt) }

    func read(for key: String, now: Date) -> Data? {
        let dURL = dataURL(for: key)
        let mURL = metaURL(for: key)
        guard
            fm.fileExists(atPath: dURL.path),
            let mdata = try? Data(contentsOf: mURL),
            let meta = try? JSONDecoder().decode(Meta.self, from: mdata)
        else { return nil }

        if meta.expireAt < now {
            try? fm.removeItem(at: dURL)
            try? fm.removeItem(at: mURL)
            return nil
        }

        // 更新访问时间
        let newMeta = Meta(expireAt: meta.expireAt, length: meta.length, lastAccessAt: now)
        if let updated = try? JSONEncoder().encode(newMeta) {
            try? updated.write(to: mURL, options: .atomic)
        }
        return try? Data(contentsOf: dURL)
    }

    func write(data: Data, for key: String, ttl: TimeInterval) {
        let dURL = dataURL(for: key)
        let mURL = metaURL(for: key)
        do {
            try data.write(to: dURL, options: .atomic)
            let meta = Meta(expireAt: Date().addingTimeInterval(ttl),
                            length: data.count,
                            lastAccessAt: Date())
            let mdata = try JSONEncoder().encode(meta)
            try mdata.write(to: mURL, options: .atomic)
        } catch {
            // 失败则尝试清理并忽略
        }
        Task { await trimIfNeeded() }
    }

    func contains(_ key: String, now: Date) -> Bool {
        return read(for: key, now: now) != nil
    }

    func remove(_ key: String) {
        try? fm.removeItem(at: dataURL(for: key))
        try? fm.removeItem(at: metaURL(for: key))
    }

    func removeAll() {
        guard let items = try? fm.contentsOfDirectory(atPath: directory.path) else { return }
        for i in items {
            try? fm.removeItem(at: directory.appendingPathComponent(i))
        }
    }

    private func directorySizeAndMetas() -> (Int, [(String, Meta)]) {
        guard let items = try? fm.contentsOfDirectory(atPath: directory.path) else { return (0, []) }
        var total = 0
        var metas: [(String, Meta)] = []
        for name in items where !name.hasSuffix(".\(metaExt)") {
            let key = name
            let dURL = directory.appendingPathComponent(name)
            let mURL = metaURL(for: key)
            guard let mdata = try? Data(contentsOf: mURL),
                  let meta = try? JSONDecoder().decode(Meta.self, from: mdata)
            else { continue }
            total += meta.length
            metas.append((key, meta))
        }
        return (total, metas)
    }

    func trimIfNeeded() {
        var (total, metas) = directorySizeAndMetas()
        guard total > diskCapacityBytes else { return }
        // 按 lastAccessAt 升序淘汰
        metas.sort { $0.1.lastAccessAt < $1.1.lastAccessAt }
        for (key, meta) in metas {
            if total <= diskCapacityBytes { break }
            remove(key)
            total -= meta.length
        }
    }
}

// MARK: - 解码工具（下采样）

enum ImageDecode {
    static func decode(data: Data, options: ImageDecodingOptions?) -> UIImage? {
        guard let options, let target = options.downsampleToPixelSize else {
            return UIImage(data: data, scale: options?.scale ?? UIScreen.main.scale)
        }
        let cfData = data as CFData
        guard let src = CGImageSourceCreateWithData(cfData, nil) else {
            return UIImage(data: data, scale: options.scale)
        }
        let maxPixel: CGFloat = {
            switch options.contentMode {
            case .fit:
                return max(target.width, target.height)
            case .fill:
                return min(target.width, target.height)
            }
        }()
        let dict: [CFString: Any] = [
            kCGImageSourceCreateThumbnailFromImageAlways: true,
            kCGImageSourceCreateThumbnailWithTransform: true,
            kCGImageSourceThumbnailMaxPixelSize: Int(maxPixel)
        ]
        guard let cg = CGImageSourceCreateThumbnailAtIndex(src, 0, dict as CFDictionary) else {
            return UIImage(data: data, scale: options.scale)
        }
        return UIImage(cgImage: cg, scale: options.scale, orientation: .up)
    }

    static func estimatedMemoryCostBytes(for image: UIImage) -> Int {
        guard let cg = image.cgImage else {
            let size = image.size
            let scale = image.scale
            return Int(size.width * scale * size.height * scale * 4)
        }
        return cg.bytesPerRow * cg.height
    }
}

// MARK: - 默认两级缓存实现

public final class DefaultImageCache: ImageCache {
    public var memoryCapacityBytes: Int {
        didSet { Task { await memory.updateCapacity(memoryCapacityBytes) } }
    }
    public var diskCapacityBytes: Int {
        didSet { Task { await disk.updateCapacity(diskCapacityBytes) } }
    }
    public var defaultTTL: TimeInterval
    public let keyProvider: ImageKeyProviding

    private let memory: MemoryCacheBox
    private let disk: DiskCacheBox

    public init(memoryCapacityBytes: Int = 64 * 1024 * 1024,
                diskCapacityBytes: Int = 512 * 1024 * 1024,
                defaultTTL: TimeInterval = 7 * 24 * 3600,
                keyProvider: ImageKeyProviding = DefaultKeyProvider()) {
        self.memoryCapacityBytes = memoryCapacityBytes
        self.diskCapacityBytes = diskCapacityBytes
        self.defaultTTL = defaultTTL
        self.keyProvider = keyProvider
        self.memory = MemoryCacheBox(capacityBytes: memoryCapacityBytes)
        self.disk = try! DiskCacheBox(diskCapacityBytes: diskCapacityBytes)
    }

    public func image(forKey key: String,
                      decoding: ImageDecodingOptions?) async -> UIImage? {
        let now = Date()
        if let img = await memory.image(forKey: key, now: now) { return img }
        // 磁盘命中则解码并回填内存
        if let data = await disk.read(for: key, now: now),
           let img = ImageDecode.decode(data: data, options: decoding) {
            let cost = ImageDecode.estimatedMemoryCostBytes(for: img)
            await memory.set(image: img, forKey: key, ttl: defaultTTL, cost: cost)
            return img
        }
        return nil
    }

    public func store(image: UIImage,
                      originalData: Data?,
                      forKey key: String,
                      ttl: TimeInterval?,
                      costHintBytes: Int?) async {
        let ttlValue = ttl ?? defaultTTL
        let cost = costHintBytes ?? ImageDecode.estimatedMemoryCostBytes(for: image)
        await memory.set(image: image, forKey: key, ttl: ttlValue, cost: cost)
        // 优先写入原始数据，否则回退编码 PNG（注意：PNG 编码成本较高）
        if let data = originalData {
            await disk.write(data: data, for: key, ttl: ttlValue)
        } else if let data = image.pngData() {
            await disk.write(data: data, for: key, ttl: ttlValue)
        }
    }

    public func contains(_ key: String, in scope: CacheScope) async -> Bool {
        let now = Date()
        switch scope {
        case .memory:
            return await memory.contains(key, now: now)
        case .disk:
            return await disk.contains(key, now: now)
        case .all:
            return await memory.contains(key, now: now) || await disk.contains(key, now: now)
        }
    }

    public func remove(_ key: String, in scope: CacheScope) async {
        switch scope {
        case .memory: await memory.remove(key)
        case .disk: await disk.remove(key)
        case .all:
            await memory.remove(key)
            await disk.remove(key)
        }
    }

    public func removeAll(in scope: CacheScope) async {
        switch scope {
        case .memory: await memory.removeAll()
        case .disk: await disk.removeAll()
        case .all:
            await memory.removeAll()
            await disk.removeAll()
        }
    }

    public func trimToCapacityIfNeeded() async {
        await disk.trimIfNeeded()
        // NSCache 自动按 totalCostLimit 淘汰，无需手动
    }
}

// MARK: - 占位提供者

public struct DefaultPlaceholderProvider: ImagePlaceholderProviding {
    public init() {}
    public func placeholder(for request: ImageRequest) -> UIImage? {
        // 简单的灰底占位，实现不应阻塞
        let size = CGSize(width: 16, height: 16)
        let format = UIGraphicsImageRendererFormat()
        format.scale = UIScreen.main.scale
        let img = UIGraphicsImageRenderer(size: size, format: format).image { ctx in
            UIColor(white: 0.95, alpha: 1).setFill()
            ctx.fill(CGRect(origin: .zero, size: size))
        }
        return img
    }
}

// MARK: - 默认 Provider（带网络）

public final class DefaultImageProvider: ImageProvider {
    public let cache: ImageCache
    public let keyProvider: ImageKeyProviding
    public let placeholderProvider: ImagePlaceholderProviding?

    private let session: URLSession
    private let decoder = ImageDecode.self
    private let defaultTTL: TimeInterval

    public init(cache: ImageCache = DefaultImageCache(),
                keyProvider: ImageKeyProviding = DefaultKeyProvider(),
                placeholderProvider: ImagePlaceholderProviding? = DefaultPlaceholderProvider(),
                session: URLSession = .shared,
                defaultTTL: TimeInterval = 7 * 24 * 3600) {
        self.cache = cache
        self.keyProvider = keyProvider
        self.placeholderProvider = placeholderProvider
        self.session = session
        self.defaultTTL = defaultTTL
    }

    public func loadImage(with request: ImageRequest) async throws -> ImageLoadResult {
        let key = keyProvider.makeKey(for: request)

        // 1) 按策略尝试缓存读取
        switch request.cachePolicy {
        case .reloadIgnoringCache:
            break
        case .reloadIgnoringMemory:
            if let img = await cache.image(forKey: key, decoding: request.decodingOptions) {
                // 已经从磁盘回填到内存，无需额外处理
                return ImageLoadResult(image: img, source: .disk, key: key)
            }
        default:
            if let img = await cache.image(forKey: key, decoding: request.decodingOptions) {
                return ImageLoadResult(image: img, source: .memory, key: key)
            }
        }

        // 2) 走网络
        var urlRequest = URLRequest(url: request.url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 30)
        let (data, response) = try await session.data(for: urlRequest)
        guard let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode) else {
            throw URLError(.badServerResponse)
        }

        // 3) 解码（遵循 request.decodingOptions）
        guard let image = decoder.decode(data: data, options: request.decodingOptions) else {
            throw URLError(.cannotDecodeContentData)
        }

        // 4) 回写缓存
        await cache.store(image: image, originalData: data, forKey: key, ttl: defaultTTL, costHintBytes: nil)

        return ImageLoadResult(image: image, source: .network, key: key)
    }

    // MARK: ImagePrefetching

    private var prefetchTasks = [String: Task<Void, Never>]()
    public func prefetch(_ requests: [ImageRequest]) {
        for req in requests {
            let key = keyProvider.makeKey(for: req)
            if prefetchTasks[key] != nil { continue }
            // 若内存或磁盘已命中则跳过网络
            let task = Task.detached(priority: .utility) { [weak self] in
                guard let self else { return }
                if await self.cache.image(forKey: key, decoding: req.decodingOptions) != nil { return }
                var urlRequest = URLRequest(url: req.url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 15)
                if let (data, resp) = try? await self.session.data(for: urlRequest),
                   let http = resp as? HTTPURLResponse, (200..<300).contains(http.statusCode),
                   let image = ImageDecode.decode(data: data, options: req.decodingOptions) {
                    await self.cache.store(image: image, originalData: data, forKey: key, ttl: self.defaultTTL, costHintBytes: nil)
                }
            }
            prefetchTasks[key] = task
        }
    }

    public func cancelPrefetch(for requests: [ImageRequest]) {
        for req in requests {
            let key = keyProvider.makeKey(for: req)
            prefetchTasks[key]?.cancel()
            prefetchTasks.removeValue(forKey: key)
        }
    }

    public func invalidate(keys: [String], scope: CacheScope) async {
        for k in keys { await cache.remove(k, in: scope) }
    }
}

// MARK: - 使用示例（UIKit）

final class FeedImageView: UIImageView {
    private var task: Task<Void, Never>?

    func setImage(with request: ImageRequest, provider: ImageProvider) {
        task?.cancel()
        self.image = provider.placeholderProvider?.placeholder(for: request)

        task = Task { [weak self] in
            guard let self else { return }
            do {
                let result = try await provider.loadImage(with: request)
                // UI 更新在主线程
                await MainActor.run { self.image = result.image }
            } catch {
                // 可设置错误占位
            }
        }
    }

    func cancelLoad() {
        task?.cancel()
        task = nil
    }
}

// MARK: - 结合 UICollectionView 预取（示意）

final class FeedViewController: UIViewController, UICollectionViewDataSource, UICollectionViewDataSourcePrefetching {
    let provider = DefaultImageProvider()
    var items: [URL] = []

    func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int { items.count }

    func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "cell", for: indexPath) as! FeedCell
        let url = items[indexPath.item]
        let req = ImageRequest(url: url, decodingOptions: .init(downsampleToPixelSize: CGSize(width: 400, height: 400)))
        cell.imageView.setImage(with: req, provider: provider)
        return cell
    }

    // 预取：提前下载并落盘/入内存
    func collectionView(_ collectionView: UICollectionView, prefetchItemsAt indexPaths: [IndexPath]) {
        let reqs = indexPaths.map { idx in
            ImageRequest(url: items[idx.item], decodingOptions: .init(downsampleToPixelSize: CGSize(width: 400, height: 400)))
        }
        provider.prefetch(reqs)
    }

    func collectionView(_ collectionView: UICollectionView, cancelPrefetchingForItemsAt indexPaths: [IndexPath]) {
        let reqs = indexPaths.map { idx in
            ImageRequest(url: items[idx.item], decodingOptions: .init(downsampleToPixelSize: CGSize(width: 400, height: 400)))
        }
        provider.cancelPrefetch(for: reqs)
    }
}

final class FeedCell: UICollectionViewCell {
    let imageView = FeedImageView()
    override init(frame: CGRect) {
        super.init(frame: frame)
        contentView.addSubview(imageView)
        imageView.frame = contentView.bounds
        imageView.contentMode = .scaleAspectFill
        imageView.clipsToBounds = true
    }
    required init?(coder: NSCoder) { fatalError() }
}

注意事项

• 并发与线程安全

  • 协议实现需满足 Sendable 与并发安全。示例通过 actor 封装内存/磁盘状态；NSCache 本身是线程安全的，但 TTL 元数据需要 actor 保护
  • URLSession 回调为任意线程，UI 更新需切回主线程

• Key 生成规则

  • Key 必须包含会影响像素内容的参数（URL、下采样尺寸、scale、contentMode 等），避免错误命中
  • 对于带鉴权或动态查询参数的 URL，如参数不影响像素内容，建议在生成 Key 前做归一化处理

• TTL 与容量控制

  • TTL：示例对内存与磁盘均生效。磁盘以 sidecar 元数据存 expireAt/lastAccessAt 实现过期与近似 LRU
  • 容量：内存依赖 NSCache totalCostLimit；磁盘示例按 lastAccessAt 近似 LRU 裁剪。生产中可维护更精细的访问日志或使用文件访问时间

• 解码与下采样

  • 解码在后台进行，避免主线程阻塞
  • 下采样目标尺寸建议使用“像素尺寸”，并结合屏幕 scale
  • 若需要渐进式/动图解码，可在 ImageDecodingOptions 扩展相应字段并扩展解码实现

• 占位与预取

  • 占位图应为轻量级、同步可得的 UIImage
  • 预取应避免重复与过度并发，注意在列表快速滚动时取消不再可见项的预取

• 网络与缓存一致性

  • 当请求的 HTTP 响应包含强缓存/协商缓存头时，可结合 URLCache 或自行将 TTL 绑定到响应头（如 Cache-Control max-age）来设定 per-entry TTL
  • 对错误响应应避免写入磁盘；对过大的图片建议直接下采样后写入，降低磁盘与内存压力

• 内存告警

  • 可在收到 UIApplication.didReceiveMemoryWarningNotification 时调用 removeAll(in: .memory)

• 单元测试建议

  • 覆盖点：Key 生成一致性、TTL 过期、容量裁剪、并发访问一致性、下采样正确性、网络失败回退、预取取消行为

通过以上协议与示例实现，可在 Feed 流和详情页中实现一致的图片获取与失效处理，降低重复下载，提升滑动场景的命中率与 UI 流畅度。

协议概述

该协议集用于统一约定“表单字段与整表校验流程”，覆盖以下能力：

• 支持同步/异步规则验证（如本地规则与远程用户名占用校验）
• 错误消息本地化（基于Localizable.strings）
• 依赖字段联动（如“密码不包含用户名”）
• 可组合校验器（顺序执行、失败收集策略）
• 实时校验与提交时校验两种模式
• 整表结果聚合与回调提示

适用场景：登录/注册页等表单组件，对用户名/密码/验证码进行实时校验，并在提交前汇总错误提示以提升转化。

注：示例基于 Swift 5.7+、iOS 15+（使用 async/await），不依赖第三方库，适合初级开发者集成与扩展。

协议定义

import Foundation

// MARK: - 错误本地化

/// 错误本地化协议：将 messageKey + arguments 转换为最终文案
public protocol ErrorLocalizer {
    /// - Parameters:
    ///   - key: 本地化 key（Localizable.strings）
    ///   - arguments: 文案占位符参数
    ///   - locale: 目标本地化区域（可忽略，系统会根据用户设置选择）
    func localizedString(for key: String, arguments: [String], locale: Locale) -> String
}

/// 默认基于主 Bundle 的本地化实现
public struct BundleErrorLocalizer: ErrorLocalizer {
    public let table: String?
    public let bundle: Bundle

    public init(table: String? = nil, bundle: Bundle = .main) {
        self.table = table
        self.bundle = bundle
    }

    public func localizedString(for key: String, arguments: [String], locale: Locale) -> String {
        let format = NSLocalizedString(key, tableName: table, bundle: bundle, comment: "")
        return String(format: format, arguments: arguments)
    }
}

// MARK: - 校验模型

/// 单条校验问题
public struct ValidationIssue: Equatable, Sendable {
    /// 字段标识（推荐使用固定字符串，如 "username"、"password"）
    public let fieldID: String
    /// 问题代码（便于统计/埋点）
    public let code: String
    /// 本地化 key（Localizable.strings）
    public let messageKey: String
    /// 文案占位符参数（字符串形式）
    public let arguments: [String]

    public init(fieldID: String, code: String, messageKey: String, arguments: [String] = []) {
        self.fieldID = fieldID
        self.code = code
        self.messageKey = messageKey
        self.arguments = arguments
    }

    /// 通过 Localizer 获取最终展示文案
    public func message(using localizer: ErrorLocalizer, locale: Locale) -> String {
        localizer.localizedString(for: messageKey, arguments: arguments, locale: locale)
    }
}

/// 校验上下文：提供跨字段访问与本地化环境
public struct ValidationContext {
    /// 全量字段值快照（值类型为 Any，规则内自行转换）
    public let values: [String: Any]
    /// 当前本地化区域
    public let locale: Locale
    /// 文案本地化器
    public let localizer: ErrorLocalizer

    public init(values: [String: Any], locale: Locale, localizer: ErrorLocalizer) {
        self.values = values
        this.locale = locale
        self.localizer = localizer
    }

    /// 按字段读取并转换为目标类型
    public func value<T>(for fieldID: String, as type: T.Type = T.self) -> T? {
        values[fieldID] as? T
    }
}

// MARK: - 单字段规则

/// 单字段规则（支持同步 + 异步）
public protocol FieldRule {
    /// 规则标识（便于调试与埋点）
    var id: String { get }

    /// 同步校验（常用于非网络类规则）
    /// - Returns: 存在问题返回单条问题，无问题返回 nil
    func validate(value: Any?, context: ValidationContext) -> ValidationIssue?

    /// 异步校验（常用于网络校验），默认无问题
    func validateAsync(value: Any?, context: ValidationContext) async -> ValidationIssue?
}

public extension FieldRule {
    func validateAsync(value: Any?, context: ValidationContext) async -> ValidationIssue? { nil }
}

// MARK: - 组合策略

/// 多规则组合策略
public enum CompositionStrategy {
    /// 遇到第一条失败即停止（性能优先/体验常用）
    case stopAtFirstFailure
    /// 收集全部失败（用于提交汇总）
    case collectAllFailures
}

// MARK: - 表单级别

/// 表单校验模式
public enum FormValidationMode {
    /// 实时校验（输入过程中触发）
    case realtime
    /// 提交时校验（点击提交按钮时一次性校验）
    case onSubmit
}

/// 表单校验协议：聚合字段规则、执行校验、提供结果回调
public protocol FormValidating: AnyObject {
    /// 模式：实时/提交时
    var mode: FormValidationMode { get set }
    /// 文案本地化器
    var localizer: ErrorLocalizer { get set }

    /// 获取某字段的规则集合
    func rules(for fieldID: String) -> [FieldRule]

    /// 实时校验问题变更回调（建议在主线程更新 UI）
    var onRealtimeIssuesChanged: (([String: [ValidationIssue]]) -> Void)? { get set }

    /// 提交时校验结果回调（聚合全部字段）
    var onSubmitIssues: (([String: [ValidationIssue]]) -> Void)? { get set }

    /// 校验单字段
    func validateField(_ fieldID: String,
                       values: [String: Any],
                       strategy: CompositionStrategy) async -> [ValidationIssue]

    /// 校验整表
    func validateAll(values: [String: Any],
                     strategy: CompositionStrategy) async -> [String: [ValidationIssue]]
}

方法说明

• ErrorLocalizer.localizedString(for:arguments:locale:)

  • 用途：将 messageKey + arguments 转换为最终文案
  • 参数：
    • key：本地化键
    • arguments：占位符参数（按顺序替换）
    • locale：目标区域（通常可由系统语言自动处理）
  • 返回值：最终字符串

• ValidationIssue.message(using:locale:)

  • 用途：基于 Localizer 获取最终展示文案
  • 参数：localizer、locale
  • 返回值：本地化后的文案

• FieldRule.validate(value:context:)

  • 用途：执行单字段同步校验
  • 参数：
    • value：字段当前值（Any?，规则内自行转换成期望类型）
    • context：校验上下文，可获取其它字段值与本地化信息
  • 返回值：发现问题返回 ValidationIssue，否则返回 nil

• FieldRule.validateAsync(value:context:)

  • 用途：执行单字段异步校验（如网络）
  • 返回值：发现问题返回 ValidationIssue，否则返回 nil

• FormValidating.rules(for:)

  • 用途：为指定字段返回规则列表，按顺序执行

• FormValidating.validateField(_:values:strategy:)

  • 用途：校验单个字段，支持组合策略
  • 返回值：该字段的所有问题列表（按策略可能为 0/1/多条）

• FormValidating.validateAll(values:strategy:)

  • 用途：校验整表，返回字典：fieldID -> 问题列表

• onRealtimeIssuesChanged

  • 用途：实时模式下，某字段问题变化后回调最新聚合结果

• onSubmitIssues

  • 用途：提交按钮触发整表校验后的聚合回调

属性说明

• FormValidating.mode: FormValidationMode

  • 实时或提交时校验模式

• FormValidating.localizer: ErrorLocalizer

  • 错误文案本地化器

• onRealtimeIssuesChanged: (([String: [ValidationIssue]]) -> Void)?

  • 实时校验结果变更回调；参数为当前所有字段的聚合问题字典

• onSubmitIssues: (([String: [ValidationIssue]]) -> Void)?

  • 提交校验结果回调；参数为整表问题聚合字典

使用示例

以下示例演示「登录/注册」场景，对用户名/密码/验证码字段进行实时与提交时校验，含依赖字段与异步规则。字段标识采用字符串：

• username
• password
• captcha

import UIKit

// MARK: - 具体规则实现

struct NonEmptyRule: FieldRule {
    let id = "non_empty"
    let fieldID: String
    let messageKey: String

    func validate(value: Any?, context: ValidationContext) -> ValidationIssue? {
        let text = value as? String
        if let t = text, !t.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
            return nil
        }
        return ValidationIssue(fieldID: fieldID,
                               code: id,
                               messageKey: messageKey)
    }
}

struct MinLengthRule: FieldRule {
    let id = "min_length"
    let fieldID: String
    let min: Int
    let messageKey: String

    func validate(value: Any?, context: ValidationContext) -> ValidationIssue? {
        guard let text = value as? String, text.count >= min else {
            return ValidationIssue(fieldID: fieldID,
                                   code: id,
                                   messageKey: messageKey,
                                   arguments: ["\(min)"])
        }
        return nil
    }
}

struct RegexRule: FieldRule {
    let id = "regex"
    let fieldID: String
    let pattern: String
    let messageKey: String

    func validate(value: Any?, context: ValidationContext) -> ValidationIssue? {
        guard let text = value as? String else {
            return ValidationIssue(fieldID: fieldID,
                                   code: id,
                                   messageKey: messageKey)
        }
        let regex = try? NSRegularExpression(pattern: pattern)
        let range = NSRange(location: 0, length: (text as NSString).length)
        if let r = regex, r.firstMatch(in: text, options: [], range: range) != nil {
            return nil
        }
        return ValidationIssue(fieldID: fieldID,
                               code: id,
                               messageKey: messageKey)
    }
}

/// 依赖字段：密码不得包含用户名
struct NotContainFieldRule: FieldRule {
    let id = "not_contain_field"
    let fieldID: String
    let otherFieldID: String
    let messageKey: String

    func validate(value: Any?, context: ValidationContext) -> ValidationIssue? {
        guard
            let text = value as? String,
            let other: String = context.value(for: otherFieldID)
        else { return nil }

        if text.isEmpty || other.isEmpty { return nil }
        if text.lowercased().contains(other.lowercased()) {
            return ValidationIssue(fieldID: fieldID,
                                   code: id,
                                   messageKey: messageKey,
                                   arguments: [otherFieldID])
        }
        return nil
    }
}

/// 异步用户名占用检查（模拟网络）
struct RemoteUsernameAvailabilityRule: FieldRule {
    let id = "username_availability"
    let fieldID: String
    let messageKey: String

    func validate(value: Any?, context: ValidationContext) -> ValidationIssue? {
        // 本地同步校验先行（如非空）
        nil
    }

    func validateAsync(value: Any?, context: ValidationContext) async -> ValidationIssue? {
        guard let username = value as? String, !username.isEmpty else { return nil }

        // 模拟网络延时（生产环境换成 URLSession 调用）
        try? await Task.sleep(nanoseconds: 300_000_000)

        // 这里假设 "admin" 已被占用
        if username.lowercased() == "admin" {
            return ValidationIssue(fieldID: fieldID,
                                   code: id,
                                   messageKey: messageKey,
                                   arguments: [username])
        }
        return nil
    }
}

// MARK: - 简易表单校验器实现

@MainActor
public final class SimpleFormValidator: FormValidating {
    public var mode: FormValidationMode = .realtime
    public var localizer: ErrorLocalizer = BundleErrorLocalizer()

    public var onRealtimeIssuesChanged: (([String : [ValidationIssue]]) -> Void)?
    public var onSubmitIssues: (([String : [ValidationIssue]]) -> Void)?

    /// 字段 -> 规则数组
    private var rulesMap: [String: [FieldRule]] = [:]

    /// 内部状态：当前聚合的字段问题
    private var issuesMap: [String: [ValidationIssue]] = [:]

    public init() {}

    public func setRules(_ rules: [FieldRule], for fieldID: String) {
        rulesMap[fieldID] = rules
    }

    public func rules(for fieldID: String) -> [FieldRule] {
        rulesMap[fieldID] ?? []
    }

    public func validateField(_ fieldID: String,
                              values: [String : Any],
                              strategy: CompositionStrategy) async -> [ValidationIssue] {
        let context = ValidationContext(values: values, locale: .current, localizer: localizer)
        var fieldIssues: [ValidationIssue] = []
        let value = values[fieldID]

        // 1) 同步规则
        for rule in rules(for: fieldID) {
            if let issue = rule.validate(value: value, context: context) {
                fieldIssues.append(issue)
                if strategy == .stopAtFirstFailure { break }
            }
        }

        // 2) 异步规则（仅当同步未中断或策略为收集全部）
        if strategy == .collectAllFailures || fieldIssues.isEmpty {
            for rule in rules(for: fieldID) {
                if let issue = await rule.validateAsync(value: value, context: context) {
                    fieldIssues.append(issue)
                    if strategy == .stopAtFirstFailure { break }
                }
            }
        }

        // 3) 维护聚合状态并回调（实时模式）
        issuesMap[fieldID] = fieldIssues
        if mode == .realtime {
            onRealtimeIssuesChanged?(issuesMap)
        }
        return fieldIssues
    }

    public func validateAll(values: [String : Any],
                            strategy: CompositionStrategy) async -> [String : [ValidationIssue]] {
        var result: [String: [ValidationIssue]] = [:]
        for fieldID in rulesMap.keys {
            let issues = await validateField(fieldID, values: values, strategy: strategy)
            result[fieldID] = issues
        }
        // 提交模式回调
        onSubmitIssues?(result)
        return result
    }
}

// MARK: - 示例：登录/注册表单集成

final class AuthViewController: UIViewController {
    // 假设 storyboard 或代码创建
    @IBOutlet private weak var usernameField: UITextField!
    @IBOutlet private weak var passwordField: UITextField!
    @IBOutlet private weak var captchaField: UITextField!
    @IBOutlet private weak var submitButton: UIButton!

    private let validator = SimpleFormValidator()

    override func viewDidLoad() {
        super.viewDidLoad()
        setupValidator()
        setupBindings()
    }

    private func setupValidator() {
        validator.mode = .realtime
        validator.localizer = BundleErrorLocalizer()

        // username 规则：非空、长度、格式、远程占用
        validator.setRules([
            NonEmptyRule(fieldID: "username", messageKey: "error.username.empty"),
            MinLengthRule(fieldID: "username", min: 3, messageKey: "error.username.min"),
            RegexRule(fieldID: "username",
                      pattern: "^[A-Za-z0-9_]{3,}$",
                      messageKey: "error.username.pattern"),
            RemoteUsernameAvailabilityRule(fieldID: "username", messageKey: "error.username.taken")
        ], for: "username")

        // password 规则：非空、长度、不得包含用户名
        validator.setRules([
            NonEmptyRule(fieldID: "password", messageKey: "error.password.empty"),
            MinLengthRule(fieldID: "password", min: 6, messageKey: "error.password.min"),
            NotContainFieldRule(fieldID: "password",
                                otherFieldID: "username",
                                messageKey: "error.password.contains_username")
        ], for: "password")

        // captcha 规则：非空
        validator.setRules([
            NonEmptyRule(fieldID: "captcha", messageKey: "error.captcha.empty")
        ], for: "captcha")

        // 回调：更新 UI 提示（此处仅打印，可替换为 label 或下划线高亮）
        validator.onRealtimeIssuesChanged = { [weak self] issuesMap in
            self?.applyIssues(issuesMap)
        }
        validator.onSubmitIssues = { [weak self] issuesMap in
            self?.applyIssues(issuesMap)
            // 若全部通过，执行提交
            if issuesMap.values.allSatisfy({ $0.isEmpty }) {
                self?.performSubmit()
            }
        }
    }

    private func setupBindings() {
        usernameField.addTarget(self, action: #selector(textChanged(_:)), for: .editingChanged)
        passwordField.addTarget(self, action: #selector(textChanged(_:)), for: .editingChanged)
        captchaField.addTarget(self, action: #selector(textChanged(_:)), for: .editingChanged)
    }

    @objc private func textChanged(_ sender: UITextField) {
        guard validator.mode == .realtime else { return }
        let values = currentValues()
        let fieldID: String
        switch sender {
        case usernameField: fieldID = "username"
        case passwordField: fieldID = "password"
        case captchaField:  fieldID = "captcha"
        default: return
        }
        Task { [weak self] in
            _ = await self?.validator.validateField(fieldID, values: values, strategy: .stopAtFirstFailure)
        }
    }

    @IBAction private func submitTapped(_ sender: UIButton) {
        Task { [weak self] in
            guard let self else { return }
            // 提交前整表校验，采用“收集全部失败”策略
            _ = await validator.validateAll(values: currentValues(), strategy: .collectAllFailures)
        }
    }

    private func currentValues() -> [String: Any] {
        [
            "username": usernameField.text ?? "",
            "password": passwordField.text ?? "",
            "captcha":  captchaField.text ?? ""
        ]
    }

    private func applyIssues(_ issuesMap: [String: [ValidationIssue]]) {
        // 示例：简单打印。实际中可更新每个文本框下的错误 Label
        let localizer = validator.localizer
        for (fieldID, issues) in issuesMap {
            let texts = issues.map { $0.message(using: localizer, locale: .current) }
            print("[\(fieldID)] issues: \(texts)")
        }
        // 可根据是否有错误启用/禁用提交按钮
        let hasError = issuesMap.values.contains { !$0.isEmpty }
        submitButton.isEnabled = !hasError
    }

    private func performSubmit() {
        // 执行登录/注册网络请求
        print("All validations passed. Proceed to submit.")
    }
}

示例 Localizable.strings（简体中文）：

"error.username.empty" = "请输入用户名";
"error.username.min" = "用户名长度至少 %@ 位";
"error.username.pattern" = "用户名仅可包含字母、数字或下划线";
"error.username.taken" = "用户名“%@”已被占用";

"error.password.empty" = "请输入密码";
"error.password.min" = "密码长度至少 %@ 位";
"error.password.contains_username" = "密码不应包含用户名";

"error.captcha.empty" = "请输入验证码";

注意事项

• 平台与语言
  • 示例使用 async/await，要求 Xcode 13.2+、Swift 5.5+，建议 iOS 15+ 运行环境。
• 值类型与安全转换
  • 协议选择 [String: Any] 作为字段值容器，规则内部需将 Any? 转为预期类型（如 String）。请确保转换失败时返回合理错误或忽略。
• 组合策略
  • 实时校验建议使用 .stopAtFirstFailure 提升体验与性能；
  • 提交时校验建议使用 .collectAllFailures 以一次性呈现全部问题。
• 异步规则并发
  • 示例按顺序执行异步规则，便于控制依赖。若需并发可使用 TaskGroup，但要注意结果顺序与取消策略。
• 本地化
  • 建议以稳定的 messageKey 管理文案，避免在代码中硬编码中文；
  • arguments 按顺序对应字符串格式化占位符（%@、%1$@ 等）。
• 依赖字段联动
  • 通过 ValidationContext.values 读取其它字段值，注意空值与类型转换；
  • 当某字段变化后，如该字段被其它规则依赖，建议在实时模式下同时触发相关字段校验。
• UI 线程
  • 回调中若更新 UI，请确保在主线程执行。示例的 SimpleFormValidator 标注了 @MainActor 以简化此问题。
• 可扩展性
  • 可新增 FieldRule 实现（例如 EmailRule、ConfirmPasswordMatchRule、ServerCaptchaVerifyRule）；
  • 可封装 AnyFieldRule（类型擦除）或引入类型安全的 Field 泛型包装，进一步增强可维护性。
• 错误收敛
  • 生产中通常仅展示首条错误；可在 applyIssues 中自行裁剪展示策略。
• 网络错误处理
  • 异步规则中应区分“网络失败”与“业务校验失败”，必要时返回不同 code 与文案 key，以便明确提示（如“网络异常，请重试”）。

以上协议与实现示例可直接用于登录/注册表单场景，并可按需扩展到其他表单页面。