MikroORM 基于文件夹的实体自动发现(Folder-based Discovery)完整指南

原创2026-09-25 23:37:391,377 阅读
文章标签:后端

MikroORM 基于文件夹的实体自动发现(Folder-based Discovery)完整指南

导读

在 MikroORM 中,实体既可以像 entities: [User, Article] 这样被显式列出,也可以通过 glob 模式自动发现——这就是"基于文件夹的发现"(Folder-based Discovery)。本文将以 MikroORM 7.x 版本(对应 docs/versioned_docs/version-7.0/ 文档)为基准,系统讲解如何用 glob 模式按文件命名约定自动扫描实体、entities 与 entitiesTs 两个配置项的协作机制、底层扫描与动态导入原理、mikro-orm debug 调试手段,以及显式引用与文件夹发现两种方式的取舍。读完本文,你将能在大型多模块项目中落地一套"新增实体零配置"的开发流程。


一、为什么需要文件夹式发现

当项目规模变大、实体分散在多个业务模块时,手动在配置中维护实体清单会带来两个问题:

  • 每新增一个实体都要记得修改配置文件,遗漏后会出现"实体未被识别"的运行时错误;
  • 实体清单随项目膨胀,配置代码变得冗长。

MikroORM 提供了基于 glob 通配符的自动发现机制:只要实体文件遵循统一的命名约定(如 *.entity.ts 后缀),ORM 就能在初始化时自动扫描、动态导入并注册它们,无需显式列出。

在核心配置类型中,entities 被定义为"实体类数组或实体模块路径数组,路径支持用于自动发现的 glob 模式"(见 Configuration.ts),这正是文件夹式发现的数据模型基础。


二、基础配置:entities 与 entitiesTs

文件夹式发现的核心是两组配置项(见 Configuration.ts):

配置项 指向目标 典型场景
entities 编译后的 JavaScript 文件(*.js) 生产环境、编译后运行
entitiesTs TypeScript 源码文件(*.ts) 开发环境(tsx、ts-node、Vitest/Jest 等)

标准配置示例(mikro-orm.config.ts):

import { defineConfig } from '@mikro-orm/sqlite';

export default defineConfig({
  // Glob patterns for compiled JavaScript files
  entities: ['dist/**/*.entity.js'],
  // Glob patterns for TypeScript source files (used in development)
  entitiesTs: ['src/**/*.entity.ts'],
  // ...
});

工作流程

  1. 当从 TypeScript 运行(例如通过 tsx,或在测试中)时,MikroORM 使用 entitiesTs 模式;
  2. 当从编译后的 JavaScript 运行时,MikroORM 使用 entities 模式;
  3. 匹配到的文件会被动态导入,并扫描其中的实体定义。

重要:entities 必须指向编译后的 JS 文件,entitiesTs 必须指向 TS 源文件,二者不可混用。

底层如何二选一:preferTs 判定

MikroORM 在初始化时通过 preferTs 标志决定使用哪组路径。MikroORM.init() 会执行:

const preferTs = orm.config.get('preferTs', Utils.detectTypeScriptSupport());
orm.#metadata = await orm.#discovery.discover(preferTs);

(见 MikroORM.ts)

随后在 MetadataDiscovery.findEntities() 中完成二选一:

const { entities, entitiesTs, baseDir } = this.#config.getAll();
const targets = preferTs && entitiesTs.length > 0 ? entitiesTs : entities;

(见 MetadataDiscovery.ts)

preferTs 的默认值由 Utils.ts 中的 detectTypeScriptSupport() 自动探测,例如:

  • 进程以 ts-node 启动;
  • 设置了 TS_JEST、VITEST 环境变量(测试场景);
  • 运行在 Bun 上;
  • 显式设置 MIKRO_ORM_CLI_ALWAYS_ALLOW_TS 环境变量或调用 registerTypeScriptSupport()。

也就是说,开发与测试环境通常会命中 TS 分支而自动使用 entitiesTs,编译部署后则回落使用 entities。你也可以在配置中显式设置 preferTs: false 强制使用 entities(mikro-orm debug 会提示此时应指向编译产物)。

发现循环中的类型过滤

discoverEntities() 对 glob 命中的文件还有一个类型过滤:只处理扩展名为 .js、.cjs、.mjs、.ts、.cts、.mts 的文件,并跳过 .d.ts / .d.mts 之类的声明文件(见 discover-entities.ts),避免把类型声明当作实体源码导入。


三、文件命名约定

文件夹式发现依赖稳定的命名约定。常见做法是使用 .entity.ts 后缀:

src/
├── modules/
│   ├── user/
│   │   └── user.entity.ts
│   ├── article/
│   │   ├── article.entity.ts
│   │   └── tag.entity.ts
│   └── common/
│       └── base.entity.ts
└── mikro-orm.config.ts

配合上述目录结构,entitiesTs: ['src/**/*.entity.ts'] 即可覆盖所有业务模块。这种"按模块分目录 + 统一后缀"的组织方式,让新增实体的成本降到最低——新建一个 x.entity.ts 文件即可被下次初始化自动发现。


四、glob 模式详解

路径解析基于原生 Node.js glob 能力,可以使用标准的通配语法:

const orm = await MikroORM.init({
  // 递归匹配 dist 目录下所有 .entity.js 文件
  entities: ['./dist/**/*.entity.js'],

  // 多个模式
  entities: ['./dist/modules/**/*.entity.js', './dist/shared/**/*.entity.js'],

  // 否定模式排除文件
  entities: ['./dist/**/*.entity.js', '!./dist/**/*.test.entity.js'],
});

否定模式(negative patterns)的实现

以 ! 开头的模式会被当作排除规则处理。核心工具函数 fs.glob() 会把输入拆分为"正向模式"与"负向模式"两组,先解析正向得到候选文件集合,再解析负向并从集合中删除匹配项(见 fs-utils.ts):

const positive: string[] = [];
const negative: string[] = [];

for (const p of patterns) {
  if (p.startsWith('!')) {
    negative.push(p.slice(1));
  } else {
    positive.push(p);
  }
}

const included = new Set(this.resolveGlob(positive, cwd));

if (included.size > 0 && negative.length > 0) {
  const excluded = this.resolveGlob(negative, cwd);
  for (const file of excluded) {
    included.delete(file);
  }
}

这解释了为什么 ! 模式必须紧跟在对应的正向模式之后、且二者相对同一基准目录书写。

目录路径的展开

resolveGlob() 还支持直接传入目录路径而非 glob 模式:当输入不含 *、?、<a href="https://link.gitcode.com/i/6d92a94a68491f86074ad9b0706e330f" target="_blank">、] 等通配字符且指向一个目录时,会自动展开为该目录下所有文件(见 [fs-utils.ts)。因此:

entities: ['./dist/entities'] // 等价于递归扫描该目录

也是合法的写法,官方配置注释中同样给出了 entities: <a href="https://link.gitcode.com/i/cd9feb91e3bda34fc356228ae95633e8" target="_blank">'./dist/entities'] 的示例(见 [Configuration.ts)。

注意:不支持 brace expansion

原生 Node.js glob 不支持 src/{entities,modules}/*.ts 这种花括号展开(brace expansion)。如果需要该能力,可以借助 tinyglobby 预先展开成具体路径列表:

import { glob } from 'tinyglobby';

export default defineConfig({
  entities: await glob(['src/{entities,modules}/*.ts']),
});

有意思的是,MikroORM 自身在初始化时会尝试动态加载 tinyglobby 作为 glob 实现(见 fs-utils.ts),但对外暴露的配置语义仍以原生 glob 语法为准。


五、底层原理:动态导入与实体扫描

MetadataDiscovery.findEntities() 会把配置中的字符串路径收集起来,调用 discoverEntities() 完成扫描(见 MetadataDiscovery.ts):

if (paths.length > 0) {
  const { discoverEntities } = await import('@mikro-orm/core/file-discovery');
  processed.push(...(await discoverEntities(paths, { baseDir })));
}

而 discoverEntities() 的核心流程(见 discover-entities.ts)是:

  1. 规范化路径:将配置中的模式数组统一为规范化路径,并以 baseDir(默认 process.cwd())作为解析基准;
  2. glob 解析:fs.glob(paths, baseDir) 返回全部命中文件;
  3. 类型过滤:跳过非 JS/TS 扩展名文件与 .d.ts 声明文件;
  4. 动态导入:对每个文件调用 fs.dynamicImport()(底层通过 pathToFileURL 转为 file:// URL 后执行 import(),见 fs-utils.ts);
  5. 提取实体:遍历模块导出的所有值,识别 EntitySchema 实例、实体类(通过 EntitySchema.REGISTRY 查表)以及已知实体类,去重后收入结果集合。

也就是说,"扫描"并非文本解析,而是真实的模块加载——被命中的文件必须能被正常 import,其中的装饰器/EntitySchema 定义才会生效。

基类实体的自动补齐

文件夹发现只保证命中模式的文件被注册;对于继承关系中的基类,discoverReferences() 会遍历已发现实体的 extends 引用,自动把父类(base entity)也纳入发现(见 MetadataDiscovery.ts)。这意味着即使 base.entity.ts 未被 glob 直接命中,只要被某个实体继承,也会被自动发现。


六、调试:mikro-orm debug

如果发现行为与预期不符,MikroORM CLI 提供了诊断命令:

npx mikro-orm debug

该命令会展示(对应 DebugCommand.ts 的实现):

  • 加载了哪个配置文件、搜索了哪些配置路径;
  • 驱动依赖及其版本、数据库连接是否成功;
  • preferTs 标志的显式取值,以及当前将使用 entitiesTs 还是 entities 数组;
  • entities / entitiesTs 数组中各路径(含 glob 与目录)是否真实存在,逐条标注 found / not found。

例如在 preferTs: true 时,命令会明确输出"将使用 entitiesTs 数组",并把每个路径与 baseDir 拼接后做存在性检查(见 DebugCommand.ts)。仓库中的 DebugCommand.test.ts 展示了典型输出:分别列出 entities 与 entitiesTs 中"0 个引用 + 2 个路径"及其 found/not found 状态。

如果 glob 路径拼写错误(例如 dist 目录实际在别处),debug 输出中的 (not found) 标记能帮你快速定位是"路径错"还是"模式错"。


七、显式引用 vs 文件夹发现:如何选择

方面 显式引用(entities: [User]) 文件夹发现(entities: ['**/*.entity.js'])
配置复杂度 代码更多 代码更少
重构支持 IDE 完全支持 需手动更新模式
构建工具 随处可用 可能需要额外配置
启动性能 更快 略慢(文件扫描)
错误发现时机 编译期 运行时

何时优先使用显式引用

  • 中小型项目,实体数量有限;
  • 使用 webpack、esbuild 等打包器(打包产物中按 glob 动态导入的文件可能被 tree-shaking 或分块逻辑影响);
  • 想要最大化 IDE 支持与类型安全;
  • 使用 defineEntity(官方推荐的实体定义方式)时。

何时优先使用文件夹发现

  • 大型项目,实体数量众多且分散在多个模块;
  • 使用装饰器式实体配合 ts-morph 等元数据提供器;
  • 希望避免每新增一个实体就改一次配置。

需要说明:文件夹发现之所以"错误发现时机为运行时",是因为 glob 路径拼写、命名约定不符等问题只有到初始化扫描时才会暴露;而显式引用在编译阶段就能发现实体类引用缺失。


八、同步初始化限制

文件夹发现依赖异步的动态导入,因此只支持异步初始化:

// 这可以工作 —— 异步初始化支持文件夹发现
const orm = await MikroORM.init({
  entities: ['dist/**/*.entity.js'],
});

// 这不能工作 —— 同步初始化必须使用显式实体引用
const orm = new MikroORM({
  entities: ['dist/**/*.entity.js'],
  // 同步初始化只能使用显式引用
  // entities: [User, Article],
});

这一点在源码层面有硬性约束:discoverReferences() 一旦遇到字符串类型的实体引用会直接抛出 'Folder based discovery requires the async MikroORM.init() method.'(见 MetadataDiscovery.ts)。因此,凡是使用文件夹发现的项目,都必须走 MikroORM.init() 异步初始化路径。


九、多位置组合:混合模式

entities / entitiesTs 数组允许同时混合显式引用与 glob 模式,这在需要"先加载基类实体、再扫描其余实体"时非常有用:

import { BaseEntity } from './entities/base.entity.js';

export default defineConfig({
  entities: [
    BaseEntity, // 显式引用
    'dist/modules/**/*.entity.js', // glob 模式
  ],
  entitiesTs: [
    BaseEntity,
    'src/modules/**/*.entity.ts',
  ],
});

从实现看,findEntities() 会把数组中的字符串元素收集为 paths、非字符串元素(类/EntitySchema 引用)收集为 processed,二者并行处理后再合并进入后续的引用发现(见 MetadataDiscovery.ts)。因此混合模式与纯模式在机制上完全等价,只是路径集合的来源不同。

多模式与多路径的实用建议

  • 不同业务模块的实体文件分散时,可列出多个 glob 模式,例如 ['dist/modules/**/*.entity.js', 'dist/shared/**/*.entity.js'];
  • 需要排除的测试实体、临时实体,用 ! 否定模式过滤;
  • 基类等必须"先注册"的实体,优先用显式引用放进数组头部,配合内置的父类自动补齐机制,可彻底避免继承链上的遗漏。

十、小结

文件夹式发现是 MikroORM 应对大型多模块项目实体注册问题的主要手段:

  1. 配置:entities 指向编译后的 JS、entitiesTs 指向 TS 源码,preferTs 自动决定当前用哪组;
  2. 约定:统一的 .entity.ts 后缀 + 按模块分目录,新增实体零配置;
  3. 机制:glob 命中 → 类型过滤 → 动态导入 → 提取 EntitySchema 与实体类,父类引用自动补齐;
  4. 调试:npx mikro-orm debug 逐路径检查 found/not found,并明确提示将使用哪组实体数组;
  5. 边界:仅异步初始化可用;原生 glob 不支持 brace expansion,需要时可借助 tinyglobby 预展开;
  6. 取舍:小项目/打包器场景建议显式引用(编译期发现错误、类型安全更佳),大项目/多模块场景建议文件夹发现(维护成本更低)。

按以上方案配置后,新增业务实体只需创建文件、无需触碰配置文件,实体注册流程即可自动完成。

登录后查看全文
mikro-orm