MikroORM 简介
MikroORM 是一个运行在 Node.js 上的 TypeScript ORM,基于 Data Mapper、Unit of Work 和 Identity Map 模式,灵感来自 Doctrine 和 Hibernate。实体是带有 @Entity()、@Property() 等装饰器的普通类;EntityManager 在内存中跟踪变更,并在调用 em.flush() 时将其批量合并为最精简的 SQL。它支持 PostgreSQL、MySQL/MariaDB、SQLite 和 MongoDB。
安装
安装核心包和一个驱动包:
npm install @mikro-orm/core @mikro-orm/postgresql @mikro-orm/cli reflect-metadata
或 @mikro-orm/mysql、@mikro-orm/sqlite、@mikro-orm/mongodb
每个驱动包都会重新导出 MikroORM 与已针对该驱动预配置好的 defineConfig。应从驱动包导入,而不是从 @mikro-orm/core 导入,这样驱动特有的功能(如 SQL 驱动上的 QueryBuilder)才能获得正确的类型。当前 MikroORM 中没有 type: "postgresql" 这样的配置键,导入的驱动本身即选定后端。
定义实体
可使用 @Entity、@PrimaryKey、@Property、@ManyToOne、@OneToMany、Collection、Enum、Index、Unique、Embeddable、Embedded、Filter 等装饰器定义实体。示例中包含一个 @Embeddable() 的 Address 类(street、city、country),一个带 @Filter 软删除过滤器的 User 实体,其中包含 @PrimaryKey 的 uuid 主键、@Index 与 @Unique 的 email、@Enum 的 role、@Embedded 的 address、@OneToMany 的 posts 集合,以及 createdAt、updatedAt(onUpdate 更新)和可空的 deletedAt 字段;Post 实体包含 uuid 主键、title、text 类型的 body、published 布尔值、@ManyToOne 的 author 和 createdAt。
初始化 ORM 与 Unit of Work
从 @mikro-orm/postgresql 导入 MikroORM 与 defineConfig,从 @mikro-orm/core 导入 RequestContext。使用 MikroORM.init(defineConfig({...})) 初始化,配置中指定 entities、dbName,并可按环境开启 debug。
在 Express 中,用 RequestContext.create(orm.em, next) 为每个请求派生一个 EntityManager fork,避免并发请求共享 Identity Map 状态。在路由处理器中调用 orm.em,对实体直接赋值修改后调用 await em.flush(),MikroORM 会对比差异并生成 UPDATE 语句。
Identity Map 使得同一上下文中两次加载同一实体返回相同引用(例如两次 em.findOne 同一 id,结果 user1 === user2 为 true)。
QueryBuilder 可从驱动包导入后使用,示例通过 createQueryBuilder 配合 select、leftJoin、where、groupBy、orderBy、limit 和 getResultList 查询发帖数最多的管理员作者。
迁移与种子数据
常用命令包括:
npx mikro-orm migration:create # 根据实体/模式差异生成 npx mikro-orm migration:create --initial npx mikro-orm migration:up # 应用待执行迁移 npx mikro-orm migration:down # 回滚上一条 npx mikro-orm migration:pending # 列出未执行的迁移 npx mikro-orm seeder:run --class=UserSeeder
在共享或生产数据库上运行 migration:up 之前,应先审查生成的 SQL。
示例场景
示例一:为 Express API 添加请求级 EntityManager。用 RequestContext.create(orm.em, next) 包装应用,使每个请求从 orm.em 派生独立的 EntityManager,而不是复用全局实例;在路由处理器中继续调用 orm.em(MikroORM 会通过 RequestContext 将其解析为当前请求的 fork),而不是导入共享的 em 常量;通过负载测试确认并发的 PUT /users/:id 请求不再看到彼此未 flush 的变更。结果是每个 HTTP 请求拥有隔离的 Identity Map 和 Unit of Work,不再出现跨请求状态泄漏。
示例二:添加软删除过滤器和值对象。为 User 添加可空的 deletedAt: Date 属性,以及 @Filter({ name: "active", cond: { deletedAt: null }, default: true }) 类装饰器,使普通查询自动排除已软删除的行;添加带 street/city/country 属性的 @Embeddable() Address 类,并在 User 上添加 @Embedded(() => Address, { nullable: true }) 字段,字段会内联存储在 user 表中,而不是单独的表;生成迁移(npx mikro-orm migration:create)并审查 SQL,应新增 deleted_at 及三个 address_* 列,不创建新表。结果是软删除用户从默认查询中消失,无需在应用代码中额外写 WHERE 子句,地址作为类型化值对象存在且无需 join。
使用准则
在修改实体后,每个逻辑工作单元调用一次 em.flush();MikroORM 会将所有待处理变更批量合并为最少数量的 SQL 语句,而不是每个变更一条查询。
在 SQL 驱动上,关联关系不会隐式懒加载,需要显式 populate(例如 em.find(User, {}, { populate: ["posts"] })),否则会得到未初始化的 Collection 或引用。
在 Web 框架中为每个请求使用 RequestContext.create(),让每个请求拥有独立的 EntityManager fork 和 Identity Map;跨并发请求共享一个全局 em 会导致陈旧数据和跨请求 bug。
用 @Filter 处理软删除或多租户,而不是到处重复 where 子句;除非在单个查询中显式禁用,过滤器会自动应用。
对于应在所属表内联存储而非 join 表的值对象(地址、金额),使用 @Embedded/@Embeddable。
在将生成的迁移 SQL 应用到重要数据之前务必审查;migration:fresh 会删除数据库,仅用于本地/开发环境。
应从驱动包(@mikro-orm/postgresql、@mikro-orm/sqlite 等)导入 MikroORM/defineConfig,而不是从 @mikro-orm/core 导入,以获得 QueryBuilder 等驱动特有的类型。