MikroORM v4 到 v5 升级指南:完整破坏性变更解析与迁移实战
MikroORM v4 到 v5 升级指南:完整破坏性变更解析与迁移实战
本篇指南以 MikroORM 官方 v5 升级文档为主体,系统梳理从 v4 升级到 v5 时涉及的全部破坏性变更,覆盖 API 签名重构、类型系统增强、全局身份映射(Identity Map)限制、加载策略与表别名变化、迁移配置调整等核心主题。读完本文,你将能逐条对照检查自己的代码库,理解每一项变更背后的设计动机,并借助源码实现细节安全完成升级迁移。
说明:下文每个小节均对应升级文档中的一项破坏性变更。多数变更只影响使用了特定特性的用户——例如你未使用自定义
NamingStrategy,就无需关心其接口变化。建议按小节逐条核对,仅处理与你相关的部分。
运行环境要求升级:Node 14+ 与 TypeScript 4.1+
v5 首先提升了运行环境的下限:
- Node.js 14+:对旧版本 Node 的支持被正式移除;
- TypeScript 4.1+:对旧版本 TypeScript 的支持被正式移除。
升级前请确认本机 node --version 与 tsc --version(或项目依赖中的 typescript 版本)满足上述要求。这一硬性门槛是整个 v5 类型系统重构(如后续的 Loaded 响应类型、OptionalProps 推断)能够成立的前提。
Options 参数重构:告别一长串位置参数
v5 对大量 API 做了可读性重构:此前许多方法接受多个(往往是布尔型的)位置参数,v5 统一改为传入 options 对象;部分方法在 v4 中同时提供了两种签名(多参数签名与 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()、repo.create()、repo.assign()collection.init()
该重构同样适用于 IDatabaseDriver 接口上的方法。迁移时,只需把原来散落的位置参数整理进一个 options 对象即可,例如把 em.find(Book, where, <a href="https://link.gitcode.com/i/4526e0ea5fe7f491721d9dde792212b6" target="_blank">'author'], 1, true) 形式的调用改写为 em.find(Book, where, { populate: ['author'], limit: 1, ... })。从源码结构看,EntityManager 的方法定义(见 [EntityManager.ts)与 IDatabaseDriver 接口(见 IDatabaseDriver.ts)均以 options 对象统一了这些方法的入参。
类型安全全面增强:populate、fields 与 orderBy
v5 在类型层面做了三处重要收紧:
FindOptions.populate 严格类型化:现在只接受字符串数组或布尔值,v4 中的对象写法不再支持。如需设置加载策略(loading strategy),请使用独立的 FindOptions.strategy 选项。相应的,所有此类方法的返回类型现在都是正确推导的 Loaded 响应类型——这依赖 packages/core/src/typings.ts 中定义的 Loaded、MergeLoaded 等类型工具,populate 提示会直接反映到方法返回值的类型上。
FindOptions.fields 严格类型化:字段选择同样支持点号(dot notation)并做严格类型校验。
FindOptions.orderBy 严格类型化:除了单一对象,现在允许传入对象数组,以表达多层排序条件:
const books = await em.find(Book, {}, {
orderBy: [
{ title: 1 },
{ author: { name: -1 } },
],
});
移除 @Repository() 装饰器:改用 customRepository
@Repository() 装饰器在 v4 中存在一个根本性缺陷:它只有在文件被足够早地加载(早于 ORM 初始化)时才能正常工作,否则自定义仓库根本不会被注册。v5 将其移除,推荐做法是在实体定义中通过 @Entity() 的 customRepository 选项声明:
@Entity({ customRepository: () => CustomRepository })
export class Author {
// ...
}
迁移要点:删除所有 @Repository() 装饰器,把仓库类改为在实体装饰器里以回调函数(延迟求值)方式注册,避免循环依赖问题。
全局身份映射被禁止:请求必须有独立上下文
v5 起不再允许使用全局身份映射(global identity map)。此前在无 Request Context 的情况下直接使用全局 EM 是常见的问题来源——每个请求必须拥有专属上下文,互不干扰,否则会引发难以排查的诡异 bug。
现在若尝试使用全局上下文,会直接得到校验错误。若确实需要关闭该检查(例如在单元测试中),可以通过配置项 allowGlobalContext 或对应的环境变量 MIKRO_ORM_ALLOW_GLOBAL_CONTEXT 实现:
// mikro-orm.config.ts
defineConfig({
allowGlobalContext: true,
});
# 或通过环境变量
MIKRO_ORM_ALLOW_GLOBAL_CONTEXT=true
从源码看,allowGlobalContext 的默认值为 false(见 Configuration.ts),环境变量映射实现在 env-vars.ts(布尔值解析接受 true/t/1)。另外值得注意:em.fork() 内部会临时放开该限制再恢复,因为从全局 EM fork 出子上下文是被允许的合法操作(见 EntityManager.ts)。
LoadedCollection.get() 与 $ 现在返回 Collection 实例
v5 之前,LoadedCollection 动态添加的 get() 与 $ getter 返回的是集合元素的数组拷贝;v5 起改为返回 Collection 实例本身。该实例同样是可迭代的,并提供 length getter 与索引访问支持,因此行为上"模拟"了数组。若需要像以前那样拿到数组拷贝,请像操作普通集合一样调用 getItems():
// v5 之前:返回数组拷贝
const items = loadedCollection.get();
// v5:返回 Collection 实例(可迭代、支持 length 与索引访问)
const collection = loadedCollection.get();
const first = collection[0];
const count = collection.length;
// 需要数组时
const items = loadedCollection.get().getItems();
表别名策略变更:select-in 策略与 QueryBuilder 统一为实体名推断
此前,select-in 加载策略与 QueryBuilder 生成的表别名始终是字母 e 加上唯一索引(如 e0、e1)。v5 改为与 joined 策略一致的做法:从实体名推断别名首字母。如果你在自定义 SQL 片段等位置硬编码使用了旧别名,这会成为破坏性变更。
两种应对方式:
方式一:恢复旧行为——实现自定义命名策略,覆写 aliasName 方法:
import { AbstractNamingStrategy } from '@mikro-orm/core';
class CustomNamingStrategy extends AbstractNamingStrategy {
aliasName(entityName: string, index: number) {
return 'e' + index;
}
}
方式二(推荐):使用 raw()/expr() 动态获取别名。v5 起可以借助 raw() 辅助函数在查询中动态拿到当前属性别名,避免硬编码:
import { raw } from '@mikro-orm/core';
// 回调签名接收当前属性别名,等价于 expr(alias => `lower('${alias}.name')`)
await em.find(User, { [raw(alias => `lower(${alias}.name)`)]: name.toLowerCase() });
从源码实现看,raw() 支持函数签名——当传入函数时,内部以 ALIAS_REPLACEMENT 占位符调用它,最终由 ORM 在生成 SQL 时替换为实际别名(见 RawQueryFragment.ts)。这应成为新代码的首选方式。
迁移文件不再带扩展名存储
在 v5 中,通过 node 与 tsx 在生产环境运行迁移的流程得到统一,新记录的迁移文件名不再包含扩展名。这实际上通常不构成破坏:旧格式(带扩展名)依然受支持,例如仍可正常回滚;只是新生成的迁移日志不再含扩展名。
assign() 助手的行为变化
v5 对 em.assign() 做了三处调整:
-
Embeddable 实例现在经由
EntityFactory创建,并遵守forceEntityConstructor配置。因此,在给嵌入属性赋值时你需要持有 EM 实例——建议优先使用em.assign()来完成赋值操作。 -
子实体的深度赋值默认启用:现在会基于 payload 中是否存在主键(PK)来决定子实体的赋值行为(存在 PK 视为更新、不存在视为新建)。可通过
assignoptions 中的updateByPrimaryKey: false关闭。从源码看,updateByPrimaryKey的默认值为true(见 Configuration.ts)。 -
mergeObjects选项默认启用,合并对象行为成为默认。
em.populate() 始终返回实体数组
v4 中 em.populate() 传入单个实体时,返回值也是单个实体;由于 TypeScript 4.5 的类型问题,v5 起该方法始终返回实体数组。若想保留单实体的返回类型,可用解构:
const [loadedAuthor] = await em.populate(author, ...);
从源码看,populate() 的实现先把输入统一转为数组(Utils.asArray(entities)),再交给 EntityLoader 执行加载(见 EntityManager.ts),其返回类型会依据输入是数组还是单个实体分别推导为数组或 MergeLoaded 包装的实体——这是类型层面的行为,与运行时统一走数组处理并不矛盾。
QueryBuilder 变得可 await
v4 中直接 await 一个 QueryBuilder 实例是无操作(no-op);v5 起 QueryBuilder 实现了 promise-like 接口,可以直接 await 执行查询。关于执行方式与结果格式的完整说明,参见 执行查询 一节:execute('all') 返回对象数组、execute('get') 返回单个对象、execute('run') 返回 { affectedRows, insertId, row },并可通过第二参数 ExecuteOptions(mapResults、mergeResults、rawResults)控制结果处理。
UnitOfWork.getScheduledCollectionDeletions() 被移除
该方法此前服务于一个特殊 hack:在通过孤儿删除(orphan removal)移除 1:m 集合时,若同一工作单元内要插入同一主键的新实体实例,可能需要提前删除以避免唯一约束冲突。v5 将其移除,同时 IDatabaseDriver.clearCollection() 也不再存在于驱动 API 中。这意味着相关清理逻辑已由 UnitOfWork 内部机制接管,自定义驱动实现若依赖该方法需要同步更新。
populateAfterFlush 默认开启
v5 起,flush 新实体后其所有关联都会被标记为已加载(populated),就像该实体刚从数据库加载一样。这使已加载实体的 e.toJSON() 序列化输出与新插入实体保持一致。v4 中该行为默认关闭,新实体 flush 后其序列化结果只包含关联的外键。如需恢复旧行为,设置 populateAfterFlush: false(默认值为 true,见 Configuration.ts)。
migrations.pattern 被 migrations.glob 取代
迁移底层使用 umzug 库,v5 将其升级到 v3.0,pattern 配置项随之不再可用,替换为 glob,MikroORM 的配置也同步跟进。
defineConfig({
migrations: {
// 默认值:!(*.d).{js,ts,cjs}
glob: '!(*.d).{js,ts,cjs}',
},
});
默认值会同时匹配 JS 与 TS 文件(但不匹配 .d.ts 声明文件),通常无需改动——该默认对开发与生产环境都适用。注意当前仓库源码中默认值为 !(*.d).{js,ts,cjs}(见 Configuration.ts),相比文档所述 !(*.d).{js,ts} 额外包含了 cjs,升级时如使用自定义 glob 请按需调整。
Population 不再默认推断 where 条件(populateWhere)
此变更仅影响 SELECT_IN 策略,JOINED 策略天然隐含推断。
v4 中,当你在 em.find() 等调用里使用 populate 提示时,ORM 会分析实体查询并抽取部分条件用于 population。例如下面的查询会找到拥有指定书籍的作者,并仅用该 PK 条件填充其 books 集合,导致集合里只有 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 选项全局或局部配置:
- 全局:在 ORM 配置中指定
PopulateHint.ALL或PopulateHint.INFER。前者是 v5 默认值(不推断),后者是 v4 的默认行为(推断)。 - 局部:通过
FindOptions传入populateWhere,甚至可以直接指定一个自定义 where 条件,该条件会被透传给em.populate()调用。
// 局部恢复旧行为
const a = await em.find(Author, { books: [1, 2, 3] }, {
populate: ['books'],
populateWhere: PopulateHint.INFER,
});
PopulateHint 枚举定义于 enums.ts:INFER = 'infer'(从 where 条件推断)、ALL = 'all'(应用到所有关联);配置默认值 populateWhere: PopulateHint.ALL 见 Configuration.ts。
em.create() 尊重必填属性:使用 OptionalProps
v5 起 em.create() 会要求你传入所有非可选(non-optional)属性。有些属性在 TS 类型上被声明为必填,但运行时或数据库层有默认值——对这类属性,可以使用 OptionalProps 符号声明哪些属性应被视为可选:
import { OptionalProps } from '@mikro-orm/core';
@Entity()
export class User {
[OptionalProps]?: 'createdAt'; // 声明 createdAt 可选
@PrimaryKey()
id!: number;
@Property({ default: 'now()' })
createdAt?: Date;
}
OptionalProps 符号定义于 typings.ts,类型系统据此计算 em.create() 的入参类型(相关类型工具见 typings.ts)。Opt<Date> 类型包装器(见 typings.ts)是另一种替代写法。
必填属性在插入前校验(validateRequired)
v4 中必填属性校验发生在数据库层,因此只对 SQL 驱动生效。v5 改为基于实体元数据的运行时校验,MongoDB 用户也因此需要:
- 在可选属性上使用
nullable: true,或 - 通过 ORM 配置
validateRequired: false全局关闭该校验。
validateRequired 默认值为 true(见 Configuration.ts)。若你的 Mongo 实体有大量可选属性且不想逐一加 nullable: true,全局关闭校验是更省事的迁移路径。
PrimaryKeyType 符号可声明为可选
此前当主键类型非标准时,可用 PrimaryKeyType 符号让类型系统知晓;v4 要求该属性声明为必填,v5 起声明为可选(optional)也可以了:
@Entity()
export class Book {
[PrimaryKeyType]?: [string, number]; // v5 中可选声明即可
@PrimaryKey()
code!: string;
@PrimaryKey()
no!: number;
}
升级顺序建议与检查清单
综合以上变更,建议按以下顺序完成迁移:
- 环境升级:Node 14+、TypeScript 4.1+,升级 MikroORM 各包(
@mikro-orm/core、@mikro-orm/<driver>、@mikro-orm/cli、@mikro-orm/migrations等)至 v5。 - 编译期排查:先让 TypeScript 编译器暴露所有签名不匹配的调用点——Options 参数重构、populate/fields/orderBy 类型收紧、
em.populate()返回值变化都会在此阶段显现。 - 按清单逐项核对:移除
@Repository()改用customRepository;检查是否依赖全局 EM(改用 RequestContext 或临时开启allowGlobalContext);搜索硬编码表别名(改用自定义aliasName或raw()回调);检查自定义 SQL 片段与迁移文件命名。 - 行为差异验证:重点回归测试
assign()深度赋值、populateAfterFlush序列化输出、populateWhere加载结果,以及 Mongo 实体必填属性校验。
文中涉及的源码与配置依据可在以下位置继续深入:配置默认值见 Configuration.ts,环境变量映射见 env-vars.ts,PopulateHint 枚举见 enums.ts,EntityManager 相关方法实现见 EntityManager.ts,类型工具与符号定义见 typings.ts,raw() 辅助函数见 RawQueryFragment.ts。