class-validator 의 @IsBoolean 데코레이터와 enableImplicitConversion 설정된 Transform 의 문제

개요

본 개요는 문제를 만나게 된 과정을 설명하고 있으므로, 이미 문제를 겪으신 분들은 생략하셔도 좋습니다.

 

NestJS에서는 애플리케이션에 필요한 설정(Configuration)들을 위해 `@nestjs/config` 패키지를 제공합니다. 환경변수 파일(대표적으로 .env 파일)에 기재된 환경변수(Environment variables)들은 위 패키지가 제공하는 `ConfigModule` 로 주입되며 애플리케이션 곳곳에서 이용될 수 있게 됩니다.

이 때, 파일에 기재되고 애플리케이션으로 불러온 환경변수가, 필수인데도 입력되지 않았거나 잘못된 포맷으로 입력되었는지 확인하지 않는다면 애플리케이션은 정상적으로 동작할 수 없습니다. 이러한 문제를 해결하기 위해 Joi 와 같은 패키지가 공식 문서를 통해 추천되고 있습니다. 해당 패키지는 `ConfigModule.forRoot` 모듈 주입에서 `validationSchema` 옵션으로 전달하여, 불러오는 환경변수의 타입이나 포맷, 값의 범위 등을 검사할 수 있게 합니다.

 

저는 예전부터 이 방식을 사용해 왔는데 Joi 패키지에 대한 의존성이 있다는 느낌이 들어 추가적인 패키지를 이용하는 대신, DTO 검사 등을 위해 이미 사용하고 있는 검증(Validation) 패키지인 class-validator 및 class-transformer 패키지를 기반으로 해당 환경변수 객체를 검사하는 방식으로 변경하고자 하였습니다. 해당 방식 또한 공식 문서에서 추천하고 있는 Custom Validation 방식입니다.

해당 방식은 특정 환경변수 그룹(도메인)을 Class로 만들고 class-validator 및 class-transformer 에서 제공하는 데코레이터들을 응용하여 환경변수들에 적용될 포맷을 지정합니다. 그리고 class-validator 에서 제공하는 `validateSync` 함수를 통해 해당 Class를 검사하여 올바른 환경변수가 입력되었는지 확인할 수 있게 합니다.

이 방식을 기반으로, 저는 `@ConfigValidation` 이라고 하는 클래스 데코레이터를 구현하여, `validateSync` 함수를 가지고 있는 검사함수를 Class 자체에 대입될 수 있도록 적용하였습니다. 그러면 Class가 선언 또는 생성될 때 클래스 데코레이터가 호출되며, 해당 클래스 데코레이터가 확장한 생성자(Constructor) 함수를 실행합니다.

 

결론적으로 `@ConfigValidation` 클래스 데코레이터가 확장한 생성자는 `process.env` 값을 해당 Class 를 기반으로 인스턴스화합니다. 그리고 `validateSync` 함수를 이용하여, 인스턴스 내부 멤버변수(환경변수)들이 올바른 포맷을 가지고 있는지 검사합니다. 검사 결과, 에러가 포함되었다면 해당 에러(`validateSync` 함수는 검증 결과 발생한 에러들을 `ValidationError[]` 배열로 반환합니다.)를 발생시키며, 에러가 발생하지 않으면 통과합니다. (생성자 함수이므로, 반환하는 값을 지정하면 `process.env` 에서 추출되어 생성된 해당 인스턴스를 반환할 수 있습니다.)

그 과정에서...

 

문제

데이터베이스의 환경변수들을 가지고 검사하는 `DatabaseConfigValidation` Class를 구현하고자 합니다.

데이터베이스를 위한 환경변수들을 아래와 같이 정의하였습니다.

데이터베이스 환경변수

데이터베이스의 환경변수 중 `DB_SYNC` 와 `DB_LOGGING` 환경변수들은 Boolean으로써 `true` 또는 `false` 값을 가집니다.

 

`DatabaseConfigValidation` Class는 아래와 같이 정의될 수 있습니다.

데이터베이스 환경변수 Class

각 환경변수들이 존재해야 하며, 필요한 포맷들을 검사하도록 설정하였습니다. 이 때, `DB_SYNC` 와 `DB_LOGGING` 환경변수들은 `boolean` 값을 가지기 때문에, `@IsBoolean` 데코레이터가 이용되었습니다.

 

해당 Class에 구현한 `@ConfigValidation` 데코레이터를 붙이도록 합니다. `@ConfigValidation` 데코레이터의 코드는 다음과 같습니다.

@ConfigValidation 데코레이터

 

해당 클래스 데코레이터는 클래스의 생성자를 확장(Extend)하여, 클래스 생성을 통해 실행될 수 있습니다. 개요에서 설명한 것과 같이 다음과 같은 로직을 가집니다.

1. class-transformer 패키지가 지원하는 `plainToInstance` 함수는 두번째 인자에 대입되는 값을 첫번째 인자에 대입되는 클래스 형태로 인스턴스화 해줍니다. 이 과정에서 class-transformer 가 제공하는 Transform(값에 맞는 타입 변경)가 동반될 수 있습니다.
2. class-validator 패키지가 지원하는 `validateSync` 함수는 해당 인스턴스에 포함된 각종 검증 데코레이터를 통해 각 멤버변수가 올바른 포맷을 가지고 있는지 검사합니다.
3. 에러가 있는 경우, 에러를 발생시키며, 그렇지 않은 경우 생성자 함수의 반환값으로 대입된 인스턴스를 반환합니다.

 

위의 과정에서 `plainToInstance` 함수는 `enableImplicitConversion` 이라는 옵션이 대입되어 있습니다.

enableImplicitConversion 옵션

이 옵션을 `true` 로 설정하는 경우, class-transformer 기능에 의해 해당 값이 가질 수 있는 대상 값을 자동으로(암시적으로) 형 변환해줍니다. 이것을 사용하는 이유는 환경변수로 대입된 값들을 원하는 변수의 타입으로 자동 형 변환하기 위함입니다.

 

DB_PORT 환경변수는 숫자 타입을 가집니다.

앞서 설정한 `DatabaseConfigValidation` 클래스의 `DB_PORT` 변수는 데이터베이스가 가지는 포트번호를 나타내며, 숫자 타입으로 다루고자 합니다.

그러나 환경변수 파일에서 불러오는 모든 값들은 기본적으로 문자열(String) 타입을 가집니다. 따라서 별도의 문자열 - 숫자 타입 변환이 필요한데, 이를 자동으로 해주는 것이 class-transformer 의 역할입니다.

이를 통해, 환경변수에서 초기 작성되었던 값(예를 들어, `DB_PORT=8000`)은 문자열 `"8000"` 으로 대입되나, `plainToInstance` 함수를 통과함에 따라 숫자 `8000` 으로 변형되어 이용할 수 있게 됩니다.

 

그런데 이와 똑같은 과정에서 `@IsBoolean` 데코레이터와 `boolean` 타입을 가진 `DB_LOGGING` 환경변수는 계속해서 `true` 값만을 가지고 있는 문제를 발견하였습니다.

DB_LOGGING 변수의 데코레이터들

 

`DatabaseConfigValidation` Class에 `@ConfigValidation` 데코레이터를 붙인 뒤, 생성 및 로그를 출력하여 확인해 보았습니다.

DatabaseConfigValidation Class

대입되는 환경변수들

실행하는 코드

 

그 결과 출력된 값은 환경변수에서 설정한 `false` 값이 아닌, `true` 값이 나옵니다.

코드 실행 결과

 

이것은 `@IsBoolean` 및 `boolean` 타입으로 설정된 `DB_LOGGING` 변수에 `false` 값이 대입되었지만, `plainToInstance` 값과 그 설정된 `enableImplicitConversion` 옵션으로 변경된 부울 값은 `true` 로 나온다는 의미입니다.

즉, `enableImplicitConversion` 옵션은 암시적 형 변환을 수행하면서, 대입된 변수가 문자열(String) 타입이고, 비어있지 않을 때, Boolean으로의 변환(Transform)을 시도한다면 이것들을 모두 `true` 로 변환한다는 것을 알 수 있습니다. (직관적으로 해석하면, 문자열이 존재하므로 해당 문자열은 '존재한다'로 인식하여 `true` 값이 되는 것입니다. 따라서 빈 값인 경우에는 `false` 로 변환됩니다.)

 

문제 해결

서두가 길었지만, 결론적으로는 class-transformer 의 자동 형 변환에서의 문제가 발생한 것이기 때문에 직접 형 변환을 수행해 주는 것으로 문제를 해결하였습니다.

class-transformer 의 `@Transform` 데코레이터는 사용 시 해당 멤버변수에 대한 강제 형 변환을 수행합니다. 이 데코레이터를 활용하여, 대입된 값을 실제 원하는 Boolean으로 변경될 수 있도록 하였습니다.

@Transform 데코레이터

 

`@Transform` 데코레이터에 입력되는 파라미터 값을 보면 다음과 같은 인터페이스 `TransformFnParams` 를 가지고 있습니다.

TransformFnParams 인터페이스

 

얼추 유추해 보기로는, 해당 파라미터로 대입되는 `value` 값이 해당 멤버변수(데코레이터가 적용된 변수)의 값일 것으로 예상됩니다. 데코레이터를 이용하여 해당 값을 출력해 봅니다.

@Transform 데코레이터의 적용

실행 결과

그러나 `value` 값은 `true` 로 나오고 있습니다. 이는 이미 앞선 `@ConfigValidation` 데코레이터에 의해 형 변환이 이루어진 이후라는 뜻입니다.

 

실제 `DB_LOGGING` 에 대입될 다른 값을 찾기 위해, 이번에는 `obj` 값을 확인해 보았더니, `plainToInstance` 값에 대입되었던 `process.env` 값이 전부 출력됩니다. (스크린샷은 생략하겠습니다.) 그러면 이제 실제 `DB_LOGGING` 값에 대한 접근을 수행해야 하므로, 이에 대한 키값을 알 수 있는 `key` 값을 이용하면 됩니다.

 

결론적으로, 다음과 같은 `@Transform` 데코레이터 적용을 통해, 강제 형 변환을 적용하였습니다.

@Transform 을 기반으로, boolean 타입으로의 강제 형 변환

 

이제 출력을 확인해 보면, 환경변수 파일에 기재하였던 `false` 값이 그대로 출력되는 것을 확인할 수 있습니다. 이제 `@ConfigValidation` 데코레이터를 사용할 수 있게 되었습니다.

코드 실행 결과

 

결론

발생했던 문제와 해결 방법을 정리하면 아래와 같습니다.

1. class-transformer 의 `plainToInstance` 함수에서 `enableImplicitConversion` 옵션을 활성화하면, 암시적 형 변환이 일어납니다.
2. `plainToInstance` 함수에서, 입력된 문자열(String)을 부울(Boolean) 값으로 변환하게 되면, 해당 문자열 값을 읽는 것이 아니라, 문자열의 존재(빈 값이 아닌지)에 따라 `true` 또는 `false` 로 자동 형 변환을 수행합니다.
3. 환경변수를 검사하는 Class 및 데코레이터를 구현하여 class-validator 가 제공하는 `validateSync` 함수를 이용하려고 하였으나, 위 문제로 인해 실제 부울 값이 반영되지 않는 문제가 있었습니다.
4. 이 문제를 해결하기 위해, 검사에서 사용될 변수를 다시 형 변환해주기 위하여 class-transformer 의 `@Transform` 데코레이터를 이용하였습니다.
5. `@Transform` 데코레이터에서 입력된 원본 값으로 접근하여, 해당 값이 문자열 `"true"` 와 같은지 검사함으로써, 실제 입력된 환경변수가 제대로 반영될 수 있도록 하였습니다.

 

위 문제에 대한 해결 방법은 직관적으로 생각해서 적용한 방식이므로, 더 좋은 방법이 있을 수 있습니다. 특히, 매번 `@IsBoolean` 데코레이터를 사용하는 경우 (입력 문자열 값으로부터 부울 값으로의 형 변환이 필요한 경우), `@Transform` 데코레이터를 같이 붙여서 사용해야 한다는 단점이 있습니다. 이 부분을 해결하려면, 새로운 데코레이터로 정의해주는 것이 좋습니다. 기존의 `@IsBoolean` 과 `@Transform` 데코레이터들을 하나의 데코레이터로 묶거나, 필요한 여러 가지 로직이나 자세한 옵션들을 동반하여 구현할 수 있겠습니다.