신뢰할 수 없는 데이터를 검증하고 타입을 자동으로 추론하는 방법
API 응답이나 사용자 입력처럼 출처가 불분명한 데이터를 처리할 때, 미리 정해둔 규칙대로 모양을 확인하고 싶을 때 이 도구를 씁니다. 스키마를 한 번만 작성하면 런타임에서 데이터를 검증하는 동시에 타입스크립트에서 사용할 정적 타입을 자동으로 만들어 줍니다. 덕분에 데이터가 유효한지 확인하는 코드와 타입을 선언하는 코드를 따로 쓰지 않아도 됩니다.
스키마 정의와 타입 추출
객체의 각 필드에 어떤 타입이 들어가는지 z.object 같은 메서드로 설명하면, 그 스키마를 이용해 데이터를 파싱할 때 유효하지 않은 값은 걸러지고 유효한 값은 타입이 보장된 상태로 반환됩니다. z.infer 유틸리티를 사용하면 이 스키마에서 파생된 타입을 별도의 타입 선언 없이 추출할 수 있습니다. 입력과 출력 타입이 다른 변환 로직을 사용할 때는 z.input과 z.output으로 각각의 타입을 독립적으로 가져올 수도 있습니다. 이러한 구조 덕분에 데이터 검증 로직과 타입 시스템이 항상 일치하도록 유지됩니다.
컴파일로 검증 속도 높이기
데이터를 매우 자주 검증해야 하는 경로에서는 z.compile을 사용해 성능을 높일 수 있습니다. 이 메서드는 스키마를 미리 컴파일하여 검증 속도를 개선하며, 55개 스키마를 대상으로 한 벤치마크에서 중앙값 기준 2.4배의 속도 향상을 보였습니다. 특히 객체 배열이나 키가 많은 객체처럼 처리량이 큰 경우 약 9배까지 빨라지지만, 단순 문자열 검증처럼 처리량이 적은 경우에는 속도 차이가 없습니다. 컴파일된 스키마는 유효한 입력에 대해 빠른 경로를 따르지만, 유효하지 않은 입력은 기존 파서로 넘어가므로 에러 보고 방식은 동일하게 유지됩니다. 다만 비동기 정제나 변환을 포함하는 스키마는 컴파일할 수 없으며, 이 경우 기존 파서를 그대로 사용합니다.
에러 처리와 설치
검증에 실패하면 ZodError가 발생하며, 어떤 필드가 어떤 이유로 실패했는지 상세한 정보를 제공합니다. try/catch 블록을 피하고 싶다면 safeParse를 사용해 성공 여부와 데이터를 하나의 결과 객체로 받을 수 있습니다. 이 도구는 외부 의존성이 전혀 없으며, 노드.js와 모든 최신 브라우저에서 동작합니다. 압축된 코어 번들 크기는 2kb입니다. 설치 방법은 npm install zod 명령을 실행하는 것뿐이며, 타입스크립트뿐 아니라 일반 자바스크립트 프로젝트에서도 사용할 수 있습니다.
컴파일 사용 시 주의할 점
z.compile을 전역으로 활성화하려면 new Function을 사용하므로, 콘텐츠 보안 정책(CSP)이 엄격한 환경에서는 jitless 옵션을 설정하거나 직접 컴파일 호출을 피해야 합니다. 또한 컴파일된 스키마에서 새로운 스키마를 파생하면 컴파일 상태가 해제되므로, 최종 스키마를 정의한 후에 컴파일하는 것이 좋습니다. 비동기 로직이 포함된 스키마는 컴파일 대상에서 제외되므로, 이러한 기능이 필요한 경우 기존 파서를 사용하는 것을 전제로 설계해야 합니다.
