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

原创2026-10-07 13:50:271,708 阅读
文章标签:后端

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

导读

本文基于 MikroORM 官方升级文档,系统梳理从 v4 迁移到 v5 时涉及的全部破坏性变更,覆盖 API 签名重构、类型安全增强、全局身份映射(Identity Map)禁用、populate 行为调整、迁移工具链变更等关键主题。读完本文,你将能够对照清单逐项审查自己的代码,理解每个破坏性变更背后的设计动机,并掌握对应的迁移写法与配置选项,从而安全、平滑地完成 v4 → v5 升级。

说明:以下各节描述了(我们希望是)所有破坏性变更。其中大部分可能与你无关——例如,如果你没有自定义 NamingStrategy 实现,就不需要关心其接口的变化。

Node 与 TypeScript 版本要求

v5 收紧了运行时与编译器的版本底线:

  • Node 14+ 必需:不再支持更旧的 Node 版本。
  • TypeScript 4.1+ 必需:不再支持更旧的 TypeScript 版本。

升级前请确认你的开发环境与 CI 镜像满足上述要求,否则安装依赖或编译时会直接失败。

方法签名重构:从多参数改为 Options 对象

v5 最大的 API 变化是:大量方法原先接收多个(往往是布尔类型的)位置参数,现统一重构为接收单个 options 对象,以提升可读性与可扩展性。v4 中部分方法同时提供了两种签名,v5 中多参数签名已被彻底移除,只保留 options 对象形式。

涉及的方法包括:

  • 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)。迁移时,把原先散落的布尔参数(如 refresh、populate、where 等)整理进 options 对象的对应字段即可,编译器会通过类型检查帮助你找出所有需要修改的调用点。

类型安全的 populate、fields 与 orderBy 参数

v5 将 FindOptions 的多个参数升级为严格类型化,让编译期就能捕获拼写错误与深层路径错误:

  • populate:现在只支持字符串数组或布尔值,且路径支持点号(dot notation)并做严格类型检查;原先的"对象方式"不再支持。要指定加载策略(如 JOINED / SELECT_IN),请使用独立的 FindOptions.strategy。这些方法的返回类型也会被正确推导为 Loaded<T>,即"已加载"后的实体类型。
  • fields:同样支持点号表示法并严格类型化,可用于部分字段加载。
  • orderBy:严格类型化,并且从"只能传单个对象"放宽为"允许传对象数组":
const books = await em.find(Book, {}, {
  orderBy: [
    { title: 1 },
    { author: { name: -1 } },
  ],
});

数组形式可以表达"先按标题升序,再按作者姓名降序"这类复合排序,且每一层路径都会被类型系统校验。

移除 @Repository() 装饰器

@Repository() 装饰器被移除,原因是它存在固有缺陷:只有当装饰器所在的文件在 ORM 初始化之前被及时 require 时它才能正常工作,否则仓库根本不会被注册——这种隐式的时序依赖极易踩坑。

迁移方式:改用实体定义中的 @Entity({ customRepository: () => CustomRepository }) 显式声明自定义仓库:

@Entity({ customRepository: () => AuthorRepository })
export class Author {
  // ...
}

这样仓库与实体的绑定关系一目了然,且不再依赖模块加载顺序。

禁止全局身份映射(Global Identity Map)

v4 中直接使用全局 EM(MikroORM.em)是常见的错误来源:没有请求级上下文(RequestContext)时共享全局 EM,会导致不同请求的身份映射互相污染,产生各种诡异的 bug。v5 中这一行为被正式禁止——一旦检测到在无上下文的情况下使用全局 EM,你会得到校验错误(对应源码位于 errors.ts,检测逻辑见 EntityManager.ts)。

如果你确实需要(例如单元测试中),可以通过配置关闭该检查:

  • 配置项:allowGlobalContext: true
  • 环境变量:MIKRO_ORM_ALLOW_GLOBAL_CONTEXT

注意这只是一个逃生舱,生产环境应始终使用 RequestContext 或 fork() 为每个请求创建独立上下文。从源码看,allowGlobalContext 的默认值为 false(见 Configuration.ts),且该配置可通过环境变量读取(见 env-vars.ts)。

LoadedCollection.get() 与 $ 现在返回 Collection 实例

v4 中,动态添加的 get() 与 $ getter 返回的是集合项的数组拷贝。v5 改为返回 Collection 实例本身。这个实例同样可迭代(iterable)、带 length getter、支持索引访问,因此在使用层面几乎可以"伪装"成数组。

如果你确实需要原来的数组拷贝,请像操作普通集合一样调用 getItems():

const items = author.books.getItems(); // 数组拷贝

表别名规则变更:select-in 策略与 QueryBuilder 统一

v4 中,select-in 加载策略与 QueryBuilder 生成 SQL 时,表别名恒为字母 e 加唯一索引(如 e0、e1);v5 改为与 joined 策略一致的规则——别名首字母从实体名推断。

这对在自定义 SQL 片段中硬编码了别名的用户是破坏性变更。两种应对方式:

  1. 自定义命名策略,覆写 aliasName 方法恢复旧行为:
import { AbstractNamingStrategy } from '@mikro-orm/core';

class CustomNamingStrategy extends AbstractNamingStrategy {
  aliasName(entityName: string, index: number) {
    return 'e' + index;
  }
}
  1. 优先使用 expr() 动态获取别名(v5 推荐做法):
expr(alias => `lower('${alias}.name')`)

这样即使别名规则再变,你的自定义 SQL 片段也不需要跟着改。

迁移文件不再存储扩展名

v5 中,通过 node 与 tsx 在生产环境运行迁移的方式被统一:新生成的迁移文件不再包含扩展名。这并不是破坏性变更——旧的带扩展名格式依然受支持(例如仍可正常回滚),只是新记录的迁移将不带扩展名。

如果你的工作流依赖文件名中的扩展名(例如手动排序或脚本扫描),需要留意这一变化。

assign() 助手的改动

em.assign() / repo.assign() 在 v5 中有三处行为变化:

  1. Embeddable 实例改由 EntityFactory 创建:它们会尊重 forceEntityConstructor 配置。因此,向嵌入式属性赋值时你必须持有 EM 实例——优先使用 em.assign() 而不是静态的辅助方法,可以绕开这个限制。
  2. 子实体深赋值默认开启:现在默认根据 payload 中是否存在主键(PK)来决定对子实体执行 deep assign。若想关闭,在 assign options 中传入 updateByPrimaryKey: false。
  3. mergeObjects 选项默认启用:即默认会对目标对象进行合并而非整体替换。

em.populate() 总是返回实体数组

由于 TS 4.5 下的类型推断问题,v5 中 em.populate() 无论输入是单个实体还是实体数组,都统一返回实体数组。如果你需要单实体返回类型,使用解构:

const [loadedAuthor] = await em.populate(author, ...);

QueryBuilder 变为可 await

v4 中 await 一个 QueryBuilder 实例是无操作(no-op);v5 中 QueryBuilder 是 promise-like 接口,可以直接 await 执行查询并拿到结果。这简化了查询执行方式,详细用法参见文档中的 "Executing the Query" 章节(query-builder.md)。

UnitOfWork.getScheduledCollectionDeletions() 被移除

v4 中,调度式集合删除(scheduled collection deletions)用于一个特殊 hack:删除 1:m 集合(孤儿删除)时可能需要提前删除——防止在同一工作单元内插入"相同 PK 的不同实例"时触发唯一约束冲突。

v5 中该方法已从 UnitOfWork 移除,IDatabaseDriver.clearCollection() 也不再属于 driver API。依赖这两个内部方法的自定义实现需要同步清理。

populateAfterFlush 默认开启

v5 中,flush 一个新实体后,其所有关联都会被标记为已加载(populated),效果等同于该实体刚从数据库加载。这保证了"刚插入的实体"与"从数据库加载的实体"在 e.toJSON() 序列化输出上保持一致。

v4 中该行为默认关闭,因此 flush 后新实体的序列化形式只包含关联的 FK。如果你希望恢复旧行为,可以显式设置 populateAfterFlush: false。当前版本中该配置默认值为 true(见 Configuration.ts)。

migrations.pattern 替换为 migrations.glob

MikroORM 的迁移基于 umzug,v5 将其升级到 v3.0。该版本不再提供 pattern 配置项,取而代之的是 glob,这一变化同步反映在 MikroORM 的迁移配置中。

glob 的默认值为 !(*.d).{js,ts}:即同时匹配 JS 与 TS 文件,但排除 .d.ts。该默认值同时适用于开发与生产环境,通常你不需要修改它。

Population 不再默认推断 where 条件

仅适用于 SELECT_IN 策略;JOINED 策略本身隐含了条件推断。

v4 中,当你在 em.find() 等方法的 populate 提示中使用了某些条件时,ORM 会分析主查询并从中提取部分条件用于 populate 查询。例如:

// v4 行为:Author.books 集合中只会包含 PK 为 1、2、3 的书籍
const a = await em.find(Author, { books: [1, 2, 3] }, { populate: ['books'] });

也就是说,populate 出的集合被主查询条件"过滤"了。如果你想加载全部书籍,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。ALL 是 v5 默认值(见 Configuration.ts),INFER 才是 v4 的默认行为。
  • 局部配置:通过 FindOptions.populateWhere 传入,除了枚举值,还可以直接传入一个自定义 where 条件,该条件会被传递给内部的 em.populate() 调用。

PopulateHint 枚举定义见 enums.ts:

export enum PopulateHint {
  INFER = 'infer', // 从 where 条件推断 populate 提示
  ALL = 'all',     // 对全部关联应用 populate 提示
}

在局部恢复 v4 旧行为:

const a = await em.find(Author, { books: [1, 2, 3] }, {
  populate: ['books'],
  populateWhere: PopulateHint.INFER,
});

em.create() 开始要求必填属性

em.create() 现在要求传入所有非可选属性。某些属性在 TS 类型层面是必填的,但实际拥有默认值(运行时默认值或数据库默认值)——对这些属性,你可以使用 OptionalProps 符号显式声明它们为可选:

import { OptionalProps } from '@mikro-orm/core';

@Entity()
export class Author {
  [OptionalProps]?: 'createdAt' | 'updatedAt';

  @Property()
  createdAt: Date = new Date();
}

OptionalProps 符号在 typings.ts 中定义,其注释明确说明用途:"用于声明 em.create() 中哪些属性是可选的(例如 <a href="https://link.gitcode.com/i/f3c46f844af5c67c550bff62e05abb61" target="_blank">OptionalProps]?: 'createdAt')"。em.create() 的"严格检查必填属性"行为在 [EntityManager.ts 与 EntityRepository.ts 的文档注释中均有体现。

必填属性在插入前进行运行时校验

v4 中必填属性校验发生在数据库端,因此只对 SQL driver 生效;v5 改为基于实体元数据的运行时校验,在插入前执行。这意味着:

  • MongoDB 用户现在也需要在可选属性上使用 nullable: true,否则这些属性会被当作必填而校验失败;
  • 或者全局关闭该校验:validateRequired: false。

该配置的默认值为 true(见 Configuration.ts),即运行时必填校验默认开启。

PrimaryKeyType 符号可声明为可选

此前,当实体主键类型非常规(nonstandard)时,你可以使用 PrimaryKeyType 符号帮助类型系统识别它。v4 要求该属性必须声明为必填;v5 放宽了这一限制——现在将它声明为可选([PrimaryKeyType]?: string)也可以正常工作。

升级检查清单

按上述变更整理出一份可执行的迁移清单:

  1. 确认 Node ≥ 14、TypeScript ≥ 4.1;
  2. 用类型检查找出所有多参数调用,改为 options 对象形式;
  3. 将 @Repository() 替换为 @Entity({ customRepository: () => CustomRepository });
  4. 检查是否有代码依赖全局 EM;如有,改用 RequestContext/fork(),测试场景可临时开启 allowGlobalContext;
  5. 检查自定义 SQL 片段中硬编码的表别名,改用 expr() 动态别名或自定义 aliasName;
  6. 确认 populate、fields、orderBy 的新类型签名通过编译;
  7. 按需显式设置 populateWhere,确认集合 populate 行为符合预期;
  8. 为拥有默认值的必填属性补充 OptionalProps 声明,为 Mongo 可选属性补充 nullable: true;
  9. 检查迁移配置,将 migrations.pattern 迁移到 migrations.glob;
  10. 全量运行测试,重点关注 assign()、populate()、em.create() 与序列化输出(populateAfterFlush)相关的用例。

完成上述检查后,你的代码即可平滑过渡到 v5 的 API 语义与类型系统。

登录后查看全文
mikro-orm