后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载midwayjs/mikro7是 Midway 专为 MikroORM v7 打造的独立组件包。本文以仓库中的设计文档 design.md 为核心骨架结合 packages/mikro7 的实际实现、测试用例与官方文档 site/docs/extensions/mikro.md完整讲解该组件为何拆分、API 边界如何设计、ESM 模块策略如何落地以及 v7 项目从安装、实体定义、数据源配置到仓储注入的完整实战流程。读完本文你将能在 Midway 应用中正确接入 MikroORM v7并清楚 v6 与 v7 两条技术路径的分工与注意事项。背景MikroORM v7 为什么需要独立的组件包Midway 原有的midwayjs/mikro组件是针对 MikroORM v6 构建与验证的。而 MikroORM v7 发生了两个根本性变化MikroORM v7 是原生 ESMnative ESM模块加载机制与 CommonJS 存在本质差异v7 将装饰器从mikro-orm/core中移出实体装饰器改由独立的mikro-orm/decorators包提供。这意味着如果继续用单一组件包同时支持 v6 与 v7就必须在一个包内处理两种截然不同的模块假设CommonJS 与 ESM以及两种用户代码写法极易引入脆弱的条件加载逻辑。同时由于文档示例基于 v6 验证用户在按文档安装时也可能“意外”装上 v7 的大版本导致组件与 ORM 版本不匹配。因此设计文档给出的结论是为 v7 提供独立、清晰的组件包midwayjs/mikro7而不是在旧包中强行兼容两个大版本。设计目标与非目标Goals要做的为 MikroORM v7 用户提供清晰、稳定的组件包避免在现有 v6 包内做脆弱的 CommonJS/ESM 条件加载保留现有midwayjs/mikro的 APIv6 用户不受影响让安装命令与实体示例显式区分版本避免用户误装不受支持的大版本。Non-Goals明确不做的不将完整的 MikroORM v7 支持 retrofit 回midwayjs/mikro不移除或重命名midwayjs/mikro不提供 v6 装饰器与 v7 装饰器之间的运行时自动迁移层。在仓库中这一目标被规范化为 openspec 需求见 specs/mikro-orm-component/spec.md系统必须提供专用的midwayjs/mikro7包、完成 v7 数据源初始化与请求级 EntityManager 集成、保持 v6 包路径不变并让文档按版本区分安装与配置方式。对应的 proposal.md 与 tasks.md 显示该变更已全部实施完成。包边界与 v6 组件保持 API 对齐设计文档明确了midwayjs/mikro7的边界在可行前提下暴露与midwayjs/mikro相同的 Midway 侧装饰器名称与注入概念但类型面向 MikroORM v7。实际实现的导出面见 packages/mikro7/src/index.ts如下导出类型说明Configuration即MikroConfiguration组件配置类将 MikroORM v7 数据源接入 Midway 生命周期与注入钩子InjectRepository(modelKey, connectionName?)属性装饰器注入指定数据源下的实体仓储EntityRepositoryInjectEntityManager(connectionName?)属性装饰器注入指定数据源下的 EntityManagerInjectDataSource(dataSourceName?)属性装饰器注入指定名称的 MikroORM 数据源对象MikroDataSourceManager数据源管理器创建、持有并销毁 v7 数据源MikroConfigOptions配置类型面向 MikroORM v7 的配置类型别名装饰器实现packages/mikro7/src/decorator.ts通过DecoratorManager.createCustomPropertyDecorator注册三个注入键ENTITY_MODEL_KEY mikro:entity_model_key—— 对应InjectRepositoryENTITY_MANAGER_KEY mikro:entity_manager_key—— 对应InjectEntityManagerDATA_SOURCE_KEY mikro:data_source_key—— 对应InjectDataSource。配置类型MikroConfigOptionspackages/mikro7/src/interface.ts基于 Midway 的DataSourceManagerConfigOption泛型每个数据源接受 MikroORM v7 的OptionsD | ConfigurationD并额外允许logger为日志器名称字符串或回调函数export type MikroConfigOptionsD extends IDatabaseDriver IDatabaseDriver DataSourceManagerConfigOption (OptionsD | ConfigurationD) { logger?: string | ((message: string) void); } ;说明设计文档中提到的InjectMikroORM数据源注入 API 对齐在实际实现中以InjectDataSource呈现语义一致——注入的是 MikroORM 实例本身。模块策略原生 ESM 输出设计文档要求v7 包必须以能够直接 import MikroORM v7 的方式编写与发布避免 CommonJS interop 陷阱在仓库级构建工具无法产出纯 ESM 包时仅在packages/mikro7内增加最小化的包级构建配置。从 packages/mikro7/package.json 可以看到落地结果{ name: midwayjs/mikro7, version: 4.2.3, type: module, main: dist/index.js, typings: index.d.ts, exports: { .: { types: ./index.d.ts, import: ./dist/index.js }, ./package.json: ./package.json }, peerDependencies: { mikro-orm/core: ^7.0.0 }, engines: { node: 20 } }关键点type: module声明包本身为 ESM源码内部统一使用带.js后缀的相对导入如./decorator.js与原生 ESM 规范一致exports仅暴露import条件ESM 消费者直接加载dist/index.js不提供 CommonJS 入口从根本上绕开 interop 问题peerDependencies只声明mikro-orm/core: ^7.0.0保证包不会与 v6 大版本混用engines.node 20与 MikroORM v7 的运行环境要求对齐。TypeScript 侧packages/mikro7/tsconfig.json仅继承仓库根 tsconfig 并指定rootDir: src、outDir: dist将 ESM 化约束局部化不影响其他包的构建输出。Jest 测试则采用 ESM presetpackages/mikro7/jest.config.js使用ts-jest/presets/default-esm、useESM: true并通过moduleNameMapper将.js后缀映射回.ts源码同时由node --experimental-vm-modules驱动见 package.json 的test脚本。文档策略按大版本拆分安装路径官方文档 site/docs/extensions/mikro.md 明确按大版本拆分MikroORM v6使用midwayjs/mikro配套mikro-orm/*^6MikroORM v7使用midwayjs/mikro7配套mikro-orm/*^7与mikro-orm/decorators。文档特别强调v7 项目不要与midwayjs/mikro混用。同时v7 文档必须写明两件事使用 legacy TypeScript 装饰器时实体装饰器需从mikro-orm/decorators/legacy导入配置中显式设置metadataProvider: ReflectMetadataProvider且项目 TypeScript 的moduleResolution需为nodenext、node20或bundler。安装与引入组件安装 v7 组件$ npm i midwayjs/mikro74 mikro-orm/core^7 mikro-orm/decorators^7 mikro-orm/sqlite^7 --save对应package.json依赖{ dependencies: { midwayjs/mikro7: ^4.0.0, mikro-orm/core: ^7.0.0, mikro-orm/decorators: ^7.0.0, mikro-orm/sqlite: ^7.0.0 } }其中mikro-orm/decorators是 v7 的装饰器独立包mikro-orm/sqlite可按数据库驱动替换为 mysql、postgresql 等适配包。在 configuration.ts 中引入组件// src/configuration.ts import { Configuration } from midwayjs/core; import * as mikro from midwayjs/mikro7; import { join } from path; Configuration({ imports: [ // ... mikro // 加载 mikro7 组件 ], importConfigs: [ join(__dirname, ./config) ] }) export class MainConfiguration { }定义实体v7 装饰器路径与元数据提供器MikroORM v7 将装饰器移出mikro-orm/core因此实体的编写方式与 v6 不同。仓库测试夹具 packages/mikro7/test/fixtures/base-fn-origin/src/entity/Author.ts 给出了标准写法// src/entity/Author.ts import { Cascade, Collection, OptionalProps, type Rel, } from mikro-orm/core; import { Entity, ManyToOne, OneToMany, Property, } from mikro-orm/decorators/legacy; import { Book } from ./Book.js; import { BaseEntity } from ./BaseEntity.js; Entity() export class Author extends BaseEntity { [OptionalProps]?: termsAccepted; Property() name: string; Property() email: string; Property({ nullable: true }) age?: number; OneToMany(() Book, b b.author, { cascade: [Cascade.ALL] }) books new CollectionBook(this); ManyToOne(() Book, { nullable: true }) favouriteBook?: RelBook; constructor(name: string, email: string) { super(); this.name name; this.email email; } }要点运行时类型Entity、Property、ManyToOne、OneToMany等从mikro-orm/decorators/legacy导入这是 legacy TypeScript 装饰器experimentalDecorators下的 v7 用法纯类型Cascade、Collection、OptionalProps、Rel仍从mikro-orm/core导入实体间相对导入需带.js后缀./Book.js这是原生 ESM 的解析约定。配置数据源ReflectMetadataProvider 与 logger 对接v7 数据源配置同样在src/config/config.default.ts中完成。仓库测试夹具 packages/mikro7/test/fixtures/base-fn-origin/src/config/config.default.ts 展示了完整形态import { Author, BaseEntity, Book, BookTag, Publisher } from ../entity/index.js; import { join } from path; import { SqliteDriver } from mikro-orm/sqlite; import { ReflectMetadataProvider } from mikro-orm/decorators/legacy; export default (appInfo) { return { midwayLogger: { clients: { mikroLogger: { disableFile: false, transports: { console: { autoColors: false }, file: { fileLogName: mikro.log } }, } } }, mikro: { dataSource: { default: { entities: [Author, Book, BookTag, Publisher, BaseEntity], dbName: join(appDir, test.sqlite), driver: SqliteDriver, metadataProvider: ReflectMetadataProvider, debug: true, allowGlobalContext: true, logger: mikroLogger, colors: false, } }, defaultDataSourceName: default, } } }关键配置项说明配置项作用entities实体数组或扫描路径如entity目录、**/entity/*.entity.{j,t}s通配已由框架处理勿照搬原始 MikroORM 文档driver数据库驱动类v7 沿用SqliteDriver等驱动类写法metadataProvider使用 legacy 装饰器时必须显式设置为ReflectMetadataProvider从mikro-orm/decorators/legacy导入logger: mikroLogger字符串形式指定 Midway logger 客户端名称组件会将 SQL 等日志接入该 loggercolors: false关闭 MikroORM 自带日志颜色allowGlobalContext非请求链路如src/configuration.ts内调用时开启避免 Identity Map 上下文报错defaultDataSourceName指定默认数据源名称省略注入参数时使用多数据源同样支持在dataSource下配置多个键如custom1、custom2使用注入装饰器时通过第二个参数指定数据源例如InjectRepository(Book, custom1)。业务使用仓储与实体管理器注入在业务代码中midwayjs/mikro7提供与 v6 一致的注入体验以下示例以 v7 包名替换逻辑来自官方文档// src/service/book.service.ts import { Book } from ../entity/book.entity; import { Provide } from midwayjs/core; import { InjectEntityManager, InjectRepository } from midwayjs/mikro7; import { QueryOrder } from mikro-orm/core; import { EntityManager, EntityRepository } from mikro-orm/sqlite; // 使用数据库驱动对应的类 Provide() export class BookService { InjectRepository(Book) bookRepository: EntityRepositoryBook; InjectEntityManager() em: EntityManager; async queryByRepo() { // 使用 Repository 查询 const books await this.bookRepository.findAll({ populate: [author], orderBy: { title: QueryOrder.DESC }, limit: 20, }); return books; } async createBook() { const book new Book({ title: b1, author: { name: a1, email: e1 } }); // 标记保存 Book this.em.persist(book); // 执行所有变更 await this.em.flush(); return book; } }提示自 MikroORM 5.7 起Repository上的persist、flush等接口已被弃用v6 起彻底移除建议统一通过EntityManager执行增删改仓储仅用于查询。运行时集成原理源码级midwayjs/mikro7的运行时行为由两个核心类驱动二者均可在仓库源码中直接验证。数据源管理MikroDataSourceManagerMikroDataSourceManager 继承 Midway 的DataSourceManager注册为 Singleton通过Config(mikro)读取mikro配置节在init()中以concurrent: true并发初始化所有数据源createDataSource中若logger为字符串则取对应 Midway logger 并包装为message logger.info(message)回调未指定contextName时以数据源名填充对应多库连接场景registerRequestContext默认置为false请求上下文由组件中间件统一管理最终调用MikroORM.init(config)checkConnected通过dataSource.isConnected()探测连接destroyDataSource在应用关闭时对已连接的数据源执行close()。生命周期与请求上下文MikroConfigurationMikroConfiguration 是组件配置类导出为ConfigurationInit()通过midwayDecoratorService.registerPropertyHandler注册三个注入处理器。仓储注入ENTITY_MODEL_KEY优先从请求上下文RequestContext.getEntityManager(name)取 EntityManager 再getRepository(modelKey)否则回退到数据源上的emEntityManager 注入ENTITY_MANAGER_KEY同理优先取请求上下文数据源注入DATA_SOURCE_KEY直接由dataSourceManager.getDataSource(...)返回。onReady异步获取MikroDataSourceManager对所有已注册的 Midway 应用挂载中间件通过RequestContext.create(entityManagers, next)为每个请求创建 MikroORM 请求级上下文Identity Map这正是“请求期间仓储与 EntityManager 从请求上下文解析”的实现依据。onStop调用dataSourceManager.stop()关闭全部数据源。这一设计与设计文档“v7 运行时集成”的要求一一对应并由测试夹具 packages/mikro7/test/fixtures/base-fn-origin/src/configuration.ts 验证其中同时注入了默认与命名数据源、仓储、EntityManager并在onReady中执行建表、创建实体、persist().flush()与findAll查询。测试与验证组件测试集中在 packages/mikro7/test/index.test.ts覆盖两个场景base 夹具验证实体仓储创建、EntityManager 写入与查询、数据源注入与请求上下文行为断言结果包含写入的b1multi-enitymanager 夹具验证多组件、多 EntityManager 场景下的隔离行为m1、withEntity、home三组结果断言。测试通过fork子进程 ts-node/register运行夹具覆盖包导入行为。在仓库中可运行pnpm -C packages/mikro7 test风险与注意事项设计文档明确列出以下风险使用时应特别注意ESM-only 输出纯 ESM 包对 CommonJS 项目不友好需确认测试配置与包导出元数据midwayjs/mikro7已通过type: module与仅import条件的exports落地跨版本耦合mikro与mikro7共享代码应保持最小化避免 v6/v7 耦合回灌drop-in 预期用户可能误以为midwayjs/mikro7是midwayjs/mikro的无缝替换。实际上 v7 路径必须同时调整实体导入路径改用mikro-orm/decorators/legacy、元数据提供器ReflectMetadataProvider与TypeScript 模块设置moduleResolution: nodenext | node20 | bundler并保持 Node.js 20 运行环境。综上midwayjs/mikro7以“版本显式、模块策略隔离、API 对齐”为设计主轴为 MikroORM v7 用户提供了稳定、可维护的接入路径v6 用户则继续留在midwayjs/mikro。两条路径在 site/docs/extensions/mikro.md 中已有明确区分新项目选择 v7 时按本文步骤即可完成从安装到业务注入的完整接入。赞分享后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载相关推荐Midway 接入 MikroORM v7midwayjs/mikro7 独立组件实战指南Midway 接入 MikroORM v7 midwayjs/mikro7 独立组件实战指南 midwayjs/mikro7 是 Midway 为 Mik后端微服务云原生Midway 接入 MikroORM v7midwayjs/mikro7 独立组件包的设计与实战指南Midway 接入 MikroORM v7 midwayjs/mikro7 独立组件包的设计与实战指南 本指南以仓库 变更提案 https://link.g后端微服务云原生Midway 集成 MikroORM v7midwayjs/mikro7 独立组件包安装、迁移与源码解析Midway 集成 MikroORM v7midwayjs/mikro7 独立组件包安装、迁移与源码解析 MikroORM v7 切换为 native ES后端微服务云原生上一篇OpenCode v0.4.x 团队培训要点下一篇uncss代码评审指南贡献者提交PR的检查清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考