MikroORM v4 升级到 v5 完整指南:破坏性变更、迁移步骤与源码级解读
MikroORM v4 升级到 v5 完整指南:破坏性变更、迁移步骤与源码级解读
本篇指南以 MikroORM 官方 v4→v5 升级文档为骨架,逐条梳理全部破坏性变更(breaking changes),包括方法签名重构、类型安全增强、全局 identity map 限制、populate 行为变化、migrations 配置调整等,并结合当前仓库源码(packages/core、packages/migrations 等)给出默认值、配置项来源与底层实现证据。读完本文,你将能够对照自己的代码库逐项排查并完成 v4→v5 的平滑迁移,同时理解这些变更背后的设计动机。
说明:v5 是 MikroORM 一次大规模 API 重构版本,本文覆盖其全部破坏性变更。若你的项目未使用自定义
NamingStrategy、未使用@Repository()装饰器等特性,部分条目可直接跳过。
环境要求:Node 与 TypeScript 版本门槛
- Node 14+ 必需:v5 放弃了对更早 Node 版本的支持。
- TypeScript 4.1+ 必需:v5 放弃了对更早 TypeScript 版本的支持。
升级前请先确认运行环境满足上述版本要求,否则包安装、类型检查或运行时行为都可能异常。
方法签名重构:全面切换到 options 对象
v5 之前,许多方法接受多个(往往是布尔类型的)位置参数;v5 将这些方法统一重构为接受 options 对象,以提升可读性。部分方法此前同时提供两种签名(多参数签名与 options 签名),v5 中多参数签名被彻底移除。
受影响的完整方法列表如下:
em.find()em.findOne()em.findOneOrFail()em.findAndCount()em.getReference()em.merge()em.fork()em.begin()em.assign()em.create()repo.find()repo.findOne()repo.findOneOrFail()repo.findAndCount()repo.findAll()repo.getReference()repo.merge()collection.init()repo.create()repo.assign()
此外,IDatabaseDriver 接口上的对应方法也一并遵循该约定(见 IDatabaseDriver.ts)。迁移时,请将调用点逐一改写为 options 对象形式,例如把布尔参数移入 FindOptions、AssignOptions 等命名选项中。
类型安全增强:populate、fields、orderBy 严格类型化
populate 参数严格类型化(支持点号表示法)
FindOptions.populate 现在只接受字符串数组或布尔值,对象形式不再支持。设置加载策略(loading strategy)请改用 FindOptions.strategy。所有相关方法的返回类型也升级为正确推导的 Loaded 响应类型,让链式访问已 populate 的关系时获得完整的类型提示。
fields 参数严格类型化
FindOptions.fields 同样进行了严格类型化,**点号表示法(dot notation)**也在类型检查范围内,可精确选择嵌套字段。
orderBy 参数严格类型化,且支持数组形式
FindOptions.orderBy 现在严格类型化,并且允许传入对象数组而非仅单个对象:
const books = await em.find(Book, {}, {
orderBy: [
{ title: 1 },
{ author: { name: -1 } },
],
});
数组形式让"多条件排序、且不同字段方向不同"的写法更加直观。
移除 @Repository() 装饰器
@Repository() 装饰器存在设计缺陷:它只有在文件被足够早地 require(即在 ORM 初始化之前)时才能正常工作,否则该仓库根本不会被注册。因此 v5 将其移除。
请改用实体定义中的 customRepository 配置:
@Entity({ customRepository: () => CustomRepository })
export class Author {
// ...
}
禁止全局 identity map
v5 不再允许使用全局 identity map。此前在无 request context 的情况下直接使用全局 EM 是常见错误根源——每个请求都应该有独立上下文,避免互相干扰。
现在若尝试使用全局上下文会得到校验错误。仍可通过以下两种方式关闭该校验(尤其在单元测试中很有用):
- 配置项:
allowGlobalContext: true - 环境变量:
MIKRO_ORM_ALLOW_GLOBAL_CONTEXT
从源码看,该配置的默认值为 false(见 Configuration.ts),接口注释明确说明"每个请求应有自己的上下文,不建议在生产环境使用全局 EM",并指出可通过 MIKRO_ORM_ALLOW_GLOBAL_CONTEXT 环境变量设置(见 Configuration.ts)。
LoadedCollection.get() 与 $ 返回 Collection 实例
此前动态添加的 getter 返回的是集合项(items)的数组拷贝;v5 改为返回 Collection 实例本身。该实例同样可迭代、有 length getter、支持索引访问,因此行为上模拟了数组。若想恢复旧的数组拷贝行为,请像普通集合一样调用 getItems()。
表别名规则变更:select-in 策略与 QueryBuilder
此前 select-in 加载策略以及 QueryBuilder 中,表别名始终是字母 e 加唯一索引;v5 改为与 joined 策略相同的方式——从实体名推断首字母。
如果你在自定义 SQL 片段等位置硬编码了别名,这一变更会破坏现有 SQL。可通过自定义命名策略重写 aliasName 方法恢复旧行为:
import { AbstractNamingStrategy } from '@mikro-orm/core';
class CustomNamingStrategy extends AbstractNamingStrategy {
aliasName(entityName: string, index: number) {
return 'e' + index;
}
}
aliasName 是 AbstractNamingStrategy 与 NamingStrategy 接口中定义的核心方法(见 AbstractNamingStrategy.ts)。
更推荐的方式是使用 expr() 辅助函数动态获取别名,避免硬编码:
expr(alias => `lower('${alias}.name')`)
Migrations 不再存储扩展名
生产环境通过 node 与 ts-node 运行迁移现在行为一致:新记录的迁移文件名不再包含扩展名。旧格式(带扩展名)仍然受支持(例如仍可回滚),因此实际上并非严格破坏性变更,但新生成的迁移文件会使用无扩展名格式。
assign() helper 行为变化
- Embeddable 实例现在由
EntityFactory创建,并且遵循forceEntityConstructor配置。因此,向 embedded 属性赋值时需要有 EM 实例——推荐改用em.assign()以规避此限制。 - 子实体深赋值默认启用:根据 payload 中是否含 PK 来决定是更新还是新建。可通过
assign选项中的updateByPrimaryKey: false关闭该行为。从源码看,其默认值为true(见 Configuration.ts)。 mergeObjects选项默认开启:v5 中该选项默认启用(源码中assign.mergeObjectProperties默认值见 Configuration.ts)。
em.populate() 始终返回实体数组
此前可用单个实体调用 em.populate() 并期望返回单个实体;由于 TS 4.5 的类型问题,该方法现在总是返回实体数组。若希望得到单实体返回类型,可使用解构:
const [loadedAuthor] = await em.populate(author, ...);
QueryBuilder 可被 await
v4 中 await 一个 QB 实例是 no-op;v5 中 QB 是 promise-like 接口,可以直接 await。详见 Awaiting the QueryBuilder 一节。
UnitOfWork.getScheduledCollectionDeletions() 被移除
此前计划中的集合删除(scheduled collection deletions)用于一个 hack 场景:当通过 orphan removal 删除 1:m 集合时,若同一工作单元内插入同 PK 的实体(不同实例),可能提前触发删除以避免唯一约束冲突。v5 移除了该方法,同时 IDatabaseDriver.clearCollection() 也不再存在于 driver API 中。
populateAfterFlush 默认启用
flush 新实体后,其所有关系现在默认被标记为"已 populate",就像从数据库加载过一样。这使已加载实体与刚插入实体的 e.toJSON() 序列化输出保持一致。
v4 中该行为默认关闭,因此 flush 后的新实体序列化时关系部分只含 FK。可通过 populateAfterFlush: false 恢复旧行为。源码中默认值确认为 true(见 Configuration.ts),接口注释也解释了该选项是为了"对齐已加载实体与刚插入实体的序列化输出"(见 Configuration.ts)。
migrations.pattern 替换为 migrations.glob
MikroORM 底层使用 umzug 管理迁移,v5 将 umzug 升级到 v3.0,导致 pattern 配置项不可用,取而代之的是 glob。
glob 的默认值为 !(*.d).{js,ts},即同时匹配 JS 与 TS 文件(但排除 .d.ts)。通常无需修改,因为该默认值同时适用于开发与生产环境。
Population 不再默认推断 where 条件
该行为仅影响 SELECT_IN 策略——JOINED 策略天然隐含推断。
v4 中,使用 em.find() 等方法的 populate 提示时,会分析主查询并把部分条件提取出来用于 populate。以下示例会找出所有"拥有指定 ID 图书"的作者,并 populate 其 books 集合,且再次使用该 PK 条件,导致集合中只有 PK 为 1、2、3 的书:
// v4 行为:Author.books 集合中只会有 PK 1、2、3 的书
const a = await em.find(Author, { books: [1, 2, 3] }, { populate: ['books'] });
若想加载全部图书,v4 中需要额外的 em.populate() 调用:
const a = await em.find(Author, { books: [1, 2, 3] });
await em.populate(a, ['books']);
v5 改变了该行为,可通过 populateWhere 选项全局或局部配置:
- 全局配置:
PopulateHint.ALL(v5 默认)或PopulateHint.INFER(v4 默认行为)。 - 局部配置(
FindOptions):除PopulateHint外,还可传入自定义 where 条件,该条件会传递给em.populate()。
// 局部恢复旧行为
const a = await em.find(Author, { books: [1, 2, 3] }, {
populate: ['books'],
populateWhere: PopulateHint.INFER,
});
从源码看,PopulateHint 枚举定义于 enums.ts:INFER = 'infer'(从 where 条件推断 populate 提示)、ALL = 'all'(对全部关系应用 populate 提示)。配置默认值 populateWhere: PopulateHint.ALL 见 Configuration.ts。在 EntityLoader.ts 中可以看到,em.populate() 内部会把 populateWhere 默认回退为 'infer',且当传入对象时会通过 extractChildCondition 提取子条件——这正是局部自定义 where 条件的底层实现路径。
em.create() 尊重必填属性
em.create() 现在要求传入所有非可选属性。部分属性在 TS 类型上标记为 required,但实际有默认值(运行时或数据库层),此时可使用 OptionalProps symbol 显式指定哪些属性应被视为可选。
必填属性在插入前校验
v4 中必填属性校验发生在数据库层,因此只对 SQL 驱动生效;v5 改为基于实体元数据的运行时校验,因此 MongoDB 用户现在需要:
- 在可选属性上使用
nullable: true;或 - 通过
validateRequired: false全局关闭该校验(见 Configuration.ts,默认值为true,见 Configuration.ts)。
PrimaryKeyType symbol 可定义为可选
当使用非标准 PK 类型时,可用 PrimaryKeyType symbol 告知类型系统。v4 中该属性必须定义为 required;v5 中也可定义为 optional,类型约束更宽松。
迁移自查清单
按上述条目逐项对照你的代码库,建议按以下顺序排查:
- 升级 Node 至 14+、TypeScript 至 4.1+;
- 全局搜索文档列出的 20 个方法调用点,改写为 options 对象签名;
- 检查
populate/fields/orderBy的类型错误并修正为点号数组形式; - 将
@Repository()装饰器替换为@Entity({ customRepository }); - 确认每个请求都有独立 EM 上下文(或用
allowGlobalContext显式绕过校验); - 检查自定义 SQL 中硬编码的表别名,改用
expr()或自定义aliasName; - 核对
migrations.pattern→migrations.glob的配置迁移; - 确认
populateAfterFlush、populateWhere、validateRequired、assign相关默认值变化是否符合预期; - 将
em.populate()返回值按数组处理,并用OptionalProps/PrimaryKeyType修正实体类型定义。
完成上述步骤后,即可平滑过渡到 v5,并享受更严格的类型推导与更清晰的 API 设计带来的长期收益。相关行为细节可继续阅读 query-builder.md、entity-manager.md 与 cascading.md 等文档,或直接查阅 packages/core/src 下的源码实现。