NestJS + TypeORM实战：从零搭建一个用户管理系统（附完整代码）

NestJS TypeORM 实战构建企业级用户管理系统引言在当今快速发展的互联网时代后端开发框架的选择直接影响着项目的开发效率和可维护性。NestJS作为一款渐进式Node.js框架结合TypeORM这一强大的ORM工具能够为开发者提供高效、安全的数据库操作体验。本文将带你从零开始构建一个完整的用户管理系统涵盖从环境搭建到高级功能实现的全部流程。1. 环境准备与项目初始化1.1 安装必要工具首先确保你的开发环境已经安装以下工具Node.js (建议版本16.x或更高)npm或yarnDocker (用于运行数据库服务)你喜欢的代码编辑器(VS Code推荐)# 全局安装NestJS CLI npm i -g nestjs/cli1.2 创建NestJS项目使用Nest CLI快速生成项目骨架nest new user-management-system cd user-management-system1.3 配置TypeORM安装TypeORM及相关依赖npm install typeorm nestjs/typeorm mysql2在项目根目录下创建ormconfig.json文件配置数据库连接{ type: mysql, host: localhost, port: 3306, username: root, password: yourpassword, database: user_management, synchronize: true, logging: true, entities: [dist/**/*.entity{.ts,.js}] }2. 数据库设计与实体定义2.1 用户实体设计创建用户实体是系统的基础我们定义User实体如下// src/users/entities/user.entity.ts import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, UpdateDateColumn } from typeorm; Entity() export class User { PrimaryGeneratedColumn() id: number; Column({ length: 50, unique: true }) username: string; Column({ length: 100, select: false }) password: string; Column({ length: 100 }) email: string; Column({ default: true }) isActive: boolean; CreateDateColumn() createdAt: Date; UpdateDateColumn() updatedAt: Date; }2.2 角色与权限实体为系统添加基本的RBAC权限控制// src/roles/entities/role.entity.ts import { Entity, Column, PrimaryGeneratedColumn, ManyToMany, JoinTable } from typeorm; import { User } from ../../users/entities/user.entity; Entity() export class Role { PrimaryGeneratedColumn() id: number; Column({ length: 50, unique: true }) name: string; Column({ length: 100 }) description: string; ManyToMany(() User, user user.roles) users: User[]; }记得在User实体中添加对应的关系ManyToMany(() Role, role role.users) JoinTable() roles: Role[];3. 核心功能实现3.1 用户模块创建使用Nest CLI生成用户模块nest generate module users nest generate service users nest generate controller users3.2 用户服务实现在users.service.ts中实现基本的CRUD操作// src/users/users.service.ts import { Injectable } from nestjs/common; import { InjectRepository } from nestjs/typeorm; import { Repository } from typeorm; import { User } from ./entities/user.entity; Injectable() export class UsersService { constructor( InjectRepository(User) private usersRepository: RepositoryUser, ) {} async create(userData: PartialUser): PromiseUser { const user this.usersRepository.create(userData); return this.usersRepository.save(user); } async findAll(): PromiseUser[] { return this.usersRepository.find(); } async findOne(id: number): PromiseUser { return this.usersRepository.findOne({ where: { id } }); } async update(id: number, updateData: PartialUser): PromiseUser { await this.usersRepository.update(id, updateData); return this.usersRepository.findOne({ where: { id } }); } async remove(id: number): Promisevoid { await this.usersRepository.delete(id); } }3.3 用户控制器实现RESTful API接口// src/users/users.controller.ts import { Controller, Get, Post, Body, Param, Put, Delete } from nestjs/common; import { UsersService } from ./users.service; import { User } from ./entities/user.entity; Controller(users) export class UsersController { constructor(private readonly usersService: UsersService) {} Post() create(Body() userData: PartialUser): PromiseUser { return this.usersService.create(userData); } Get() findAll(): PromiseUser[] { return this.usersService.findAll(); } Get(:id) findOne(Param(id) id: string): PromiseUser { return this.usersService.findOne(id); } Put(:id) update(Param(id) id: string, Body() updateData: PartialUser): PromiseUser { return this.usersService.update(id, updateData); } Delete(:id) remove(Param(id) id: string): Promisevoid { return this.usersService.remove(id); } }4. 高级功能实现4.1 查询构建器使用TypeORM的查询构建器提供了强大的查询能力async findUsersWithRoles(): PromiseUser[] { return this.usersRepository .createQueryBuilder(user) .leftJoinAndSelect(user.roles, role) .where(user.isActive :isActive, { isActive: true }) .orderBy(user.createdAt, DESC) .getMany(); }4.2 事务管理确保数据一致性的关键操作应使用事务async transferRoles(fromUserId: number, toUserId: number): Promisevoid { await this.usersRepository.manager.transaction(async transactionalEntityManager { const fromUser await transactionalEntityManager.findOne(User, { where: { id: fromUserId }, relations: [roles] }); const toUser await transactionalEntityManager.findOne(User, { where: { id: toUserId }, relations: [roles] }); toUser.roles [...toUser.roles, ...fromUser.roles]; fromUser.roles []; await transactionalEntityManager.save([fromUser, toUser]); }); }4.3 数据验证与DTO使用class-validator进行数据验证// src/users/dto/create-user.dto.ts import { IsEmail, IsString, MinLength, MaxLength, IsBoolean } from class-validator; export class CreateUserDto { IsString() MinLength(4) MaxLength(50) username: string; IsString() MinLength(8) password: string; IsEmail() email: string; IsBoolean() isActive: boolean; }然后在控制器中使用Post() async create(Body() createUserDto: CreateUserDto) { return this.usersService.create(createUserDto); }5. 系统优化与扩展5.1 分页查询实现对于大量数据的查询实现分页功能async findPaginated(page: number 1, limit: number 10): Promise{ data: User[]; count: number } { const [data, count] await this.usersRepository.findAndCount({ skip: (page - 1) * limit, take: limit, }); return { data, count }; }5.2 软删除实现通过装饰器实现软删除而非物理删除import { DeleteDateColumn } from typeorm; Entity() export class User { // ...其他字段 DeleteDateColumn() deletedAt: Date; }然后使用softDelete和restore方法async softDelete(id: number): Promisevoid { await this.usersRepository.softDelete(id); } async restore(id: number): Promisevoid { await this.usersRepository.restore(id); }5.3 日志记录使用TypeORM的订阅者功能记录重要操作// src/database/subscribers/user.subscriber.ts import { Connection, EntitySubscriberInterface, EventSubscriber, InsertEvent } from typeorm; import { User } from ../../users/entities/user.entity; EventSubscriber() export class UserSubscriber implements EntitySubscriberInterfaceUser { constructor(connection: Connection) { connection.subscribers.push(this); } listenTo() { return User; } beforeInsert(event: InsertEventUser) { console.log(BEFORE USER INSERTED: , event.entity); } }6. 测试与部署6.1 单元测试为服务层编写单元测试// src/users/users.service.spec.ts import { Test, TestingModule } from nestjs/testing; import { getRepositoryToken } from nestjs/typeorm; import { User } from ./entities/user.entity; import { UsersService } from ./users.service; describe(UsersService, () { let service: UsersService; const mockUserRepository { create: jest.fn().mockImplementation(dto dto), save: jest.fn().mockImplementation(user Promise.resolve({ id: Date.now(), ...user })), find: jest.fn().mockImplementation(() Promise.resolve([mockUser])), findOne: jest.fn().mockImplementation(({ where: { id } }) Promise.resolve(id 1 ? mockUser : null)), update: jest.fn().mockImplementation((id, dto) Promise.resolve({ ...mockUser, ...dto })), delete: jest.fn().mockImplementation(() Promise.resolve()), }; const mockUser { id: 1, username: testuser, email: testexample.com, isActive: true, }; beforeEach(async () { const module: TestingModule await Test.createTestingModule({ providers: [ UsersService, { provide: getRepositoryToken(User), useValue: mockUserRepository, }, ], }).compile(); service module.getUsersService(UsersService); }); it(should be defined, () { expect(service).toBeDefined(); }); it(should create a user, async () { expect(await service.create(mockUser)).toEqual({ id: expect.any(Number), ...mockUser, }); }); });6.2 集成测试测试API端点// test/users.e2e-spec.ts import { Test, TestingModule } from nestjs/testing; import { INestApplication } from nestjs/common; import * as request from supertest; import { AppModule } from ../src/app.module; import { getConnection } from typeorm; describe(UsersController (e2e), () { let app: INestApplication; beforeAll(async () { const moduleFixture: TestingModule await Test.createTestingModule({ imports: [AppModule], }).compile(); app moduleFixture.createNestApplication(); await app.init(); }); afterAll(async () { await getConnection().close(); await app.close(); }); it(/users (POST), () { return request(app.getHttpServer()) .post(/users) .send({ username: testuser, email: testexample.com, password: password123, isActive: true, }) .expect(201) .then(response { expect(response.body).toHaveProperty(id); expect(response.body.username).toEqual(testuser); }); }); });6.3 生产环境部署创建Dockerfile和docker-compose.yml文件# Dockerfile FROM node:16-alpine WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build EXPOSE 3000 CMD [npm, run, start:prod]# docker-compose.yml version: 3.8 services: app: build: . ports: - 3000:3000 environment: NODE_ENV: production depends_on: - db db: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: yourpassword MYSQL_DATABASE: user_management ports: - 3306:3306 volumes: - mysql_data:/var/lib/mysql volumes: mysql_data:7. 性能优化与监控7.1 数据库索引优化为常用查询字段添加索引Column({ length: 50, unique: true }) Index() username: string; Column({ length: 100 }) Index() email: string;7.2 缓存策略使用Redis缓存频繁访问的数据// src/cache/cache.module.ts import { CacheModule, Module } from nestjs/common; import * as redisStore from cache-manager-redis-store; Module({ imports: [ CacheModule.register({ store: redisStore, host: localhost, port: 6379, ttl: 60, // 缓存时间(秒) }), ], exports: [CacheModule], }) export class CustomCacheModule {}然后在服务中使用import { CACHE_MANAGER, Inject, Injectable } from nestjs/common; import { Cache } from cache-manager; Injectable() export class UsersService { constructor( Inject(CACHE_MANAGER) private cacheManager: Cache, InjectRepository(User) private usersRepository: RepositoryUser, ) {} async findOne(id: number): PromiseUser { const cachedUser await this.cacheManager.getUser(user_${id}); if (cachedUser) { return cachedUser; } const user await this.usersRepository.findOne({ where: { id } }); if (user) { await this.cacheManager.set(user_${id}, user, { ttl: 60 }); } return user; } }7.3 性能监控集成NestJS的性能监控工具npm install nestjs/platform-express prom-client express-prom-bundle创建监控模块// src/monitoring/monitoring.module.ts import { Module } from nestjs/common; import { PrometheusModule } from nestjs/prometheus; import { MonitoringController } from ./monitoring.controller; Module({ imports: [ PrometheusModule.register({ defaultMetrics: { enabled: true, }, }), ], controllers: [MonitoringController], }) export class MonitoringModule {}8. 安全最佳实践8.1 密码加密使用bcrypt加密用户密码import * as bcrypt from bcrypt; async create(createUserDto: CreateUserDto): PromiseUser { const salt await bcrypt.genSalt(); const hashedPassword await bcrypt.hash(createUserDto.password, salt); const user this.usersRepository.create({ ...createUserDto, password: hashedPassword, }); return this.usersRepository.save(user); }8.2 输入验证加强DTO验证import { IsEmail, IsString, MinLength, MaxLength, IsBoolean, Matches } from class-validator; export class CreateUserDto { IsString() MinLength(4) MaxLength(50) Matches(/^[a-zA-Z0-9_]$/, { message: 用户名只能包含字母、数字和下划线, }) username: string; IsString() MinLength(8) Matches(/^(?.*[a-z])(?.*[A-Z])(?.*\d)[a-zA-Z\d]{8,}$/, { message: 密码必须包含至少一个大写字母、一个小写字母和一个数字, }) password: string; IsEmail() email: string; IsBoolean() isActive: boolean; }8.3 API限流防止暴力破解攻击npm install nestjs/throttler在AppModule中配置import { ThrottlerModule } from nestjs/throttler; Module({ imports: [ ThrottlerModule.forRoot({ ttl: 60, limit: 10, }), ], }) export class AppModule {}然后在需要保护的控制器上添加装饰器import { Throttle } from nestjs/throttler; Controller(auth) export class AuthController { Throttle(5, 60) // 60秒内最多5次 Post(login) async login(Body() loginDto: LoginDto) { // 登录逻辑 } }9. 文档生成与API测试9.1 Swagger集成自动生成API文档npm install nestjs/swagger swagger-ui-express在main.ts中配置import { SwaggerModule, DocumentBuilder } from nestjs/swagger; async function bootstrap() { const app await NestFactory.create(AppModule); const config new DocumentBuilder() .setTitle(用户管理系统API) .setDescription(用户管理系统的API文档) .setVersion(1.0) .addBearerAuth() .build(); const document SwaggerModule.createDocument(app, config); SwaggerModule.setup(api, app, document); await app.listen(3000); }9.2 DTO文档注释为Swagger添加详细的字段描述import { ApiProperty } from nestjs/swagger; import { IsEmail, IsString, MinLength, MaxLength, IsBoolean } from class-validator; export class CreateUserDto { ApiProperty({ description: 用户名4-50个字符, example: john_doe, }) IsString() MinLength(4) MaxLength(50) username: string; ApiProperty({ description: 密码至少8个字符, example: Password123, }) IsString() MinLength(8) password: string; ApiProperty({ description: 有效的电子邮件地址, example: johnexample.com, }) IsEmail() email: string; ApiProperty({ description: 用户是否激活, default: true, }) IsBoolean() isActive: boolean; }9.3 Postman集合创建Postman集合进行API测试{ info: { name: 用户管理系统API, schema: https://schema.getpostman.com/json/collection/v2.1.0/collection.json }, item: [ { name: 用户管理, item: [ { name: 创建用户, request: { method: POST, header: [], body: { mode: raw, raw: {\n \username\: \testuser\,\n \password\: \password123\,\n \email\: \testexample.com\,\n \isActive\: true\n}, options: { raw: { language: json } } }, url: { raw: http://localhost:3000/users, protocol: http, host: [localhost], port: 3000, path: [users] } } } ] } ] }10. 前端集成与实战建议10.1 前端项目对接创建简单的React组件与后端交互// UserList.tsx import React, { useState, useEffect } from react; import axios from axios; const UserList () { const [users, setUsers] useState([]); useEffect(() { const fetchUsers async () { try { const response await axios.get(http://localhost:3000/users); setUsers(response.data); } catch (error) { console.error(获取用户列表失败:, error); } }; fetchUsers(); }, []); return ( div h2用户列表/h2 ul {users.map(user ( li key{user.id} {user.username} - {user.email} /li ))} /ul /div ); }; export default UserList;10.2 错误处理最佳实践全局异常过滤器// src/filters/http-exception.filter.ts import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from nestjs/common; import { Request, Response } from express; Catch(HttpException) export class HttpExceptionFilter implements ExceptionFilter { catch(exception: HttpException, host: ArgumentsHost) { const ctx host.switchToHttp(); const response ctx.getResponseResponse(); const request ctx.getRequestRequest(); const status exception.getStatus(); response.status(status).json({ statusCode: status, timestamp: new Date().toISOString(), path: request.url, message: exception.message || Internal server error, }); } }在main.ts中使用app.useGlobalFilters(new HttpExceptionFilter());10.3 项目结构优化建议推荐的项目结构src/ ├── app.module.ts ├── main.ts ├── common/ │ ├── filters/ │ ├── interceptors/ │ ├── decorators/ │ └── guards/ ├── config/ ├── database/ │ ├── migrations/ │ └── subscribers/ ├── modules/ │ ├── auth/ │ ├── users/ │ ├── roles/ │ └── shared/ └── utils/这种结构保持了模块化同时将通用功能集中管理便于大型项目的扩展和维护。