MikroORM v4 到 v5 升级指南:完整破坏性变更解析与迁移实战

原创2026-09-28 15:31:131,768 阅读
文章标签:后端

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() 做了三处调整:

  1. Embeddable 实例现在经由 EntityFactory 创建,并遵守 forceEntityConstructor 配置。因此,在给嵌入属性赋值时你需要持有 EM 实例——建议优先使用 em.assign() 来完成赋值操作。

  2. 子实体的深度赋值默认启用:现在会基于 payload 中是否存在主键(PK)来决定子实体的赋值行为(存在 PK 视为更新、不存在视为新建)。可通过 assign options 中的 updateByPrimaryKey: false 关闭。从源码看,updateByPrimaryKey 的默认值为 true(见 Configuration.ts)。

  3. 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;
}

升级顺序建议与检查清单

综合以上变更,建议按以下顺序完成迁移:

  1. 环境升级:Node 14+、TypeScript 4.1+,升级 MikroORM 各包(@mikro-orm/core、@mikro-orm/<driver>、@mikro-orm/cli、@mikro-orm/migrations 等)至 v5。
  2. 编译期排查:先让 TypeScript 编译器暴露所有签名不匹配的调用点——Options 参数重构、populate/fields/orderBy 类型收紧、em.populate() 返回值变化都会在此阶段显现。
  3. 按清单逐项核对:移除 @Repository() 改用 customRepository;检查是否依赖全局 EM(改用 RequestContext 或临时开启 allowGlobalContext);搜索硬编码表别名(改用自定义 aliasName 或 raw() 回调);检查自定义 SQL 片段与迁移文件命名。
  4. 行为差异验证:重点回归测试 assign() 深度赋值、populateAfterFlush 序列化输出、populateWhere 加载结果,以及 Mongo 实体必填属性校验。

文中涉及的源码与配置依据可在以下位置继续深入:配置默认值见 Configuration.ts,环境变量映射见 env-vars.ts,PopulateHint 枚举见 enums.ts,EntityManager 相关方法实现见 EntityManager.ts,类型工具与符号定义见 typings.ts,raw() 辅助函数见 RawQueryFragment.ts。

登录后查看全文
mikro-orm