mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-30 07:39:06 +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.
9.9 KiB
9.9 KiB
DataApi System Overview
The DataApi system provides type-safe IPC communication for business data operations between the Renderer and Main processes.
Purpose
DataApiService handles data that:
- Is business data accumulated through user activity
- Has dedicated database schemas/tables
- Users can create, delete, modify records without fixed limits
- Would be severe and irreplaceable if lost
- Can grow to large volumes (potentially GBs)
Key Characteristics
Type-Safe Communication
- End-to-end TypeScript types from client call to handler
- Path parameter inference from route definitions
- Compile-time validation of request/response shapes
RESTful-Style API
- Familiar HTTP semantics (GET, POST, PUT, PATCH, DELETE)
- Resource-based URL patterns (
/topics/:id/messages) - Standard status codes and error responses
On-Demand Data Access
- No automatic caching (fetch fresh data when needed)
- Explicit cache control via query options
- Supports large datasets with pagination
Architecture Diagram
┌─────────────────────────────────────────────────────────────────┐
│ Renderer Process │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ React Components │ │
│ │ - useQuery('/topics') │ │
│ │ - useMutation('/topics', 'POST') │ │
│ └──────────────────────────┬──────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ DataApiService (Renderer) │ │
│ │ - Type-safe ApiClient interface │ │
│ │ - Request serialization │ │
│ │ - Automatic retry with exponential backoff │ │
│ │ - Error handling and transformation │ │
│ └──────────────────────────┬──────────────────────────────┘ │
└──────────────────────────────┼───────────────────────────────────┘
│ IPC
┌──────────────────────────────┼───────────────────────────────────┐
│ Main Process ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ IpcAdapter │ │
│ │ - Receives IPC requests │ │
│ │ - Routes to ApiServer │ │
│ └──────────────────────────┬──────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ApiServer │ │
│ │ - Request routing by path and method │ │
│ │ - Middleware pipeline processing │ │
│ └──────────────────────────┬──────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Handlers (api/handlers/) │ │
│ │ - Thin layer: extract params, call service, transform │ │
│ │ - NO business logic here │ │
│ └──────────────────────────┬──────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Services (services/) │ │
│ │ - Business logic and validation │ │
│ │ - Transaction coordination │ │
│ │ - Domain workflows │ │
│ └──────────────────────────┬──────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────┴─────────────────────┐ │
│ ▼ ▼ │
│ ┌───────────────┐ ┌─────────────────────┐ │
│ │ Repositories │ │ Direct Drizzle │ │
│ │ (Complex) │ │ (Simple domains) │ │
│ │ - Query logic │ │ - Inline queries │ │
│ └───────┬───────┘ └──────────┬──────────┘ │
│ │ │ │
│ └────────────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SQLite Database (via Drizzle ORM) │ │
│ │ - topic, message, file tables │ │
│ │ - Full-text search indexes │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
Four-Layer Architecture
1. API Layer (Handlers)
- Location:
src/main/data/api/handlers/ - Responsibility: HTTP-like interface layer
- Does: Extract parameters, call services, transform responses
- Does NOT: Contain business logic
2. Business Logic Layer (Services)
- Location:
src/main/data/services/ - Responsibility: Domain logic and workflows
- Does: Validation, transaction coordination, orchestration
- Uses: Repositories or direct Drizzle queries
3. Data Access Layer (Repositories)
- Location:
src/main/data/repositories/ - Responsibility: Complex data operations
- When to use: Complex queries, large datasets, reusable patterns
- Alternative: Direct Drizzle for simple CRUD
4. Database Layer
- Location:
src/main/data/db/ - Technology: SQLite + Drizzle ORM
- Schemas:
db/schemas/directory
Data Access Pattern Decision
Use Repository Pattern When:
- ✅ Complex queries (joins, subqueries, aggregations)
- ✅ GB-scale data requiring optimization and pagination
- ✅ Complex transactions involving multiple tables
- ✅ Reusable data access patterns across services
- ✅ High testing requirements (mock data access)
Use Direct Drizzle When:
- ✅ Simple CRUD operations
- ✅ Small datasets (< 100MB)
- ✅ Domain-specific queries with no reuse potential
- ✅ Fast development is priority
Key Features
Automatic Retry
- Exponential backoff for transient failures
- Configurable retry count and delays
- Skips retry for client errors (4xx)
Error Handling
- Typed error codes (
ErrorCodeenum) DataApiErrorclass with retryability detection- Factory methods for consistent error creation
Request Timeout
- Configurable per-request timeouts
- Automatic cancellation of stale requests
Usage Summary
For detailed code examples, see:
- DataApi in Renderer - Client-side usage
- DataApi in Main - Server-side implementation
- API Design Guidelines - RESTful conventions
- API Types - Type system details