유효성 검사 데코레이터 (Validation Decorators)
Express-Cargo는 요청 데이터가 클래스에 바인딩될 때 데코레이터를 사용하여 해당 데이터를 검증합니다.
유효성 검사는 독립적인 validate
함수에 의해 수행되지 않습니다. 대신, bindingCargo
미들웨어에 통합되어 있어 요청 처리 과정에서 자동으로 유효성 검사를 수행합니다.
기본 제공 유효성 검사기 (Built-in Validators)
@min(value: number)
숫자가 지정된 최소값 이상인지 확인합니다.
value
: 허용되는 최소값
@max(value: number)
숫자가 지정된 최대값 이하인지 확인합니다.
value
: 허용되는 최대값
@prefix(value: string)
문자열이 지정된 접두사로 시작하는지 확인합니다.
value
: 요구되는 시작 텍스트
@suffix(value: string)
문자열이 지정된 접미사로 끝나는지 확인합니다.
value
: 요구되는 종료 텍스트
@equal(value: any)
입력 값이 주어진 값과 엄격하게 동일함 (===
)을 확인합니다.
value
: 비교할 대상 값
@notEqual(value: any)
입력 값이 주어진 값과 엄격하게 동일하지 않음 (!==
)을 확인합니다.
value
: 비교할 대상 값
사용 예시
아래는 Express 애플리케이션에서 유효성 검사 데코레이터를 사용하는 전체 예제입니다.
import express, { Request, Response, NextFunction } from 'express';
import { bindingCargo, getCargo, body, min, max, suffix, CargoValidationError } from 'express-cargo';
// 1. 바인딩 및 검증 규칙이 정의된 클래스
class CreateAssetRequest {
@body('name')
assetName!: string;
@body('type')
@suffix('.png')
assetType!: string;
@body('quantity')
@min(1)
@max(100)
quantity!: number;
}
const app = express();
app.use(express.json());
// 2. bindingCargo 미들웨어를 라우트에 적용
app.post('/assets', bindingCargo(CreateAssetRequest), (req: Request, res: Response) => {
// 3. 검증 성공 시 getCargo로 데이터 접근
const assetData = getCargo<CreateAssetRequest>(req);
res.json({
message: 'Asset created successfully!',
data: assetData
});
});
// 4. 유효성 검증 에러 처리용 미들웨어 추가
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
if (err instanceof CargoValidationError) {
res.status(400).json({
message: 'Validation Failed',
errors: err.errors.map(e => e.message)
});
} else {
next(err);
}
});
/*
이 엔드포인트를 테스트하려면 /assets 로 POST 요청을 보내세요.
[유효한 요청 예시]
{
"name": "My-Asset",
"type": "icon.png",
"quantity": 10
}
[유효하지 않은 요청 예시]
{
"name": "My-Asset",
"type": "icon.jpg", // @suffix('.png') 실패
"quantity": 101 // @max(100) 실패
}
*/
에러 처리 (Error Handling)
유효성 검사가 실패하면, bindingCargo
미들웨어는 CargoValidationError
예외를 발생시킵니다. 이 예외를 처리하기 위해 Express 에러 핸들링 미들웨어를 등록해야 합니다.
CargoValidationError
객체는 errors
속성을 가지며, 이 안에는 여러 개의 CargoFieldError
인스턴스가 배열로 포함되어 있습니다. 각각의 CargoFieldError
객체는 구체적인 오류 메시지를 담고 있는 message
속성을 포함합니다 (예: "quantity: quantity must be <= 100"
).
코드 예시에서 보았듯이, 일반적으로는 err.errors
배열을 map()
을 통해 단순한 메시지 배열로 변환해 응답을 구성합니다.
에러 응답 예시:
위의 유효하지 않은 요청을 보낼 경우, 아래와 같은 JSON 응답이 반환됩니다:
{
"message": "Validation Failed",
"errors": [
"type: assetType must end with .png",
"quantity: quantity must be <= 100"
]
}