NestJS完整指南：模块、控制器、服务、依赖注入、TypeORM、JWT认证和测试

什么是 NestJS？

NestJS 是一个渐进式的、TypeScript 优先的 Node.js 框架，用于构建高效、可扩展的服务端应用。 NestJS 深受 Angular 的启发——将装饰器、依赖注入和模块化架构带入了 Node.js 后端世界。

在底层，NestJS 默认构建于 Express.js 之上（也可选择 Fastify），让你可以访问整个 Express 生态系统， 同时提供强大的抽象层，使大型应用易于维护。

截至 2026 年，NestJS 拥有超过 65,000 个 GitHub Star、每周 900 万次 npm 下载， 并被 Adidas、Roche、Autodesk 等公司用于生产环境。

安装与项目搭建

# 全局安装 NestJS CLI
npm install -g @nestjs/cli

# 创建新项目
nest new my-nestjs-app

# 进入项目目录并启动开发服务器
cd my-nestjs-app
npm run start:dev
# 应用运行在: http://localhost:3000

核心概念：模块与架构

NestJS 应用围绕模块组织。模块是使用 @Module() 装饰器标注的类， 提供 NestJS 组织应用结构所需的元数据。每个模块封装一组相关的控制器、服务和提供者。

// src/users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],  // 处理 HTTP 请求
  providers: [UsersService],       // 业务逻辑 + DI 提供者
  exports: [UsersService],         // 导出供其他模块使用
})
export class UsersModule {}

控制器与服务

控制器负责处理传入的 HTTP 请求并返回响应，是轻量层，将实际业务逻辑委托给服务。 服务包含所有业务逻辑和数据访问代码，使两者都易于独立测试。

// src/users/users.controller.ts
import { Controller, Get, Post, Body, Param, ParseIntPipe } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll() {
    return this.usersService.findAll({ page: 1, limit: 20 });
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }

  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }
}

依赖注入

NestJS 内置 IoC（控制反转）容器，自动管理类的实例化。 用 @Injectable() 标记类，在模块中注册为提供者， 然后通过构造函数注入到任何控制器或服务中。 NestJS 在启动时解析依赖图，默认创建单例实例，并在需要时注入。

// 标记为可注入
@Injectable()
export class EmailService {
  sendWelcome(email: string) {
    // 发送邮件逻辑
  }
}

// 在 UsersService 中注入
@Injectable()
export class UsersService {
  constructor(private emailService: EmailService) {}

  async create(dto: CreateUserDto) {
    const user = await this.userRepository.save(dto);
    await this.emailService.sendWelcome(user.email);
    return user;
  }
}

数据库集成

NestJS 为 TypeORM 和 Prisma 提供官方集成包，两者都有一流的 TypeScript 支持。

// TypeORM 实体示例
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn } from 'typeorm';

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

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

  @Column()
  name: string;

  @Column({ select: false })
  password: string;

  @CreateDateColumn()
  createdAt: Date;
}

// Prisma Schema 示例 (prisma/schema.prisma)
// model User {
//   id        Int      @id @default(autoincrement())
//   email     String   @unique
//   name      String
//   createdAt DateTime @default(now())
// }

JWT 认证与 Guards

NestJS 中的认证通常通过 @nestjs/passport 包装的 Passport.js 策略实现。 最常见的模式是使用 JWT（JSON Web Token）进行无状态认证。

// Guard 保护路由
@Controller('profile')
export class ProfileController {
  @Get()
  @UseGuards(JwtAuthGuard)   // 只有持有有效 JWT 的请求才能通过
  getProfile(@Request() req) {
    return req.user;  // 由 JwtStrategy.validate() 设置
  }
}

// 基于角色的访问控制
@Get('admin')
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin')
getAdminData() {
  return { secret: 'admin only' };
}

测试

NestJS 内置测试工具，使用 Test.createTestingModule() 创建隔离测试环境， 替换真实依赖为 Mock 对象。

// 单元测试示例
describe('UsersService', () => {
  let service: UsersService;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UsersService,
        {
          provide: getRepositoryToken(User),
          useValue: {
            findOne: jest.fn(),
            save: jest.fn(),
          },
        },
      ],
    }).compile();

    service = module.get<UsersService>(UsersService);
  });

  it('should throw NotFoundException for missing user', async () => {
    jest.spyOn(service['userRepository'], 'findOne').mockResolvedValue(null);
    await expect(service.findOne(99)).rejects.toThrow(NotFoundException);
  });
});

# 运行测试
# npm run test          — 单元测试
# npm run test:e2e      — 端到端测试
# npm run test:cov      — 测试覆盖率报告

总结

NestJS 是 2026 年最成熟、功能最完整的 TypeScript Node.js 框架。 其 Angular 风格的架构将企业级软件设计模式带入后端：依赖注入、模块化组织、 基于装饰器的配置以及内置测试工具。

从 Express 迁移有一定学习曲线，但在大型代码库中，一致性、可测试性和可维护性的回报 远超前期投入。从 nest new my-app 开始，用 nest generate resource 生成资源，遵循模块模式——你的未来自己和队友都会感谢你。