MikroORM 项目搭建实战：Fastify + Vitest 下的请求上下文、Seeder 与迁移管理

后端【免费下载链接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.项目地址https://gitcode.com/gh_mirrors/mi/mikro-orm点击查看免费下载本篇技术指南基于 MikroORM 官方入门指南第三章docs/docs/guide/03-project-setup.md完整讲解如何把一个玩具级实体定义升级为真正可运行、可测试、可演进的 Web 应用工程包括基于 Fastify 的服务端搭建、RequestContext请求级 EntityManager 分叉原理、轻量 DI 容器、Vitest 端点测试、Seeder 数据填充以及 SchemaGenerator / Migrator 的配合使用。读完你将掌握 MikroORM 在真实 Node.js Web 项目中的标准落地姿势并能直接用npm test跑通一个含分页端点与数据库播种的完整测试链路。从实体玩具到真实项目先搭起 Fastify 应用骨架前两章你已经在内存数据库里摆弄过实体现在开始构建真实应用。本章约定以Fastify作为 Web 服务器、以Vitest作为测试框架。第一步是创建src/app.ts导出bootstrap函数来创建 Fastify 实例并初始化 ORM。这里需要先解决一个关键问题之前的章节中你不得不手动 forkEntityManager来绕开全局上下文校验ValidationError.cannotUseGlobalContext()。Web 服务器场景下更优雅的做法是利用中间件或 Fastify 的 hook为每个请求自动创建独立的 EM 分叉而 MikroORM 提供的RequestContext正是为此设计的工具类。RequestContext用 AsyncLocalStorage 为每个请求提供独立 EMRequestContext的内部实现位于 packages/core/src/utils/RequestContext.ts。从源码看它持有private static storage createAsyncContextRequestContext()底层正是 Node.js 核心的AsyncLocalStorage类RequestContext.create(em, done)会先对传入的 EM 调用em.fork({ useContext: true })创建分叉再通过storage.run(ctx, next)让回调及其全部异步后代共享这个上下文。它的工作链条可以概括为所有与 Identity Map 相关的 EM 方法如em.find()、em.getReference()内部都会先调用em.getContext()获取上下文分叉该方法的实现见 EntityManager.ts 的 getContext 定义先优先返回TransactionContext中的 EM若已开启显式事务否则调用this.config.get(context)(this.name)解析请求上下文即RequestContext.getEntityManager()RequestContext.getEntityManager()再从AsyncLocalStorage静态实例中取出当前请求对应的 EM fork。所以你在全局实例上写的orm.em.find(Book, {})实际解析路径是const res await orm.em.find(Book, {}); // 等价于 const res await orm.em.getContext().find(Book, {}); // 最终等价于 const res await RequestContext.getEntityManager().find(Book, {});AsyncLocalStorage是这里的魔术师它允许把 fork 的创建在中间件/hook 中完成与通过全局orm.em的使用解耦从而在异步调用链中始终追踪到正确的请求上下文。import { MikroORM, RequestContext } from mikro-orm/core; import { fastify } from fastify; import config from ./mikro-orm.config.js; export async function bootstrap(port 3001) { const orm await MikroORM.init(config); const app fastify(); // 为每个请求创建独立的 EM 分叉 app.addHook(onRequest, (request, reply, done) { RequestContext.create(orm.em, done); }); // 应用关闭时释放数据库连接 app.addHook(onClose, async () { await orm.close(); }); // 在这里注册路由 // ... const url await app.listen({ port }); return { app, url }; }RequestContext.create的第三个参数还支持传入CreateContextOptions或按 EM 名称返回该选项的函数用于在创建 fork 时附加全局覆盖项例如设置preferQueryBuilder、loadStrategy等ForkOptions中除useContext、disableContextResolution、keepTransactionContext、clear之外的字段参见 RequestContext.ts 中的 CreateContextOptions 定义。另外源码还提供了RequestContext.enter()方法它基于AsyncLocalStorage.enterWith()适合没有next回调风格的中间件如 Elysia 风格。接着把启动入口放进src/server.ts可清空之前的临时代码import { bootstrap } from ./app.js; try { const { url } await bootstrap(); console.log(server started at ${url}); } catch (e) { console.error(e); }再次运行npm start你会看到类似输出[info] MikroORM version: 7.0.0 [discovery] ORM entity discovery started [discovery] - processing entity User [discovery] - processing entity Article [discovery] - processing entity Tag [discovery] - processing entity BaseEntity [discovery] - entity discovery finished, found 5 entities, took 5 ms [info] MikroORM successfully connected to database sqlite.db server started at http://127.0.0.1:3001服务已启动按CTRL C停止。第一个端点用 findAndCount 实现分页列表添加GET /article端点公开接口接收limit与offset查询参数返回分页条目与全量总数。虽然可以分别用em.count()和em.find()实现但em.findAndCount()是更贴合此场景的组合方法——它同时返回条目数组与总数元组。从源码看EntityManager.ts 中的 findAndCount 实现 本质上是Promise.all([em.find(...), em.count(...)])的封装先通过getContext(false)取上下文分叉并tryFlush一次然后以flushMode: commit避免再次自动 flush。这意味着分页结果与计数基于同一份已 flush 的数据语义可靠。app.get(/article, async request { const { limit, offset } request.query as { limit?: number; offset?: number }; const [items, total] await orm.em.findAndCount(ArticleSchema, {}, { limit, offset, }); return { items, total }; });轻量 DI 容器让 ORM 初始化可复用、可覆写在写测试之前先重构使架构更抗未来变化。新建src/db.ts作为简易依赖注入DI容器导出initORM()函数首次初始化后缓存结果后续调用直接返回同一实例。虽然借助 top-level await 可以初始化后直接导出但测试场景往往需要先覆写若干选项再初始化函数式封装更灵活。import { EntityManager, EntityRepository, MikroORM, Options } from mikro-orm/sqlite; import { UserSchema, type User } from ./modules/user/user.entity.js; import { ArticleSchema, type IArticle } from ./modules/article/article.entity.js; import { TagSchema, type ITag } from ./modules/article/tag.entity.js; import config from ./mikro-orm.config.js; export interface Services { orm: MikroORM; em: EntityManager; article: EntityRepositoryIArticle; user: EntityRepositoryUser; tag: EntityRepositoryITag; } let cache: Services; export function initORM(options?: PartialOptions): Services { if (cache) { return cache; } const orm new MikroORM({ ...config, ...options, }); // 先存入缓存再返回 return cache { orm, em: orm.em, article: orm.em.getRepository(ArticleSchema), user: orm.em.getRepository(UserSchema), tag: orm.em.getRepository(TagSchema), }; }注意这里是从mikro-orm/sqlite驱动包导入EntityManager、EntityRepository、MikroORM、Options而不是mikro-orm/core——这些导出都被类型化绑定到SqliteDriver。随后在app.ts中使用它取代直接初始化import { RequestContext } from mikro-orm/core; import { fastify } from fastify; import { initORM } from ./db.js; export async function bootstrap(port 3001) { const db initORM(); const app fastify(); app.addHook(onRequest, (request, reply, done) { RequestContext.create(db.em, done); }); app.addHook(onClose, async () { await db.orm.close(); }); app.get(/article, async request { const { limit, offset } request.query as { limit?: number; offset?: number }; const [items, total] await db.article.findAndCount({}, { limit, offset, }); return { items, total }; }); const url await app.listen({ port }); return { app, url }; }为什么从驱动包导入 EntityManager / EntityRepositoryEntityManager与EntityRepository的基类定义在mikro-orm/core但它们是驱动无关的基础实现。以QueryBuilder为例它是 SQL 概念不属于 core 包SQL 驱动包如mikro-orm/sqlite其公共实现定义于mikro-orm/sql提供了继承自EntityManager的SqlEntityManager额外暴露em.createQueryBuilder()等 SQL 专属方法。为方便使用SqlEntityManager同时以EntityManager别名被重新导出因此你可以写import { EntityManager } from mikro-orm/sqlite直接拿到它。运行时 MikroORM 始终使用驱动专属的 EM 实现可用console.log(orm.em)验证打印出的是SqlEntityManager实例但 TypeScript 需要你从驱动包导入才能获得正确的类型。EntityRepository与SqlEntityRepository同理。此外MikroORM、defineConfig和Options也都可以从驱动包导出免去写泛型的麻烦。EntityRepositoryEntityManager 之上的薄封装仓库Repository是EntityManager之上的轻量抽象层充当扩展点可添加或覆写自定义方法。默认的EntityRepository实现只是把调用转发给底层的 EM 实例。它携带实体类型因此调用find/findOne时无需重复传实体类名。注意不存在flush 某个 repository这种操作——它只是em.flush()的快捷方式。换句话说flush 的永远是整个 Unit of Work而非该 repository 代表的单个实体。用 Vitest 测试第一个端点vitest已随npm test可用。测试文件放入test目录并以.test.ts结尾。Fastify 提供app.inject()便捷地模拟 HTTP 请求但直接在测试里bootstrap()会打到生产数据库——这是我们不想要的。先创建测试工具文件test/utils.ts不带.test.ts后缀定义initTestApp一次性完成覆写 ORM 选项初始化 → 创建 schema → bootstrap Fastify并以port为参数让每个测试用例拥有独立的:memory:内存数据库和独立端口的 app从而支持并行测试。import { bootstrap } from ../src/app.js; import { initORM } from ../src/db.js; import config from ../src/mikro-orm.config.js; export async function initTestApp(port: number) { // 初始化所有 ORM 服务并缓存 const { orm } initORM({ // 先并入主配置 ...config, // 关闭调试日志避免污染测试输出 debug: false, // 使用内存数据库测试易于并行 dbName: :memory:, }); // 创建 schema数据库即可使用 await orm.schema.create(); const { app } await bootstrap(port); return app; }然后是测试用例。当前内存库为空文章列表端点会先返回空数组马上会处理数据问题import { afterAll, beforeAll, expect, test } from vitest; import { FastifyInstance } from fastify; import { initTestApp } from ./utils.js; let app: FastifyInstance; beforeAll(async () { // 使用不同端口以支持并行测试 app await initTestApp(30001); }); afterAll(async () { // 只关闭 fastify app —— onClose hook 会自动关闭数据库连接 await app.close(); }); test(list all articles, async () { // 通过 app.inject() 模拟 http 请求 const res await app.inject({ method: get, url: /article, }); // 断言响应成功 expect(res.statusCode).toBe(200); // 断言响应结构 expect(res.json()).toMatchObject({ items: [], total: 0, }); });使用beforeAll初始化 app、afterAll拆卸app.close()会触发onClosehook 进而调用orm.close()缺少这一步进程会挂住。运行npm test✓ test/article.test.ts (1) Test Files 1 passed (1) Tests 1 passed (1) Start at 15:56:41 Duration 876ms (transform 264ms, setup 0ms, collect 300ms, tests 147ms) PASS Waiting for file changes... press h to show help, press q to quit关于单元测试的一个重要提醒不要因为某些单测不需要数据库连接就跳过MikroORM.init()阶段——init做的事远不止建连。最关键的是元数据发现metadata discoveryORM 会检查全部实体定义为各类元数据选项主要是命名策略和双向关系设置默认值。而 discovery 阶段是 propagation级联传播 正常工作的必要前提。const orm new MikroORM({ // ... });用 Seeder 给测试库填充数据填充测试数据库的方式很多最直白的是在测试的beforeAll里手动em.create()。另一种方案是使用mikro-orm/seeder包它提供一系列工具用于向数据库灌入不一定虚假的数据。Seeder 也完全适用于生产库的初始化——例如创建默认文章标签集合或初始管理员用户你可以建立 seeder 层级也可以逐个调用。安装并注册扩展npm install mikro-orm/seederimport { defineConfig } from mikro-orm/sqlite; import { SeedManager } from mikro-orm/seeder; export default defineConfig({ // ... extensions: [SeedManager], });注册SeedManager扩展后即可通过orm.seeder属性访问。其他常用扩展还有SchemaGenerator、Migrator和EntityGenerator其中SchemaGenerator以及MongoSchemaGenerator会自动注册因为它不依赖任何第三方包。生成测试 seedernpx mikro-orm seeder:create test这会创建src/seeders目录及TestSeeder.ts骨架import type { EntityManager } from mikro-orm/core; import { Seeder } from mikro-orm/seeder; export class TestSeeder extends Seeder { async run(em: EntityManager): Promisevoid {} }填充逻辑使用em.create()——它内部会先调用em.persist(entity)再返回实体因此仅调用em.create()本身就足够了export class TestSeeder extends Seeder { async run(em: EntityManager): Promisevoid { em.create(UserSchema, { fullName: Foo Bar, email: foobar.com, password: password123, articles: [ { title: title 1/3, description: desc 1/3, text: text text text 1/3, tags: [{ id: 1, name: foo1 }, { id: 2, name: foo2 }], }, { title: title 2/3, description: desc 2/3, text: text text text 2/3, tags: [{ id: 2, name: foo2 }], }, { title: title 3/3, description: desc 3/3, text: text text text 3/3, tags: [{ id: 2, name: foo2 }, { id: 3, name: foo3 }], }, ], }); } }在initTestApp中、orm.schema.create()之后运行 seederawait orm.schema.create(); await orm.seeder.seed(TestSeeder);并同步调整测试断言——现在应该返回 3 篇文章expect(res.json()).toMatchObject({ items: [ { author: 1, slug: title-13, title: title 1/3 }, { author: 1, slug: title-23, title: title 2/3 }, { author: 1, slug: title-33, title: title 3/3 }, ], total: 3, });再跑npm test验证一切正常。SchemaGenerator从实体元数据生成并同步 DDL前面创建测试数据库时用到的SchemaGenerator值得展开讲。它负责基于实体元数据生成 SQL 查询——即把实体定义翻译成 DDL数据定义语言同时它还能读取当前数据库 schema 并与元数据比对产出使两者同步所需的查询。完整文档见 schema-generator.md。编程式使用// 只获取需要执行的查询 const diff await orm.schema.getUpdateSchemaSQL(); console.log(diff); // 或直接执行 await orm.schema.update();orm.schema.update()可以复刻 TypeORM 的synchronize: true行为——把它放进 ORM 初始化后的 bootstrap 代码即可。但请牢记这种方式可能是破坏性的不推荐用于生产执行前务必人工核对 SchemaGenerator 产出的每条 SQL。CLI 方式把--dump换成--run即执行npx mikro-orm schema:create --dump # 输出建表 SQL npx mikro-orm schema:update --dump # 输出同步 SQL npx mikro-orm schema:drop --dump # 输出删表 SQL你的生产库项目根目录的sqlite.db大概率已与元数据不同步测试一直用内存库。先--dump或-d检查生成的 SQL确认无误后再--run或-r执行# 先看会生成什么 npx mikro-orm schema:update --dump # 确认无误后同步 schema npx mikro-orm schema:update --run若命令生成了无效查询可以先用schema:drop --run清掉再重建。SchemaGenerator 在原型阶段与测试场景需要多个同构数据库、且不关心生产 schema 形态非常顺手但对真实生产库则相当危险——好在有 migrations 来兜底。Migrations用版本化迁移替代危险的同步SQL 驱动需先安装mikro-orm/migrationsMongoDB 用mikro-orm/migrations-mongodb并在 ORM 配置中注册Migrator扩展。MikroORM 的迁移支持基于当前 schema 差异生成迁移也支持管理执行。默认每条迁移在独立事务中执行且全部迁移被包在一个主事务里——只要有一条失败整体回滚。npm install mikro-orm/migrationsimport { defineConfig } from mikro-orm/sqlite; import { SeedManager } from mikro-orm/seeder; import { Migrator } from mikro-orm/migrations; export default defineConfig({ // ... extensions: [SeedManager, Migrator], });创建第一条迁移npx mikro-orm migration:create紧跟指南操作的话会看到No changes required, schema is up-to-date这是因为刚才schema:update --run已把 schema 同步过了。此时有两个选择先 drop schema或采用破坏性更小的初始迁移。初始迁移已有 schema、又想开始用迁移时--initial标志能在保留现有 schema 的同时、仅基于实体元数据生成首条迁移。它只在 schema 为空或完全最新时可用。若 schema 已存在生成的迁移会被自动标记为已执行若不存在则需像普通迁移一样手动npx mikro-orm migration:up。初始迁移仅当此前没有任何已生成或已执行的迁移时才可创建。若从零开始且尚无 schema不必用--initial普通迁移即可。npx mikro-orm migration:create --initial这会在src/migrations目录生成包含schema:create全部查询的初始迁移由于 schema 已同步它会被自动标记为已执行。迁移类结构生成的迁移是一个继承mikro-orm/migrations中Migration抽象类的类import { Migration } from mikro-orm/migrations; export class Migration20220913202829 extends Migration { async up(): Promisevoid { this.addSql(create table tag (id integer not null primary key autoincrement, created_at datetime not null, updated_at datetime not null, name text not null);); // ... } }如需支持回滚可实现down方法默认抛错。MikroORM 会自动生成 down 迁移初始迁移除外出于安全考虑——唯一例外是SQLite 驱动因其能力受限其他驱动都会生成 down 迁移。还可在up()/down()中通过this.execute(...)执行 SQL它与迁移其余部分处于同一事务this.addSql(...)同样接受原生 QueryBuilder 实例或raw()SQL 片段。迁移完整文档见 migrations.md。再加一个实体Comment用新实体检验迁移流程。新增src/modules/article/comment.entity.tsimport { defineEntity, type InferEntity, p } from mikro-orm/core; import { ArticleSchema } from ./article.entity.js; import { UserSchema } from ../user/user.entity.js; import { BaseSchema } from ../common/base.entity.js; export const CommentSchema defineEntity({ name: Comment, extends: BaseSchema, properties: { text: p.string(), article: () p.manyToOne(ArticleSchema).ref(), author: () p.manyToOne(UserSchema).ref(), }, }); export type IComment InferEntitytypeof CommentSchema;在Article实体中补上 OneToMany 反向侧comments: () p.oneToMany(CommentSchema).mappedBy(article).eager().orphanRemoval(),这里用到两个新的 builder 方法.eager()自动 populate 该关系等价于显式写populate: [comments].orphanRemoval()一种特殊的级联——从集合中移除的实体将被从数据库删除而非仅通过将外键置null解除关联。别忘了把 repository 加进 DI 容器export interface Services { orm: MikroORM; em: EntityManager; user: UserRepository; article: EntityRepositoryIArticle; comment: EntityRepositoryIComment; // 新增 tag: EntityRepositoryITag; } export function initORM(options?: PartialOptions): Services { // ... return cache { orm, em: orm.em, user: orm.em.getRepository(UserSchema), article: orm.em.getRepository(ArticleSchema), comment: orm.em.getRepository(CommentSchema), // 新增 tag: orm.em.getRepository(TagSchema), }; }创建迁移并执行顺带体验其余迁移命令# 基于 schema 差异创建新迁移 npx mikro-orm migration:create # 列出待执行迁移 npx mikro-orm migration:pending # 执行待执行迁移 npx mikro-orm migration:up # 列出已执行迁移 npx mikro-orm migration:list预期输出类似npx mikro-orm migration:create Migration20220913205718.ts successfully creatednpx mikro-orm migration:pending ┌─────────────────────────┐ │ Name │ ├─────────────────────────┤ │ Migration20220913205718 │ └─────────────────────────┘npx mikro-orm migration:up Processing Migration20220913205718 Applied Migration20220913205718 Successfully migrated up to the latest versionnpx mikro-orm migration:list ┌─────────────────────────┬──────────────────────────┐ │ Name │ Executed at │ ├─────────────────────────┼──────────────────────────┤ │ Migration20220913202829 │ 2022-09-13T18:57:12.000Z │ │ Migration20220913205718 │ 2022-09-13T18:57:27.000Z │ └─────────────────────────┴──────────────────────────┘迁移快照snapshot创建新迁移时会自动把目标 schema 快照存进 migrations 目录。之后创建迁移将基于该快照而非当前数据库 schema——这意味着即使 pending 迁移尚未执行新迁移仍能拿到正确的 schema 差异。快照应像普通迁移文件一样纳入版本控制。可通过migrations.snapshot: false关闭快照功能。在 bootstrap 中自动执行迁移最后把迁移执行自动化像 SchemaGenerator 一样编程式使用Migrator在 app 开始接收连接前的 bootstrap 阶段运行。但必须条件执行——测试库直接用 SchemaGenerator Seeder无需迁移export async function bootstrap(port 3001, migrate true) { const db initORM(); if (migrate) { // 同步 schema await db.orm.migrator.up(); } // ... }测试侧调用时传falseexport async function initTestApp(port: number) { const { orm } initORM({ ... }); await orm.schema.create(); await orm.seeder.seed(TestSeeder); const { app } await bootstrap(port, false); // -- 这里 return app; }⛳ 检查点 3目前掌握的完整能力至此你拥有 4 个实体、一个带 GET 端点的 Web 应用、一个基础测试用例以及迁移与数据播种能力。本章最终的app.ts形态可参考官方指南中的 StackBlitz 示例guide 03-project-setup.md。测试全程使用 SQLite 内存数据库通过特殊库名:memory:启用。整体架构的关键链路可以总结为Fastify hook 触发RequestContext.create()→ 每请求独立的 EM forkAsyncLocalStorage 支撑→ DI 容器复用同一 ORM 实例 → 测试用initTestApp以内存库 Seeder 播种 SchemaGenerator 建表 → 生产用 Migrator 版本化演进 schema。这套组合正是 MikroORM 在真实 Web 项目中开发、测试、生产三态一致性的标准样板。赞分享后端【免费下载链接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.项目地址https://gitcode.com/gh_mirrors/mi/mikro-orm点击查看免费下载相关推荐ESP-IDF mbedTLS 动态缓冲区管理RX/TX 缓冲区按需分配架构与实现剖析ESP IDF mbedTLS 动态缓冲区管理RX/TX 缓冲区按需分配架构与实现剖析 本文以 ESP IDF 仓库内的 dynamic_buffer_arc后端DiceDB上下文传递请求上下文管理DiceDB上下文传递请求上下文管理 概述 在现代分布式系统中上下文Context管理是确保系统可靠性和可维护性的关键要素。DiceDB作为一个用Go语数据库缓存后端Play Framework 2.7 Java Http.Context 迁移指南告别 ThreadLocal 请求上下文Play Framework 2.7 Java Http.Context 迁移指南告别 ThreadLocal 请求上下文 play.mvc.Http.Con后端Web框架上一篇快速掌握NiBabel API5个实用函数解决90%的神经影像文件处理需求下一篇NVIDIA Profile Inspector终极指南解锁显卡隐藏性能的5大实战技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考