EntityManager

Defined in: packages/rxdb/src/entity/entity-manager.ts:64

实体管理器

负责管理实体的整个生命周期，包括：

1. 实体的创建、更新和删除
2. 实体缓存管理
3. 实体关系处理
4. 实体仓库访问
5. 实体代理和变更跟踪

实体管理器是连接实体、仓库和数据库的桥梁， 它确保实体状态的一致性，并处理实体间的关系。

Properties

rxdb

readonly rxdb: RxDB;

Defined in: packages/rxdb/src/entity/entity-manager.ts:92

RxDB实例，提供数据库访问和事件分发

Methods

addEntityCache()

addEntityCache<T>(entity): void;

Defined in: packages/rxdb/src/entity/entity-manager.ts:309

添加实体到缓存 将实体实例添加到对应类型的缓存映射中

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
entity	InstanceType<T>	要缓存的实体实例

Returns

void

Remarks

主键还没有值的实体不入缓存：身份缓存是按 id 索引的，此刻它没有身份可索引。 从前照写不误，结果所有 id 缺失的实体共用 undefined 这一个槽， getEntityRef(T, undefined) 会返回其中随机一个 —— 稀疏水合据此更新，改的是另一条记录。 主键随后被赋值时由 reindexEntityCache 补登记（Proxy set 拦截触发），不会漏。

---

cleanAllCache()

cleanAllCache(): void;

Defined in: packages/rxdb/src/entity/entity-manager.ts:205

清理所有缓存

Returns

void

---

create()

create<T>(data): Promise<InstanceType<T>>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:483

创建实体 在数据库中创建新实体，并分发相关事件

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
data	InstanceType<T>	要创建的实体实例

Returns

Promise<InstanceType<T>>

创建后的实体实例

Throws

如果创建失败，抛出错误

---

createEntityRef()

createEntityRef<T>(
   EntityType, 
   data, 
   status?
): EntityInstanceType<T>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:246

创建实体引用 根据提供的数据创建或获取实体实例，并设置其状态 如果实体已存在于缓存中，则返回缓存的实例

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
EntityType	T	实体类型
data	EntityUpdateData<T>	实体数据，必须包含id
status?	EntityStatusOptions<T>	可选的实体状态配置

Returns

EntityInstanceType<T>

创建或获取的实体实例

---

destroy()

destroy(): void;

Defined in: packages/rxdb/src/entity/entity-manager.ts:218

销毁管理器并解除实体类绑定

Returns

void

---

getEntityRef()

getEntityRef<T>(EntityType, id): 
  | EntityInstanceType<T>
  | undefined;

Defined in: packages/rxdb/src/entity/entity-manager.ts:276

获取实体引用 从缓存中获取指定ID的实体实例

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
EntityType	T	实体类型
id	EntityStaticType<T, "idType">	实体ID

Returns

| EntityInstanceType<T> | undefined

实体实例，如果不存在则返回 undefined

---

getRepository()

getRepository<T, RT>(EntityType): RT;

Defined in: packages/rxdb/src/entity/entity-manager.ts:567

获取实体仓库 获取指定实体类型的仓库实例

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型
RT extends Repository<T, IRepository<T>>	-

Parameters

Parameter	Type	Description
EntityType	T	实体类型

Returns

RT

实体仓库实例

---

hasEntityRef()

hasEntityRef<T>(EntityType, id): boolean;

Defined in: packages/rxdb/src/entity/entity-manager.ts:292

检查实体是否在缓存中 判断指定ID的实体是否已在缓存中初始化

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
EntityType	T	实体类型
id	EntityStaticType<T, "idType">	实体ID

Returns

boolean

如果实体在缓存中存在则返回 true

---

init()

init(): void;

Defined in: packages/rxdb/src/entity/entity-manager.ts:96

Returns

void

---

instantiate()

instantiate<T>(EntityType, initData?): InstanceType<T>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:228

在当前数据库上下文中构造实体。 多个数据库共用一个 Entity class 时，直接 new Entity() 无法判断目标数据库， 应使用该方法保留实体构造函数的默认值和自定义初始化逻辑。

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type
EntityType	T
initData?	Partial<InstanceType<T>>

Returns

InstanceType<T>

---

mutations()

mutations<T>(options): Promise<InstanceType<T>[]>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:423

批量修改实体（创建/更新/删除）

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type	Description
options	RxDBMutationsMap<T>	批量修改选项

Returns

Promise<InstanceType<T>[]>

---

notifyExternalUpdate()

notifyExternalUpdate<T>(
   EntityType, 
   id, 
   patch
): void;

Defined in: packages/rxdb/src/entity/entity-manager.ts:533

通知外部更新 当通过 rawQuery 等方式绕过 ORM 直接修改数据库后， 调用此方法触发标准事件流（QueryCache 更新 + 跨 tab 广播）

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type	Description
EntityType	T	实体类型
id	EntityStaticType<T, "idType">	实体 ID
patch	Readonly<Partial<InstanceType<T>>>	变更的字段

Returns

void

Throws

已启用提交能力的库上、目标是版本化业务实体时，由捕获钩子抛出写拒绝错误； 此时一条事件都不会派发

Remarks

写入口语义矩阵行 11：库外的那次改动不经任何捕获挂载点，业务表变了而工作树不会多出单元。 让它照常派发，下游 QueryCache 会照着 patch 改内存实体，于是工作树、业务表、内存三方各说各话。

核心一次都不做归类，整段判定转交钩子的 WorkingTreeCaptureHook.gateExternalNotify()。 从前这里要自己问一次「这张表算哪类」 再把结果送进门禁，等于核心侧留着半句捕获语义；捕获规则随插件走之后，那半句就成了第二份真相。 现在交出去的只有实体身份与还没被调用的派发体。

取钩子走 RxDB.workingTreeCaptureHook 而不是 localAdapterSync：后者在「没配本地 适配器」与「还没连上」两种情形下抛错，而本方法今天在这两种库上都能调（它只派发事件）。 给它们凭空加一个「未连接」异常，就违反了 FR-046 的零行为差异。

---

reindexEntityCache()

reindexEntityCache<T>(entity, previousId): void;

Defined in: packages/rxdb/src/entity/entity-manager.ts:331

主键写入后重建身份缓存索引

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
entity	InstanceType<T>	主键已经是新值的实体实例（须为代理实例，与缓存里存的是同一个引用）
previousId	RxDBEntityId | undefined	写入前的主键值；构造后首次赋值时为 undefined

Returns

void

Remarks

由 createEntityProxy 的 set 拦截调用，覆盖两种情形：

• 构造后才有身份（主键无默认值，如 RxDBBranch.id）：此时旧槽不存在，只需登记新槽。 不补这一步，调用方手上的实例永远进不了身份缓存，后续 hydrate 会另造一个实例去更新， 两个对象各持一份状态（RXD-070）。
• 主键改名：旧槽必须清掉，否则按旧 id 查出来的实体 id 已经是新值， 身份缓存「cache.get(id).id === id」的不变式当场破掉。

旧槽只在确实存着这一个实例时才删：同 id 的其他引用不该被本次改名波及。

---

remove()

remove<T>(data): Promise<InstanceType<T>>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:451

删除实体 从数据库中删除实体，并分发相关事件

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
data	InstanceType<T>	要删除的实体实例

Returns

Promise<InstanceType<T>>

删除后的实体实例

Throws

如果删除失败，抛出错误

---

removeEntityCache()

removeEntityCache<T>(entity): void;

Defined in: packages/rxdb/src/entity/entity-manager.ts:346

从缓存中删除实体 将实体实例从缓存映射中移除

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
entity	InstanceType<T>	要移除的实体实例

Returns

void

---

removeMany()

removeMany<T>(entities): Promise<any[]>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:411

批量删除

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type
entities	InstanceType<T>[]

Returns

Promise<any[]>

---

reset()

reset<T>(data): void;

Defined in: packages/rxdb/src/entity/entity-manager.ts:467

重置实体

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type
data	InstanceType<T>

Returns

void

Remarks

这里此前是 async，而 EntityBase.reset 及三处系统实体都声明 reset: () => void —— 声明与运行时对不上（实际返回 Promise<void>）。 这个方法只把 status 回滚到 origin，不碰任何 I/O， 所以正解是让实现变同步去迎合声明，而不是把 4 处声明改成 Promise<void>： 后者会让所有既有的 entity.reset() 调用点凭空多出一个未处理的 Promise。

---

save()

save<T>(entity): Promise<InstanceType<T>>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:359

保存实体 根据实体状态决定是创建新实体还是更新现有实体 如果有关联实体需要保存，会使用事务进行批量保存

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type
entity	InstanceType<T>

Returns

Promise<InstanceType<T>>

保存后的实体实例

---

saveMany()

saveMany<T>(entities): Promise<InstanceType<T>[]>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:393

批量保存

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type
entities	InstanceType<T>[]

Returns

Promise<InstanceType<T>[]>

---

update()

update<T>(data): Promise<InstanceType<T>>;

Defined in: packages/rxdb/src/entity/entity-manager.ts:498

更新实体 在数据库中更新实体，只更新已修改的属性，并分发相关事件

Type Parameters

Type Parameter	Description
T extends EntityType	实体类型

Parameters

Parameter	Type	Description
data	InstanceType<T>	要更新的实体实例

Returns

Promise<InstanceType<T>>

更新后的实体实例

Throws

如果更新失败，抛出错误