# Expo + AsyncStorage 移动端缓存架构设计报告 ## 一、架构概览 ### 1.1 设计哲学基于 Electron 版本的核心思想，针对移动端单进程、单窗口特性进行简化： ``` ┌─────────────────────────────────────────┐ │ React Native 应用 (单线程) │ │ │ │ ┌────────────────────────────────────┐ │ │ │ CacheService (单例) │ │ │ │ │ │ │ │ ┌──────────────┐ ┌────────────┐ │ │ │ │ │ 内存缓存 │ │ AsyncStorage│ │ │ │ │ │ (Map) │ │ (持久化) │ │ │ │ │ │ │ │ │ │ │ │ │ │ • 同步访问 │ │ • 异步持久化 │ │ │ │ │ │ • 运行时存储 │ │ • 应用重启保留│ │ │ │ │ │ • TTL支持 │ │ • 6-10MB限制 │ │ │ │ │ └──────────────┘ └────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ 订阅系统 │ │ │ │ │ │ (useSyncExternalStore) │ │ │ │ │ └──────────────────────────────┘ │ │ │ └────────────────────────────────────┘ │ │ ▲ │ │ │ │ │ ┌─────────────────┴──────────────────┐ │ │ │ React Hooks 层 │ │ │ │ • useCache() - 内存缓存 │ │ │ │ • usePersistCache() - 持久化缓存 │ │ │ │ • useAsyncCache() - 异步加载 │ │ │ └────────────────────────────────────┘ │ └─────────────────────────────────────────┘ ``` ### 1.2 核心特性 ✅ **保留 Electron 优秀设计** - 类型安全的 Schema 系统 - TTL 惰性清理机制 - Hook 引用保护 - 订阅-发布模式 - 值对比优化 ✅ **移动端特化** - AsyncStorage 替代 localStorage - 智能预加载策略 - 内存占用控制 - 离线优先设计 ❌ **移除多余复杂度** - 无 IPC 通信 - 无跨窗口同步 - 无主进程层 ## 二、技术实现 ### 2.1 类型定义与 Schema ```typescript // types/cacheTypes.ts /** * 缓存条目结构 */ export interface CacheEntry { value: T expireAt?: number // Unix 时间戳 lastAccess?: number // LRU 清理用 } /** * 缓存订阅回调 */ export type CacheSubscriber = () => void /** * 存储状态 */ export interface StorageStatus { memorySize: number // 内存缓存大小 (字节) persistSize: number // 持久化数据大小 (字节) totalKeys: number // 总键数 isStorageAvailable: boolean } ``` ```typescript // types/cacheSchemas.ts /** * 内存缓存 Schema (运行时临时数据) */ export type MemoryCacheSchema = { // UI 状态 'ui.theme': 'light' | 'dark' | 'auto' 'ui.modal_visible': boolean 'ui.bottom_sheet_open': boolean // 聊天状态 'chat.generating': boolean 'chat.current_topic_id': string | null 'chat.selected_messages': string[] // 临时数据 'temp.draft_message': string 'temp.scroll_position': number } export const DefaultMemoryCache: MemoryCacheSchema = { 'ui.theme': 'auto', 'ui.modal_visible': false, 'ui.bottom_sheet_open': false, 'chat.generating': false, 'chat.current_topic_id': null, 'chat.selected_messages': [], 'temp.draft_message': '', 'temp.scroll_position': 0 } /** * 持久化缓存 Schema (应用重启保留) */ export type PersistCacheSchema = { // 用户偏好 'user.preferences': { language: string fontSize: number enableNotifications: boolean } // 应用设置 'app.settings': { apiKey: string | null model: string temperature: number } // 最近使用 'app.recent_topics': string[] 'app.last_sync_time': number | null } export const DefaultPersistCache: PersistCacheSchema = { 'user.preferences': { language: 'zh-CN', fontSize: 16, enableNotifications: true }, 'app.settings': { apiKey: null, model: 'gpt-4', temperature: 0.7 }, 'app.recent_topics': [], 'app.last_sync_time': null } // 类型约束 export type MemoryCacheKey = keyof MemoryCacheSchema export type PersistCacheKey = keyof PersistCacheSchema ``` ### 2.2 核心 CacheService 实现 ```typescript // services/CacheService.ts import AsyncStorage from '@react-native-async-storage/async-storage' import { MemoryCacheKey, MemoryCacheSchema, PersistCacheKey, PersistCacheSchema, DefaultMemoryCache, DefaultPersistCache } from '../types/cacheSchemas' import type { CacheEntry, CacheSubscriber, StorageStatus } from '../types/cacheTypes' const STORAGE_PREFIX = 'cache_' const PERSIST_PRELOAD_KEYS = 'cache_preload_keys' // 预加载键列表 const MAX_MEMORY_SIZE = 5 * 1024 * 1024 // 5MB 内存限制 export class CacheService { private static instance: CacheService // 双层缓存 private memoryCache = new Map() private persistCache = new Map() // 订阅系统 private subscribers = new Map>() // Hook 引用保护 private activeHooks = new Set() // 持久化防抖 private persistDebounceTimers = new Map() private readonly DEBOUNCE_MS = 200 // 状态标记 private initialized = false private storageAvailable = true private constructor() {} public static getInstance(): CacheService { if (!CacheService.instance) { CacheService.instance = new CacheService() } return CacheService.instance } /** * 初始化服务 - 预加载持久化数据 */ public async initialize(): Promise { if (this.initialized) { console.warn('[CacheService] 已经初始化') return } try { // 1. 测试 AsyncStorage 可用性 await this.checkStorageAvailability() // 2. 批量加载常用持久化数据 await this.preloadPersistCache() // 3. 清理过期数据 this.cleanExpiredEntries() this.initialized = true console.log('[CacheService] 初始化成功') } catch (error) { console.error('[CacheService] 初始化失败:', error) this.storageAvailable = false } } // ============ 内存缓存 (同步) ============ /** * 获取内存缓存 */ public get(key: K): MemoryCacheSchema[K] | undefined { const entry = this.memoryCache.get(key) if (!entry) return undefined // TTL 惰性清理 if (entry.expireAt && Date.now() > entry.expireAt) { this.memoryCache.delete(key) this.notifySubscribers(key) return undefined } // 更新访问时间 (LRU) entry.lastAccess = Date.now() return entry.value } /** * 设置内存缓存 */ public set(key: K, value: MemoryCacheSchema[K], ttl?: number): void { const existingEntry = this.memoryCache.get(key) // 值对比优化 if (existingEntry && Object.is(existingEntry.value, value)) { if (ttl && existingEntry.expireAt !== Date.now() + ttl) { existingEntry.expireAt = Date.now() + ttl } return } // 内存保护：超限时清理 LRU this.enforceMemoryLimit() const entry: CacheEntry = { value, expireAt: ttl ? Date.now() + ttl : undefined, lastAccess: Date.now() } this.memoryCache.set(key, entry) this.notifySubscribers(key) } /** * 删除内存缓存 */ public delete(key: K): boolean { if (this.activeHooks.has(key)) { console.error(`[CacheService] 无法删除 "${key}" - Hook 正在使用`) return false } const deleted = this.memoryCache.delete(key) if (deleted) { this.notifySubscribers(key) } return deleted } // ============ 持久化缓存 (异步) ============ /** * 获取持久化缓存 (优先返回内存副本) */ public getPersist(key: K): PersistCacheSchema[K] { // 优先返回已加载的内存副本 if (this.persistCache.has(key)) { return this.persistCache.get(key)! } // 未加载则返回默认值 const defaultValue = DefaultPersistCache[key] console.warn(`[CacheService] 持久化键 "${key}" 未加载，使用默认值`) return defaultValue } /** * 异步加载持久化缓存 (首次访问时调用) */ public async loadPersist(key: K): Promise { if (this.persistCache.has(key)) { return this.persistCache.get(key)! } try { const storageKey = STORAGE_PREFIX + key const data = await AsyncStorage.getItem(storageKey) if (data) { const value = JSON.parse(data) this.persistCache.set(key, value) this.notifySubscribers(key) return value } } catch (error) { console.error(`[CacheService] 加载 "${key}" 失败:`, error) } // 加载失败，使用默认值 const defaultValue = DefaultPersistCache[key] this.persistCache.set(key, defaultValue) return defaultValue } /** * 设置持久化缓存 (防抖写入) */ public async setPersist(key: K, value: PersistCacheSchema[K]): Promise { const existingValue = this.persistCache.get(key) // 深度对比优化 if (this.deepEqual(existingValue, value)) { return } // 更新内存副本 this.persistCache.set(key, value) this.notifySubscribers(key) // 防抖写入 AsyncStorage this.debouncePersistWrite(key, value) } /** * 防抖写入 AsyncStorage */ private debouncePersistWrite(key: K, value: PersistCacheSchema[K]): void { // 清除旧定时器 const oldTimer = this.persistDebounceTimers.get(key) if (oldTimer) { clearTimeout(oldTimer) } // 设置新定时器 const timer = setTimeout(async () => { try { const storageKey = STORAGE_PREFIX + key await AsyncStorage.setItem(storageKey, JSON.stringify(value)) this.persistDebounceTimers.delete(key) } catch (error) { console.error(`[CacheService] 持久化 "${key}" 失败:`, error) if (error.message?.includes('quota')) { this.handleStorageQuotaExceeded() } } }, this.DEBOUNCE_MS) this.persistDebounceTimers.set(key, timer) } // ============ 订阅系统 ============ public subscribe(key: string, callback: CacheSubscriber): () => void { if (!this.subscribers.has(key)) { this.subscribers.set(key, new Set()) } this.subscribers.get(key)!.add(callback) return () => { const keySubscribers = this.subscribers.get(key) if (keySubscribers) { keySubscribers.delete(callback) if (keySubscribers.size === 0) { this.subscribers.delete(key) } } } } private notifySubscribers(key: string): void { const keySubscribers = this.subscribers.get(key) if (keySubscribers) { keySubscribers.forEach(callback => { try { callback() } catch (error) { console.error(`[CacheService] 订阅者错误 "${key}":`, error) } }) } } // ============ Hook 保护 ============ public registerHook(key: string): void { this.activeHooks.add(key) } public unregisterHook(key: string): void { this.activeHooks.delete(key) } // ============ 内部工具方法 ============ /** * 预加载常用持久化数据 */ private async preloadPersistCache(): Promise { try { // 定义需要预加载的键 const preloadKeys: PersistCacheKey[] = ['user.preferences', 'app.settings', 'app.recent_topics'] const storageKeys = preloadKeys.map(key => STORAGE_PREFIX + key) const values = await AsyncStorage.multiGet(storageKeys) values.forEach(([storageKey, data], index) => { const key = preloadKeys[index] if (data) { try { this.persistCache.set(key, JSON.parse(data)) } catch { this.persistCache.set(key, DefaultPersistCache[key]) } } else { this.persistCache.set(key, DefaultPersistCache[key]) } }) console.log(`[CacheService] 预加载了 ${preloadKeys.length} 个持久化键`) } catch (error) { console.error('[CacheService] 预加载失败:', error) } } /** * 内存限制保护 (LRU 清理) */ private enforceMemoryLimit(): void { const currentSize = this.estimateMemorySize() if (currentSize <= MAX_MEMORY_SIZE) return // 按最后访问时间排序 const entries = Array.from(this.memoryCache.entries()) .filter(([key]) => !this.activeHooks.has(key)) // 保护活跃 hook .sort((a, b) => (a[1].lastAccess || 0) - (b[1].lastAccess || 0)) // 删除最旧的 20% const deleteCount = Math.ceil(entries.length * 0.2) for (let i = 0; i < deleteCount; i++) { this.memoryCache.delete(entries[i][0]) } console.warn(`[CacheService] LRU 清理: 移除了 ${deleteCount} 个条目`) } /** * 估算内存占用 */ private estimateMemorySize(): number { let size = 0 for (const [key, entry] of this.memoryCache.entries()) { size += key.length * 2 // Unicode 字符 size += JSON.stringify(entry.value).length } return size } /** * 清理过期条目 */ private cleanExpiredEntries(): void { const now = Date.now() for (const [key, entry] of this.memoryCache.entries()) { if (entry.expireAt && now > entry.expireAt) { this.memoryCache.delete(key) } } } /** * 深度相等比较 */ private deepEqual(a: any, b: any): boolean { if (Object.is(a, b)) return true if (typeof a !== 'object' || typeof b !== 'object') return false if (a === null || b === null) return false if (Array.isArray(a) !== Array.isArray(b)) return false if (Array.isArray(a)) { if (a.length !== b.length) return false for (let i = 0; i < a.length; i++) { if (!this.deepEqual(a[i], b[i])) return false } return true } const keysA = Object.keys(a) const keysB = Object.keys(b) if (keysA.length !== keysB.length) return false for (const key of keysA) { if (!keysB.includes(key)) return false if (!this.deepEqual(a[key], b[key])) return false } return true } /** * 检查存储可用性 */ private async checkStorageAvailability(): Promise { try { const testKey = '__cache_test__' await AsyncStorage.setItem(testKey, 'test') await AsyncStorage.removeItem(testKey) this.storageAvailable = true } catch { this.storageAvailable = false throw new Error('AsyncStorage 不可用') } } /** * 处理存储配额超限 */ private async handleStorageQuotaExceeded(): Promise { console.error('[CacheService] 存储配额超限，清理旧数据...') try { // 清理所有持久化缓存，保留默认值 const keys = await AsyncStorage.getAllKeys() const cacheKeys = keys.filter(k => k.startsWith(STORAGE_PREFIX)) await AsyncStorage.multiRemove(cacheKeys) // 重置内存副本为默认值 this.persistCache.clear() for (const [key, value] of Object.entries(DefaultPersistCache)) { this.persistCache.set(key as PersistCacheKey, value) } } catch (error) { console.error('[CacheService] 处理配额失败:', error) } } // ============ 工具 API ============ /** * 获取存储状态 */ public async getStatus(): Promise { const memorySize = this.estimateMemorySize() let persistSize = 0 try { const keys = await AsyncStorage.getAllKeys() const cacheKeys = keys.filter(k => k.startsWith(STORAGE_PREFIX)) const values = await AsyncStorage.multiGet(cacheKeys) persistSize = values.reduce((sum, [, value]) => { return sum + (value?.length || 0) }, 0) } catch { // 忽略错误 } return { memorySize, persistSize, totalKeys: this.memoryCache.size + this.persistCache.size, isStorageAvailable: this.storageAvailable } } /** * 清理所有缓存 */ public async clearAll(): Promise { this.memoryCache.clear() this.persistCache.clear() try { const keys = await AsyncStorage.getAllKeys() const cacheKeys = keys.filter(k => k.startsWith(STORAGE_PREFIX)) await AsyncStorage.multiRemove(cacheKeys) } catch (error) { console.error('[CacheService] 清理存储失败:', error) } } /** * 强制保存所有待写入数据 */ public async flush(): Promise { // 清除所有防抖定时器，立即写入 for (const [key, timer] of this.persistDebounceTimers.entries()) { clearTimeout(timer) } this.persistDebounceTimers.clear() // 批量写入 const entries: [string, string][] = [] for (const [key, value] of this.persistCache.entries()) { entries.push([STORAGE_PREFIX + key, JSON.stringify(value)]) } try { await AsyncStorage.multiSet(entries) } catch (error) { console.error('[CacheService] 刷新失败:', error) } } } // 导出单例 export const cacheService = CacheService.getInstance() ``` ### 2.3 React Hooks 层 ```typescript // hooks/useCache.ts import { useCallback, useEffect, useSyncExternalStore } from 'react' import { cacheService } from '../services/CacheService' import { MemoryCacheKey, MemoryCacheSchema, PersistCacheKey, PersistCacheSchema, DefaultMemoryCache, DefaultPersistCache } from '../types/cacheSchemas' /** * 内存缓存 Hook (同步) * * @example * const [theme, setTheme] = useCache('ui.theme') * setTheme('dark') */ export function useCache( key: K, initValue?: MemoryCacheSchema[K] ): [MemoryCacheSchema[K], (value: MemoryCacheSchema[K]) => void] { const value = useSyncExternalStore( useCallback(callback => cacheService.subscribe(key, callback), [key]), useCallback(() => cacheService.get(key), [key]), useCallback(() => cacheService.get(key), [key]) ) // 初始化 useEffect(() => { if (cacheService.get(key) === undefined) { cacheService.set(key, initValue ?? DefaultMemoryCache[key]) } }, [key, initValue]) // 注册 hook useEffect(() => { cacheService.registerHook(key) return () => cacheService.unregisterHook(key) }, [key]) const setValue = useCallback( (newValue: MemoryCacheSchema[K]) => { cacheService.set(key, newValue) }, [key] ) return [value ?? initValue ?? DefaultMemoryCache[key], setValue] } /** * 持久化缓存 Hook (同步读取内存副本) * * @example * const [settings, setSettings] = usePersistCache('app.settings') * setSettings({ ...settings, model: 'gpt-4-turbo' }) */ export function usePersistCache( key: K ): [PersistCacheSchema[K], (value: PersistCacheSchema[K]) => void] { const value = useSyncExternalStore( useCallback(callback => cacheService.subscribe(key, callback), [key]), useCallback(() => cacheService.getPersist(key), [key]), useCallback(() => cacheService.getPersist(key), [key]) ) useEffect(() => { cacheService.registerHook(key) return () => cacheService.unregisterHook(key) }, [key]) const setValue = useCallback( async (newValue: PersistCacheSchema[K]) => { await cacheService.setPersist(key, newValue) }, [key] ) return [value, setValue] } /** * 异步加载持久化缓存 Hook (带 loading 状态) * * @example * const { data, loading, error, reload } = useAsyncCache('app.settings') */ export function useAsyncCache(key: K) { const [loading, setLoading] = useState(true) const [error, setError] = useState(null) const value = useSyncExternalStore( useCallback(callback => cacheService.subscribe(key, callback), [key]), useCallback(() => cacheService.getPersist(key), [key]), useCallback(() => cacheService.getPersist(key), [key]) ) const load = useCallback(async () => { setLoading(true) setError(null) try { await cacheService.loadPersist(key) } catch (err) { setError(err as Error) } finally { setLoading(false) } }, [key]) useEffect(() => { load() }, [load]) useEffect(() => { cacheService.registerHook(key) return () => cacheService.unregisterHook(key) }, [key]) const setValue = useCallback( async (newValue: PersistCacheSchema[K]) => { await cacheService.setPersist(key, newValue) }, [key] ) return { data: value, loading, error, reload: load, setValue } } ``` ## 三、使用示例 ### 3.1 应用初始化 ```typescript // App.tsx import { useEffect, useState } from 'react' import { cacheService } from './services/CacheService' export default function App() { const [ready, setReady] = useState(false) useEffect(() => { async function init() { await cacheService.initialize() setReady(true) } init() }, []) if (!ready) { return } return } ``` ### 3.2 临时 UI 状态 ```typescript // screens/ChatScreen.tsx import { useCache } from '../hooks/useCache' export function ChatScreen() { const [generating, setGenerating] = useCache('chat.generating') const [draftMessage, setDraftMessage] = useCache('temp.draft_message') const handleSend = async () => { setGenerating(true) try { await sendMessage(draftMessage) setDraftMessage('') // 清空草稿 } finally { setGenerating(false) } } return (