TypeScript Academy · 강의

스키마로 검증하는 설정

시작 시 스키마로 설정을 검증합니다.

스키마로 검증하는 설정은(는) CoddyKit의 무료 TypeScript Academy 강의입니다. 이것은 4개 중 2번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 TypeScript Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. TypeScript Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

시작 시 Config 검증하기

수동 파싱 도우미도 작동하지만, 스키마를 사용하면 전체 구조와 규칙을 한곳에서 선언하고 시작 시 모두 검증하여 앱이 트래픽을 처리하기 전에 즉시 실패하게 할 수 있습니다.

즉시 실패의 의미

즉시 실패한다는 것은 구성이 잘못되었을 때 프로세스가 명확한 메시지와 함께 즉시 종료되는 것을 의미합니다. 요청을 처리하는 중 모호한 코드 경로에서 나중에 충돌하는 것과 반대입니다.

Zod를 사용한 스키마

zod와 같은 라이브러리를 사용하면 구성을 선언적으로 설명할 수 있습니다. 각 필드에 타입과 제약 조건을 지정하면 검증을 통해 타입이 완전히 지정된 객체가 생성됩니다.

import { z } from "zod";
const EnvSchema = z.object({
  PORT: z.coerce.number().int().positive(),
  NODE_ENV: z.enum(["development", "production"]),
  DATABASE_URL: z.string().url(),
});

내장된 타입 변환

스키마는 문자열을 올바른 타입으로 변환할 수 있습니다. z.coerce.number()는 "8081"을 8081로 바꾸므로 원시 환경 변수 문자열을 안전하게 실제 숫자로 변환할 수 있습니다.

// "8081" -> 8081 via z.coerce.number()

파싱하고 즉시 실패하기

parse를 호출하면 모든 항목이 검증됩니다. 하나라도 유효하지 않으면 zod가 자세한 오류를 발생시키므로, 해당 오류를 기록하고 종료하여 시작을 즉시 중단할 수 있습니다.

function loadConfig() {
  const result = EnvSchema.safeParse(process.env);
  if (!result.success) {
    console.error(result.error.format());
    process.exit(1);
  }
  return result.data;
}

타입 추론하기

가장 큰 이점은 z.infer를 사용해 검증된 타입을 스키마에서 파생할 수 있다는 점입니다. 스키마가 실행 시점 검증과 컴파일 시점 타입 모두에 대한 단일 기준점이 됩니다.

type Env = z.infer<typeof EnvSchema>;
// { PORT: number; NODE_ENV: "development" | "production"; DATABASE_URL: string }

설명적인 오류

스키마 검증기는 어떤 필드가 왜 실패했는지 정확히 알려 줍니다. 예를 들어 "PORT: 양수가 예상됨"과 같이 표시합니다. 명확한 메시지를 사용하면 잘못된 구성을 쉽게 진단할 수 있습니다.

// e.g. { PORT: { _errors: ["Expected number, received nan"] } }

선택적 필드와 기본값 필드

스키마에서 선택 여부와 기본값을 직접 표현할 수 있으므로 직접 작성한 대체값 로직을 없애고 모든 규칙을 하나의 선언에 모을 수 있습니다.

const Schema = z.object({
  LOG_LEVEL: z.enum(["info", "debug"]).default("info"),
  TIMEOUT_MS: z.coerce.number().optional(),
});

한 번 검증하고 어디서나 사용하기

시작할 때 한 번만 검증을 실행하고 그 결과인 타입이 지정된 객체를 내보냅니다. 이후의 코드는 config가 존재하며 올바른 형식이라고 신뢰할 수 있습니다.

export const config = loadConfig();

Env를 넘어 파일과 인수까지

동일한 스키마로 process.env뿐 아니라 JSON 파일이나 병합된 원본의 구성도 검증할 수 있습니다. 값의 출처와 검증 단계는 서로 독립적입니다.

임시 검증보다 스키마가 나은 이유

스키마는 검증과 타입 지정을 통합하고, 일관되고 풍부한 오류를 생성하며, 타입 변환과 기본값을 지원하고, 즉시 실패합니다. 곳곳에 흩어진 수동 if 검사를 하나의 선언으로 대체할 수 있습니다.

빠른 확인

이 레슨을 간단히 확인해 봅니다.

복습

config 스키마(예: zod)는 타입, 제약 조건, 타입 변환, 기본값을 한곳에서 선언합니다. 시작 시 검증을 수행하여 설명적인 오류와 함께 즉시 실패하게 하며, 단일 기준점인 스키마에서 타입이 지정된 config를 z.infer로 추론할 수 있습니다.

자주 묻는 질문

“스키마로 검증하는 설정” 강의는 무료인가요?

네 — “스키마로 검증하는 설정” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 TypeScript Academy 강의 전체를 잠금 해제할 수 있습니다. TypeScript Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“스키마로 검증하는 설정”에서 뭘 배우나요?

시작 시 스키마로 설정을 검증합니다. 브라우저에서 직접 실행하는 실습 코드로 TypeScript Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

TypeScript Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 TypeScript Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 2번째 강의입니다.

“스키마로 검증하는 설정” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 TypeScript Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 TypeScript Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← TypeScript Academy(으)로 돌아가기