NestJS 集成 TypeORM 或 Prisma 实现数据库持久化操作

在构建基于 NestJS 的企业级后端应用时，数据持久化层是决定应用架构质量、类型安全与维护成本的核心基础设施。NestJS 本身对底层持久化框架保持中立，但社区与生产实践中最为主流的两种方案分别是 TypeORM 与 Prisma。TypeORM 采用类装饰器和仓储模式，与 NestJS 自身的面向对象体系和依赖注入风格天然契合；而 Prisma 采用独立 Schema 描述与客户端自动生成模式，以端到端类型安全和流畅的链式查询著称。本文将围绕这两种主流持久化方案，深入拆解其架构差异、在 NestJS 中的完整配置与 CRUD 实现步骤，并针对数据迁移与高可用运维给出明确的落地建议。

一、架构选型：TypeORM 与 Prisma 的本质差异

选择持久化方案的前提是理清两者的设计哲学与抽象层级差异：

• TypeORM（Code-First 实体驱动）：采用典型的 Active Record 与 Data Mapper 设计模式。开发者使用 TypeScript 的 Class 配合 @Entity()、@Column() 等装饰器声明数据模型。实体既是 TypeScript 类型，也是映射到数据库物理表的蓝图。在 NestJS 中，TypeORM 通过 @nestjs/typeorm 包装为标准的模块与 Provider，天然支持基于类的细粒度注入（如 @InjectRepository()）。
• Prisma（Schema-First 生成驱动）：摒弃了传统的对象关系映射装饰器体系，使用独立的声明式建模语言（schema.prisma）。开发者定义数据表结构后，通过 Prisma CLI 自动生成专门适配当前 Schema 的强类型客户端库（@prisma/client）。在 NestJS 中，Prisma 通常封装为一个单例 Service（继承自 PrismaClient），通过全局依赖注入供各业务 Service 直接调用。

为了帮助团队在项目初期做出客观决策，两者在关键工程维度的对比与判定依据如下：

二、TypeORM 在 NestJS 中的完整落地实践

以 PostgreSQL 为例（MySQL 仅需替换驱动包为 mysql2），下面演示在 NestJS 中集成 TypeORM 的标准配置与业务编写全流程。

1. 依赖安装与根模块异步配置

首先在项目根目录安装必要依赖：

npm install @nestjs/typeorm typeorm pg @nestjs/config

在生产级项目中，数据库连接参数必须从环境变量读取。我们采用 TypeOrmModule.forRootAsync 搭配 ConfigService 进行异步初始化，确保配置解耦且具备环境适应性：

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { UserModule } from './user/user.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        host: config.get<string>('DB_HOST', 'localhost'),
        port: config.get<number>('DB_PORT', 5432),
        username: config.get<string>('DB_USERNAME', 'postgres'),
        password: config.get<string>('DB_PASSWORD', 'secret'),
        database: config.get<string>('DB_DATABASE', 'app_db'),
        autoLoadEntities: true,
        synchronize: false, // 警告：生产环境切勿设置为 true
      }),
    }),
    UserModule,
  ],
})
export class AppModule {}

2. 声明 Entity 数据实体

定义用户实体 User，使用装饰器显式指定字段类型、默认值以及索引：

// src/user/entities/user.entity.ts
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ unique: true, length: 120 })
  email: string;

  @Column({ length: 60, nullable: true })
  name: string;

  @Column({ default: true })
  isActive: boolean;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

3. 业务模块注册与仓储注入调用

在 UserModule 中通过 TypeOrmModule.forFeature 注册该实体，随后即可在 UserService 中通过 @InjectRepository 获取专属的 Repository<User> 实例：

// src/user/user.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './entities/user.entity';
import { UserService } from './user.service';
import { UserController } from './user.controller';

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UserController],
  providers: [UserService],
  exports: [UserService],
})
export class UserModule {}

// src/user/user.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './entities/user.entity';

@Injectable()
export class UserService {
  constructor(
    @InjectRepository(User)
    private readonly userRepository: Repository<User>,
  ) {}

  async create(data: { email: string; name?: string }): Promise<User> {
    const user = this.userRepository.create(data);
    return await this.userRepository.save(user);
  }

  async findAll(): Promise<User[]> {
    return await this.userRepository.find({
      where: { isActive: true },
      order: { createdAt: 'DESC' },
    });
  }

  async findOne(id: number): Promise<User> {
    const user = await this.userRepository.findOneBy({ id });
    if (!user) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    return user;
  }

  async update(id: number, data: Partial<User>): Promise<User> {
    const user = await this.findOne(id);
    Object.assign(user, data);
    return await this.userRepository.save(user);
  }

  async remove(id: number): Promise<void> {
    const result = await this.userRepository.delete(id);
    if (result.affected === 0) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
  }
}

三、Prisma 在 NestJS 中的完整落地实践

Prisma 提供了与 TypeORM 完全不同的开发体验。其核心是将数据库结构抽象为独立的 schema.prisma，并通过 CLI 工具生成对应的纯 TypeScript 客户端。

1. 初始化与依赖安装

安装 Prisma CLI 开发依赖与运行时客户端库：

npm install prisma --save-dev
npm install @prisma/client
npx prisma init

执行 npx prisma init 后，项目根目录下会自动生成 prisma/schema.prisma 文件以及配置数据库连接串的 .env 文件。

2. 编写 schema.prisma 建模规范

在 prisma/schema.prisma 中定义数据源与数据模型：

// prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  isActive  Boolean  @default(true)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  posts     Post[]

  @@map("users")
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  Int
  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
  createdAt DateTime @default(now())

  @@map("posts")
}

编写完成后，在终端运行迁移与代码生成命令：

# 自动执行迁移并生成 node_modules/@prisma/client
npx prisma migrate dev --name init_users_and_posts

3. 封装具备 NestJS 生命周期的 PrismaService

为了让 NestJS 的 IoC 容器有效管理数据库连接，避免热重载或进程退出时出现连接泄漏，我们需要创建继承自 PrismaClient 的服务类，并在 OnModuleInit 钩子中建立连接：

// src/prisma/prisma.service.ts
import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    await this.$connect();
  }

  async onModuleDestroy() {
    await this.$disconnect();
  }
}

将 PrismaService 封装为全局模块，使得所有业务模块均可直接使用，而无需重复导入：

// src/prisma/prisma.module.ts
import { Global, Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Global()
@Module({
  providers: [PrismaService],
  exports: [PrismaService],
})
export class PrismaModule {}

4. 业务 Service 中的强类型数据访问

在 UserService 中直接注入 PrismaService，即可享受完全强类型的查询体验：

// src/user/user.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { User, Prisma } from '@prisma/client';

@Injectable()
export class UserService {
  constructor(private readonly prisma: PrismaService) {}

  async create(data: Prisma.UserCreateInput): Promise<User> {
    return await this.prisma.user.create({
      data,
    });
  }

  async findAll(): Promise<User[]> {
    return await this.prisma.user.findMany({
      where: { isActive: true },
      orderBy: { createdAt: 'desc' },
      include: {
        posts: {
          select: { id: true, title: true },
        },
      },
    });
  }

  async findOne(id: number): Promise<User> {
    const user = await this.prisma.user.findUnique({
      where: { id },
    });
    if (!user) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    return user;
  }

  async update(id: number, data: Prisma.UserUpdateInput): Promise<User> {
    try {
      return await this.prisma.user.update({
        where: { id },
        data,
      });
    } catch (error) {
      throw new NotFoundException(`User with ID ${id} update failed`);
    }
  }

  async remove(id: number): Promise<User> {
    try {
      return await this.prisma.user.delete({
        where: { id },
      });
    } catch (error) {
      throw new NotFoundException(`User with ID ${id} delete failed`);
    }
  }
}

四、数据库迁移与事务处理对比

在实际生产环境中，业务逻辑的编写只占开发周期的一部分，数据结构的平滑演进与多步操作的原子性保障同样关键。

1. 数据迁移（Migration）工作流差异

• TypeORM CLI 迁移：TypeORM 通过比对实体代码与数据库当前表结构的差异来生成迁移脚本。

  # 自动对比生成迁移脚本
  npx typeorm migration:generate src/migrations/AddUserRole -d src/data-source.ts
  
  # 执行迁移
  npx typeorm migration:run -d src/data-source.ts

  TypeORM 迁移脚本完全为原生 TypeScript 代码，包含 up() 与 down() 方法，允许开发者在迁移过程中注入复杂的逻辑或数据清洗脚本。
• Prisma Migrate：Prisma 采用了声明式 Diff 机制。在开发环境中，运行 npx prisma migrate dev 会自动计算变更、生成 SQL 脚本并即时应用；在生产环境流水线中，通过 npx prisma migrate deploy 仅执行待应用的 SQL 文件，绝不产生交互提示或破坏已有数据。

2. 事务（Transaction）处理机制对比

当多个写操作必须具备原子性时，两者的实现语法如下：

• TypeORM 事务：可以通过注入 DataSource 开启交互式运行器 QueryRunner，或者直接使用 dataSource.transaction() 包装业务：

  await this.dataSource.transaction(async (manager) => {
    const user = manager.create(User, { email: 'test@example.com' });
    await manager.save(user);
    await manager.save(Log, { action: 'USER_CREATED', userId: user.id });
  });

• Prisma 事务：原生支持数组并行事务与交互式闭包事务，语法直观且自动处理回滚：

  await this.prisma.$transaction(async (tx) => {
    const user = await tx.user.create({
      data: { email: 'test@example.com' },
    });
    await tx.log.create({
      data: { action: 'USER_CREATED', userId: user.id },
    });
  });

五、生产环境高危问题与避坑指南