点滴生活

Appearance

Electron开发手册 ​

Electron 数据库操作与数据持久化架构设计 ​

作为前端架构师，我将设计一个完整的 Electron 数据库操作架构，确保数据安全、高效和可维护。以下是完整的架构设计方案：

整体架构设计 ​

技术选型 ​

  • 本地数据库：SQLite（关系型） + Dexie.js（IndexedDB封装）
  • 状态管理：MobX 或 Zustand
  • 数据加密：Node.js crypto 模块
  • 数据同步：PouchDB + CouchDB
  • ORM：TypeORM 或 Sequelize

文件结构设计 ​

src/
├── main/                  # 主进程代码
│   ├── database/          # 数据库核心
│   │   ├── models/        # 数据模型
│   │   ├── services/      # 数据库服务
│   │   ├── migrations/    # 数据库迁移
│   │   └── index.ts       # 数据库初始化
│   ├── ipc/              # IPC通信处理
│   ├── security/         # 安全模块
│   └── main.ts           # 主进程入口
│
├── renderer/             # 渲染进程代码
│   ├── stores/           # 状态管理
│   ├── services/         # API服务
│   ├── components/       # UI组件
│   └── App.tsx           # 主应用组件
│
├── preload/              # 预加载脚本
│   └── index.ts
│
├── resources/            # 静态资源
└── types/                # 类型定义

数据库服务层设计 ​

1. 数据库初始化 (main/database/index.ts) ​

typescript
import { app } from 'electron';
import path from 'path';
import { Sequelize } from 'sequelize';

class Database {
    private sequelize: Sequelize;

    constructor() {
        const dbPath = path.join(app.getPath('userData'), 'app-database.sqlite');

        this.sequelize = new Sequelize({
            dialect: 'sqlite',
            storage: dbPath,
            logging: process.env.NODE_ENV === 'development'
        });
    }

    async init() {
        try {
            await this.sequelize.authenticate();
            console.log('Database connection established');

            // 运行数据库迁移
            await this.runMigrations();

            // 初始化模型
            this.initializeModels();

            return this.sequelize;
        } catch (error) {
            console.error('Database initialization failed:', error);
            throw error;
        }
    }

    private async runMigrations() {
        // 数据库迁移逻辑
    }

    private initializeModels() {
        // 注册所有数据模型
    }

    get instance() {
        return this.sequelize;
    }
}

export default new Database();

2. 数据模型设计 (main/database/models/User.ts) ​

typescript
import { DataTypes, Model } from 'sequelize';
import db from '../index';

class User extends Model {
    public id!: number;
    public username!: string;
    public email!: string;
    public passwordHash!: string;
    public createdAt!: Date;
    public updatedAt!: Date;
}

User.init(
    {
        id: {
            type: DataTypes.INTEGER,
            autoIncrement: true,
            primaryKey: true
        },
        username: {
            type: DataTypes.STRING(50),
            allowNull: false,
            unique: true
        },
        email: {
            type: DataTypes.STRING(100),
            allowNull: false,
            unique: true,
            validate: {
                isEmail: true
            }
        },
        passwordHash: {
            type: DataTypes.STRING(128),
            allowNull: false
        }
    },
    {
        sequelize: db.instance,
        tableName: 'users',
        timestamps: true,
        indexes: [
            {
                unique: true,
                fields: ['username']
            },
            {
                unique: true,
                fields: ['email']
            }
        ]
    }
);

export default User;

3. 数据库服务层 (main/database/services/UserService.ts) ​

typescript
import User from '../models/User';
import { hashPassword } from '../../security/crypto';
import { IpcMainInvokeEvent } from 'electron';

interface CreateUserParams {
    username: string;
    email: string;
    password: string;
}

interface UpdateUserParams {
    id: number;
    username?: string;
    email?: string;
    password?: string;
}

class UserService {
    async createUser(event: IpcMainInvokeEvent, params: CreateUserParams) {
        try {
            const passwordHash = await hashPassword(params.password);

            const user = await User.create({
                username: params.username,
                email: params.email,
                passwordHash
            });

            return {
                success: true,
                data: user.toJSON()
            };
        } catch (error) {
            return {
                success: false,
                error: error.message
            };
        }
    }

    async updateUser(event: IpcMainInvokeEvent, params: UpdateUserParams) {
        try {
            const user = await User.findByPk(params.id);

            if (!user) {
                throw new Error('User not found');
            }

            if (params.username) user.username = params.username;
            if (params.email) user.email = params.email;

            if (params.password) {
                user.passwordHash = await hashPassword(params.password);
            }

            await user.save();

            return {
                success: true,
                data: user.toJSON()
            };
        } catch (error) {
            return {
                success: false,
                error: error.message
            };
        }
    }

    async getUserById(event: IpcMainInvokeEvent, id: number) {
        try {
            const user = await User.findByPk(id, {
                attributes: { exclude: ['passwordHash'] }
            });

            if (!user) {
                throw new Error('User not found');
            }

            return {
                success: true,
                data: user.toJSON()
            };
        } catch (error) {
            return {
                success: false,
                error: error.message
            };
        }
    }

    async listUsers(event: IpcMainInvokeEvent, page = 1, pageSize = 20) {
        try {
            const offset = (page - 1) * pageSize;

            const { count, rows } = await User.findAndCountAll({
                attributes: { exclude: ['passwordHash'] },
                offset,
                limit: pageSize,
                order: [['createdAt', 'DESC']]
            });

            return {
                success: true,
                data: {
                    total: count,
                    page,
                    pageSize,
                    users: rows.map((u) => u.toJSON())
                }
            };
        } catch (error) {
            return {
                success: false,
                error: error.message
            };
        }
    }
}

export default new UserService();

IPC 通信架构 ​

1. IPC 服务端 (main/ipc/index.ts) ​

typescript
import { ipcMain } from 'electron';
import userService from '../database/services/UserService';

function setupDatabaseIPC() {
    // 用户管理
    ipcMain.handle('db:createUser', userService.createUser);
    ipcMain.handle('db:updateUser', userService.updateUser);
    ipcMain.handle('db:getUserById', userService.getUserById);
    ipcMain.handle('db:listUsers', userService.listUsers);

    // 其他数据库操作...
}

export function initializeIPC() {
    setupDatabaseIPC();
    // 其他IPC设置...
}

2. 预加载脚本 (preload/index.ts) ​

typescript
import { contextBridge, ipcRenderer } from 'electron';

contextBridge.exposeInMainWorld('electronAPI', {
    // 数据库操作
    createUser: (params) => ipcRenderer.invoke('db:createUser', params),
    updateUser: (params) => ipcRenderer.invoke('db:updateUser', params),
    getUserById: (id) => ipcRenderer.invoke('db:getUserById', id),
    listUsers: (page, pageSize) => ipcRenderer.invoke('db:listUsers', page, pageSize)

    // 其他API...
});

3. 渲染进程服务封装 (renderer/services/api.ts) ​

typescript
class DatabaseAPI {
    async createUser(userData) {
        try {
            const result = await window.electronAPI.createUser(userData);
            if (!result.success) throw new Error(result.error);
            return result.data;
        } catch (error) {
            console.error('Create user failed:', error);
            throw error;
        }
    }

    async updateUser(userData) {
        try {
            const result = await window.electronAPI.updateUser(userData);
            if (!result.success) throw new Error(result.error);
            return result.data;
        } catch (error) {
            console.error('Update user failed:', error);
            throw error;
        }
    }

    async getUserById(id) {
        try {
            const result = await window.electronAPI.getUserById(id);
            if (!result.success) throw new Error(result.error);
            return result.data;
        } catch (error) {
            console.error('Get user failed:', error);
            throw error;
        }
    }

    async listUsers(page = 1, pageSize = 20) {
        try {
            const result = await window.electronAPI.listUsers(page, pageSize);
            if (!result.success) throw new Error(result.error);
            return result.data;
        } catch (error) {
            console.error('List users failed:', error);
            throw error;
        }
    }
}

export const dbAPI = new DatabaseAPI();

安全模块设计 ​

1. 数据加密 (main/security/crypto.ts) ​

typescript
import crypto from 'crypto';
import { app } from 'electron';
import path from 'path';
import fs from 'fs';

const ALGORITHM = 'aes-256-cbc';
const IV_LENGTH = 16;

// 安全获取加密密钥
function getEncryptionKey(): Buffer {
    const keyPath = path.join(app.getPath('userData'), 'secret.key');

    if (fs.existsSync(keyPath)) {
        return fs.readFileSync(keyPath);
    }

    const key = crypto.randomBytes(32);
    fs.writeFileSync(keyPath, key);
    return key;
}

export function encrypt(text: string): string {
    const iv = crypto.randomBytes(IV_LENGTH);
    const cipher = crypto.createCipheriv(ALGORITHM, getEncryptionKey(), iv);
    let encrypted = cipher.update(text, 'utf8', 'hex');
    encrypted += cipher.final('hex');
    return `${iv.toString('hex')}:${encrypted}`;
}

export function decrypt(text: string): string {
    const [ivHex, encryptedText] = text.split(':');
    const iv = Buffer.from(ivHex, 'hex');
    const decipher = crypto.createDecipheriv(ALGORITHM, getEncryptionKey(), iv);
    let decrypted = decipher.update(encryptedText, 'hex', 'utf8');
    decrypted += decipher.final('utf8');
    return decrypted;
}

export async function hashPassword(password: string): Promise<string> {
    return new Promise((resolve, reject) => {
        const salt = crypto.randomBytes(16).toString('hex');

        crypto.scrypt(password, salt, 64, (err, derivedKey) => {
            if (err) reject(err);
            resolve(`${salt}:${derivedKey.toString('hex')}`);
        });
    });
}

export async function verifyPassword(password: string, hash: string): Promise<boolean> {
    return new Promise((resolve, reject) => {
        const [salt, key] = hash.split(':');
        crypto.scrypt(password, salt, 64, (err, derivedKey) => {
            if (err) reject(err);
            resolve(key === derivedKey.toString('hex'));
        });
    });
}

状态管理集成 (渲染进程) ​

用户状态管理 (renderer/stores/userStore.ts) ​

typescript
import { makeAutoObservable } from 'mobx';
import { dbAPI } from '../services/api';

class UserStore {
    users = [];
    currentUser = null;
    loading = false;
    error = null;

    constructor() {
        makeAutoObservable(this);
    }

    async loadUsers(page = 1, pageSize = 20) {
        this.loading = true;
        this.error = null;

        try {
            const result = await dbAPI.listUsers(page, pageSize);
            this.users = result.users;
        } catch (error) {
            this.error = error.message;
        } finally {
            this.loading = false;
        }
    }

    async createUser(userData) {
        this.loading = true;
        this.error = null;

        try {
            const newUser = await dbAPI.createUser(userData);
            this.users = [newUser, ...this.users];
            return newUser;
        } catch (error) {
            this.error = error.message;
            throw error;
        } finally {
            this.loading = false;
        }
    }

    async updateUser(userData) {
        this.loading = true;
        this.error = null;

        try {
            const updatedUser = await dbAPI.updateUser(userData);
            this.users = this.users.map((u) => (u.id === updatedUser.id ? updatedUser : u));
            return updatedUser;
        } catch (error) {
            this.error = error.message;
            throw error;
        } finally {
            this.loading = false;
        }
    }

    async login(username, password) {
        this.loading = true;
        this.error = null;

        try {
            // 实际项目中会有专门的认证服务
            const user = await dbAPI.getUserByUsername(username);
            const isValid = await verifyPassword(password, user.passwordHash);

            if (!isValid) {
                throw new Error('Invalid credentials');
            }

            this.currentUser = user;
            return user;
        } catch (error) {
            this.error = error.message;
            throw error;
        } finally {
            this.loading = false;
        }
    }

    logout() {
        this.currentUser = null;
    }
}

export default new UserStore();

数据流架构图 ​

数据同步机制 ​

1. 本地-云端同步设计 ​

2. 同步服务实现 (main/database/syncService.ts) ​

typescript
import PouchDB from 'pouchdb';
import PouchDBFind from 'pouchdb-find';
import { remoteDBUrl } from '../../config';

PouchDB.plugin(PouchDBFind);

class SyncService {
    private localDB: PouchDB.Database;
    private remoteDB: PouchDB.Database;

    constructor() {
        this.localDB = new PouchDB('local-sync-db');
        this.remoteDB = new PouchDB(remoteDBUrl);
    }

    async startSync() {
        try {
            // 初始同步
            await this.initialSync();

            // 设置实时同步
            this.localDB
                .sync(this.remoteDB, {
                    live: true,
                    retry: true
                })
                .on('change', (info) => {
                    console.log('Sync change:', info);
                })
                .on('error', (err) => {
                    console.error('Sync error:', err);
                });
        } catch (error) {
            console.error('Sync initialization failed:', error);
        }
    }

    private async initialSync() {
        // 获取最后同步时间
        const lastSync = await this.getLastSync();

        // 执行初始同步
        await this.localDB.replicate.from(this.remoteDB, {
            since: lastSync,
            batch_size: 100,
            batches_limit: 5
        });

        // 更新最后同步时间
        await this.setLastSync();
    }

    private async getLastSync(): Promise<string> {
        // 从本地存储获取最后同步时间
        // 实现省略...
        return '0';
    }

    private async setLastSync() {
        // 保存当前同步时间
        // 实现省略...
    }
}

export default new SyncService();

最佳实践 ​

  1. 数据安全：

    • 使用加密存储敏感数据
    • 主进程验证所有输入数据
    • 使用预加载脚本隔离上下文

  2. 性能优化：

    • 批量处理数据库操作
    • 使用分页加载大数据集
    • 缓存常用查询结果

  3. 错误处理：

    • 统一错误处理中间件
    • 用户友好的错误消息
    • 详细的日志记录

  4. 数据迁移：

    • 使用迁移脚本管理数据库变更
    • 支持版本回滚
    • 备份重要数据

  5. 测试策略：

    • 单元测试数据库服务
    • 集成测试IPC通信
    • E2E测试用户流程

总结 ​

本架构设计提供了一个完整的 Electron 数据库操作解决方案，关键优势包括：

  1. 分层架构：清晰的职责分离（渲染进程/主进程/数据库）
  2. 安全设计：数据加密、输入验证、安全通信
  3. 可扩展性：模块化设计便于功能扩展
  4. 数据同步：本地优先策略与云端同步
  5. 错误恢复：事务支持与数据备份机制

此架构适用于需要本地数据存储的 Electron 应用，如笔记应用、数据管理工具、离线应用等。实际实施时，应根据具体业务需求调整数据模型和同步策略。