nestjs-patterns

NestJS 개발 패턴

모듈형 TypeScript 백엔드를 위한 운영 수준 NestJS 패턴입니다.

사용 시점

• NestJS API나 서비스를 만들 때
• 모듈, 컨트롤러, 프로바이더를 구조화할 때
• DTO 검증, 가드, 인터셉터, 예외 필터를 추가할 때
• 환경 인식 설정과 데이터베이스 연동을 구성할 때
• NestJS 단위 테스트나 HTTP 엔드포인트 테스트를 작성할 때

프로젝트 구조

src/
├── app.module.ts
├── main.ts
├── common/
│   ├── filters/
│   ├── guards/
│   ├── interceptors/
│   └── pipes/
├── config/
│   ├── configuration.ts
│   └── validation.ts
├── modules/
│   ├── auth/
│   │   ├── auth.controller.ts
│   │   ├── auth.module.ts
│   │   ├── auth.service.ts
│   │   ├── dto/
│   │   ├── guards/
│   │   └── strategies/
│   └── users/
│       ├── dto/
│       ├── entities/
│       ├── users.controller.ts
│       ├── users.module.ts
│       └── users.service.ts
└── prisma/ or database/

• 도메인 코드는 기능 모듈 안에 둡니다.
• 공통 필터, 데코레이터, 가드, 인터셉터는 common/에 둡니다.
• DTO는 그것을 소유한 모듈 가까이에 둡니다.

부트스트랩과 전역 검증

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { bufferLogs: true });

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
      transformOptions: { enableImplicitConversion: true },
    }),
  );

  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
  app.useGlobalFilters(new HttpExceptionFilter());

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

• 공개 API에서는 whitelist, forbidNonWhitelisted를 항상 켭니다.
• 라우트마다 검증 설정을 반복하기보다 전역 validation pipe 하나를 우선합니다.

모듈, 컨트롤러, 프로바이더

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

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

  @Get(':id')
  getById(@Param('id', ParseUUIDPipe) id: string) {
    return this.usersService.getById(id);
  }

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

@Injectable()
export class UsersService {
  constructor(private readonly usersRepo: UsersRepository) {}

  async create(dto: CreateUserDto) {
    return this.usersRepo.create(dto);
  }
}

• 컨트롤러는 얇게 유지합니다. HTTP 입력을 파싱하고, 프로바이더를 호출하고, 응답 DTO를 반환하는 정도에 그쳐야 합니다.
• 비즈니스 로직은 컨트롤러가 아니라 주입 가능한 서비스에 둡니다.
• 다른 모듈이 실제로 필요한 프로바이더만 export합니다.

DTO와 검증

export class CreateUserDto {
  @IsEmail()
  email!: string;

  @IsString()
  @Length(2, 80)
  name!: string;

  @IsOptional()
  @IsEnum(UserRole)
  role?: UserRole;
}

• 모든 요청 DTO는 class-validator로 검증합니다.
• ORM 엔티티를 직접 반환하지 말고 전용 응답 DTO나 serializer를 사용합니다.
• 비밀번호 해시, 토큰, 감사 컬럼 같은 내부 필드가 노출되지 않게 합니다.

인증, 가드, 요청 컨텍스트

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin')
@Get('admin/report')
getAdminReport(@Req() req: AuthenticatedRequest) {
  return this.reportService.getForUser(req.user.id);
}

• 인증 전략과 가드는 정말 공유되는 경우가 아니면 모듈 내부에 둡니다.
• 거친 접근 규칙은 가드에 두고, 리소스별 권한 검사는 서비스에서 처리합니다.
• 인증된 요청 객체에는 명시적 request 타입을 사용합니다.

예외 필터와 오류 형식

@Catch()
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const response = host.switchToHttp().getResponse<Response>();
    const request = host.switchToHttp().getRequest<Request>();

    if (exception instanceof HttpException) {
      return response.status(exception.getStatus()).json({
        path: request.url,
        error: exception.getResponse(),
      });
    }

    return response.status(500).json({
      path: request.url,
      error: 'Internal server error',
    });
  }
}

• API 전반에서 일관된 오류 envelope를 유지합니다.
• 예상 가능한 클라이언트 오류는 프레임워크 예외를 던지고, 예상치 못한 실패는 중앙에서 로깅하고 감쌉니다.

설정과 환경 검증

ConfigModule.forRoot({
  isGlobal: true,
  load: [configuration],
  validate: validateEnv,
});

• 환경 변수는 첫 요청 시점이 아니라 부팅 시점에 검증합니다.
• 설정 접근은 타입이 있는 헬퍼나 config service 뒤에 둡니다.
• 개발/스테이징/운영 분기는 기능 코드 곳곳이 아니라 config factory에서 분리합니다.

영속성과 트랜잭션

• 저장소/ORM 코드는 도메인 언어를 말하는 프로바이더 뒤에 둡니다.
• Prisma나 TypeORM에서는 unit of work를 소유한 서비스 안에 트랜잭션 워크플로를 격리합니다.
• 다단계 쓰기 작업을 컨트롤러가 직접 조정하게 하지 않습니다.

테스트

describe('UsersController', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleRef = await Test.createTestingModule({
      imports: [UsersModule],
    }).compile();

    app = moduleRef.createNestApplication();
    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
    await app.init();
  });
});

• 프로바이더는 mock 의존성과 함께 격리된 단위 테스트를 합니다.
• 가드, validation pipe, 예외 필터에는 요청 수준 테스트를 추가합니다.
• 테스트에서도 운영과 같은 전역 pipe/filter를 재사용합니다.

운영 기본값

• 구조화 로깅과 요청 상관관계 ID를 활성화합니다.
• 잘못된 env/config 상태에서는 부분 부팅하지 말고 종료합니다.
• DB/캐시 클라이언트는 명시적 헬스체크와 함께 async provider 초기화를 우선합니다.
• 백그라운드 작업과 이벤트 소비자는 HTTP 컨트롤러 안이 아니라 별도 모듈에 둡니다.
• 공개 엔드포인트에는 rate limiting, auth, audit logging을 명시적으로 적용합니다.