mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-31 00:10:22 +08:00
819c209821
- Revised the README files for shared data and main data layers to improve clarity and structure. - Consolidated documentation on shared data types and API types, removing the now-deleted `api-design-guidelines.md`. - Streamlined directory structure descriptions and updated links to relevant documentation. - Enhanced quick reference sections for better usability and understanding of the data architecture.
126 lines
5.6 KiB
Markdown
126 lines
5.6 KiB
Markdown
# Cache System Overview
|
|
|
|
The Cache system provides a three-tier caching architecture for temporary and regenerable data across the Cherry Studio application.
|
|
|
|
## Purpose
|
|
|
|
CacheService handles data that:
|
|
- Can be **regenerated or lost without user impact**
|
|
- Requires no backup or cross-device synchronization
|
|
- Has lifecycle tied to component, window, or app session
|
|
|
|
## Three-Tier Architecture
|
|
|
|
| Tier | Scope | Persistence | Use Case |
|
|
|------|-------|-------------|----------|
|
|
| **Memory Cache** | Component-level | Lost on app restart | API responses, computed results |
|
|
| **Shared Cache** | Cross-window | Lost on app restart | Window state, cross-window coordination |
|
|
| **Persist Cache** | Cross-window + localStorage | Survives app restarts | Recent items, non-critical preferences |
|
|
|
|
### Memory Cache
|
|
- Fastest access, in-process memory
|
|
- Isolated per renderer process
|
|
- Best for: expensive computations, API response caching
|
|
|
|
### Shared Cache
|
|
- Synchronized across all windows via IPC
|
|
- Main process acts as the source of truth
|
|
- Best for: window layouts, shared UI state
|
|
|
|
### Persist Cache
|
|
- Backed by localStorage in renderer
|
|
- Main process maintains authoritative copy
|
|
- Best for: recent files, search history, non-critical state
|
|
|
|
## Key Features
|
|
|
|
### TTL (Time To Live) Support
|
|
```typescript
|
|
// Cache with 30-second expiration
|
|
cacheService.set('temp.calculation', result, 30000)
|
|
```
|
|
|
|
### Hook Reference Tracking
|
|
- Prevents deletion of cache entries while React hooks are subscribed
|
|
- Automatic cleanup when components unmount
|
|
|
|
### Cross-Window Synchronization
|
|
- Shared and Persist caches sync across all windows
|
|
- Uses IPC broadcast for real-time updates
|
|
- Main process resolves conflicts
|
|
|
|
### Type Safety
|
|
- Schema-based keys for compile-time checking
|
|
- Casual methods for dynamic keys with manual typing
|
|
|
|
## Data Categories
|
|
|
|
### Performance Cache (Memory tier)
|
|
- Computed results from expensive operations
|
|
- API response caching
|
|
- Parsed/transformed data
|
|
|
|
### UI State Cache (Shared tier)
|
|
- Sidebar collapsed state
|
|
- Panel dimensions
|
|
- Scroll positions
|
|
|
|
### Non-Critical Persistence (Persist tier)
|
|
- Recently used items
|
|
- Search history
|
|
- User-customized but regenerable data
|
|
|
|
## Architecture Diagram
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Renderer Process │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ useCache │ │useSharedCache│ │usePersistCache│ │
|
|
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
|
|
│ │ │ │ │
|
|
│ └────────────────┼────────────────┘ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────┐ │
|
|
│ │ CacheService │ │
|
|
│ │ (Renderer) │ │
|
|
│ └──────────┬──────────┘ │
|
|
└─────────────────────────┼────────────────────────────────────┘
|
|
│ IPC (shared/persist only)
|
|
┌─────────────────────────┼────────────────────────────────────┐
|
|
│ Main Process ▼ │
|
|
│ ┌─────────────────────┐ │
|
|
│ │ CacheService │ │
|
|
│ │ (Main) │ │
|
|
│ └─────────────────────┘ │
|
|
│ - Source of truth for shared/persist │
|
|
│ - Broadcasts updates to all windows │
|
|
└──────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Main vs Renderer Responsibilities
|
|
|
|
### Main Process CacheService
|
|
- Manages shared and persist cache storage
|
|
- Handles IPC requests from renderers
|
|
- Broadcasts updates to all windows
|
|
- Manages TTL expiration for shared caches
|
|
|
|
### Renderer Process CacheService
|
|
- Manages local memory cache
|
|
- Proxies shared/persist operations to Main
|
|
- Handles hook subscriptions and updates
|
|
- Local TTL management for memory cache
|
|
|
|
## Usage Summary
|
|
|
|
For detailed code examples and API usage, see [Cache Usage Guide](./cache-usage.md).
|
|
|
|
| Method | Tier | Type Safety |
|
|
|--------|------|-------------|
|
|
| `useCache` / `get` / `set` | Memory | Schema-based keys |
|
|
| `getCasual` / `setCasual` | Memory | Dynamic keys (manual typing) |
|
|
| `useSharedCache` / `getShared` / `setShared` | Shared | Schema-based keys |
|
|
| `getSharedCasual` / `setSharedCasual` | Shared | Dynamic keys (manual typing) |
|
|
| `usePersistCache` / `getPersist` / `setPersist` | Persist | Schema-based keys only |
|