MikroORM v4 升级到 v5 完整指南:破坏性变更、迁移步骤与源码级解读

原创2026-09-24 17:06:121,644 阅读
文章标签:后端

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,类型约束更宽松。

迁移自查清单

按上述条目逐项对照你的代码库,建议按以下顺序排查:

  1. 升级 Node 至 14+、TypeScript 至 4.1+;
  2. 全局搜索文档列出的 20 个方法调用点,改写为 options 对象签名;
  3. 检查 populate / fields / orderBy 的类型错误并修正为点号数组形式;
  4. 将 @Repository() 装饰器替换为 @Entity({ customRepository });
  5. 确认每个请求都有独立 EM 上下文(或用 allowGlobalContext 显式绕过校验);
  6. 检查自定义 SQL 中硬编码的表别名,改用 expr() 或自定义 aliasName;
  7. 核对 migrations.pattern → migrations.glob 的配置迁移;
  8. 确认 populateAfterFlush、populateWhere、validateRequired、assign 相关默认值变化是否符合预期;
  9. 将 em.populate() 返回值按数组处理,并用 OptionalProps / PrimaryKeyType 修正实体类型定义。

完成上述步骤后,即可平滑过渡到 v5,并享受更严格的类型推导与更清晰的 API 设计带来的长期收益。相关行为细节可继续阅读 query-builder.md、entity-manager.md 与 cascading.md 等文档,或直接查阅 packages/core/src 下的源码实现。

登录后查看全文
mikro-orm