后端【免费下载链接】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点击查看免费下载本篇技术指南以 mikro-orm/mongodb 包说明文档 为核心骨架系统讲解 MikroORM 在 MongoDB 上的驱动能力包括安装接入、基于defineEntity的实体定义、ObjectId 与字符串主键的自动转换、MongoDB 专属查询操作符、事务、索引与 Schema 管理、原生集合方法以及collation/indexHint/maxTimeMS等查询选项。读完本文你将能够独立完成 MikroORM MongoDB 项目的初始化、实体建模、复杂查询与索引维护并理解驱动底层MongoDriver.ts、MongoConnection.ts是如何把这些能力映射到官方mongodbNode.js 驱动之上的。一、包定位与安装mikro-orm/mongodb是 MikroORM 面向 MongoDB 的数据库驱动driver包建立在官方mongodb可以看到它仅声明mongodb当前仓库锁定版本 7.6.0为直接依赖并以mikro-orm/core当前仓库版本 7.2.1为 peerDependency运行时要求 Node.js 22.17.0。安装命令与 README 保持一致npm install mikro-orm/core mikro-orm/mongodb安装后即可从mikro-orm/mongodb包入口src/index.ts获得完整能力。该入口文件会重新导出mikro-orm/core的全部 API并额外导出ObjectId来自mongodb驱动、MongoConnection、MongoDriver、MongoPlatform、MongoEntityManager同时以EntityManager别名导出、MongoEntityRepository同时以EntityRepository别名导出以及MongoMikroORM以MikroORM别名导出。因此下文所有示例都直接使用import { MikroORM } from mikro-orm/mongodb这一统一入口。二、最小可运行示例定义实体并完成增查README 给出了一套完整的开箱即用示例。该示例使用defineEntity 属性辅助器p的 Schema 方式定义实体不依赖装饰器是 MikroORM 7.x 推荐的实体定义方式再通过MikroORM.init初始化并完成创建、持久化与带关联预加载的查询import { defineEntity, p, MikroORM } from mikro-orm/mongodb; const AuthorSchema defineEntity({ name: Author, properties: { id: p.objectId().primary(), name: p.string(), books: () p.oneToMany(Book).mappedBy(author), }, }); export class Author extends AuthorSchema.class {} AuthorSchema.setClass(Author); const BookSchema defineEntity({ name: Book, properties: { id: p.objectId().primary(), title: p.string(), author: () p.manyToOne(Author).inversedBy(books), }, }); export class Book extends BookSchema.class {} BookSchema.setClass(Book); const orm await MikroORM.init({ entities: [Author, Book], dbName: my-db, clientUrl: mongodb://localhost:27017, }); const author orm.em.create(Author, { name: Jon Snow }); orm.em.create(Book, { title: My Life on The Wall, author }); await orm.em.flush(); const authors await orm.em.find( Author, { name: /Jon/ }, { populate: [books], }, );几个值得注意的细节主键使用p.objectId().primary()声明为 MongoDB 原生ObjectId类型这与装饰器写法中PrimaryKey() _id: ObjectId语义一致关系通过p.oneToMany(...).mappedBy(author)与p.manyToOne(...).inversedBy(books)双向声明一对多集合默认不落库、按需加载查询条件直接使用原生正则/Jon/MongoDriver 会在查询翻译阶段将其原样透传给底层findpopulate: [books]会触发关联集合的加载。初始化代码的底层路径是MongoMikroORM.init 会调用defineMongoConfig(options)——它通过defineConfig({ driver: MongoDriver, ...options })自动注入MongoDriver作为驱动因此你甚至不需要显式传driver选项。同一文件还提供了类型安全的defineMongoConfig配置函数与带类型参数的MongoOptions类型方便在独立配置文件中以强类型方式声明初始化参数。三、连接配置clientUrl、认证与连接池MongoDB 驱动的连接配置有几个与其他 SQL 驱动显著不同的约束官方使用指南docs/docs/usage-with-mongo.md与 MongoConnection.mapOptions 源码共同确认了以下事实必须使用clientUrl指定主机。MongoConnection.mapOptions明确抛错Mongo driver does not support host options, use clientUrl instead!即host/port配置项在 MongoDB 驱动下不被支持连接串应形如mongodb://localhost:27017多节点副本集则是mongodb://localhost:27017,localhost:27018,localhost:27019/my-db-name?replicaSetrs0。dbName用于选定数据库createClient()与getDb()中通过this.#client.db(this.config.get(dbName))绑定目标库MongoConnection.ts。认证信息配置了user与password时会组装成ret.auth { username, password }传给MongoClient。连接池映射pool.min、pool.max、pool.idleTimeoutMillis分别映射为驱动层的minPoolSize、maxPoolSize、waitQueueTimeoutMS。默认连接串MongoPlatform.getDefaultClientUrl 返回mongodb://127.0.0.1:27017未显式配置时使用该默认值。复用外部 MongoClientcreateClient()支持通过driverOptions直接传入一个已构造的MongoClient实例此时驱动会记录日志Reusing MongoClient provided via driverOptions并直接复用避免重复建连仓库测试 reusing-mongo-client.test.ts 即覆盖该场景。连接建立后驱动还会通过this.#client.appendMetadata({ name: MikroORM, version: Utils.getORMVersion() })把 MikroORM 的标识信息附加到客户端元数据上便于在 MongoDB 服务端观测请求来源。四、ObjectId 与字符串 id 双主键机制这是 MongoDB 驱动最有特色的能力之一。README 将其概括为“Automatic serialized primary key conversion (_id↔id)”官方文档给出了装饰器写法PrimaryKey() _id: ObjectId; SerializedPrimaryKey() id!: string; // wont be saved in the database要点是只有_id: ObjectId真正落库id: string是虚拟字段。但 ORM 层所有EntityManager与EntityRepository方法都同时支持用字符串 id 或ObjectId查询二者结果一致const author orm.em.getReference(...id...); console.log(author.id); // 返回字符串 id console.log(author._id); // 返回 ObjectId // 下面四种写法结果完全相同 const repo orm.em.getRepository(Author); const foo1 await repo.find({ id: { $in: [article] }, favouriteBook: book }); const bar1 await repo.find({ id: { $in: [new ObjectId(article)] }, favouriteBook: new ObjectId(book) }); const foo2 await repo.find({ _id: { $in: [article] }, favouriteBook: book }); const bar2 await repo.find({ _id: { $in: [new ObjectId(article)] }, favouriteBook: new ObjectId(book) });这一机制在源码中的实现分为三层序列化/反序列化MongoPlatform.normalizePrimaryKey 将ObjectId转为toHexString()字符串denormalizePrimaryKey 反向用new ObjectId( data)还原。字段重命名MongoDriver.renameFieldsMongoDriver.ts在元数据存在serializedPrimaryKey时先用Utils.renameKey(copiedData, meta.serializedPrimaryKey, meta.primaryKeys[0])把查询/写入数据里的id键改回_id再把实体属性名映射为数据库字段名prop.fieldNames[0]。ObjectId 自动转换MongoDriver.convertObjectIdsMongoDriver.ts递归地把 24 位十六进制字符串转换为ObjectId实例覆盖普通字符串、数组与嵌套对象若属性类型本身就是ObjectId则直接透传。例如find(Author, { id: 507f1f77bcf86cd799439011 })最终落到驱动层的条件就是{ _id: ObjectId(507f1f77bcf86cd799439011) }。同时MongoPlatform.validateMetadata强制要求主键的数据库字段名必须是_idpk.fieldNames?.[0] ! _id时抛出MetadataError.invalidPrimaryKey从元数据层面保证了这一约定不被破坏。五、MongoDB 专属查询操作符与全文搜索README 的功能清单提到驱动支持 MongoDB 专属操作符$regex、$exists、$elemMatch等。这些操作符与原生$in、$and、$or一样可以直接出现在FilterQuery中由驱动原样下推给官方驱动执行// $regex等价于直接传 /Jon/ await orm.em.find(Author, { name: { $regex: /Jon/i } }); // $exists字段存在性判断 await orm.em.find(Book, { title: { $exists: true } }); // $elemMatch数组元素级匹配 await orm.em.find(Author, { books: { $elemMatch: { title: /Wall/ } } });除了这些原生操作符驱动还做了两项 MikroORM 层面的特殊翻译见 MongoDriver.renameFields$fulltext→$text.$searchMikroORM 的全文搜索操作符$fulltext会被转换为 MongoDB 原生结构data.$text { $search: data.$fulltext }如果$fulltext出现在$and子句中驱动会尝试把它提升到查询对象顶层MongoDB 只允许$text出现在查询根层若无法合并则抛错。$re对象 → RegExp 实例当属性值形如{ $re: pattern }时会被转换为new RegExp(...)方便以可序列化的形式传正则。顶层操作符白名单由 MongoPlatform.isAllowedTopLevelOperator 定义为[$not, $fulltext]。六、关系映射内联 pivot 数组的 ManyToMany与 SQL 驱动使用中间表pivot table不同MongoDB 驱动利用文档模型天然支持数组类型的特性把 ManyToMany 关联以“内联标识数组”的形式存储在拥有方实体上官方文档 “ManyToMany collections with inlined pivot array” 一节。这样做的两个直接收益集合规模可见集合存储在拥有方实体文档内部即使集合尚未初始化hydration也能直接得知其中有多少个元素查询更简单没有中间表读写关联只涉及拥有方单文档底层查询数量显著减少。在元数据层面MongoPlatform.shouldHaveColumnMongoPlatform.ts保证MANY_TO_MANY且为拥有方owner的属性会被当作需要存储的列处理从而在文档中生成内联数组字段。一对多/多对一如 README 示例中的Author.books/Book.author则通过外键字段author存储对方_id关联查询时由populate触发加载。七、事务支持MongoDB 驱动完整支持事务但官方文档强调使用事务需要满足三个前提必须运行副本集例如用run-rs启动本地副本集# 先创建副本集 $ run-rs -v 4.2.3隐式事务默认关闭MongoDB 驱动不支持 SQL 驱动默认开启的隐式事务MongoPlatform.usesImplicitTransactions()返回false。需要全局开启时配置implicitTransactions: true或者用显式的事务边界em.transactional()。先建集合再使用事务中使用的集合必须已存在因此初始化后要调用orm.schema.create()预建集合。完整的副本集 事务配置示例// 必须从 MongoDriver 包导入 import { MikroORM } from mikro-orm/mongodb; const orm await MikroORM.init({ entities: [Author, Book, ...], clientUrl: mongodb://localhost:27017,localhost:27018,localhost:27019/my-db-name?replicaSetrs0, implicitTransactions: true, // 默认为 false }); await orm.schema.create();底层实现上事务被映射为 MongoDB 官方的ClientSessionMongoConnection.begin调用client.startSession()与session.startTransaction(txOptions)commit/rollback分别对应commitTransaction()/abortTransaction()transactional()则封装了 begin → 回调 → commit异常则 rollback→endSession的完整生命周期见 MongoConnection.ts。所有涉及写操作的驱动方法insertOne、updateMany、deleteMany等都接受ctx?: TransactionClientSession参数事务会话会作为session选项传给官方驱动。八、索引与 Schema 管理MongoDB 驱动支持索引与唯一约束。官方文档指出使用Index()与Unique()装饰器即可声明索引详见 defining-entities.md但要在 ORM 初始化时自动创建索引需要开启ensureIndexes选项const orm await MikroORM.init({ entities: [Author, Book, ...], dbName: my-db-name, ensureIndexes: true, // 默认为 false });也可以不开启该选项而是在需要时手动调用 SchemaGenerator 的方法MongoDB 驱动同样提供 SchemaGeneratorawait orm.schema.ensureIndexes();MongoDB 的索引声明还有若干文档化的扩展写法部分索引通过options传partialFilterExpressionUnique({ options: { partialFilterExpression: { name: { $exists: true } } } })文本索引通过type: text驱动内部会把 MikroORM 的fulltext类型归一化为 MongoDB 的text见 MongoSchemaGenerator.createIndexesIndex({ properties: [name, caption], type: text })任意索引规格只提供options时按原样透传给驱动可定义任意类型的索引如2dsphere地理索引Index({ options: { point: 2dsphere, title: -1 } })权重设置用二元组数组形式传options第二个元素为权重Index({ options: [ { title: text, perex: text, key: 1 }, { weights: { title: 10, perex: 5 } }, ] })源码层面MongoSchemaGenerator 负责集合与索引的完整生命周期create()先listCollections()找出已存在的集合为缺失的实体逐个createCollection()然后默认ensureIndexes ?? true调用ensureIndexes()建索引对“集合已存在”的 MongoServerError 会静默忽略。ensureIndexes()为每个实体的元数据索引、唯一约束、属性级index/unique逐项执行createIndex失败时会记录失败集合、先dropIndexes()清理半成品再按retryLimit默认 3递归重试处理了建索引过程中的竞态与部分失败恢复。drop()按元数据顺序删除所有实体对应集合可附带删除迁移表。refresh()先 drop 再 create用于测试或重建场景。索引的where条件即partialFilterExpression支持options.partialFilterExpression优先、where兜底的合并逻辑字符串形式的where会被拒绝并提示使用对象形式。属性级索引在字段可空prop.nullable true时会自动附加sparse: true避免唯一索引把多个null值也判重。九、原生集合方法insert / nativeUpdate / nativeDelete / aggregate当需要批量灌入初始数据、执行原生更新或聚合时走 ORM 的实体生命周期反而繁琐。官方文档提供的原生方法签名如下em.insertT extends AnyEntity(entityName: string, data: any): PromiseIPrimaryKey; em.nativeUpdateT extends AnyEntity(entityName: string, where: FilterQueryT, data: any): Promisenumber; em.nativeDeleteT extends AnyEntity(entityName: string, where: FilterQueryT | any): Promisenumber;这些方法在 MongoDB 驱动上分别对应原生集合方法的insertOne、updateMany、deleteMany见 MongoDriver.nativeInsert / nativeUpdate / nativeDelete。注意它们不做实体水合hydration也不会触发生命周期钩子是纯粹的底层直通操作。它们同样以EntityRepository快捷方法的形式可用EntityRepository.insert(data: any): PromiseIPrimaryKey; EntityRepository.nativeUpdate(where: FilterQueryT, data: any): Promisenumber; EntityRepository.nativeDelete(where: FilterQueryT | any): Promisenumber;此外还有聚合的快捷入口em.aggregate(entityName: string, pipeline: any[]): Promiseany[]; EntityRepository.aggregate(pipeline: any[]): Promiseany[];aggregate是 MongoDB 驱动特有能力位于 MongoEntityManager.aggregate 与 MongoEntityRepository.aggregate最终落到 MongoDriver.aggregate 并调用MongoConnection.aggregate底层执行collection.aggregate(pipeline).toArray()。由于该方法不在 SQL 驱动上存在官方文档提醒要访问驱动特有方法需要在MikroORM.initD()时指定驱动类型或把orm.em断言为从驱动包导出的EntityManagerimport { EntityManager } from mikro-orm/mongodb; const em orm.em as EntityManager; const qb em.aggregate(...);MongoEntityManager还提供了流式聚合streamAggregate()以及直接获取底层Collection的getCollection()方法可结合MongoQueryOptions.signal实现查询取消。countBy分组计数也由该驱动通过聚合管道$match → $group实现MongoEntityManager.countBy但文档明确having选项在 MongoDB 上不被支持。十、查询选项collation、indexHint、maxTimeMS 与 allowDiskUse官方文档列出四类可传给em.find()/em.count()的 MongoDB 专属查询选项Collation排序规则控制字符串比较规则同时作用于过滤与排序。MongoDB 的 collation 作用于整个查询操作因此必须传CollationOptions对象如{ locale: en, strength: 2 }不能传 SQL 风格的字符串——MongoDriver.buildQueryOptions 对字符串 collation 会直接抛错提示“MongoDB 请传 CollationOptions 对象字符串仅用于 SQL 驱动”。大小写不敏感的查找与排序示例const users await em.find(User, { name: john }, { collation: { locale: en, strength: 2 }, orderBy: { name: QueryOrder.ASC }, });Index Hints索引提示传入索引名称字符串或索引规格对象映射到官方驱动的hint选项// 按索引名 const users await em.find(User, {}, { indexHint: name_1 }); // 或按索引规格 const users await em.find(User, {}, { indexHint: { name: 1 } });该选项也支持通过using传入但 MongoDB 单次查询只允许一个索引提示多个索引名数组会抛错见 MongoDriver.buildQueryOptions。maxTimeMS 与 allowDiskUseconst users await em.find(User, {}, { maxTimeMS: 5000, // 查询超时时间毫秒 allowDiskUse: true, // 大排序时允许使用磁盘 });collation、indexHint、maxTimeMS同样适用于em.count()allowDiskUse仅适用于em.find()。这些选项在 MongoQueryOptions 接口 中统一定义除上述外还包括signalAbortSignal触发时官方驱动会关闭底层 socket 中止操作拒绝原因是signal.reason。MongoDriver.buildQueryOptions会把它们从FindOptions中提取出来最终由MongoConnection._find映射为官方驱动的projection、hint、maxTimeMS、allowDiskUse、batchSize来自chunkSize与session等原生选项MongoConnection.ts。排序方向映射也有细节MongoDB 不支持nulls first / nulls last排序语义MongoPlatform.supportsNullsOrdering()返回false且sortsNullsLowest()返回true因此 MongoConnection.getSortDirection 会忽略排序键中的 null 限定符只把方向映射为1/-1。十一、驱动内部从 ORM 调用到原生命令的完整链路把上面的内容串联起来一次orm.em.find(Author, { name: /Jon/ }, { populate: [books] })在 MongoDB 驱动中的完整链路是MongoEntityManager继承自 core 的EntityManager解析条件、加载策略与 populate 计划MongoDriver.find 负责对虚拟实体走findVirtual构造字段投影buildFields会自动剔除未 populate 的 lazy 属性并确保主键被投影调用renameFields完成id → _id键名转换、embedable 内联与 ObjectId 转换把orderBy逐字段重命名MongoConnection._find用转换后的FilterQuery调用collection.find(where, options)并按需附加.sort()、.limit()、.skip()同时生成可读的日志语句如db.getCollection(Author).find({...}).sort([...]).limit(...)结果经MongoDriver.mapResult水合为实体normalizePrimaryKey把ObjectId转成字符串 idpopulate按需触发关联集合的二次查询。写入侧同理em.flush()最终调用MongoDriver.nativeInsert/nativeUpdate/nativeDelete其中 handleVersionProperty 负责乐观锁版本字段的自动填充Date 类型写入当前时间数值类型插入时置 1、更新时用$inc: 1MongoConnection.createUpdatePayload 会把普通对象包装为$set/$unset/$inc更新指令并支持$setOnInsert语义以实现upsert时的“冲突忽略/仅插入缺失字段”控制onConflictAction: ignore、onConflictMergeFields、onConflictExcludeFields。批量更新走initializeUnorderedBulkOp构造 bulk 操作。所有查询日志都由 rethrow / logQuery 统一记录出错时会在错误信息后追加实际执行的查询语句便于排障。十二、平台级行为与限制MongoDB 驱动在 MongoPlatform 中声明了一组与其他数据库不同的平台行为理解这些有助于规避使用误区加载策略强制使用select-inconfig.set(loadStrategy, select-in)并关闭autoJoinOneToOneOwner默认值推断关闭discovery.inferDefaultValues隐式事务默认关闭usesImplicitTransactions() falseJSON 处理convertsJsonAutomatically()与preservesDatesInsideJson()均为trueJSON 字段内的 Date 会被保留读写时无需额外序列化命名策略默认MongoNamingStrategy元数据校验不支持tpttable-per-type继承与数据库触发器triggers使用时会抛出对应MetadataErrorEntityGeneratorMongoDB 驱动不支持getExtension(EntityGenerator)直接抛错迁移迁移扩展通过mikro-orm/migrations-mongodb提供见 MongoMikroORM.migrator 与 MongoPlatform.getExtension对应包文档可参考 migrations-mongodb/README.md主键强制数据库字段名为_id且tpt之外的普通继承不受影响流式查询stream()不支持populateMongoEntityManager.stream 会显式抛错但支持rawResults直通原始文档。README 中提到的Embeddables嵌入式对象、虚拟实体virtual entities与懒加载lazy loading也是 MongoDB 场景下的常用能力MongoDriver.renameFields对EMBEDDED属性按目标元数据递归重命名支持array/object两种内联形式MongoDriver.findVirtual/streamVirtual支持基于expression函数定义虚拟实体MongoDriver.buildFields会自动跳过未加载的懒加载属性。这些细节表明虽然驱动层直通原生 MongoDB实体层仍然完整保留了 MikroORM 的 Identity Map、Unit of Work 与数据映射语义。结语mikro-orm/mongodb在保持 MikroORM 统一 API 的同时完整继承了 MongoDB 的文档模型特性_id/id双主键自动转换、内联数组关系、$text全文搜索、副本集事务、聚合管道与原生查询选项。配合 官方使用指南、驱动源码MongoDriver.ts、MongoConnection.ts、MongoPlatform.ts、MongoSchemaGenerator.ts以及仓库测试如 EntityHelper.mongo.test.ts、transactions.mongo.test.ts、reusing-mongo-client.test.ts开发者可以按需深入任意一层从“会用”走向“理解原理”。赞分享后端【免费下载链接】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点击查看免费下载相关推荐vanilla-extract × Next.js 集成实战从安装配置到源码级原理vanilla extract × Next.js 集成实战从安装配置到源码级原理 vanilla extract 是一套 Zero runtime零运行时前端开发工具better-scroll/slide 轮播插件从安装配置到源码级实现原理better scroll/slide 轮播插件从安装配置到源码级实现原理 better scroll/slide 是 BetterScroll 官方提供前端UI组件MikroORM 5.9 安装与初始化实战指南从依赖安装、实体发现到 CLI 配置MikroORM 5.9 安装与初始化实战指南从依赖安装、实体发现到 CLI 配置 本篇指南以 MikroORM 官方 v5.9 文档 安装与使用 http后端上一篇Flet Charts 折线图数据点详解使用 LineChartDataPoint 构建交互式折线图下一篇还在为WeMod高级功能付费Wand-Enhancer零门槛解锁完整版手机躺着也能远程改游戏创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考