Dexie.js 中 Entity 类的正确使用方式

在 Dexie.js 这个 IndexedDB 的封装库中，Entity 类是一个强大但容易被误用的功能。本文将深入解析 Entity 的设计理念和正确使用方法，帮助开发者避免常见的陷阱。

Entity 类的设计初衷

Dexie.js 的 Entity 类主要目的是为数据库对象提供方法扩展能力。它允许开发者为存储在 IndexedDB 中的数据对象添加自定义方法，同时保持与数据库的无缝交互。

关键点在于：Entity 实例必须由 Dexie 系统内部创建，而不是通过传统的 new 操作符实例化。这是因为 Dexie 使用 Object.create() 来生成正确的原型链，而不是调用构造函数。

常见错误模式

许多开发者（包括我自己最初）会尝试这样使用：

class MyEntity extends Entity<MyDexie> {
  constructor() {
    super(); // 这里会抛出 TypeError
  }
}

这种模式会直接导致 TypeError，因为 Dexie 禁止直接实例化 Entity 子类。

正确使用模式

1. 声明 Dexie 子类： 首先需要创建一个继承自 Dexie 的数据库类。

2. 定义 Entity 子类： 创建一个继承自 Entity 的类，添加你需要的属性和方法。在这些方法中，你可以通过 this.db 访问数据库实例。

3. 映射类到表： 使用 mapToClass() 方法将实体类连接到特定的表。

4. 创建对象： 通过 db.yourTable.add({...普通对象}) 来创建新对象，而不是使用 new 操作符。

5. 查询数据： 当从数据库查询时，返回的结果会自动成为你的实体类实例，因此你可以直接调用定义的方法。

实际应用示例

假设我们有一个任务管理应用：

// 1. 声明Dexie子类
class TaskDB extends Dexie {
  tasks: Dexie.Table<ITask, number>;
  
  constructor() {
    super('TaskDB');
    this.version(1).stores({
      tasks: '++id,title,completed'
    });
    
    // 3. 映射实体类到表
    this.tasks.mapToClass(Task);
  }
}

// 2. 定义Entity子类
class Task extends Entity<TaskDB> {
  id!: number;
  title!: string;
  completed!: boolean;
  
  // 自定义方法
  markComplete() {
    return this.db.tasks.update(this.id, {completed: true});
  }
}

// 使用
const db = new TaskDB();

// 4. 添加新任务（正确方式）
await db.tasks.add({
  title: '学习Dexie',
  completed: false
});

// 5. 查询并使用方法
const task = await db.tasks.get(1);
await task.markComplete();

为什么不能使用构造函数

Dexie 的这种设计有几个优点：

1. 性能优化：使用 Object.create() 比调用构造函数更高效
2. 序列化友好：数据库存储的是纯数据对象，不包含方法
3. 原型继承：查询时自动恢复原型链和方法

替代构造函数的方案

如果需要初始化逻辑，可以考虑：

1. 使用工厂函数创建普通对象
2. 在方法中添加初始化逻辑
3. 使用数据库钩子（hooks）进行初始化

总结

理解 Dexie.js 中 Entity 类的特殊设计对于正确使用这个库至关重要。记住关键原则：永远不要直接实例化 Entity 子类，而是让 Dexie 通过数据库操作来管理实体对象的生命周期。这种模式虽然初看起来有些反直觉，但它为 IndexedDB 操作提供了强大而灵活的扩展能力。