13 NestJS 集成 TypeORM 完全指南

前言

TypeORM 是 Node.js 生态中历史最悠久的 ORM，也是 NestJS 官方文档中首推的数据库解决方案之一。它以装饰器驱动的 Entity 定义为核心，支持 Active Record 与 Data Mapper 两种模式，与 TypeScript 有着天然的契合。

相比 Prisma 的 Schema-first 理念，TypeORM 更贴近传统 ORM 思想：Entity 类既是数据库表的映射，也是业务对象。对于习惯 Java/Spring 或 C#/EF 体系的开发者来说，TypeORM 的上手成本更低。

本文使用 Data Mapper 模式（Repository 模式），这是 NestJS 中更推荐的生产方式。与 Active Record 相比，Repository 模式将数据库操作与业务逻辑分离，测试更友好，依赖关系更清晰。

本文基于 TypeORM 最新版 和 NestJS 最新版，以 MySQL 为主要示例（PostgreSQL 差异处会单独说明），从安装到生产级集成，覆盖以下内容：

• 生产级目录结构与 data-source.ts 的设计原则
• 与 ConfigService 整合，异步读取配置，避免硬编码
• 自定义日志系统，与 NestJS Logger 对接
• Entity 定义：公共基类、软删除、索引、钩子
• 数据库迁移（CLI 工作流）
• Repository 模式 CRUD 与 QueryBuilder 进阶
• 关联关系（OneToOne / OneToMany / ManyToMany）
• 事务管理（DataSource.transaction / QueryRunner）
• 生产级全局异常过滤器

本文假设你已有一个使用 @nestjs/config 的 NestJS 项目。ConfigModule 的配置请参考本系列第 01 篇。