后端【免费下载链接】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 官方部署文档为主线系统梳理 TypeScript ORM 应用在生产环境部署时因实体元数据发现机制基于ts-morph读取 TS 源文件而遇到的典型问题及其解决方案。文章覆盖四种主路径——部署预构建元数据缓存、为实体显式补齐类型/关联属性、随编译产物一并部署实体源码以及使用 Webpack 或 esbuild 将实体与依赖打成单一 bundle——并结合仓库源码讲解底层原理与配置细节。读完本文你将能根据实际部署形态纯编译产物、Docker 镜像、边缘运行时、单文件 bundle选择最合适的方案并正确配置 metadata cache、discovery.disableDynamicFileAccess、Webpack 的 externals/IgnorePlugin 与 esbuild 的 external 列表。部署问题的根源发现过程依赖 TS 源码MikroORM 的实体发现机制在底层使用ts-morph读取所有实体的 TypeScript 源文件以检测每个属性的类型number、string、enum、关联目标等并将检测到的类型值保存为字符串供运行时校验使用。这意味着在开发阶段只要写出类型标注即可获得完整的运行时校验能力——但代价是运行时需要能访问到实体的 TS 源文件。当应用部署时只带上编译后的产物如dist/目录不带任何.ts源码时发现过程大概率会失败。从源码看发现过程由 MetadataDiscovery 承担其discover()方法负责定位实体、读取元数据、填充默认值并完成校验整个过程依赖 MetadataProvider 提供的元数据来源默认的TsMorphMetadataProvider需要真实读取.ts文件而ReflectMetadataProvider则依赖装饰器反射详见 Configuration.ts 中metadataProvider选项的注释。围绕这一根源官方文档给出了四类可行的部署策略下文逐一展开。方案一部署预构建的元数据缓存Deploy pre-built cache生成并复用缓存文件默认情况下元数据发现的结果会被缓存在temp文件夹中缓存文件以实体源文件命名例如Author.ts实体的缓存保存在temp/Author.ts.json。运行编译后的代码时JS 实体被纳入发现因此你需要先在本地运行一次编译后的代码以生成temp/Author.js.json然后将该文件随应用一起部署——这正是该方案在早期版本v5 及以前的标准做法。v6 进阶一条命令生成单一缓存 bundle自 v6 起MikroORM 支持通过 CLI 将生产缓存一次性生成到单个 JSON 文件npx mikro-orm cache:generate --combined该命令会在当前目录生成./temp/metadata.json文件生产配置中配合GeneratedCacheAdapter使用即可import { GeneratedCacheAdapter, MikroORM } from mikro-orm/core; await MikroORM.init({ metadataCache: { enabled: true, adapter: GeneratedCacheAdapter, options: { data: require(./temp/metadata.json) }, }, // ... });还可以通过--combined参数指定输出路径相对于当前目录下的temp文件夹npx mikro-orm cache:generate --combined../cache/mikro-orm-metadata.json上面的命令会把缓存保存到./cache/mikro-orm-metadata.json注意文档语义路径是相对temp文件夹的。此方式的价值在于可以把mikro-orm/reflection保留为 devDependency构建时用 CLI 生成缓存 bundle生产构建只依赖该 JSON 文件。GeneratedCacheAdapter的实现位于 GeneratedCacheAdapter.ts它把 CLI 产出的静态数据装入Map查询时按实体名自动去除.js/.ts后缀直接命中完全不触碰文件系统CLI 侧的命令实现见 GenerateCacheCommand.ts其中--combined别名-c同时支持--ts参数生成面向.ts文件的开发缓存。提示缓存 bundle 支持静态导入import metadata from ./temp/metadata.json在使用打包器时尤其方便可避免require造成打包器无法静态分析的问题。方案二为所有属性显式补齐类型或实体引用Fill type or entity attributes everywhere发现过程本质上是“嗅探”TS 类型并把值保存为字符串供后续校验使用。如果你手动提供这些值就能完全跳过类型嗅探过程Entity() export class Book { PrimaryKey({ type: number }) id!: number; Property({ type: string }) title!: string; Enum(() BookStatus) status?: BookStatus; ManyToOne(() Author) // 或 ManyToOne({ type: Author }) 或 ManyToOne({ entity: () Author }) author1!: Author; // 或 ManyToOne({ type: Author }) author2!: Author; // 或 ManyToOne({ entity: () Author }) author3!: Author; } export enum BookStatus { SOLD_OUT sold, ACTIVE active, UPCOMING upcoming, }要点标量属性用type显式声明类型字符串如number、string即可不依赖源码嗅探关联属性可以用() Author回调、{ type: Author }字符串或{ entity: () Author }三种写法之一数值枚举numeric enum无需显式补type。从仓库测试实体可以看到这套写法的实际形态例如 AuthorWp.ts 中每个属性都显式带上了type声明PrimaryKey({ type: number })、Property({ type: string })等这正是为 Webpack 打包场景准备的实体范例。方案三直接部署实体源码文件Deploy your entity source files多数场景下多部署几个文件并无大碍因此最简单的做法是把 TS 实体源文件放在编译产物旁边像开发阶段一样一起部署。这样发现过程依然能读到源码无需任何额外配置。该方案适合不介意部署包体积、追求零改动的团队。方案四使用 Webpack 将实体与依赖打成单一 bundleWebpack 可以把每个实体及其依赖打包成一个单一文件该文件包含所有所需模块且无外部依赖适合单文件交付场景。打包前的项目准备Webpack 要求所有被引用的文件在代码中“硬编码”动态拼接路径的导入无法工作Webpack 不知道要包含哪个文件会直接报错let dependencyNameInVariable dependency; const dependency import(dependencyNameInVariable);同时由于 Webpack 产物是静态文件 bundle不应在运行时扫描目录来发现实体或元数据。因此必须满足三个条件在初始化函数中用entities选项显式列出实体文件夹/文件级发现不支持为所有属性补齐type或entity属性见方案二关闭元数据缓存会略微降低启动速度。注意使用ReflectMetadataProvider时缓存默认就是关闭的因此无需手动处理。禁用动态文件访问首先应通过discovery.disableDynamicFileAccess开关关闭发现过程中的动态文件访问该开关会一次性产生三个效果将 metadata provider 切换为ReflectMetadataProvider关闭元数据缓存禁止在entities/entitiesTs中使用路径形式只能传实体类引用。在 Configuration.ts 的discovery默认配置中可以看到该选项与warnWhenNoEntities、checkDuplicateTableNames等同属于发现阶段的可调项仓库文档 configuration.md 的“Entity Discovery”一节对disableDynamicFileAccess有更完整的语义说明。方式 A手动定义实体列表import { Author, Book, BookTag, Publisher, Test } from ../entities; await MikroORM.init({ ... entities: [Author, Book, BookTag, Publisher, Test], discovery: { disableDynamicFileAccess: true }, ... });方式 B动态加载依赖利用 Webpack 的 dynamic imports利用 Webpack 的 dynamic imports 特性只要路径的一部分是已知的就能批量导入依赖。下面的示例使用require.context该“函数”只在 Webpack 构建期间可用因此文档同时提供了备选方案当环境变量WEBPACK未设置时例如开发期用ts-node/tsx/swc运行时回退到fs.readdirSync 动态import()await MikroORM.init({ // ... entities: await getEntities(), discovery: { disableDynamicFileAccess: true }, // ... }); async function getEntities(): Promiseany[] { if (process.env.WEBPACK) { const modules require.context(../entities, true, /\.ts$/); return modules .keys() .map(r modules(r)) .flatMap(mod Object.keys(mod).map(className mod[className])); } const promises fs.readdirSync(../entities).map(file import(../entities/${file})); const modules await Promise.all(promises); return modules.flatMap(mod Object.keys(mod).map(className mod[className])); }上面会从../entities目录导入所有扩展名为.ts的文件。flatMap是 ECMAScript 2019 的方法需要 Node.js 11 及以上版本。Webpack 配置Webpack 可以无配置文件运行但打包 MikroORM 与 Node.js bundle 需要额外配置。官方推荐的webpack.config.js完整示例如下其中关键点已加注释const path require(path); const { EnvironmentPlugin, IgnorePlugin } require(webpack); const TerserPlugin require(terser-webpack-plugin); // 将 devDependencies 标记为 externals避免被打进 bundle const { devDependencies } require(./package.json); const externals {}; for (const devDependency of Object.keys(devDependencies)) { externals[devDependency] commonjs ${devDependency}; } // MikroORM 打包时可忽略的可选模块后面会动态检查并告诉 webpack 忽略未安装的 const optionalModules new Set([ ...Object.keys(require(knex/package.json).browser), ...Object.keys(require(mikro-orm/core/package.json).peerDependencies), ...Object.keys(require(mikro-orm/core/package.json).devDependencies || {}) ]); module.exports { entry: path.resolve(app, server.ts), // 开发期可切换 development 模式便于观察 bundle生产部署务必使用 production // mode: development, mode: production, optimization: { minimizer: [ new TerserPlugin({ terserOptions: { // 只压缩、不改实体类名关闭 mangling变量名混淆 mangle: false, // 压缩时也保留类名与函数名防止 Terser 自行改名 compress: { keep_classnames: true, keep_fnames: true, }, } }) ] }, target: node, module: { rules: [ // 处理 TypeScript 文件 { test: /\.ts$/, exclude: /node_modules/, loader: ts-loader, }, // 原生模块也可以被打包 { test: /\.node$/, use: node-loader, }, // 部分 MikroORM 依赖使用 mjs 文件 { test: /\.mjs$/, include: /node_modules/, type: javascript/auto, }, ], }, // 上面动态计算得到 externals, resolve: { extensions: [.ts, .js] }, plugins: [ // 忽略未安装的可选模块例如未使用的数据库驱动 new EnvironmentPlugin({ WEBPACK: true }), new IgnorePlugin({ checkResource: resource { const baseResource resource.split(/, resource[0] ? 2 : 1).join(/); if (optionalModules.has(baseResource)) { try { require.resolve(resource); return false; } catch { return true; } } return false; }, }), ], output: { filename: server.js, libraryTarget: commonjs, path: path.resolve(__dirname, .., output), }, };配置要点解读externals把所有 devDependencies 排除在 bundle 之外commonjs xxx表示运行时以require方式引用避免把打包工具链自身卷进去optionalModules从knex的 browser 字段、mikro-orm/core的 peerDependencies 与 devDependencies 汇总出一份“可选模块”清单配合IgnorePlugin.checkResource动态判断能require.resolve到的保留否则忽略——这样未安装的数据库驱动不会进入 bundleEnvironmentPlugin({ WEBPACK: true })注入WEBPACK环境变量让上面getEntities()中的require.context分支在打包时生效TerserPlugin 配置mangle: falsekeep_classnames/keep_fnames: true确保实体类名不被压缩器改写实体类名会被用于元数据与序列化必须保持稳定target: node与libraryTarget: commonjs面向 Node.js 运行时输出 CommonJS 模块。运行 Webpack在项目根目录执行webpack未全局安装时用npx webpack。构建过程大概率会输出一些警告其中关于 MikroORM 的报错可以忽略只要正确打包那些代码路径根本不会被执行。仓库中也提供了 Webpack 场景的实体测试样例见 tests/entities-webpack如 AuthorWp.ts、BookWp.ts以及对应的 Webpack.test.ts可作为配置正确性的参考。方案五使用 esbuild 将实体与依赖打成单一 bundleesbuild同样可以把 MikroORM 实体与依赖打包成包含所有必需模块的单一文件。由于打包机制不同要让 esbuild 正常工作需要解决两个特定问题。为 Knex 提供 shimRequired shim for Knex with esbuildKnex 与 esbuild 存在已知的不兼容Knex 试图用动态 import 处理各种数据库方言MySQL、MongoDB、Oracle 等而 esbuild 不支持动态 import 功能。解决方式是定义一个 shim 模块在运行时拦截 Knex 的客户端解析并自行处理从而绕开动态 import 代码。定义一个knex.d.ts文件declare module knex/lib/dialects/postgres { import { Knex } from esbuild-support/knex; const client: Knex.Client; export client; }注意该 shim 中的esbuild-support/knex路径是官方文档示例写法实际项目中应以你的工程里正确的模块路径为准。从 esbuild 中排除无关依赖默认情况下 esbuild 会把 MikroORM 的所有包都打进来包括全部数据库方言及其驱动依赖。大多数应用只连一种数据库这会造成体积膨胀因此应通过 esbuild 的external配置排除不必要的依赖。例如使用postgresql平台时可以这样排除external: [ mikro-orm/better-sqlite, mikro-orm/migrations, mikro-orm/entity-generator, mikro-orm/mariadb, mikro-orm/mongodb, mikro-orm/mysql, mikro-orm/seeder, mikro-orm/sqlite, vscode/sqlite3, sqlite3, better-sqlite3, mysql, mysql2, oracledb, pg-native, pg-query-stream, tedious, ]当前仓库的驱动包布局packages 目录下的mariadb、mongodb、mssql、mysql、oracledb、pglite、postgresql、sqlite、libsql、sql-js等与此列表一一对应——如果你使用其他平台按同样的思路排除其余方言即可。方案对比与选型建议方案适用场景优点注意事项预构建元数据缓存只部署编译产物、希望保留默认发现流程无需改动实体代码v6 单文件 bundle 便于部署需在本地运行一次编译产物生成缓存实体变更后需重新生成显式补齐类型/关联任何场景的兜底手段Webpack/esbuild 打包的前置条件彻底摆脱对源码嗅探的依赖实体属性多时代码冗余需要人工维护类型字符串部署实体源码对部署体积不敏感的常规服务零配置、与开发环境行为一致部署包中需要包含.ts文件Webpack 打包单文件交付、无外部依赖场景输出单一 bundle可整体分发需显式列出实体、补全类型、关缓存并维护较复杂的 webpack 配置esbuild 打包追求构建速度的单文件交付场景构建快、体积可控需为 Knex 提供 shim并配置 external 排除未用方言选择建议常规 Node.js 服务若只部署编译产物优先采用v6 的cache:generate --combinedGeneratedCacheAdapter方案一需要单文件 bundle如 FaaS、边缘部署或精简镜像时在Webpack方案四与 esbuild方案五之间按团队工具链偏好选择两者都要求先落实方案二的类型补全如果部署环境允许携带源码且不在乎体积方案三最省事。相关资源部署指南当前版本docs/docs/deployment.md含 v6 起cache:generate --combined与GeneratedCacheAdapter用法本文基于的 v5.9 版本见 docs/versioned_docs/version-5.9/deployment.md元数据缓存适配器实现packages/core/src/cache/GeneratedCacheAdapter.tsCLI 缓存生成命令packages/cli/src/commands/GenerateCacheCommand.ts实体发现过程packages/core/src/metadata/MetadataDiscovery.ts配置项定义metadataProvider、discovery、metadataCachepackages/core/src/utils/Configuration.tsWebpack 场景测试实体tests/entities-webpack/AuthorWp.ts 与 tests/Webpack.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点击查看免费下载相关推荐MikroORM 生产部署指南从元数据缓存、预编译函数到 Webpack/esbuild 打包的完整方案MikroORM 生产部署指南从元数据缓存、预编译函数到 Webpack/esbuild 打包的完整方案 MikroORM 的实体发现discovery机后端MikroORM 生产部署实战指南元数据缓存打包、预编译函数与 Webpack/esbuild 打包策略MikroORM 生产部署实战指南元数据缓存打包、预编译函数与 Webpack/esbuild 打包策略 本篇指南基于 MikroORM 官方文档 deplo后端在 Webpack、Rollup、ESBuild 中正确打包 G6官方打包指南与仓库实践在 Webpack、Rollup、ESBuild 中正确打包 G6官方打包指南与仓库实践 本篇指南基于 G6 官方文档 Bundle Project http数据可视化前端图表库上一篇深入了解github-hosts从原理到实践全方位提升GitHub访问速度下一篇theZoo数据库索引优化v0.60版本搜索功能底层原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
