NestJS与TypeORM数据库层实战指南

1. 从零开始搭建NestJS数据库层作为一名长期使用NestJS开发企业级应用的全栈工程师我深刻体会到数据库层的设计质量直接影响整个项目的可维护性。让我们从实战角度出发构建一个健壮的TypeORM数据访问层。1.1 环境配置与模块初始化现代Node.js项目离不开环境变量管理我推荐使用nestjs/config配合dotenv的方案。在项目根目录创建.env文件时有几个关键点需要注意# .env示例 DATABASE_HOSTlocalhost DATABASE_PORT3306 DATABASE_USERroot DATABASE_PASSWORDyour_secure_password DATABASE_NAMEnest_prod # 生产环境建议加_env后缀区分 SYNC_SCHEMAfalse # 生产环境必须设为false在app.module.ts中配置TypeORM时我强烈建议采用异步工厂模式。这种方式可以确保环境变量加载完成后再初始化数据库连接避免配置未加载导致的连接失败TypeOrmModule.forRootAsync({ imports: [ConfigModule], useFactory: (config: ConfigService) ({ type: mysql, host: config.get(DATABASE_HOST), port: config.get(DATABASE_PORT), username: config.get(DATABASE_USER), password: config.get(DATABASE_PASSWORD), database: config.get(DATABASE_NAME), autoLoadEntities: true, synchronize: config.get(SYNC_SCHEMA) true, // 生产环境必须关闭 logging: [error, warn], // 生产环境建议只记录error extra: { connectionLimit: 10, // 连接池大小 } }), inject: [ConfigService] })警告synchronize在生产环境必须设置为false我曾亲眼见过一个团队因为开启此选项导致生产数据被意外覆盖。正确的做法是使用迁移脚本管理数据库变更。1.2 实体设计最佳实践设计数据库实体时TypeORM提供了丰富的装饰器。以下是一个用户实体的完整示例包含了我从多个项目中总结的经验// user.entity.ts import { Entity, Column, Index, BeforeInsert, PrimaryGeneratedColumn, CreateDateColumn } from typeorm; import * as bcrypt from bcryptjs; Entity() export class User { PrimaryGeneratedColumn(uuid) // 使用UUID避免ID连续暴露业务量 id: string; Column({ length: 30 }) Index({ unique: true }) // 唯一索引提升查询性能 username: string; Column({ select: false, // 查询时默认排除密码字段 length: 100 }) password: string; CreateDateColumn({ precision: 3 }) // 精确到毫秒 createdAt: Date; BeforeInsert() async hashPassword() { this.password await bcrypt.hash(this.password, 10); // 自动加密 } }实体设计中的几个关键点使用UUID替代自增ID避免暴露业务规模密码字段必须设置select: false并实现自动加密高频查询字段添加适当索引时间戳精确到毫秒级有助于问题排查2. TypeORM高级关系映射实战2.1 多对多关系深度配置实际项目中用户-角色关系往往需要额外的关联表字段。比如需要记录角色分配时间这时就需要自定义关联实体// user-role.entity.ts Entity() export class UserRole { PrimaryGeneratedColumn() id: number; Column({ type: timestamp, default: () CURRENT_TIMESTAMP }) assignedAt: Date; ManyToOne(() User, user user.roles) user: User; ManyToOne(() Role, role role.users) role: Role; } // 在User实体中修改为 OneToMany(() UserRole, userRole userRole.user) roles: UserRole[];这种设计允许我们在关联关系中存储元数据是复杂系统常用的模式。查询时可以使用relations进行深度加载const user await userRepository.findOne({ where: { id: user-uuid }, relations: { roles: { role: true // 嵌套加载 } } });2.2 事务处理与查询优化数据库操作离不开事务管理。TypeORM提供了多种事务处理方式我最推荐的是使用QueryRunner的显式事务async function transferMoney(fromId: string, toId: string, amount: number) { const queryRunner dataSource.createQueryRunner(); try { await queryRunner.connect(); await queryRunner.startTransaction(); const fromAccount await queryRunner.manager.findOneBy(Account, { id: fromId }); const toAccount await queryRunner.manager.findOneBy(Account, { id: toId }); // 业务逻辑校验 if (fromAccount.balance amount) { throw new InsufficientBalanceError(); } // 执行更新 await queryRunner.manager.update(Account, fromId, { balance: () balance - ${amount} }); await queryRunner.manager.update(Account, toId, { balance: () balance ${amount} }); await queryRunner.commitTransaction(); } catch (err) { await queryRunner.rollbackTransaction(); throw err; } finally { await queryRunner.release(); } }对于复杂查询我建议使用QueryBuilder替代find方法处理多表关联合理使用cache选项缓存高频查询对大数据集使用分页查询skiptake3. 参数校验与数据转换的艺术3.1 深入理解ValidationPipeNestJS的管道系统是其核心优势之一。全局配置ValidationPipe时这些选项值得关注app.useGlobalPipes( new ValidationPipe({ transform: true, // 自动类型转换 forbidNonWhitelisted: true, // 禁止未定义字段 whitelist: true, // 过滤未定义字段 validationError: { target: false }, // 不暴露验证目标 transformOptions: { enableImplicitConversion: true, // 启用隐式转换 } }) );我曾遇到一个安全问题攻击者通过发送额外字段进行数据注入。开启whitelist后所有未在DTO中定义的字段都会被自动过滤有效防止了这种攻击。3.2 自定义验证装饰器除了标准的class-validator装饰器我们可以创建业务特定的验证规则。比如验证用户名是否已存在// unique-username.decorator.ts export function IsUniqueUsername() { return registerDecorator({ name: isUniqueUsername, target: object.constructor, propertyName: propertyName, options: validationOptions, validator: { async validate(value: any) { const user await getRepository(User) .createQueryBuilder() .where({ username: value }) .getOne(); return !user; } } }); } // 在DTO中使用 export class CreateUserDto { IsUniqueUsername({ message: 用户名已存在 }) username: string; }3.3 高级数据转换技巧管道不仅可以验证数据还能进行智能转换。比如自动将字符串ID转换为实体// entity-id.pipe.ts Injectable() export class EntityIdPipe implements PipeTransform { constructor(private dataSource: DataSource) {} async transform(value: string, metadata: ArgumentMetadata) { const repository this.dataSource.getRepository(metadata.metatype); const entity await repository.findOneBy({ id: value }); if (!entity) { throw new EntityNotFoundError(metadata.metatype.name, value); } return entity; } } // 在控制器中使用 Get(:id) async getById(Param(id, EntityIdPipe) user: User) { return user; }这种模式在RESTful API中特别有用可以大幅减少重复代码。4. 生产环境实战经验4.1 数据库迁移管理在团队协作中数据库变更必须通过迁移脚本管理。TypeORM提供的迁移工具可以这样使用# 生成迁移文件 typeorm migration:generate -n AddUserTable # 执行迁移 typeorm migration:run # 回滚迁移 typeorm migration:revert每个迁移文件应该保持幂等性我通常这样编写export class AddUserTable123456789 implements MigrationInterface { public async up(queryRunner: QueryRunner): Promisevoid { await queryRunner.query( CREATE TABLE IF NOT EXISTS users ( id VARCHAR(36) PRIMARY KEY, username VARCHAR(30) NOT NULL UNIQUE, password VARCHAR(100) NOT NULL, created_at TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ) ENGINEInnoDB ); } public async down(queryRunner: QueryRunner): Promisevoid { await queryRunner.query(DROP TABLE IF EXISTS users); } }4.2 性能监控与优化生产环境必须监控数据库性能。我推荐这些实践使用typeorm-query-logger记录慢查询配置连接池监控定期执行EXPLAIN分析关键查询// 在TypeORM配置中添加 extra: { connectionLimit: 10, queueLimit: 5, waitForConnections: true, monitor: { enabled: true, pingInterval: 10000 } }4.3 单元测试策略数据库相关代码的测试需要特殊处理。我的测试方案是describe(UserService, () { let service: UserService; let testModule: TestingModule; beforeAll(async () { testModule await Test.createTestingModule({ imports: [ TypeOrmModule.forRoot({ type: sqlite, database: :memory:, entities: [User], synchronize: true, }), TypeOrmModule.forFeature([User]) ], providers: [UserService], }).compile(); service testModule.getUserService(UserService); }); afterAll(() testModule.close()); it(should create user, async () { const user await service.create({ username: test, password: 123456 }); expect(user).toHaveProperty(id); expect(user.password).not.toBe(123456); }); });使用SQLite内存数据库进行测试既快速又隔离是单元测试的理想选择。