后端【免费下载链接】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点击查看免费下载本文档对应仓库 docs/versioned_docs/version-7.2/usage-with-nextjs.md系统讲解在 Next.js 的 App Router 场景下集成 MikroORM 的完整方案。由于 Next.js 底层使用 Turbopack/Webpack 这类打包器运行时无法访问文件系统、生产构建会压缩类名因此需要一套与常规 Node.js 服务完全不同的实体定义与配置策略。读完本文你将掌握defineEntity声明式实体定义、显式tableName、显式实体/迁移列表、单例 ORM RequestContext请求隔离等一整套可落地的集成方法。Next.js 环境下 MikroORM 面临的三大核心挑战Next.js 使用 bundlerTurbopack/Webpack对代码进行打包这给传统 ORM 带来了三类结构性约束生产构建中的类名压缩Class name manglingterser等压缩器会把User类重命名为a、t之类的短名导致依赖反射机制推断出来的表名完全错乱运行时无文件系统访问实体发现entity discovery依赖在运行时扫描文件系统中的实体文件而打包器环境中实体已经被打包进 bundlefs扫描在浏览器端/边缘运行时不可用代码分割影响迁移加载迁移文件通常通过 glob 模式按路径读取打包后路径解析失效迁移模块的加载方式必须显式化。这些挑战的根源在于MikroORM 在常规环境下依赖运行时反射 文件系统扫描来收集元数据而 Next.js 打包器切断了这两条通路。因此集成的总体思路是——把一切可以静态化、显式化的配置全部写死在代码里。实体定义优先使用defineEntity在 Next.js 中使用装饰器decorators定义实体是可行的但需要额外配置元数据提供方如mikro-orm/reflection包或其他 metadata provider。而defineEntity方式完全不需要反射和文件扫描是集成 Next.js 时阻力最小的路径。defineEntity是 MikroORM 推荐的、不依赖装饰器的编程式实体定义方式它构建在EntitySchema之上利用 TypeScript 类型推断自动生成实体类型。其核心实现在 packages/core/src/entity/defineEntity.tsdefineEntity接收一个元数据对象将properties中的属性构建器property builder逐一解析为EntitySchema属性最终返回一个携带完整类型信息的EntitySchema实例短别名p即defineEntity.properties的导出别名见 packages/core/src/entity/defineEntity.ts对应源码中的propertyBuilders每个属性构建器是一个链式 API最终会按需惰性求值lazy evaluation生成属性选项见 defineEntity 实现因此支持用函数返回构建器来处理循环引用。基础实体Base Entity将所有实体的公共字段抽到抽象基类中用defineEntity描述其属性映射// lib/base.entity.ts import { defineEntity, p } from mikro-orm/sqlite; export abstract class BaseEntity { id!: number; createdAt? new Date(); updatedAt? new Date(); } export const BaseSchema defineEntity({ name: BaseEntity, class: BaseEntity, properties: { id: p.integer().primary(), createdAt: p.datetime({ defaultRaw: current_timestamp }), updatedAt: p.datetime({ defaultRaw: current_timestamp, onUpdate: () new Date() }), }, });这里使用的属性构建器对应源码中PropertyChain提供的方法packages/core/src/entity/defineEntity.ts其中p.integer().primary()整数类型 主键标记p.datetime({ defaultRaw: current_timestamp })数据库层默认时间戳defaultRaw直接写入 DDLonUpdate: () new Date()应用层在更新时自动刷新该字段类似ON UPDATE语义。defineEntity还支持onCreate替代defaultRaw做应用层默认值。若你想让默认值在new构造时无EntityManager上下文就生效可以使用extends 基类属性初始化器的写法详见仓库中的 define-entity.md 文档。业务实体Example Entity// lib/user.entity.ts import { defineEntity, p } from mikro-orm/sqlite; import { BaseEntity, BaseProperties } from ./base.entity; import { UserRepository } from ./user.repository; export class User extends BaseEntity { fullName!: string; email!: string; password!: string; bio?: string; constructor(fullName: string, email: string, password: string) { super(); this.fullName fullName; this.email email; this.password password; } async hashPassword() { const argon2 await import(argon2); this.password await argon2.hash(this.password); } } export const UserSchema defineEntity({ name: User, class: User, tableName: user, // REQUIRED: explicit table name repository: () UserRepository, extends: BaseEntity, // inherits id, createdAt, updatedAt constructorParams: [fullName, email, password], properties: { fullName: p.string(), email: p.string({ unique: true }), password: p.string({ hidden: true, lazy: true }), bio: p.text().nullable(), }, hooks: { beforeCreate: [hashPassword], beforeUpdate: [hashPassword], }, });关键点解读repository: () UserRepository为该实体绑定自定义仓储类extends: BaseEntity继承基类的id、createdAt、updatedAt映射与 defineEntity 文档中的extends语义一致见 define-entity.mdconstructorParams声明构造器参数顺序供 ORM 在需要构造实例时正确传参password: p.string({ hidden: true, lazy: true })hidden让该字段在序列化时被排除lazy使其默认不加载、按需读取——适合密码等敏感字段hooks注册生命周期钩子beforeCreate/beforeUpdate指向类上的hashPassword方法实现密码自动哈希。注意这里使用了动态import(argon2)让重型依赖按需加载减少 Next.js 服务端 bundle 体积关于钩子的更多注册方式addHook等可参考 define-entity.md 的 Hooks 示例。显式指定tableName生产构建的必修课生产构建会压缩类名。如果不显式指定表名实体在压缩后可能得到a或t这类表名而不是预期的user、article——因为 MikroORM 默认的表名推导基于类名如User→user而压缩后的类名已不可信。因此实体定义中必须始终设置tableNameexport const UserSchema defineEntity({ name: User, tableName: user, // Always specify this! // ... });如果采用装饰器方式则对应写法为Entity({ tableName: user }) export class User {}放弃文件夹扫描显式导入并列出所有实体基于文件夹的实体发现Folder-based entity discovery在打包器环境下无法工作。以下写法在 Next.js 中必然失败// This wont work with Next.js! export default defineConfig({ entities: [./lib/**/*.entity.ts], });原因在于该配置依赖运行时对文件系统执行 glob 匹配来发现并加载实体模块而打包器环境既无文件系统访问、也无法在运行时解析通配路径。正确的做法是在配置文件中显式 import 并列出每一个实体// mikro-orm.config.ts import { defineConfig } from mikro-orm/sqlite; import { UserSchema } from ./lib/user.entity; import { ArticleSchema } from ./lib/article.entity; import { TagSchema } from ./lib/tag.entity; import { CommentSchema } from ./lib/comment.entity; export default defineConfig({ dbName: sqlite.db, entities: [UserSchema, ArticleSchema, TagSchema, CommentSchema], });显式列出实体同时也能保证打包器能静态分析到这些模块并正确纳入 bundle——这本身就是对代码分割机制的正向配合。迁移Migrations需要显式配置迁移功能在打包器环境下有两个典型问题glob 模式失效不能使用path或pathTs选项按目录扫描迁移文件。从源码看pathTs/path是迁移生成与定位的核心路径选项见 packages/migrations/src/MigrationGenerator.ts 与 packages/migrations/src/Migrator.ts它们都依赖运行时对文件系统路径的解析扩展不会被自动加载Migrator 扩展默认不会自动注册。显式配置迁移// mikro-orm.config.ts import { defineConfig } from mikro-orm/sqlite; import { Migrator } from mikro-orm/migrations; import { Migration20251221173216 } from /migrations/Migration20251221173216; export default defineConfig({ dbName: sqlite.db, entities: [/* ... */], // Explicitly register the Migrator extension extensions: [Migrator], // List migrations explicitly instead of using glob patterns migrations: { migrationsList: [Migration20251221173216], }, });新增迁移时把它追加进migrationsList数组即可import { Migration20251221173216 } from /migrations/Migration20251221173216; import { Migration20251225120000 } from /migrations/Migration20251225120000; migrations: { migrationsList: [ Migration20251221173216, Migration20251225120000, ], },为什么必须显式注册扩展MikroORM 在常规环境下会自动加载可选扩展。其机制位于 packages/core/src/MikroORM.ts 的loadOptionalDependencies函数它通过import.meta.resolve(pkg)动态解析并importmikro-orm/migrations等包若模块存在则把Migrator推入extensions数组。这种探测式动态导入依赖 Node 运行时的模块解析能力在打包器静态分析阶段无法可靠执行——所以 Next.js 下必须把Migrator显式写进extensions数组保证扩展模块被静态包含进 bundle。数据库连接管理单例 请求级上下文隔离Next.js 的 Server Components / Route Handlers 会在多个请求间复用模块实例因此不能每个请求都MikroORM.init()一次。正确做法是全局单例 ORM 每个请求用RequestContext隔离 EntityManager。// lib/db.ts import { MikroORM, RequestContext } from mikro-orm/sqlite; import config from ../mikro-orm.config; export interface Services { orm: MikroORM; em: EntityManager; } let cache: Services; export async function initORM(options?: PartialOptions): PromiseServices { if (cache) { return cache; } const orm await MikroORM.init({ ...config, ...options, }); // Run pending migrations on startup await orm.migrator.up(); return cache { orm, em: orm.em }; } export async function withRequestContextT( callback: () PromiseT, ): PromiseT { const { orm } await initORM(); return RequestContext.create(orm.em, callback); }要点说明单例缓存initORM()首次调用时初始化之后直接返回缓存避免重复建立连接池、重复执行迁移启动迁移await orm.migrator.up()在首次初始化时自动执行待运行迁移这要求Migrator已按上文显式注册请求隔离withRequestContext通过RequestContext.create(orm.em, callback)为每个请求创建一个独立的 EntityManager fork。RequestContext的底层实现基于AsyncLocalStorage见 packages/core/src/utils/RequestContext.tsRequestContext.create()内部调用storage.run(ctx, next)把携带默认 EntityManager fork的上下文注入异步调用链RequestContext.getEntityManager()则从当前存储中取出请求对应的 EMpackages/core/src/utils/RequestContext.ts。这样在同一个请求的任意异步深度中em都能拿到同一个工作单元Unit of Work既避免跨请求状态串扰又能享受身份映射Identity Map与事务一致性。在 Server Components / Route Handlers 中使用// app/users/page.tsx import { initORM, withRequestContext } from /lib/db; import { User } from /lib/user.entity; export default async function UsersPage() { return withRequestContext(async () { const { em } await initORM(); const users await em.findAll(User); return ( ul {users.map(user ( li key{user.id}{user.fullName}/li ))} /ul ); }); }完整配置示例汇总以上所有要点得到一份可直接落地的mikro-orm.config.ts// mikro-orm.config.ts import { defineConfig } from mikro-orm/sqlite; import { Migrator } from mikro-orm/migrations; import { UserSchema, Social } from ./lib/user.entity; import { ArticleSchema } from ./lib/article.entity; import { TagSchema } from ./lib/tag.entity; import { CommentSchema } from ./lib/comment.entity; import { Migration20251221173216 } from /migrations/Migration20251221173216; export default defineConfig({ dbName: sqlite.db, debug: process.env.NODE_ENV ! production, // Explicit entity list - no glob patterns entities: [ UserSchema, ArticleSchema, TagSchema, CommentSchema, Social, // Dont forget embeddables ], // Explicitly register extensions extensions: [Migrator], // Explicit migration list - no glob patterns migrations: { migrationsList: [Migration20251221173216], }, });补充说明dbName: sqlite.dbSQLite 单文件数据库最适合 Next.js 本地开发生产环境可换用 PostgreSQL/MySQL 等驱动mikro-orm/postgresql等包同样遵循上述配置原则debug: process.env.NODE_ENV ! production非生产环境打印 SQL 日志便于开发调试别忘了 embeddablesSocial这类嵌入对象embeddable与实体一样需要显式列出否则同样会被打包器遗漏。方案速览Summary关注点解决方案实体定义使用defineEntity装饰器需要额外元数据配置表名始终显式指定tableName实体发现显式 import 并列出所有实体迁移路径使用migrationsList 显式 import 迁移类Migrator 扩展把Migrator加入extensions数组连接管理全局单例 每请求RequestContext隔离示例项目与延伸阅读官方维护了一个完整的 Next.js MikroORM 真实示例应用仓库mikro-orm/nextjs-example-app涵盖本文所述的全部模式可作为对照参考的起点。本文的原始版本位于仓库 docs/versioned_docs/version-7.2/usage-with-nextjs.md与本文配套的进一步资料包括define-entity.mddefineEntity 完整 API 与模式defineEntity class推荐模式、extends继承、addHook类型安全钩子、属性构建器与EntitySchema底层 APIdefineEntity 源码属性链式构建器PropertyChain与类型推断实现RequestContext 源码基于AsyncLocalStorage的请求上下文实现MikroORM 初始化源码扩展自动加载机制loadOptionalDependencies及失效原因Migrator 源码迁移路径解析与pathTs选项的实现细节。总而言之MikroORM 与 Next.js 集成的核心方法论可以概括为一句话把所有依赖运行时反射与文件系统的隐式行为全部改写为显式、静态、可被打包器分析的代码——显式表名、显式实体列表、显式迁移列表、显式扩展注册、单例连接与请求级隔离这五个显式构成了 Next.js 环境下稳定运行 MikroORM 的完整拼图。赞分享后端【免费下载链接】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 与 Next.js 集成实战打包器环境下的实体定义、迁移与连接管理MikroORM 与 Next.js 集成实战打包器环境下的实体定义、迁移与连接管理 本文以 docs/docs/usage with nextjs.md h后端在 Next.js 中集成 MikroORM面向打包器环境的实体定义、迁移与连接管理实战指南在 Next.js 中集成 MikroORM面向打包器环境的实体定义、迁移与连接管理实战指南 本篇技术指南聚焦于如何在 Next.jsApp Router后端Next.js 搭配 Turbopack 使用 webpack Loader基于 with-turbopack-loaders 示例的完整实战指南Next.js 搭配 Turbopack 使用 webpack Loader基于 with turbopack loaders 示例的完整实战指南 Turbo前端后端Web框架SSR前端构建上一篇packer.nvim提交信息插件git-commit与模板管理下一篇gh_mirrors/exam/examples优化指南模型推理缓存机制设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考