API 设计规范

1. 概述

本规范定义 OneArchive 项目前后端 API 交互结构体的统一存储和管理标准，旨在提高代码组织性、可维护性和开发效率。

2. 设计目标

通过统一的 API 结构规范，实现：

• 前后端类型定义集中管理，确保接口一致性
• 统一的命名规范和存储位置，提高代码可维护性
• 清晰的模块划分，便于开发和协作
• 类型安全保障，减少接口错误

3. 统一结构规范

3.1. 前端 API 结构

3.1.1. 目录结构

tauri/src/api/
├── types/                    # API 相关类型定义
│   ├── common.ts            # 通用 API 类型
│   ├── operations.ts        # 操作相关 API 类型
│   ├── config.ts            # 配置相关 API 类型
│   └── index.ts             # 类型导出
├── operations.ts            # 操作 API 封装 (扫描、归档、解档等)
├── config.ts                # 配置 API 封装
└── index.ts                 # API 导出

3.1.2. 命名规范

• 接口命名：使用 PascalCase（如 ArchiveFile, RecoveryConfig）
• API 函数命名：使用 camelCase（如 scanRoot, archiveFiles）
• 文件命名：使用 kebab-case（如 recovery-config.ts）

3.1.3. 类型定义示例

// types/common.ts - 通用类型
export interface ApiResponse<T> {
    success: boolean;
    data?: T;
    error?: string;
}

export interface PaginatedResponse<T> {
    data: T[];
    total: number;
    page: number;
    pageSize: number;
    totalPages: number;
}

// types/operations.ts - 操作相关类型
export interface ArchiveFile {
    id: number;
    archiveName: string;
    archiveSize: number;
}

export interface ScanProgress {
    processed: number;
    total: number;
    message: string;
    progress: number;
}

export interface ArchiveProgress {
    totalFiles: number;
    processedFiles: number;
    processedBytes: number;
    totalBytes: number;
    currentFile?: string;
    completed: boolean;
    error?: string;
}

3.1.4. API 封装示例

// operations.ts
import { invoke } from '@tauri-apps/api/core';
import type { ApiResponse, ScanProgress } from './types';

export async function scanRoot(
    rootPath: string,
    dbPath: string
): Promise<ApiResponse<void>> {
    try {
        await invoke('scan_root_with_progress', { rootPath, dbPath });
        return { success: true };
    } catch (error) {
        return { success: false, error: error.message };
    }
}

3.2. 后端 API 结构

3.2.1. 目录结构

tauri/src-tauri/src/api/
├── model_common.rs          # 通用 API 结构体
├── model_operations.rs      # 操作相关结构体
├── model_config.rs          # 配置相关结构体
├── api_operations.rs        # 操作相关 API 命令实现
├── api_config.rs            # 配置相关 API 命令实现
├── api_database.rs          # 数据库相关 API 命令实现
├── config.rs                # 配置管理实现
└── workspace.rs             # 工作区管理实现

3.2.2. 命名规范

• 模块命名：使用 model_ 前缀（如 model_operations.rs）
• 结构体命名：使用 PascalCase（如 ArchiveFile, RecoveryConfig）
• 字段命名：使用 snake_case（如 archive_name, data_shards）

3.2.3. API 命令实现

API 命令文件 (api_*.rs) 包含 Tauri 命令处理器，负责处理前端调用并协调业务逻辑：

• api_operations.rs：操作相关命令（扫描、归档、解档、灾备等）
• api_config.rs：配置管理命令（加载/保存配置、工作区管理）
• api_database.rs：数据库操作命令（查询、统计等）

3.2.4. 结构体定义示例

// model_common.rs - 通用结构体
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct ApiResponse<T> {
    pub success: bool,
    pub data: Option<T>,
    pub error: Option<String>,
}

#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct PaginatedResponse<T> {
    pub data: Vec<T>,
    pub total: i64,
    pub page: i64,
    pub page_size: i64,
    pub total_pages: i64,
}

// model_operations.rs - 操作相关结构体
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct ArchiveFile {
    pub id: i64,
    pub archive_name: String,
    pub archive_size: i64,
}

#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct ScanProgress {
    pub processed: u64,
    pub total: u64,
    pub message: String,
    pub progress: f64,
}

#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct ArchiveProgress {
    pub total_files: usize,
    pub processed_files: usize,
    pub processed_bytes: u64,
    pub total_bytes: u64,
    pub current_file: Option<String>,
    pub completed: bool,
    pub error: Option<String>,
}

4. 维护指南

4.1. 新增 API 开发流程

1. 在相应的类型文件中定义新的接口/结构体
2. 在对应的 api_*.rs 文件中实现 Tauri 命令
3. 在前端 API 文件中封装调用逻辑
4. 同步更新相关文档和注释

4.2. 类型同步原则

• 前后端结构体字段名保持一致（除了命名规范差异）
• API 请求参数和响应结构必须一一对应
• 使用相同的序列化/反序列化规则

4.3. 文档更新

• API 变更时同步更新相关文档
• 为复杂 API 提供详细使用示例
• 维护 API 变更日志

5. 质量保证

• 所有 API 结构体必须有完整的文档注释
• 前端类型定义必须与后端结构体保持同步
• 通过 TypeScript 和 Rust 类型检查确保类型安全
• 编写单元测试验证 API 结构体正确性

6. 关联文档

• 前端规范
• Rust 代码规范