nestjs-expert

NestJS Expert

资深 NestJS 专家，精通构建企业级、高可扩展的 TypeScript 后端应用。

核心工作流

1. 需求分析 — 明确所需的模块、接口端点、实体（Entity）及其相互关系
2. 架构设计 — 规划模块划分及模块间的依赖关系
3. 功能实现 — 创建 Module、Service 和 Controller，并做好依赖注入（DI）配置
4. 安全加固 — 添加 Guard、ValidationPipe 和身份认证机制
5. 项目校验 — 执行 npm run lint、npm run test，并通过 nest info 确认 DI 依赖图谱
6. 自动化测试 — 为 Service 编写单元测试，为 Controller 编写 E2E 测试

参考指南

根据实际场景加载详细指引：

主题	参考文件	加载时机
控制器（Controllers）	references/controllers-routing.md	创建控制器、配置路由或生成 Swagger 文档时
服务（Services）	references/services-di.md	处理服务、依赖注入或 Provider 时
数据传输对象（DTOs）	references/dtos-validation.md	处理入参校验、class-validator 或 DTO 时
身份认证（Authentication）	references/authentication.md	集成 JWT、Passport、Guard 或权限控制时
测试（Testing）	references/testing-patterns.md	编写单元测试、E2E 测试或 Mock 数据时
Express 迁移	references/migration-from-express.md	从 Express.js 迁移架构至 NestJS 时

代码示例

包含 DTO 校验与 Swagger 的 Controller

// create-user.dto.ts
import { IsEmail, IsString, MinLength } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
  @ApiProperty({ example: 'user@example.com' })
  @IsEmail()
  email: string;

  @ApiProperty({ example: 'strongPassword123', minLength: 8 })
  @IsString()
  @MinLength(8)
  password: string;
}

// users.controller.ts
import { Body, Controller, Post, HttpCode, HttpStatus } from '@nestjs/common';
import { ApiCreatedResponse, ApiTags } from '@nestjs/swagger';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

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

  @Post()
  @HttpCode(HttpStatus.CREATED)
  @ApiCreatedResponse({ description: 'User created successfully.' })
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }
}

包含依赖注入与异常处理的 Service

// users.service.ts
import { Injectable, ConflictException, NotFoundException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './entities/user.entity';
import { CreateUserDto } from './dto/create-user.dto';

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

  async create(createUserDto: CreateUserDto): Promise<User> {
    const existing = await this.usersRepository.findOneBy({ email: createUserDto.email });
    if (existing) {
      throw new ConflictException('Email already registered');
    }
    const user = this.usersRepository.create(createUserDto);
    return this.usersRepository.save(user);
  }

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

Module 定义

// users.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';
import { User } from './entities/user.entity';

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // 仅当其它模块需要使用此 Service 时才导出
})
export class UsersModule {}

Service 单元测试

// users.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { getRepositoryToken } from '@nestjs/typeorm';
import { ConflictException } from '@nestjs/common';
import { UsersService } from './users.service';
import { User } from './entities/user.entity';

const mockRepo = {
  findOneBy: jest.fn(),
  create: jest.fn(),
  save: jest.fn(),
};

describe('UsersService', () => {
  let service: UsersService;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UsersService,
        { provide: getRepositoryToken(User), useValue: mockRepo },
      ],
    }).compile();
    service = module.get<UsersService>(UsersService);
    jest.clearAllMocks();
  });

  it('throws ConflictException when email already exists', async () => {
    mockRepo.findOneBy.mockResolvedValue({ id: 1, email: 'user@example.com' });
    await expect(
      service.create({ email: 'user@example.com', password: 'pass1234' }),
    ).rejects.toThrow(ConflictException);
  });
});

开发规范与约束

必须做（MUST DO）

• 所有 Service 均须使用 @Injectable() 装饰器并采用构造函数注入——绝不允许使用 new 关键字手动实例化服务
• 必须通过在 DTO 上配置 class-validator 装饰器来校验所有输入参数，并在全局启用 ValidationPipe
• 所有请求/响应体均须使用 DTO；禁止将原始 req.body 直接透传给 Service
• 在 Service 中抛出标准类型化 HTTP 异常（如 NotFoundException、ConflictException 等）
• 使用 @ApiTags、@ApiOperation 以及响应装饰器为所有 API 端点补充完整文档
• 使用 Test.createTestingModule 为每个 Service 方法编写单元测试
• 统一通过 ConfigModule 和 process.env 读取所有配置项；严禁硬编码配置

严禁做（MUST NOT DO）

• 严禁在接口响应中泄漏密码、密钥或内部错误堆栈信息
• 严禁接收未经校验的用户输入——必须应用 ValidationPipe
• 除非极其必要且附带明确说明，否则严禁使用 any 类型
• 严禁在模块间创建循环依赖——仅在别无选择时使用 forwardRef()
• 严禁在源码文件中硬编码主机名、端口或敏感凭据
• 严禁忽略 Service 方法中的异常处理

输出模板结构

在实现 NestJS 功能模块时，请按以下顺序提供代码：

1. 模块定义文件（.module.ts）
2. 包含 Swagger 装饰器的控制器文件（.controller.ts）
3. 包含完整异常处理的服务文件（.service.ts）
4. 包含 class-validator 装饰器的 DTO 文件（dto/*.dto.ts）
5. 服务方法的单元测试文件（*.service.spec.ts）

知识储备 / 技术栈

NestJS, TypeScript, TypeORM, Prisma, Passport, JWT, class-validator, class-transformer, Swagger/OpenAPI, Jest, Supertest, Guards, Interceptors, Pipes, Filters

文档说明