Swagger는 NestJS 공식 홈페이지에서 소개하는 API 문서 자동화 도구이다. 협업 시에 '어느 엔드 포인트에 들어가서 어떤 메서드를 사용하고, body에는 이런 값이 들어간다'라는 것을 설명해야 할 때가 있다. Swagger를 이용하면 ppt나 notion을 사용했을 때보다 용이하다.

코드를 짜면서 즉각적으로 작성 · 수정할 수 있다는 장점이 있으며 API를 테스트해 볼 수도 있다.

Swagger 설치

express 환경과 fastify 환경에 따라 설치해야 하는 모듈이 다르다. 나는 express를 사용하기 때문에 아래 모듈을 설치했다.

npm install --save @nestjs/swagger swagger-ui-express

Swagger 사용 (1)

main에서 SwaggerModule 클래스로 Swagger를 초기화한다. createDocument() 메서드를 사용해서 API 문서를 만들 수 있다. config는 일종의 옵션으로 title, description, version 등을 설정할 수 있다. 접속하는 엔드 포인트는 SwaggerModule.setup()메서드에서 설정한다. http://localhost:3000/docs로 접속할 수 있다.

import { HttpExceptionFilter } from 'src/cats/commons/exceptions/http-exception.filter';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe } from '@nestjs/common';
import { DocumentBuilder, OpenAPIObject, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  app.useGlobalFilters(new HttpExceptionFilter());

  const config = new DocumentBuilder()
    .setTitle('C.I.C')
    .setDescription('cat')
    .setVersion('1.0.0')
    .addTag('cats')
    .build();
  const document: OpenAPIObject = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docs', app, document);

  ⁝ 
  (생략)

http://localhost:3000/docs에 접속하면 Nest가 내 controller를 해석하여 해당하는 API를 띄워 준다. 하지만 각각의 API가 무엇을 뜻하는지 즉각적으로 알아보기 힘들다. API에 설명을 달아 주는 건 controller에서 @ApiOperation 데코레이터가 담당한다.

 @ApiOperation({ summary: '회원가입' })
  @Post()
  async signUp(@Body() body: CatRequestDto) {
    // ‥ (생략)
 }

해당하는 API에 summary를 달아 주면 Swagger에서 대응하는 설명이 나타난다.

Swagger 사용 (2) - Request body 설정

Swagger는 API 테스트 기능을 지원하기 때문에 직접 body를 입력하여 테스트해 볼 수 있다. 이때 어떤 body를 써야 하는지, 어떤 객체들을 넘겨 줘야 하는지 알려 주기 위해 또 다른 설정이 필요하다. 이 설정은 DTO, CatRequestDto에서 @ApiProperty 데코레이터로 할 수 있다.

@ApiProperty({
  example: 'qwerty@abc.com',
  description: 'email',
  required: true,
})
// ‥ (생략)

Request body 영역도 잘 뜬다.

Swagger 사용 (3) - Response 설정

지금까지는 API 설명, Request로 보내야 하는 것을 설정해 줬다. 이제 마지막으로 Response를 보냈을 때 결과값이 어떻게 출력되는지 설정할 차례다. Response 설정은 API 설명을 작성했을 때처럼 controller에서 해 준다.

우선 ResponseDto를 만들기 위해 cat.dto.ts 파일을 생성했다. response는 signUp에 대한 대응으로 readonly인 readOnlyData(버추얼 필드)가 왔기 때문에 cat.dto.ts도 이에 맞는 코드만 작성해 준다.

파일 내 코드는 아래와 같다.

export class ReadOnlyCatDto {
  @ApiProperty({
    example: '3425343334',
    description: 'id',
  })
  id: string;

  @ApiProperty({
    example: 'qwerty@abc.com',
    description: 'email',
  })
  email: string;

  @ApiProperty({
    example: '김가나',
    description: 'name',
  })
  name: string;
}

@ApiResponse 데코레이터로 status 값에 대한 description을 설정할 수 있다.

  @ApiResponse({
    status: 500,
    description: 'Server Error...',
  })
  @ApiResponse({
    status: 200,
    description: '성공',
    type: ReadOnlyCatDto
  })
  @ApiOperation({ summary: '회원가입' })

500 error가 발생했을 때와 200으로 성공했을 때 각각 작성해 준다. type에는 지금까지 사용했던 RequestDto가 아닌 Response용 DTO가 와야 한다.

Swagger 사용 (3) - 보안 설정

Swagger 문서는 노출되었을 때 심각한 보안 문제를 초래할 수 있다. 그렇기 때문에 Swagger에 보안을 해 줘야 한다.express-basic-auth 라이브러리를 사용하여 보안 설정을 해 보자.

npm install express-basic-auth

// main.ts

import * as expressBasicAuth from 'express-basic-auth';

설치와 import를 마친 후 main.ts에 미들웨어를 추가해 준다.

  app.use(
    ['/docs', '/docs-json'],
    expressBasicAuth({
      challenge: true,
      users: { [process.env.SWAGGER_USER]: process.env.SWAGGER_PASSWORD },
    }),
  );

SWAGGER_USER는 /docs로 접속을 시도할 때 필요한 아이디, SWAGGER_PASSWORD는 비밀번호로 .env에 환경변수로 저장해 두었다. (노출되면 ❌) 여기까지 설정하면 아래 캡처처럼 진입할 때 로그인을 해야 한다.

JWT(JSON Web Token)은 JSON 형식으로 사용자에 대한 정보를 저장하는 웹 토큰이다. 디지털 서명이 되어 있으므로 안전하고 신뢰할 수 있다. 정보를 안전하게 전달할 때, 유저의 권한을 체크할 때 사용하는 유용한 모듈이다.

보통 로그인을 할 때 많이 사용된다. 로그인한 고유 유저를 위한 JWT 토큰을 생성하여 안전하게 로그인하고 또 권한을 확인하는 용도다.

JWT의 구조

Header, Payload, Signiture 세 파트가 합쳐진 구조를 띈다.

1. Header 토큰에 대한 메타 데이터를 포함하고 있다. 메타 데이터란 타입, 해싱 알고리즘, SHA256 등을 뜻한다.

2. Payload 실제적으로 담긴 데이터다. 유저 정보, 만료 기간 등이 담겨 있다. 필요한 데이터만 넣는 것이 중요하나, 보안의 위험 때문에 중요한 데이터 삽입은 지양하는 게 좋다.

3. Signiture 토큰이 보낸 사람에 의해 시크릿키로 서명되었으며 조작되지 않았음을 확인하는 데 사용된다. 위 사진에서 볼 수 있듯이 base64로 인코딩된 Header와 Payload + 서명 알고리즘 + 시크릿키(혹은 퍼블릭키)가 조합되어 생성된다.

이 세 세그먼트가 모여서 하나의 JWT 토큰이 된다.

JWT의 흐름

JWT 설치

Nest 환경에서 JWT의 인증 처리를 더 간편하게 사용하기 위해 Passport 모듈도 같이 설치해 준다. 네 개 모두 설치.

npm install --save @nestjs/jwt passport-jwt
npm install --save-dev @types/passport-jwt

npm install --save @nestjs/passport passport
npm install --save-dev @types/passport-local

JWT 사용 - 로그인 과정

(1) JWT 모듈 등록

새로 생성한 auth.module에서 사용하기 때문에 imports에 JwtModule을 넣어 준다.

JwtModule.register({
  secret: `${process.env.JWT_SECRET}`,
  signOptions: { expiresIn: '1y' },
})

secret은 노출되면 안 되는 시크릿 키라서 환경 변수로 따로 저장했다. 이렇게 환경 변수를 이용할 때는 꼭 ConfigModule.forRoot()를 imports 해 줘야 한다. imports 없이 사용하면 찾을 수 없어서 오류가 발생한다.

signOptions의 expiresIn는 토큰의 유효 기간이다. 나는 우선 1년으로 지정했다.

(2) passport 모듈 등록

다음으로는 auth.module.ts에 passport 모듈을 등록한다. 마찬가지로 imports 해 주면 된다.

PassportModule.register({ defaultStrategy: 'jwt', session: false })

session을 사용하지 않을 거라서 false로 두었다.

(3) jwtService 주입

추후 서비스단에서 토큰을 생성하려면 jwtService가 필요하다. jwtService는 별도의 서비스단을 만들지 않고, 사용할 서비스단에 바로 주입하는 방식으로 사용 가능하다. 로그인 서비스를 구현할 Auth.service.ts 파일에 jwtService를 주입했다.

@Injectable()
export class AuthService {
  constructor(
    private readonly userRepository: UserRepository,
    private jwtService: JwtService,
  ) {}

(4) 토큰 생성

로그인에 필요한 유효성 검사를 거쳐 로그인에 성공하면 유저 토큰이 생성되도록 한다.

  const payload = { id: id, sub: user._id };
  return {
    token: this.jwtService.sign(payload),
  };

토큰의 payload에는 유니크값인 id와 토큰의 제목(sub)으로 user._id 고유값을 담았다. sign메서드로 payload를 담아서 토큰을 생성한다. 로그인이 성공적으로 완료되면 클라이언트는 이 토큰을 보관한다.

JWT 사용 - 인증 과정

(1) 유효한 토큰인지 확인

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private readonly userRepository: UserRepository) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: `${process.env.JWT_SECRET}`,
      ignoreExpiration: false,
    });
  }

jwt.strategy.ts를 생성하고 다른 곳에서도 인증 과정을 사용할 수 있게끔 @Injectable() 데코레이터를 달아 준다. userRepository를 주입받는 걸 확인할 수 있는데, 인증 요청이 날아온 토큰의 payload 데이터와 DB의 데이터가 상응하는지 확인하고 가져오기 위함이다.

super 안의 과정은 토큰이 Bearer 타입으로 넘어오는 걸 가져와서 시크릿 키로 유효한지 확인하는 것이다. 이때의 시크릿 키는 토큰 생성 시에 사용한 시크릿 키와 그 값이 동일해야 한다. 생성과 인증으로 용도만 다를 뿐이지 시크릿 키 자체가 달라지는 게 아니다.

(2) 데이터베이스에서 값 가지고 오기

위의 과정으로 유효한 토큰이라는 게 확인되면 validate 메서드에서 데이터베이스 검증 과정을 거쳐 boolean 타입으로 리턴한다.

  async validate(payload: Payload) {
    const user = await this.userRepository.findUserByIdWithoutPwd(payload.sub);

    if (user) {
      return user; // request.user안에 user가 들어감
    } else {
      throw new UnauthorizedException('접근 오류입니다');
    }
  }

payload에는 유저의 id 값이 id로, _id 값이 sub로 저장되어 있다. 둘 다 유니크하기 때문에 어떤 값을 이용하든 단 한 명의 유저를 뽑아낼 수 있다. 데이터베이스와 연결된 userRepository에서 payload의 sub를 이용해 유저를 찾은 후, 유저가 존재하면 그 정보를 user 객체에 담는다. 객체를 리턴해 주면 request 객체 안에서 user를 사용할 수 있게 된다.

(3) 모듈에 담기

위에서 만든 클래스 JwtStrategy를 사용하기 위해 providers에 담아 준다. 다른 곳에서도 사용해야 하므로 exports도 해 준다.

@Module({
  imports: [
    ConfigModule.forRoot(),
    // jwt 모듈 등록
    JwtModule.register({
      secret: `${process.env.JWT_SECRET}`,
      signOptions: { expiresIn: '1y' },
    }),
    // passport 모듈 등록
    PassportModule.register({ defaultStrategy: 'jwt', session: false }),

    // 두 모듈이 서로를 import하고 있기 때문에 순환 모듈 문제를 아래처럼 해결
    forwardRef(() => UserModule),
  ],
  providers: [AuthService, JwtStrategy],
  exports: [AuthService, JwtStrategy],
})
export class AuthModule {}

(4) user 객체 사용하기

나는 현재 로그인된 유저가 누구인지 알아보기 위해 user.controller.ts 파일에서 로그인 유저 인증을 필요로 했다. 현재 로그인된 유저는 request 객체에 담겼다고 (2)에서 말했는데, 이 유저를 사용하기 위해 @UseGuards(JwtAuthGuard)를 이용한다.

가드는 인증 미들웨어로, 지정된 경로로 통과할 수 있는 사람과 허용되지 않는 사람을 서버에 알려 준다. 또한 가드가 실행되면 JwtStrategy를 자동으로 실행시켜 인증이 진행되게 도와준다.

  @ApiOperation({ summary: '현재 유저 가지고 오기' })
  @UseGuards(JwtAuthGuard)
  @Get()
  getCurrentUser(@CurrentUser() user) {
    return user.readOnlyUser;
  }

나는 커스텀 데코레이터를 이용해서 @Req() req로 req.user를 얻지 않고 바로 user라는 파라미터를 가져왔다. @CurrentUser()가 커스텀 데코레이터다.

몽구스의 모든 것은 스키마에서 파생된다. 각 스키마는 몽고디비 컬렉션에 매핑되고 해당 컬렉션 내의 문서 모양을 정의한다. 스키마는 모델을 정의하는 데 사용되는데, 모델이란 몽고디비 데이터베이스에서 문서를 만들고 읽는 역할을 한다. 스키마를 만들 때에는 @Schma() 데코레이터를 사용한다.

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Document, SchemaOptions } from 'mongoose';

const options: SchemaOptions = {
  timestamps: true,
};

@Schema(options)
export class Cat extends Document {   // 몽구스의 Document를 상속받음

export const CatSchema = SchemaFactory.createForClass(Cat);

위 코드는 cat.schma 파일에 스키마를 데코레이터로 정의한 것이다. Cat이라는 클래스는 SchemaFactory.createForClass를 통해 CatSchema라는 이름의 스키마가 된다. options는 스키마에 대한 옵션인데 timestamps 옵션은 만들어진 시간과 업데이트된 시간을 찍어 준다.

💫 스키마의 컬럼

스키마의 컬럼은 각각의 @Prop으로 정의할 수 있다. 그리고 추가적인 옵션을 설정해 준다. 이를 통해 반드시 필요한 속성인지 여부를 나타내거나 기본값을 지정하거나 할 수 있다. 아래의 컬럼들 중 email, catname, password는 required 속성이 true가 된다. 이미지의 required 값은 false이므로 생략할 수 있다. (기본값이 false이다)

⁝
@Schema(options)
export class Cat extends Document {   // 몽구스의 Document를 상속받음
  @Prop({
        required: true,
        unique: true,
  })
  email: string;

  @Prop({
        required: true,
  })
  catname: number;

  @Prop({
        required: true,
  })
  password: string;

 @Prop()
  imgUrl: string;
}

export const CatSchema = SchemaFactory.createForClass(Cat);

💫 class-validation

이제 컬럼에 validation을 추가해 줄 차례다. 예를 들어 이메일이 디비에 저장될 때 이메일의 형식이 아닌 경우를 막기 위해 validation을 해 주는 것이다. 이를 위해 라이브러리를 하나 더 설치하자. npm i --save class-validator class-transformer으로 설치 가능하다. class validator의 자세한 사용법은 여기에서 확인할 수 있다.

⁝
@Schema(options)
export class Cat extends Document {   // 몽구스의 Document를 상속받음
  @Prop({
        required: true,
        unique: true,
  })
  @IsEmail()
  @IsNotEmpty()
  email: string;

  @Prop({
        required: true,
  })
  @IsString()
  @IsNotEmpty()
  name: number;

  @Prop({
        required: true,
  })
  @IsString()
  @IsNotEmpty()
  password: string;

 @Prop()
  imgUrl: string;
}

export const CatSchema = SchemaFactory.createForClass(Cat);

사용된@IsEmail(), @IsNotEmpty(), @IsString() 데코레이터들이 validator다.

이제 class validation의 원활한 사용을 위해 main 파일에서 app.useGlobalPipes(new ValidationPipe());로 등록까지 마치면 스키마 설계가 끝난다. 💁🏻‍♀️

// cats.schema.ts

@Schema(options)
export class Cat extends Document {
  @ApiProperty({
    example: 'abc@naver.com',
    description: 'email',
    required: true,
  })
  @Prop({
    required: true,
    unique: true,
  })
  @IsEmail()
  @IsNotEmpty()
  email: string;

  @ApiProperty({
    example: '김가나',
    description: 'name',
    required: true,
  })
  @Prop({
    required: true,
  })
  @IsString()
  @IsNotEmpty()
  name: string;

  @ApiProperty({
    example: 'pass4034',
    description: 'password',
    required: true,
  })
  @Prop({
    required: true,
  })
  @IsString()
  @IsNotEmpty()
  password: string;

  @Prop()
  @IsString()
  imgUrl: string;

  readonly readOnlyData: { id: string; email: string; name: string };
}

위의 코드를 cats.request.dto.ts가 상속받으면 아래와 같다.

// cats.request.dto.ts

export class CatRequestDto extends Cat {}

cat.dto.ts가 상속받으면 아래와 같다.

// cat.dto.ts

export class ReadOnlyCatDto extends Cat {
  @ApiProperty({
    example: '34230004',
    description: 'id',
  })
  id: string;
}

그런데 이렇게 Cat을 상속받으면 cats.request.dto.ts의 경우 password 값이 포함되어 버린다. 이때 PickType을 사용하면 Cat이라는 클래스에서 필요한 부분만 가져올 수 있다. PickType을 사용한 코드는 각각 아래와 같다.

// cats.request.dto.ts

export class CatRequestDto extends PickType(Cat, [
  'email',
  'name',
  'password',
] as const) {}

// cat.dto.ts

export class ReadOnlyCatDto extends PickType(Cat, ['email', 'name'] as const) {
  @ApiProperty({
    example: '34230004',
    description: 'id',
  })
  id: string;
}

이렇게 하면 객체 지향의 패턴을 잘 활용할 수 있다.

클라이언트에서 받은 body 데이터를 DTO 처리하고 service단으로 보냈다.

@Injectable()
export class CatsService {
  signUp(body: CatRequestDto) {
  }
}

이제 body로 받은 데이터를 유효성 검사와 패스워드 암호화를 걸쳐 DB에 저장하는 과정을 거쳐야 한다. DB에 저장하려면 쿼리를 써야 하므로 스키마를 서비스단 안에서 사용하기 위해 DI를 해 주자.

@Injectable()
export class CatsService {
  constructor(@InjectModel(Cat.name) private readonly catModel: Model<Cat>) {}

  signUp(body: CatRequestDto) {
  }
}

constructor(@InjectModel(Cat.name) private readonly catModel: Model<Cat>) {}가 스키마를 사용하기 위해 DI 해 준 코드이다. 그런데 그냥 이렇게만 하면 사용할 수 없다. cat.module에 가서 아래처럼 import를 해 줘야 한다.

@Module({
  imports: [MongooseModule.forFeature([{ name: Cat.name, schema: CatSchema }])],
})

이제 Cat모델을 서비스단 안에서 사용 가능하다.

🍡 signUp 로직

body에 email, name, password 데이터가 들어오면 유효성 검사, 패스워드 암호화를 거쳐 DB에 저장해야 한다.

(1) 유효성 검사

const isCatExist = await this.catModel.exists({ email }); 이메일은 중복되면 안 되므로 중복 검사를 한다. exists 쿼리 메서드는 DB의 email 필드를 검색하고 해당 이메일과 일치하는 값이 존재하는지 검사한 후 Promise<boolean>으로 return 한다. 그리고 이 return 값이 true라면 조건문을 통해 아래와 같은 오류 코드를 발생시킨다.

  if (isCatExist) {
    throw new UnauthorizedException('해당 메일이 이미 존재합니다.'); 
    // 403 에러를 발생시켜주는 자동화된 클래스
    // throw new HttpException('해당 메일이 이미 존재합니다.', 403);와 동일
  }
    }

(2) 비밀번호 암호화

비밀번호 암호화를 위한 bycript 라이브러리가 있다. 암호화, 즉 hash를 해 주는 라이브러리로 별도의 설치가 필요하다. npm으로 아래 두 개를 모두 설치해 준다.

npm i bcrypt
npm i -D @types/bcrypt

설치 후 import * as bcrypt from 'bcrypt' 해 주면 bcrypt를 사용할 수 있다! 이제 body에 있는 password를 bcrypt로 hashing하여 hashedPassword에 할당한다. 암호화된 비밀번호는 hashedPassword에 담겨 있다.

const hashedPassword = await bcrypt.hash(password, 10);

(3) 버추얼 필드

비밀번호 암호화는 성공했으나, 추후 DB에 저장하면 httpException 필터 형식에 따라 password의 암호화된 값이 노출되어 반환될 것이다.

{
"success": true,
"data": {
    "_id": "~~~"
    "name": "~~~"
    "password": 암호화된 값 노출!!
    ⁝
    ⁝
  }
}

이를 막기 위해 버추얼 필드를 만들어 주면 된다. 몽구스에서 제공하는 버추얼 필드는 패스워드 값을 숨길 수 있게 해 준다. 실제로 DB에 저장되는 필드는 아니고 비지니스 로직에서 사용할 수 있도록 제공해 주는 가상의 필드다. 이는 schema 단계에서 virtual('필드네임') 메소드를 사용하여 작성한다.

CatSchema.virtual('readOnlyData').get(function (this: Cat) {
  return {
    id: this.id,
    email: this.email,
    name: this.name,
  };
});

readOnlyData는 필드네임, this는 schema 클래스 Cat 그 자체인 Model이다. return되는 값들은 클라이언트한테 보여줄 데이터로, 패스워드는 노출될 필요가 없기 때문에 제외했다. 버추얼은 가상으로 필터링해서 나간다는 개념으로 이해하면 된다. 단순히 사용자가 보게되는 영역이며 DB에 존재하지 않는다. 때문에 schema class Cat 내부에 추가를 해 줄 때에도 readonly로, readonly readOnlyData 이렇게 추가한다.

(4) DB 저장

유효성 검사 때 catModel의 exists 메서드를 사용했던 것처럼 이번에는 catModel의 create 메서드를 사용한다. create 메서드를 이용하여 DB에 값을 저장할 수 있다. 회원가입 서비스에서 DB에 저장해야 하는 데이터는 email, name, 암호화된 hashedPassword이다. 값들을 object 형식으로 나타내면 아래와 같다.

const cat = await this.catModel.create({
  email,
  name,
  password: hashedPassword,
});

return cat.readOnlyData;

password가 들어 있지 않은 cat.readOnlyData 버추얼 필드를 return 해 주면 회원가입 서비스 로직 1차적으로 끝!

@Post()
  async signUp(@Body() body: CatRequestDto) {
    return await this.catModel.signUp(body); // 프로미스를 리턴해서 await

controller에서 미완성된 코드를 완성시키고 postman에서 실행하면 mongoDB Compass에 데이터가 들어가 있는 것을 확인할 수 있다.

DTO는 Nest의 디자인 패턴 중 하나로, 계층간 데이터 교환을 위한 객체이다. 즉, 데이터를 송수신할 때의 규격이라고 생각할 수 있다. Request용 DTO와 Response용 DTO는 View를 위한 클래스가 된다.

위 그림처럼 클라이언트가 body에 실어서 보내는 데이터를 DTO 객체로 만들어서 validation을 하고 타이핑 검사를 한 후 안전하게 Controller로 보낸다. 이 DTO는 Service를 거쳐 DB까지 도착한다.

class CatRequestDto {
  @IsEmail()
  @IsNotEmpty()
  email: string;

  @IsString()
  @IsNotEmpty()
  password: string;

  @IsString()
  @IsNotEmpty()
  name: string;
}

src 내 프로젝트 폴더 안에 dto라는 폴더를 만들고 cats.request.dto파일을 만들었다. CatRequestDto 객체에는 회원가입할 때 필요한 정보인 email과 password, name이 있다. 이 CatRequestDto를 controller의 회원가입 메서드 인자에 타이핑해 준다.

... signUP(@Body() body: CatRequestDto) {
  return this.catsService.signUp(body) ...

이제 body에 실어 보내진 데이터는 DTO 객체로 만들어져서 validation과 타이핑 검사를 통해 안전하게 받아진다. 만약 email을 email 형식으로 작성하지 않았거나 입력하지 않았으면 에러가 발생할 것이다.

ODM?

ODM은 Object Document Mapping의 줄임말이다. 객체와 문서를 1대1 매칭한다는 뜻이다. Object는 자바스크립트의 객체, Document는 몽고디비의 문서이다. ODB은 문서를 DB에서 조회할 때 자바스크립트 객체로 바꿔 준다. 그리고 몽고디비의 ODM으로 가장 많이 사용되는 게 바로 몽구스다. 🐭

🧀 몽구스 설치와 몽고DB 연결

npm install --save @nestjs/mongoose mongoose

⁝
import { MongooseModule } from '@nestjs/mongoose';

@Module({
  imports: [CatsModule, MongooseModule.forRoot('몽고디비URI')],
⁝

몽구스 설치가 완료되었으면 몽구스의 module을 app.module에 import 해 주고 몽고디비 URI를 넣어 준다. URI를 얻는 방법은 아래와 같다.

1. 몽고디비 cluster 들어가기
2. connect 버튼 클릭
3. Connect your application 버튼을 클릭
4. 이미지의 uri를 복사한다

🧀 환경 변수 설정하기

그런데 URI를 복사하여 MongooseModule.forRoot('몽고디비URI')에 붙여넣으면 URI가 날것의 주소 그대로 노출되고 만다. URI는 반드시 노출을 막아야 하기 때문에 환경 변수를 설정해 줄 필요가 있다.

환경 변수 설정을 위해서는 별도의 설치와 import가 필요하다. (공식 홈페이지 TECHNIQUES의 Configuration 참고)

$ npm i --save @nestjs/config

⁝
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [ ConfigModule.forRoot(), MongooseModule.forRoot('몽고디비URI')]
⁝

설치와 import를 마치면 환경변수 관리 파일 .env를 사용할 수 있다. .env 파일은 프로젝트 폴더 가장 상위 루트에서 생성해 주면 된다. 이렇게 생성된 파일에 아까 복사했던 몽고디비 URI 값을 MONGODB_URI = "복사했던 몽고디비 URI 값" 형태로 저장한다.

날것의 URI가 들어 있던 app.module 파일의 MongooseModule.forRoot('몽고디비URI') 중 '몽고디비URI' 부분을 process.env.MONGODB_URI로 수정해 준다. 첫 번째 인자 설정을 마쳤으면 이제 두 번째 인자를 넣어 줄 차례다.

완성된 코드로 보면 아래와 같다.

⁝
@Module({
  imports: [
    ConfigModule.forRoot(),
    MongooseModule.forRoot(process.env.MONGODB_URI, {
      useNewUrlParser: true,    // 몽구스에서 필요로 하는 두 번째 인자 -1
      useUnifiedTopology: true,    // 몽구스에서 필요로 하는 두 번째 인자 -2    
    }),
    CatsModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
  ⁝

몽고디비 URI 외에도 포트 넘버 등을 환경 변수에 넣어 관리할 수 있다. main에서 사용하고 있는 포트 넘버를 .env에 넣고 설정을 해 보았다.

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new HttpExceptionFilter());
  const PORT = process.env.PORT; // .env에 저장된 포트 넘버
  await app.listen(PORT);
}

🧀 console에 몽구스 쿼리 출력 설정

개발할 때 몽구스의 쿼리를 로그로 찍어 줄 수 있다. app.module 파일에 몽구스를 import * as mongoose from 'mongoose';로 import한다. 그리고 AppModule 클래스에서 export 하는 코드 mongoose.set('debug', true)를 작성한다. 이렇게 하면 쿼리가 로그로 찍힌다.

하지만 프로덕션 배포를 하게 될 때엔 해당 로그가 필요없다. 개발 모드와 프로덕션 모드를 구분해 주기 위해서 환경변수를 사용해 준다. .env에 MODE = 'dev'로 구분해 주는 코드를 작성했다.

app.module로 다시 이동해서 processe.env.MODE가 'dev'일 때만 로그가 찍히도록 삼항 조건 연사자를 이용한다. 완성된 클래스 코드와 찍힌 쿼리는 아래와 같다.

export class AppModule implements NestModule {
  private readonly idDev: boolean = process.env.MODE === 'dev' ? true : false;
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes('*');
    mongoose.set('debug', this.idDev);
  }
}

// 찍힌 쿼리 적기

개발할 때는 true가, 아닐 때에는 false 되어서 쿼리가 찍히지 않게 된다.

느낀점 포스팅을 정리하면서 환경 변수를 왜 사용하는지에 대한 이해를 할 수 있었다. 노출되면 안 될 중요한 정보들은 환경 변수에 담자.

몽고디비를 연결할 때, 몽구스의 쿼리를 보고자 설정할 때 모두 app.module과 관련이 있다. .env에서 환경변수를 설정하고 app.module로 가자.

인터셉터는 의존성 주입이 가능한 @Injectable() 데코레이터 주석이 달린 클래스이며 NestInterceptor 인터페이스를 구현해야 한다. 인터셉터는 AOP(Aspect Oriented Programming) 기술에서 영감을 받은 유용한 기능 세트가 있다. 관점 지향 프로그래밍(AOP)은 cross-cutting concern으로 모듈성을 증가시키는 것이 목적인 프로그래밍 패러다임이다.

Request lifecycle에 따르면 request가 들어오고 middleware, guards 그리고 pre-controller 인터셉트 순으로 실행된다. controller 실행 전에 시작되는 것이다. 그 이후 pipe, controller, service, 다시 post-request 인터셉트가 실행된다. 만약 끝까지 도달 전에 예외가 발생하면 바로 예외 필터로 나간다.

Summary

In general, the request lifecycle looks like the following:

Incoming request Globally bound middleware Module bound middleware Global guards Controller guards Route guards Global interceptors (pre-controller) Controller interceptors (pre-controller) Route interceptors (pre-controller) Global pipes Controller pipes Route pipes Route parameter pipes Controller (method handler) Service (if exists) Route interceptor (post-request) Controller interceptor (post-request) Global interceptor (post-request) Exception filters (route, then controller, then global) Server response

파이프는 @Injectable() 데코레이터 주석이 달린 클래스다. 파이프의 일반적인 사용 사례는 다음과 같다.

• 변환 : 입력 데이터를 원하는 형식으로 변환(예: 문자열에서 정수로)
• 유효성 검사 : 입력 데이터가 사용자가 정한 기준에 유효하지 않은 경우 예외를 던짐.

파이프는 클라이언트 요청에서 들어오는 데이터를 유효성 검사 및 변환을 수행하여 서버가 원하는 데이터를 얻을 수 있도록 도와주는 클래스다. 하나의 인풋이 들어오면 특정 로직을 걸쳐 아웃풋을 뱉는다. 아웃풋은 또 다음 함수로 들어가서 또 다시 아웃풋을 뱉는다. 각각의 함수들은 자신들의 자리에서 기능을 수행한 후 다음 함수에게 넘겨 주는 역할을 한다. 위 그림상에서 Task B가 필요없어진다면 바로 빼 버릴 수 있다. 이렇게 유지 보수가 편리하다는 장점이 있다.

입력 데이터를 원하는 형식으로 변환하는 '변환' 역할은 미들웨어와 비슷하게 보인다. 미들웨어도 요청과 응답에 변형을 가하는 동작을 한다. 단, 미들웨어는 현재 요청이 어떤 핸들러에서 수행되는지, 어떤 파라미터를 가지고 있는지에 대한 실행 컨텍스트를 알 수 없다. 이 차이점이 곧 파이프를 사용하는 목적과도 같다.

🌼 바인딩 사용 예시

  @Get(':id')
  getOneCat(@Param() param) {
    console.log(param); / { id: '243' }
    return 'one cat';
  }

http://localhost:3000/cats/243로 요청을 보내면 console에 param 값으로 오브젝트 형식의 { id: '243' }를 응답한다. 여기에 Param의 인자로 명확한 key값을 알려 주게 되면 파라미터는 id값의 value인 243을 뱉는다.

  @Get(':id')
  getOneCat(@Param('id') param) {
    console.log(param);     / 243
    console.log(typeof param);  / string
    return 'one cat';
  }

console에 찍힌 243의 타입은 string이다. 하지만 id 값은 string 보다 number로 사용하는 경우가 많다. string을 number로 바꿔 주는 역할을 파이프가 한다. 그때 사용할 수 있는 게 ParseIntPipe이다.

  @Get(':id')
  getOneCat(@Param('id', ParseIntPipe) param: number) {
    console.log(param);     / 243
    console.log(typeof param);  / number
    return 'one cat';
  }

console에 찍힌 타입이 number로 변환된 것을 확인할 수 있다. 만약 동적 라우팅에 abc 같은, number로 변환될 수 없는 값으로 호출이 된다면 예외 처리 메시지(Validation)를 자동으로 띄워 준다.

🌼 파이프 직접 만들어 보기

import { Injectable, PipeTransform } from '@nestjs/common';

@Injectable()
export class PositiveIntPipe implements PipeTransform {
  transform(value: number) {
    return value;
  }
}

이 파일의 transform() 함수가 위 그림의 Task다. 이 클래스를 @Param('id', ParseIntPipe, PositiveIntPipe)에 적용시킬 수 있다. Task A는 ParseIntPipe, Task B는 PositiveIntPipe가 되는 것이다. A에서 나온 결과값은 B의 value로 들어간다. 예를 들어 2.2라는 값이 A를 지나면서 2로 변경되고 이 값을 B가 받는 것이다. 이렇게 파이프들을 쭉 타고 가다 보면 최종 결과값인 param을 받게 된다.

import { Injectable, PipeTransform, HttpException } from '@nestjs/common';

@Injectable()
export class PositiveIntPipe implements PipeTransform {
  transform(value: number) {
    if (value < 0) {
      throw new HttpException('value가 0보다 작습니다.', 400);
    }
    return value;
  }
}

이렇게 exception을 낼 수도 있다. http://localhost:3000/cats/-24.3 은 0보다 작다는 예외 처리에 걸려서 작성해 놓은 오류 코드를 낸다. 파이프는 이렇게 동작한다.

Nest에는 모든 예외를 처리하는 자체 예외 레이어를 가지고 있다. 애플리케이션 코드에서 예외 처리를 하지 않아도 알아서 보기 쉬운 형식으로 에러를 변환하여 전송한다.

🌼 표준 예외 처리

각각 400과 500의 에러 코드를 Nest가 보낸 결과는 아래와 같다.

{
  "statusCode": 404,
  "message": "Cannot Get /dfesd",
  "error": "Not Found"
}

{
  "statusCode": 500,
  "message": "Internal server error"
}

기본적으로 이 작업은 내장된 전역 예외 필터에 의해 수행된다. 전역 예외 필터는 HttpException의 예외를 다루며, 인식할 수 없는 에러(HttpException도 아니고, HttpException를 상속받지도 않은 에러)의 경우 내장 예외 필터가 위와 같은 기본 JSON 응답을 생성한다.

만약 아래와 같은 라우트 핸들러에서 예외를 던지면 에러를 다음처럼 응답한다.

  @Get()
  getAllCat() {
    throw new HttpException('api is broken', 401);
    return 'all cat';
  }

{
  "statusCode": 401,
  "message": "api is broken"
}

statusCode와 message가 강제되어서 출력되는 것을 확인할 수 있다. Nest가 제공하는 대로 예외를 처리할 수도 있지만 서비스의 형태에 따라 에러를 핸들링할 때 커스텀을 할 수도 있다.

• statusCode : status인수에 제공된 HTTP 상태 코드
• message : 해당 HTTP 오류에 대한 간략한 설명

기본적으로 JSON 응답 본문에는 위의 두 가지 속성이 포함된다. JSON 응답 본문의 메시지 부분을 재정의하려면 응답 인수에 문자열을 입력하면 된다. 전체 JSON 응답 본문을 재정의하고 싶다면 아래의 코드처럼 응답 인수에 객체를 전달한다. Nest는 전달받은 객체를 직렬화하고 JSON 응답 본문으로 반환한다.

  @Get()
  getAllCat() {
    throw new HttpException({ success: false, message: 'api is broken!' });
    return 'all cat';
  }

{
  "success": false,
  "message": "api is broken!"
}

이렇게 원하는 형식으로 바꿔 커스텀을 하면 오버라이딩되어 출력이 된다.

🌼 예외 필터

예외 처리의 재사용성을 고려하여 하나로 모여 필터링을 걸친 후 response로 반환해 주는 형식으로 예외 필터를 만들 수 있다. 예외 필터를 만들기 위해 공식 홈페이지를 참고하여 http-exceiption.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.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();

    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
    });
  }
}

이렇게 생성된 필터를 적용하는 방법에는 두 가지가 있다. (1) @UseFilter() 데코레이터로 controller에 각각 적용하는 방법 (2) 전역에서 적용하는 방법이 있는데 보통 전역 필터 하나만 가지는 게 더 일반적인 방법이라고 한다.

(1) controller에 각각 적용하는 방식

  @Get()
  @UseFilters(HttpExceptionFilter)
  getAllCat() {
    throw new HttpException('api is broken', 401);
    return 'all cat';
  }

@UseFilters(HttpExceptionFilter)를 데코레이터로 넣으면 throw new ~에서 발생된 에러가 HttpExceptionFilter에서 필터링되어 response에 전달된다.

{
   "statusCode":401,
   "timestamp":"2022-01-06T02:54:26.555Z",
   "path":"/cats"
}

이전과는 예외 처리의 JSON과는 조금 다르게 찍힌 것을 확인할 수 있다. 이렇게 나타난 이유는 바로 HttpExceptionFilter에서 필터링을 거쳤기 때문이다. 해당 클래스를 보면 response.status(status).json으로 위 세 가지 속성을 받는다. 즉, 여기서 변경하는 것으로 커스텀이 가능하다.

'api is broken' 메세지를 예외 필터에 포함시키려면 exception.getResponse() 메서드를 이용할 수 있다. 'api is broken' 인자가 getResponse로 전달되어 에러 메시지가 찍힌다.

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.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();
    const error = exception.getResponse();

    response.status(status).json({
      success: false,
      timestamp: new Date().toISOString(),
      path: request.url,
      error,
    });
  }
}

error는 key와 value가 똑같기 때문에 생략했다. 이 상태에서 요청을 보내면 아래처럼 에러 코드가 발생한다.

{   
   "success":false,
   "timestamp":"2022-01-06T03:06:04.940Z",
   "path":"/cats",
   "error":"api is broken"
}

이처럼 controller 내부 라우터 각각에 @UseFilters(HttpExceptionFilter)를 데코레이터로 넣을 수도 있고 아래처럼 @Controller 데코레이터 바로 밑에 딱 하나만 넣어 줄 수도 있다.

@Controller('cats')
@UseFilters(HttpExceptionFilter)
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

...

실행 내용은 당연히 둘이 동일하다.

(2) 전역으로 적용하는 방식

http-exceiption.filter.ts 파일에 HttpExceptionFilter 클래스를 만드는 것까지는 동일하다.

import { HttpExceptionFilter } from 'src/http-exception.filter';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new HttpExceptionFilter());  // 전역 필터 적용
  await app.listen(3000);
}
bootstrap();

useGlobalFilters를 추가해 주면 된다. 404 에러는 아래와 같이 뜬다.

{
  "success":false,
  "timestamp": "2021-10-04T09:53:19.086Z",
  "path": "/cats",
  "error": {
    "statusCode": 404,
    "message": "Cannot GET /cat324234",
    "error": "api is broken"
  }
}

미들웨어는 라우트 핸들러 이전에 호출되는 컴포넌트다. 라우트 핸들러란 엔드포인트마다 동작을 수행하는 컴포넌트를 뜻한다. 라우트 핸들러는 요청 경로와 컨트롤러를 매핑해 주고, 미들웨어는 이런 라우트 핸들러 이전에 실행된다.

미들웨어는 다음과 같은 동작을 할 수 있다.

• 어떤 코드든 실행 가능하다
• 요청과 응답에 변형을 가할 수 있다
• 요청-응답 생명주기를 끝낼 수 있다
• 미들웨어는 순서가 있다. 여러 개의 미들웨어를 사용 중이라면 next()로 다음 미들웨어에게 제어권을 전달한다.

요청-응답 생명주기를 끝낸다는 것은 (1) 응답을 보내거나 (2) 에러 처리를 하는 것을 뜻한다. 생명주기를 끝내지 않을 때에는 next() 호출로 다음 미들웨어에게 제어권을 주어야 한다.

미들웨어로 수행하는 작업들은 보통 다음과 같다.

• 쿠키 파싱 : 쿠키를 파싱하여 사용하기 쉬운 데이터 구조로 변경한다.
• 세션 관리 : 세션 쿠키를 찾고 상태를 조회해서 요청에 세션 정보를 추가한다.
• 인증/인가 : 사용자가 서비스에 접근 가능한 권한이 있는지 확인한다.
• body 파싱 : POST/PUT 요청으로 들어오는 json 타입의 본문 및 파일 스트림과 같은 데이터들을 유형에 따라 해석하여 파라미터에 넣는 작업을 한다.

🌼 CLI를 통한 미들웨어 생성과 구현

$ nest g middleware 미들웨어명

일전에 모듈을 생성했던 것과 같은 방식으로 미들웨어를 생성할 수 있다. 생성한 미들웨어의 기본 코드 기반으로 logger를 구현해 봤다.

import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  private logger = new Logger();

  use(req: Request, res: Response, next: NextFunction) {
    res.on('finish', () => {
      this.logger.log(
        `${req.ip} ${req.method} ${res.statusCode}`,
        req.originalUrl,
      );
    });
    next();
  }
}

첫 번째 특징으로는 express에서 봤었던 use와 next()다. 실제로 Nest의 미들웨어는 기본적으로 express 미들웨어와 동일하다. Nest 역시 express의 미들웨어처럼 use를 이용해서 미들웨어를 사용할 수 있다.

두 번째 특징으로는 서비스단에서 봤었던 @Injectable()가 미들웨어에서도 보인다는 점이다. 즉, 의존성 주입으로 모듈단에서 공급자로 취급되었던 서비스단처럼 미들웨어 역시 의존성 주입을 할 수 있다.

이렇게 생성된 미들웨어는 바로 사용할 수 없다. 공급자는 만들어졌으나, app.module 모듈에 보내 주어야(의존성 주입을 해 주어야) 실행할 수 있다. 다만 다른 공급자들처럼 @module() 데코레이터 내에 넣는 게 아니라 모듈 클래스의configure() 메서드를 통해 미들웨어를 설정한다. 공식 홈페이지에서 제공하는 코드를 적용한 예는 다음과 같다.

import { CatsModule } from './cats/cats.module';
import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { LoggerMiddleware } from './logger.middleware';

@Module({
  imports: [CatsModule],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes('cats');
  }
}

LoggerMiddleware는 위 코드에서 볼 수 있듯이 의존성 주입이 가능한 제공자(provider)다. 그리고 consumer.apply(LoggerMiddleware) 는 말 그대로 consumer 소비자에게 LoggerMiddleware를 제공해 준다는 뜻이다. NestModule은 약속을 추가해 준 인터페이스를 의미한다.

forRoutes('cats')은 cats 라우터에 바인딩을 해 주는 것이다. '*' 와일드카드를 넣으면 전체 경로를 뜻하게 된다. 이렇게 .forRoutes 뒤에 오는 경로로 들어오는 요청을 수행하면 logger.middleware의 use 안의 내용이 실행되는 것을 확인할 수 있다.

NestJS 공식 사이트에 따르면 모듈은 @Module() 데코레이터가 주석으로 달린 클래스다. @Module() 데코레이터는 메타데이터를 제공하고, 이 메타데이터는 애플리케이션 구조를 구성하는 데 사용한다.

일반적으로 모듈은 조그만 클래스나 함수처럼 한 가지 일만 수행하는 소프트웨어 컴포넌트가 아니라, 여러 컴포넌트를 조합하여 작성한 좀 더 큰 작업을 수행하는 단위이다. 즉, 하나의 루트 모듈이 존재하고 이 루트 모듈은 다른 여러 개의 모듈들로 구성된다. 사진처럼 하나의 App Module, 루트 모듈로 향하는 형태이다.

이론적으로 루트 모듈 하나만 존재하는 것도 가능하지만 Nest는 기능별로 모듈을 나눠 사용하는 것을 더 추구한다. 모듈을 쪼개서 사용하는 이유는 여러 모듈에게 각자의 책임을 나누고 응집도를 높이기 위함이다.

import { CatsModule } from './cats/cats.module';
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { UsersModule } from './users/users.module';

@Module({
  imports: [CatsModule, UsersModule],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

app.module.ts 파일(루트 모듈)을 보면 이렇게 여러 모듈이 import되어 있다. 그럼 이제 CatsModule과 UsersModule에서 export한 서비스들을 AppController나 AppService에서 사용할 수 있게 된다. 단, 해당 모듈들은 반드시 export된 상태여야 한다. export되어 있지 않다면 캡슐화로 인해 모듈의 공급자들(서비스)을 주입할 수 없게 된다.

🌼 CLI를 통한 모듈 생성

$ nest g <schematic> <name> [options]

인수에는 다양한 Schematic이 올 수 있다. (참고: https://docs.nestjs.com/cli/usages) Schematic 중 하나가 module이다. $ nest g module 모듈명으로 생성 가능하다. 모듈명에 제한은 없지만 공식 사이트에서는 복수형으로 짓고 있으니 복수형이 좀 더 좋은 선택(?)이 아닐까 생각해 본다.

명령어 사용을 하지 않고 하나하나 입력해서 모듈을 만들 수도 있지만, $ nest g module CLI 방법으로 모듈을 생성하게 되면 app.module.ts 파일에 생성한 모듈이 자동으로 import된다.

🌼 모듈과 캡슐화

모듈은 기본적으로 공급자를 캡슐화한다. 모듈에서 내보낸 공급자는 모듈의 공개 인터페이스 또는 API로 간주할 수 있다. 이 말은 곧 (1) 현재 모듈의 일부가 아니거나 (2) 가져온 모듈에서 export되지 않은 공급자는 주입할 수 없다.

import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  controllers: [CatsController],
  providers: [CatsService],
  exports: [],
  // exports: [CatsService], 으로 변경해야 사용 가능
})
export class CatsModule {}

위의 코드는 cat.module.ts파일의 모듈 코드이다. CatsService가 공급자로 있지만 export가 되어 있지 않은 상태다. 이 경우 해당 공급자는 루트 모듈(app.module.ts)에서 import 되었다 한들 사용이 불가능하다. 캡슐화가 되어 있기 때문에 접근할 수 없는 것이다. 모듈 사용을 위해서는 반드시 CatsService를 export 해 주어야 한다.

@Controller('cats')
export class AppController {
  constructor(private readonly appService: AppService) {}

  // localhost:3000/cats/info
  @Get('info/:id/:name')
  getHello(
    @Req() req: Request,
    @Body() Body,
    @Param() param: { id: string; name: string },
  ): string {
    console.log(param);
    return this.appService.getHello();
  }
}

NestJS는 클래스 내부에서 생성자로 초기화를 한 다음 이를 (this 초기화 없이) 바로 인자로 받아서 사용한다. 이러한 패턴이 의존성 주입(Injectable) 패턴이다. 의존성 주입은 공급자와 깊은 연관이 있다. 공급자의 주요 특성 중 하나가 종속성이 있는 제품들을 주입할 수 있다는 것이기 때문이다. 즉, controller는 이들을 주입받아서 사용하는 것이다. 또한 Nest 클래스의 대부분은 공급자로 취급될 수 있다. (서비스, 리포지토리, 팩토리 등 / 이것들은 종속성을 가진다는 의미와도 같다) 공급자로 취급되는 것들은 @Injectable() 데코레이터로 표현한다.

아래 코드는 AppController의 공급자로 사용되고 있는 app.service.ts 파일 코드다. 의존성 주입 데코레이터가 달린 것을 확인할 수 있다.

import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

AppController를 소비자, appService를 제품이라고 가정할 때, AppController가 공급된 제품을 appService라는 인스턴스로 의존성 주입을 받아서 해당 제품을 사용할 수 있다. 이처럼 제품을 공급해 주는 공급자(providers)는 app.module.ts안에서 확인할 수 있다.ㅤ

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

만약 providers 안에 있는 [AppService]를 제거하면 AppController의 의존성인 appService가 resolve되지 않아 오류가 발생한다. 제품(appService)에 대한 공급자(AppService)를 찾아가고 제품을 받아 소비자(AppController)에게 넘겨주어야 하는데, 제품의 공급자가 없으니 controller에서 제품을 사용할 수 없게 되는 것이다. 관계를 순전히 이해하기 편하게 만들면 아래의 표와 같다.

의존성 주입을 사용하는 이유는?

NestJS은 객체 지향 프로그래밍이다. 객체 지향 프로그래밍의 핵심 목표는 실생활과 유사하게 코드를 짜는 것이다. 의존성 주입을 하게 되면 실생활과 같은 공급자-소비자의 관계가 명료하게 나타난다. 이렇게 함으로써 유지보수도 간편해지고 확장성 있게 더 탄탄한 백엔드 애플리케이션을 짤 수 있게 된다.

NestJS의 package.json에는 엄청 많은 확장 모듈이 기본적으로 깔려 있다. dependencies 살펴 보면 그 기능은 다음과 같다.

"dependencies": {
    "@nestjs/common": "^8.0.0",
    "@nestjs/core": "^8.0.0",
    "@nestjs/platform-express": "^8.0.0",
    "reflect-metadata": "^0.1.13",
    "rimraf": "^3.0.2",
    "rxjs": "^7.2.0"
  }

1. @nestjs/common @nestjs/core @nestjs/platform-express : NestJS 안에서 자체적으로 동작하는 라이브러리.
2. reflect-metadata : 데코레이터 사용과 관련된 패키지.
3. rimraf : 지정한 파일이나 폴더를 지우는 rm --rf 명령어를 윈도우에서 사용할 수 있게 해주는 패키지.
4. rxjs : 비동기 및 이벤트 기반 프로그래밍을 작성하기 위한 라이브러리.

controller

controller(app.controller.ts)는 들어온 요청을 처리하고 클라이언트에 응답을 반환한다. 클라이언트에서 HTTP request를 보내면 controller가 이를 받아서 응답을 하는 구조다.

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

controller를 들어가 보면 AppController 클래스 안에서 appService를 사용하기 위해 의존성 주입을 한 걸 볼 수 있다. 그래서 해당 클래스에서 appService를 사용할 수 있고, appService 내부 메서드의 return 값이 controller에 내부에서 실행되어 반환된다.

물론 controller에서도 바로 return을 할 수 있지만 Nest는 그것을 지양한다. NestJS는 controller를 비지니스 로직과 구분 짓고 싶어 한다. 즉, controller는 그저 url을 매핑하고, 리퀘스트를 받고, 쿼리나 Body 등의 것들을 넘기는 역할만을 할 뿐이다. 비지니스 로직, 일반적인 실제의 기능 함수는 service단으로 간다.

조금 복잡하지만 유지보수와 가독성에 더 유리하다..고 한다. 😇

🌼 라우팅 (Routing)

또한 controller의 데코레이터에서 라우팅을 할 수 있다. (아래처럼)

@Controller('customers')
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('profile')
  getHello(): string {
    return this.appService.getHello();
  }
}

라우팅 경로는 @Get 데코레이터의 인자가 된다. 이렇게 라우팅을 설정하면 localhost:포트넘버/customers로 경로 접두사(prefix)를 지정할 수 있다. customers 경로 접두사와 데코레이터 @Get('profile')을 결합하면 GET /customers/profile로 경로가 매핑된다. 데코레이터에서 경로 접두사를 사용하면 반복적인 코드를 최소화할 수 있고 쉬운 그룹화가 가능하다.

🌼 요청 객체 (Request object)

import { Controller, Get, Req } from '@nestjs/common';

  @Get('profile')
  getHello(@Req() req: Request): string {
    console.log(req);
    return this.appService.getHello();
  }

NestJS에서는 req, res 같은 요청 객체를 데코레이터 패턴으로 사용할 수 있다. 전용 데코레이터를 함수 인자에 넣어 주면 되는데, 반드시 import 한 후 사용해야 한다. (아니면 빨간 줄 뜬다) 타입스크립트를 사용할 경우 Request 타입도 지정해 주면 좋다. 이렇게 사용할 수 있는 전용 데코레이터들은 다음과 같다.

🌼 라우트 파라미터

'lee'라는 고객의 프로필을 가지고 오기 위해 @Get('profile/lee')와 같이 요청해야 한다고 가정해 보자.

여기서 /lee에 해당되는 부분은 동적으로 구성된다. 즉, 경로 구성에 사용되는 라우트 파라미터가 된다. 전달받은 파라미터는 함수 인자에 @Param 데코레이터로 주입(의존성 주입)받을 수 있다. 복수의 라우트 파라미터를 받는 상황이라면 아래 코드처럼 파라미터를 따로따로 받는다. 이때, @Param 데코레이터 괄호 안의 &&는 ~

  @Get('profile/:name/:cusNum')
  getHello(
   @Param('name') name: string,
   @Param('cusNum') cusNum: number,
  ): string {
    console.log(req);
  }

💨 미들웨어의 기본 코드

app.use(['실행될 특정 url'](req, res, next) => {
    모든 요청에 실행하고 싶은 코드;
    next();
})

코드의 req부터 next까지의 함수를 미들웨어라고 부른다. 이 미들웨어를 use에 장착했다고 생각하면 더 편하다. (use 자체가 미들웨어 ❌)

💨 미들웨어의 특성

미들웨어에 작성한 코드는 모든 라우터(메소드와 주소가 있는 것)에서 다 실행된다. express는 기본적으로 위에서 아래로 코드가 실행되지만, 미들웨어는 next()를 반드시 해 줘야만 다음 코드로 넘어간다.

이때 next는 반드시 다음 라우터가 실행된다는 의미가 아니라 순서는 아래로 향하되 요청에 따른 응답을 한다. 만약 next 다음에 와일드카드 라우터가 있을 경우 예상 외의 결과가 발생할 수도 있기 때문에(와일드 카드 라우터보다 아래에 있는 라우터 대신 실행된다는 등) 와일드카드 라우터나 범위가 넓은 라우터들은 라우터의 가장 아래에 둔다.

💨 에러 처리의 미들웨어

express는 에러가 발생했을 경우 기본적으로 에러 처리를 해 주지만 노출되는 에러문 구가 보안상 문제될 수도 있기 때문에 따로 에러 처리를 해 준다. 에러 처리 역시 미들웨어다.

app.use((err, req, res, next) => {
    console.error(err);
    res.[status(500).]send('에러 메시지');
})

에러 미들웨어는 반드시 err, req, res, next 네 개의 매개변수를 모두 작성해야 한다. next가 빠지게 되면 아예 다른 함수로 인지한다. res 뒤에는 기본값으로 .status(200)이 생략되어 있기 때문에 따로 status 값을 지정해 주지 않으면 클라이언트 상에서는 200 코드가 뜬다. 즉, 에러가 아니라고 뜬다. 에러 코드는 오히려 보안상 문제가 일어날 수 있어서🙄 실무에서는 보통 200번대 위주로 사용한다고 한다. 에러 코드는 조심해서 사용할 것.

404 에러의 경우 라우터들 최하단, 에러 미들웨어 위에 새로운 미들웨어를 만들어 404 에러 처리 미들웨어로 사용할 수 있다. 이 경우 에러는 아니고 404 처리 미들웨어 정도로 생각하면 된다.

app.use((req, res, next) => {
    res.[status(404).]send('404 error');
    next();
})

💨 static 미들웨어

app.use('/', express.static(path.join(__dirname, 'public')));
// app.use('요청 경로', express.static(path.join('실제 경로')));

static 미들웨어는 정적인 파일들(css, html, js)를 처리할 때 사용된다. 요청 경로와 실제 경로는 다르다.

예를 들어, localhost:3000/bin-lee.html은 요청 경로다. 하지만 실제로 이 html 파일이 public이라는 폴더 안에 있다면 실제 경로는 public/bin-lee.html이 된다.

요청 경로와 실제 경로가 다르기 때문에 클라이언트는 실제 경로를 알 수 없게 된다. 때문에 static을 사용하면 보안 면으로 유리한 면이 있다.

💨 express-session 미들웨어

요청마다 개인의 저장 공간을 만들어 주는 게 express-session이다.

💨 미들웨어 순서

미들웨어 간에는 순서도 중요한데, 요청 주소에 따라 미들웨어가 어디까지 실행되느냐가 달라진다. 순서 배치에 따라 실행될 필요도 없는 미들웨어가 실행되면서 비효율적으로 동작할 수 있다. 정해진 건 없고 서비스에 따라 조정하면 된다.

내가 찾아본 코드는 morgan > static > cookieParser > session > express.json > express.urlencoded > multer의 순서로 사용했었다.

에러.zip

1. 한 라우터에서 res.send, res.json을 여러 번 보내면 에러 발생한다. 주의하자.
2. express에서 http 방식인 writeHead와 end를 사용하지 않는 편이 좋다. express 전용인 send를 씁시다.
3. 자바스크립트는 return을 해야 함수가 끝난다. res.json 밑에 console을 찍어도 실행된다.

npm deprecate [패키지명/버전/메시지] : 패키지를 설치할 때 경고 메시지를 띄운다. npm publish : 자신이 만든 패키지 배포 npm unpublish : 자신이 만든 패키지 배포 중단 (72시간 내에만)

https://docs.npmjs.com에서 더 많은 CLI Commands에서 확인 가능!

파이썬의 pip처럼 노드에서 사용하는 패키지 매니저다. 다른 사람들이 이미 만들어 둔 소스 코드를 npm으로 설치한 후 사용할 수 있다.

package.json

현재 프로젝트에 대한 정보와 사용 중인 패키지에 대한 정보를 담은 파일이다. 같은 패키지라도 버전에 따라 기능이 다르고, 다른 버전을 사용할 경우 문제가 생길 수 있기 때문에 package.json에 버전을 기록해 둬야 한다. 📌 노드 프로젝트 시작 전 npm init으로 package.json을 만들고 시작했다.

💨 npm init으로 package.json 생성

package name: 패키지의 이름 작성 uthor: 작성자 이름 license: 오픈 소스인 MIT를 많이 사용

npm init 말고 json 형식을 따라서 직접 작성하는 것도 가능하다. 단, 직접 작성의 경우 꼭 마지막에 npm i를 해 주어야 설치가 마무리 된다!

💨 package.json의 구조

생성할 때 입력했던 정보들이 JSON 형식으로 들어가 있다. "scripts" 안에 있는 명령어들은 npm run 명령어명으로 사용할 수 있다. start라는 시작 실행 명령어가 자주 쓰인다. (start는 run을 제외 가능하다)

npm i

💨 npm i로 패키지 설치

npm i 패키지명으로 패키지 설치를 할 수 있다. 설치를 마치면 package.json 파일에 "dependencies"가 추가된다. 이 안에는 패키지들의 버전이 기록되어 있다. 버전이 정확하게 기록되어 있어야 해당 버전으로 오류 없이 설치된다.

npm i -D로 -D 옵션을 붙이면 "devDependencies"가 추가된다. devDependencies는 개발할 때만 사용하는 패키지, dependencies는 배포 및 서비스까지 쓰이는 패키지로 구분하여 설치한다.

💨 npm i -g로 패키지 설치

-g는 글로벌로 설치(전역 설치)한다는 의미이다. 명령어로 쓸 수 있는 패키지들은 글로벌로 설치하는 편이다. 설치를 해도 dependencies에 따로 기록이 안 되기 때문에 협업자가 해당 패키지를 사용하는지, 사용하지 않는지 알 수 없다. 그래서 요즘은 처음부터 전역 설치를 하는 걸 기피하고 npm i 혹은 npm i -D로 설치한 후 npx를 붙여 사용한다. npx를 붙이면 글로벌 명령어로써 사용된다. 관리가 훨씬 용이해진다.

node.modules

node.modules에는 다운받은 패키지들이 들어가 있다. 그런데 설치하지 않은 패키지들이 섞여 들어 있는 경우가 있다. 이는 설치한 패키지가 dependencies로 필요로 하는 패키지들이 설치된 것이다. 이것저것 설치되어 있어 용량이 크기 때문에 배포할 때는 지워서 배포하고, 배포 후 npm i로 그 서버에서 재설치하는 방식으로 사용한다.

package-lock.json

dependencies로 설치했던 것들의 dependencies들까지 모든 버전을 정확하게 기록해 놓은 파일이다. package-lock.json은 잘 건드리지 않는 편이다.

+ SemVer 버저닝

노드 패키지의 버전은 SemVer을 따라서 버전을 세 자리 수로 표현한다. Major -> Minor -> Patch 순이며 하위 버전과 호환되지 않는 수정, 하위 버전과 호환되는 수정, 버그 해결이 되었을 때 각각 버전을 올린다.

차이점

1. forEach for문을 간편하게 돌린다.
2. map for문을 돌려서 새로운 배열을 만든다.
3. reduce for문을 돌려서 최종적으로 다른 무언가를 만든다.
   

이렇게 reduce로 갈수록 하위 개념이며 좁은(명확한) 목적을 가지게 된다. 특히 map과 reduce는 새로운 배열 혹은 무언가를 만드는 목적이 있기 때문에 함수 내에 return을 필수로 가진다.

map

console value는 a가 순차적으로 출력된 1, 2, 3 i는 인덱스 순서대로 0, 1, 2 arr는 a 자체를 뜻하므로 [ 1, 2, 3 ] this는 [10]이다.

return값 this인 10에 value값을 더해 [ 11, 12, 13 ]이 출력된다.

reduce

배열.reduce((누적값, 현재값, 인덱스, 요소) => {return 결과}, 초기값)
배열.reduce(function(누적값, 현재값, 인덱스, 요소){return 결과}, 초기값)

reduce는 누적값이라는 개념이 있다. 누적값의 시작값은 초기값이다. 만약 초기값을 5으로 두면 누적값 역시 5로 시작하게 된다.

console acc는 누적값 10부터 시작하여 현재값을 더한 값으로 누적된다. 때문에 첫 번째 누적값은 10이고, 두 번째 누적값은 10에 현재값 1을 더한 11, 세 번째 누적값은 11에 현재값 2를 더한 13이 된다. cur은 배열에 들어 있는 현재값 1, 2, 3이다. i는 인덱스 0, 1, 2이다.

이렇게 reduce는 누적값에 현재값을 더한 값이 다음 누적값으로 누적된다.

return값 acc인 13에 cur 3이 더해져서 16이 출력된다.

그런데 초기값은 필수값이 아니다. 초기값을 지정하지 않을 때는 아래 코드처럼 동작한다.

console 초기값이 없으면 0번째 인덱스의 값이 초기값으로 지정된다. 0번째 인덱스 값은 1이므로 첫번째 누적값 역시 1이다. 이후 누적되는 과정은 위와 동일하다.

리터럴(literal)

먼저 아래는 리터럴을 사용한 값의 예시들이다. 예시만 보면 전혀 어렵지 않고 익히 알고 있는 내용이다.

100 정수 리터럴 'Hi!' 문자열 리터럴 false 불리언 리터럴 { name: 'Kim', age: 11 } 객체 리터럴 [ 0, 1, 2 ] 배열 리터럴 function() {} 함수 리터럴 ...

리터럴은 <사람이 이해할 수 있는 문자 / 또는 약속된 기호를 사용해 / 값을 생성하는 표기법>이다. 문장을 나눠서 보면 좀 더 편하다.

사람이 이해할 수 있는 문자는 영어, 한국어, 숫자 등이 약속된 기호로는 중괄호, 소괄호, 대괄호, 홑따옴표 등이 있다.

이런 것들로 값을 표기하는 방법이 리터럴인 것이다. 즉, 값 생성을 위해 미리 약속된 표기법이다.

템플릿 리터럴(template literal)

템플릿 리터럴은 ES6에서 새롭게 추가된 문자열 표기법이다. 기존 문자열 표기는 쌍따옴표(")와 홑따옴표(')로만 표현이 가능했는데, 템플릿 리터럴이 도입되면서 백틱(``)을 사용할 수 있게 되었다.

let a = 'abc'
let b = "abc"
let c = `abc`

a === b
b === c
a === c

위 결과를 보면 백틱 기호를 사용한 템플릿 리터럴과 스트링 리터럴(문자열 리터럴) 값이 같다는 것을 알 수 있다.

그런데 왜! 얘는 혼자 템플릿으로 이름이 다를까? 분명 다른 특징이 있기 때문에 이름이 다를 것이고, 템플릿 리터럴이 독자적으로 가지고 있는 특징은 다음과 같다.

템플릿 리터럴의 특징

1. 멀티라인 문자열

   var a = 'abc\n' + 'def'

기존의 스트링 리터럴이 위와 같은 이스케이프 시퀀스를 이용해 개행을 했다면, 템플릿 리터럴에선 아래처럼 엔터만으로 개행이 가능하다.

let b = `abc
def`

다만 템플릿 리터럴은 백틱 사이에 들어간 모든 뎁스를 전부 문자열로 인식하기 때문에 그 점을 고려해야 한다. 고운 정렬(?)이 좋다면 백틱 기호 안에 이스케이프 시퀀스를 동일하게 작성해 주면 된다.

let b = `abc\n` +
    `def`

이렇게 되면 기존 방법이랑 다를 바가 없기 때문에 애매한 느낌이 들지만, ${}을 이용해서 보간을 할 계획이라면 백틱이 더 좋은 선택일 수 있겠다.

2. 표현식 삽입

   const a = 10
   const b = 20
   

const before = a + ' + ' + b + ' = ' + ( a + b ); const after = ${a} + ${b} = ${ a + b }

``` before과 after의 과정은 다르지만 모두 10 + 20 = 30이라는 같은 결과가 나온다. ${} 안에는 값과 식이 들어올 수 있기 때문에 이를 이용해서 이전보다 훨씬 쉬운 표현식 삽입이 가능하다.