런타임 스키마 경계 실전 설계
정적 타입은 코드 내부의 약속을 강하게 만들어 줍니다. 하지만 API 요청, 메시지 큐, 환경 변수, 파일, 데이터베이스 결과처럼 외부에서 들어오는 값은 타입 시스템 바깥에서 옵니다. 이 경계에서 검증하지 않으면 타입이 있는 코드도 잘못된 데이터를 안전하게 처리한다고 착각할 수 있습니다.
타입은 경계 밖 데이터를 믿지 못한다
TypeScript에서 as User를 붙였다고 실제 JSON이 User가 되는 것은 아닙니다. Python의 타입 힌트나 Java의 제네릭도 런타임 입력을 자동으로 보증하지 않습니다. 외부 입력은 먼저 스키마로 검증하고, 검증을 통과한 뒤에 내부 도메인 타입으로 변환해야 합니다.
이 분리를 지키면 코드의 나머지 부분은 더 단순해집니다. 내부 서비스는 이미 정제된 값을 받는다고 믿을 수 있기 때문입니다.
스키마는 입구에 둔다
검증 코드를 비즈니스 로직 중간에 흩뿌리면 빠뜨리기 쉽고, 같은 규칙이 여러 곳에서 달라집니다. 좋은 위치는 시스템의 입구입니다.
- HTTP 컨트롤러
- 메시지 컨슈머
- 배치 파일 파서
- 환경 설정 로더
- 외부 API 응답 어댑터
입구에서 실패를 명확히 만들고, 내부에는 검증된 모델만 넘기는 방식이 가장 유지보수하기 쉽습니다.
검증과 변환을 함께 설계한다
런타임 스키마는 단순히 필드가 있는지 확인하는 도구가 아닙니다. 문자열 날짜를 날짜 타입으로 바꾸고, 빈 문자열을 null로 정규화하고, 알 수 없는 필드를 거절하거나 제거하는 정책도 함께 담아야 합니다. 검증 후에도 변환 규칙이 모호하면 내부 타입은 계속 흔들립니다.
중요한 것은 실패 메시지입니다. 외부 클라이언트가 고칠 수 있는 입력 오류라면 어느 필드가 왜 잘못됐는지 알려줘야 합니다. 내부 시스템 오류와 입력 오류를 같은 예외로 처리하면 운영이 어려워집니다.
실전 체크리스트
- 모든 외부 입력 경계에 스키마를 둔다.
- 검증된 값과 원본 값을 타입이나 이름으로 구분한다.
- 알 수 없는 필드 처리 정책을 명시한다.
- 오류 메시지는 사용자용과 로그용을 나눈다.
- 스키마 변경은 API 호환성 검토와 함께 진행한다.
런타임 스키마는 정적 타입의 대체재가 아닙니다. 타입 시스템이 책임질 수 없는 경계에서 데이터를 현실 세계와 맞춰 주는 안전 장치입니다.
Continue Reading
다음으로 읽기 좋은 글
Java 개발자를 위한 Kotlin 실전 가이드
Kotlin을 Java의 짧은 대체 문법이 아니라, null safety, 상태 모델링, coroutine 구조까지 바꾸는 언어로 보고 실무 기준으로 정리합니다.
💬 LanguageTypeScript Utility Types 실전 가이드
TypeScript 유틸리티 타입을 DTO, 업데이트 payload, selector, 파생 타입 설계에 어떻게 써야 하는지, 어디서부터는 가독성을 해치는지 정리합니다.
⚙️ Backend비동기 작업 API의 멱등성과 상태 제어
긴 작업을 HTTP 요청 하나로 끝내지 않고 작업 생성, 재시도, 취소, 결과 조회까지 안정적으로 설계하는 방법을 정리합니다.
⚙️ Backend대용량 API 작업의 Job Status 패턴
오래 걸리는 백엔드 작업을 동기 API로만 다루면 사용자 경험과 운영 안정성이 함께 흔들립니다. Job status 패턴을 실전적으로 정리합니다.
다음 탐색