后端【免费下载链接】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 v3 并计划升级到 v4 的开发者完整梳理官方升级文档见 upgrading-v3-to-v4.md列出的全部破坏性变更。文中结合当前仓库的源码实现如 SqlEntityManager、MongoEntityManager、WrappedEntity、wrap() 等逐一讲解变更背景、迁移写法与注意事项帮助你在升级后快速完成依赖调整、配置迁移与代码改造。阅读提示以下小节覆盖 v4 中应当说所有的破坏性变更。多数条目并非对所有人都生效——例如如果你没有使用自定义NamingStrategy实现就不必关心其接口变更。请对照自身项目逐条核对。环境要求Node.js 与 TypeScript 版本下限v4 对运行环境提出了硬性要求Node.js 10.13.0更早的 Node 版本不再受支持升级前请先确认运行时版本。TypeScript 3.7更早的 TypeScript 版本不再受支持。这两条是升级的前提门槛请先在 CI 与本地开发环境中统一版本避免升级后出现语法或类型层面的不兼容。Monorepo 拆分从单一包到多包架构v4 最显著的结构变化是 ORM 从单一mikro-orm包拆分成了多个独立发布的小包。升级后你需要同时安装mikro-orm/core和一个驱动包例如npm install mikro-orm/core mikro-orm/mysql驱动包已经内联了底层数据库客户端依赖如mikro-orm/mysql自带mysql2因此可以从package.json中移除之前手动安装的mysql2避免重复与版本冲突。v4 的包划分如下包名用途mikro-orm/core核心包包含EntityManager、EntityRepository、EntitySchema等基础能力不依赖 knexmikro-orm/reflection提供TsMorphMetadataProviderts-morph 元数据提供器mikro-orm/cliCLI 支持依赖 entity-generator、migrator 与 knexmikro-orm/knexSQL 支持QueryBuilder 等mikro-orm/entity-generator根据数据库 schema 反向生成实体mikro-orm/migrations数据库迁移工具mikro-orm/mysqlMySQL 驱动mikro-orm/mariadbMariaDB 驱动mikro-orm/mysql-baseMySQL 与 MariaDB 的公共实现内部包mikro-orm/sqliteSQLite 驱动mikro-orm/postgresqlPostgreSQL 驱动mikro-orm/mongodbMongoDB 驱动两点重要提醒过渡期 meta 包仍然存在为方便迁移mikro-orm这个 meta 包继续存在它重新导出 core、reflection、migrations、entity-generator 和 cli 包。但不要同时安装mikro-orm与mikro-orm/core否则会产生重复依赖问题。优先使用mikro-orm/core官方明确建议优先选择mikro-orm/core而非mikro-ormmeta 包因为 meta 包曾被报告存在一些奇怪的依赖问题。默认 Metadata Provider 改为ReflectMetadataProviderv4 起默认的元数据提供器从 ts-morph 切换为基于reflect-metadata的ReflectMetadataProvider。这意味着如果仍想使用 ts-morph需要额外安装mikro-orm/reflection包并在 ORM 配置中显式启用import { TsMorphMetadataProvider } from mikro-orm/reflection; await MikroORM.init({ metadataProvider: TsMorphMetadataProvider, // ... });使用ReflectMetadataProvider存在一些限制详见 metadata-providers.md 中的「Limitations and requirements」小节。概括而言类型推断不被支持必须显式标注类型集合属性与引用ref: true需要显式提供目标实体可选属性的空值判定不被支持需显式设置nullable字符串枚举需要显式声明存在循环依赖时需在装饰器中通过entity: () ...回调显式指定类型。其中最常见的一个坑是属性初始化器导致的类型推断丢失。reflect-metadata只能读取显式声明的类型遇到如下写法Property() createdAt: Date new Date();如果省略: Date显式类型标注ORM 会推断出Object而非Date最终大概率被映射为 JSON 列类型具体取决于驱动。因此升级后请检查所有带初始化器的属性确保类型标注完整。SqlEntityManager 与 MongoEntityManager按数据库风味拆分导入v4 中core包不再依赖 knex因此其中定义的EntityManager无法再提供返回QueryBuilder的方法。SQL 风味的 EM 被移入驱动包import { EntityManager } from mikro-orm/mysql; // 或任意其他 SQL 驱动包 const em: EntityManager; const qb await em.createQueryBuilder(...);SQL 风味的 EM 实际类名是SqlEntityManager它以SqlEntityManager和EntityManager两个名字同时导出所以你只需要修改 import 的来源位置其余代码无需变动。从源码看SqlEntityManager 继承自mikro-orm/core的EntityManager并额外提供了createQueryBuilder()、qb()等 SQL 专属方法。MongoDB 驱动同理aggregate()方法位于 Mongo 风味的 EM 中import { EntityManager } from mikro-orm/mongodb; const em: EntityManager; const ret await em.aggregate(...);Mongo 风味的 EM 实际类名是MongoEntityManager同样以两个名字导出只需修改导入来源。参见 MongoEntityManager 的aggregate()实现它直接转发到驱动层。多对多默认pivotTable命名规则变更UnderscoreNamingStrategy与EntityCaseNamingStrategy的joinTableName()实现发生了变化直接影响了多对多关系中间表的默认命名v3 行为中间表名由两个实体名拼成entity_a_to_entity_b完全忽略属性名。因此当同一对实体之间存在多个 M:N 关系时会产生命名冲突必须手动为至少一个关系指定pivotTable。v4 行为若拥有侧owning side集合属性名为collName中间表名将变为entity_a_coll_name天然避免了同实体对之间的冲突。新的命名规则保证中间表名不会与其他中间表冲突。当然你仍然可以在 M:N 关系的拥有侧通过pivotTable选项手动指定表名以完全掌控数据库结构。目录发现配置entitiesDirs移除改用entities/entitiesTsv4 删除了entitiesDirs与entitiesDirsTs取而代之的是entities与entitiesTs。其中entities会作为entitiesTs的默认值entitiesTs在检测到ts-node运行时被使用。entities的取值类型也比以前更灵活可以混用指向目录的路径字符串指向实体的 glob 通配符实体类的直接引用EntitySchema的实例。对绝大多数项目而言迁移动作只是把entitiesDirs重命名为entitiesMikroORM.init({ entities: [dist/**/entities, dist/**/*.entity.js, FooBar, FooBaz], entitiesTs: [src/**/entities, src/**/*.entity.ts, FooBar, FooBaz], });wrap()助手、WrappedEntity接口与Reference包装器重构v4 对实体包装机制做了根本性重构这是升级中代码改动面较大的一块v3 行为WrappedEntity接口的所有方法与属性在实体发现discovery阶段被直接添加到实体原型上。v4 行为发现阶段只向实体添加一个属性__helper: WrappedEntity。WrappedEntity从接口变成了真正的类见 WrappedEntity.ts。由此带来的 API 变化wrap(entity)不再返回实体本身而是返回WrappedEntity实例。它只暴露公开方法init、assign、isInitialized等。如果想访问__meta、__em这类内部属性必须显式调用wrap(entity, true)。对应重载签名定义在 wrap.tswrap(entity)返回IWrappedEntityTwrap(entity, true)返回IWrappedEntityInternalT。Reference类上带__前缀的内部方法也被移除需要改用wrap(ref, true)来访问。不再使用接口合并interface merging来扩展实体。取而代之的是经典继承从mikro-orm/core导出BaseEntity并继承它。如果实体继承自BaseEntitywrap(entity)会直接返回你的实体见 wrap.ts 对__baseEntity的判断分支。persist()/remove()移除flush参数v3 中persist()与remove()接受可选的flush布尔参数用于决定是否立即刷新。v4 中该参数被移除两个方法变为同步方法必须显式调用flush()才能真正落库推荐使用链式调用// before await em.persist(jon, true); await em.remove(Author, jon, true); // after await em.persist(jon).flush(); await em.remove(jon).flush();这背后与 Unit of Work 的工作方式一致persist()只负责把实体登记进工作单元参见 EntityManager.ts 中对unitOfWork.persist()的调用真正的 SQL 在flush()时统一发出。remove()只接受实体实例条件删除请用nativeDelete()v3 的em.remove()既允许传实体实例也允许传查询条件——传入条件时它会直接执行原生删除查询既不经过事务也不触发钩子。v4 将方法语义收窄只接受实体实例删除交由UnitOfWork统一管理跟踪、级联、生命周期钩子。如果需要按条件直接发删除 SQL请显式使用em.nativeDelete()// before await em.remove(Author, 1); // fires query directly // after await em.nativeDelete(Author, 1);另外em.removeEntity()已被删除统一收敛到em.remove()两者签名现在几乎一致。从当前源码看EntityManager.ts 中remove()的实现会明确校验传入的是实体实例或引用并在类型不符时提示“使用em.nativeDelete()按条件删除”而 nativeDelete() 则直接调用driver.nativeDelete()。类型安全的引用LoadedT, P与get()v4 的 EM 查询方法返回值类型从实体T升级为LoadedT, P。该类型会在满足加载提示populate hint的条件下自动为结果附加同步方法get()对单个引用get()返回实体对集合get()返回实体数组。Reference.get()现在只能在正确的Loaded类型提示下使用作为获取实体的同步 getter类似unwrap()。如果你需要原来的get()方法异步加载功能请改用Reference.load(prop)。另一个相关变化是em.find()等方法的类型参数变为两个。由于 TypeScript 不支持部分类型推断如果你显式指定了T却没有同时指定加载提示推断会失效。这个场景主要出现在「接口 EntitySchema」的无类用法中——v4 现在支持把EntitySchema实例作为第一个参数传给这些方法从而获得正确的类型推断const author await em.findOne(AuthorSchema, { ... }, [books]); console.log(author.books.get()); // get() 现在能被正确推断自定义类型Custom Type现在类型安全泛型Type类从单参数变为两个类型参数——输入类型与输出类型输入类型默认是string输出类型默认等于输入类型。如果你自定义类型的相关方法签名写得很严格可能需要显式提供这两个类型参数例如class MyType extends Typestring, MyRuntimeValue { // convertToDatabaseValue / convertToJSValue 等 }自定义类型序列化行为变更v3 中自定义类型在序列化toJSON()时被转换为数据库值。v4 改为默认使用运行时值。如果确实需要自定义序列化输出请在自定义类型上实现自己的toJSON()方法。属性default与新增defaultRawv3 中属性的default选项原样透传因此字符串默认值需要手动加引号例如Property({ default: foo bar })。v4 中default的类型收窄为string | number | boolean | null并且字符串值会被自动加引号写法更符合直觉Property({ default: foo bar })需要使用 SQL 函数如now()、uuid()时改用新增的defaultRaw选项Property({ defaultRaw: now() })注意两者的本质区别default会被 ORM 当作字面量值处理字符串自动引用而defaultRaw原样作为 SQL 片段嵌入建表语句。autoFlush选项移除persistLater()/removeLater()弃用v4 移除了autoFlush配置选项。同时persistLater()与removeLater()方法被标记为弃用请分别改用persist()与remove()。这与此前flush参数移除一脉相承flush 时机现在完全由开发者显式控制。IdEntity、UuidEntity、MongoEntity接口移除这三个接口被删除——它们在实际使用中从未被真正需要。如果代码里 import 了它们直接删除相关引用即可。MongoDB 不再是默认驱动v3 中 MongoDB 是默认平台v4 起你必须显式指定平台。两种方式通过type选项指定平台类型通过driver选项直接提供驱动实现。v4 可用平台类型为mongo、mysql、mariadb、postgresql、sqlite。MikroORM.init({ type: postgresql, // 或 driver: PostgreSqlDriver // ... });提示type选项在后续更高版本v6 起已被移除改为统一使用driver或从驱动包导出的defineConfig/MikroORM类参见 Configuration.ts 中的校验逻辑。若你的升级路径跨越多个大版本请留意这一演进。移除配置项discovery.tsConfigPathdiscovery.tsConfigPath被删除因为它不再需要该选项原本只服务于TsMorphMetadataProvider且仅在未显式提供entitiesDirsTs时使用。v4 中 ts-morph 发现改用.d.ts文件获取类型信息而这些文件应当位于编译产物实体旁边——所以请确保生产构建开启了compilerOptions.declaration随实体一起发布.d.ts文件。查询高亮Query Highlighting变更v3 使用 Highlight.js 对 CLI 中的 SQL、Mongo 查询以及 CLI 生成的迁移/实体进行高亮。该库体积巨大对于使用 webpack 打包、尤其是使用 lambda 的开发者造成了明显的性能问题。v4 的调整默认关闭高亮提供两个可选的高亮器需要先自行安装SQL 使用mikro-orm/sql-highlighterimport { SqlHighlighter } from mikro-orm/sql-highlighter; MikroORM.init({ highlighter: new SqlHighlighter(), // ... });MongoDB 使用mikro-orm/mongo-highlighter配置方式与上例相同将highlighter替换为 Mongo 高亮器实例即可。升级自查清单为便于对照执行将以上变更整理为一份快速核对清单Node.js 升级到 10.13.0TypeScript 升级到 3.7按驱动安装mikro-orm/core 对应驱动包移除手写的mysql2等底层依赖避免mikro-orm与mikro-orm/core共存如需 ts-morph安装mikro-orm/reflection并显式配置metadataProvider否则确认reflect-metadata已在入口引入、emitDecoratorMetadata已开启并补齐所有显式类型标注尤其是带初始化器的属性em.createQueryBuilder()的 import 来源改为 SQL 驱动包em.aggregate()的 import 来源改为mikro-orm/mongodb检查多对多中间表默认命名变化必要时用pivotTable手动指定entitiesDirs/entitiesDirsTs重命名为entities/entitiesTs检查wrap()相关调用内部__属性改用wrap(entity, true)需要实体扩展方法时考虑继承BaseEntity移除persist()/remove()的flush参数改为链式.flush()按条件删除改用nativeDelete()删除对IdEntity、UuidEntity、MongoEntity的引用显式配置type或driverMongoDB 不再是默认驱动移除discovery.tsConfigPath确认生产构建发布.d.ts如需查询高亮安装并配置mikro-orm/sql-highlighter或mikro-orm/mongo-highlighter完成上述核对后项目即可平滑过渡到 v4 架构。若你在升级中遇到具体的报错或类型问题可结合本仓库中的源码如 EntityManager.ts、WrappedEntity.ts、wrap.ts以及 metadata-providers.md 等文档进一步定位。赞分享后端【免费下载链接】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 v3 升级到 v4 完整迁移指南Monorepo 拆分、类型安全重构与破坏性变更全解析MikroORM v3 升级到 v4 完整迁移指南Monorepo 拆分、类型安全重构与破坏性变更全解析 本文基于 MikroORM 官方升级文档 docs后端MikroORM v4 到 v5 升级指南破坏性变更全景解析与迁移实战MikroORM v4 到 v5 升级指南破坏性变更全景解析与迁移实战 本文基于 MikroORM 官方升级文档v4 → v5系统梳理所有破坏性变更从运后端mikro-orm v3 到 v4 升级完全指南Monorepo 拆分、EntityManager 风味化与类型系统重构mikro orm v3 到 v4 升级完全指南Monorepo 拆分、EntityManager 风味化与类型系统重构 mikro orm v4 是一次结构后端上一篇如何快速搭建企业级CMS网站Happy Lager完整指南 下一篇推荐开源项目Android MP3 Recorder - 打造你的个性化录音应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
