mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-30 15:59:09 +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.
159 lines
9.9 KiB
Markdown
159 lines
9.9 KiB
Markdown
# 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 (`ErrorCode` enum)
|
|
- `DataApiError` class 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](./data-api-in-renderer.md) - Client-side usage
|
|
- [DataApi in Main](./data-api-in-main.md) - Server-side implementation
|
|
- [API Design Guidelines](./api-design-guidelines.md) - RESTful conventions
|
|
- [API Types](./api-types.md) - Type system details
|