AI가 생성한 TypeScript API에 Zod 런타임 입력 검증과 자동 테스트를 강제하는 방법
컴파일 타임 타입과 런타임 스키마 분리, 표준 400 에러 응답 구조, 경계값 테스트와 CI 검증

핵심 요약
- TypeScript의 type이나 interface는 트랜스파일 시점에 완전히 소거되므로, 외부 입력(Body, Query, Params, Webhook)은 반드시 Zod 같은 런타임 스키마로 파싱하고 z.infer로 타입을 추출한다.
- AI는 해피 패스(Happy Path) 위주로 스키마를 작성해 길이 제한을 빠뜨리기 쉬우므로 모든 문자열·배열·숫자 필드에 .max() 상한과 .strict() 옵션을 명시해 페이로드 폭주와 임의 필드 주입을 막는다.
- 검증 실패 시 DB나 내부 스택 트레이스를 노출하지 않고 고정된 에러 응답 구조(status 400, code: VALIDATION_ERROR, fields 배열)로 변환해 반환한다.
- AI가 만든 API 코드를 그대로 믿지 않고 Zod 스키마의 제약 조건을 역이용해 필수값 누락·타입 불일치·경계값 초과(400 응답) 단위 테스트를 자동 생성해 CI에서 강제 실행한다.
AI 코딩 어시스턴트에게 API 엔드포인트 생성을 지시하면 몇 초 만에 동작하는 라우트 핸들러를 만들어 주지만, 외부 입력 경계에서 악의적이거나 잘못된 페이로드를 걸러내는 런타임 검증은 빠지는 경우가 빈번하다. 이 글은 TypeScript 5.8과 Zod 3.23.8 환경에서 AI가 생성한 API 코드에 런타임 스키마 검증, 표준 에러 응답 포맷, 스키마 기반 실패 테스트를 강제하는 절차를 다룬다. 읽고 나면 컴파일 타임 타입의 한계를 보완하고 AI 스스로 입력 경계 누락을 리뷰·테스트하게 만드는 파이프라인을 구축할 수 있다.
TypeScript 정적 타입과 Zod 런타임 스키마의 검증 범위 비교
TypeScript 공식 핸드북에 명시되어 있듯 TypeScript의 모든 타입 정보(type, interface, as 단언)는 JavaScript로 트랜스파일되는 시점에 완전히 소거(Type Erasure)된다. 그런데 AI 코딩 도구는 종종 const body = (await req.json()) as CreateOrderInput 형태의 코드를 생성해 개발자에게 타입이 보장된다는 착각을 준다.
| 비교 항목 | TypeScript 정적 타입 (type / interface) | 런타임 스키마 검증 (Zod 3.23.8) |
|---|---|---|
| 동작 시점 | 코드 작성 및 tsc --noEmit 컴파일 시점 | 실제 HTTP 요청이 서버에 도달한 실행(Runtime) 시점 |
| 방어 대상 | 개발자의 오타, 내부 함수 간 잘못된 인자 전달 | 클라이언트가 조작한 JSON Body, Query, Params, Webhook 페이로드 |
| 값 범위 제약 | 문자열 길이 상한, 정수 범위(0~150), 정규식 검증 불가 | .min(), .max(), .int(), .email(), .uuid()로 정밀 제약 |
| 잉여 필드 처리 | 런타임 객체에 숨은 추가 프로퍼티(isAdmin: true) 유입 방치 | 기본 strip 동작 또는 .strict()로 미정의 필드 즉시 거부 |
| 실패 시 결과 | 빌드 실패 (단, as 단언 사용 시 빌드조차 통과) | safeParse 결과 객체(success: false)를 통해 400 상태 코드 반환 |
OWASP Top 10 for LLM Applications에서도 경고하듯, 외부 입력이 길이 제한이나 형식 검증 없이 내부 서비스나 LLM 프롬프트로 전달되면 서비스 거부(DoS)나 인젝션 공격의 통로가 된다.
AI가 생성한 API에 런타임 검증과 자동 리뷰를 적용하는 4단계 절차
외부 입력 경계를 빠짐없이 방어하고 테스트까지 연결하는 절차는 다음 네 단계로 구성한다.
- 런타임 스키마 우선 정의 및
z.infer타입 추출 — TypeScript 타입을 먼저 쓰지 않고 Zod 공식 문서의 스키마를 단일 진실 공급원(Single Source of Truth)으로 선언한 뒤 정적 타입을 추출한다. 모든 문자열·배열·숫자에는 상한(.max())을 강제한다. safeParse와 표준400에러 응답 매퍼 연결 — 핸들러 최상단에서 입력을 파싱하고, 실패 시 내부 스택 트레이스를 숨긴 일관된 JSON 에러 구조(VALIDATION_ERROR)로 변환한다. Next.js 서버 액션 환경이라면 Next.js App Router Server Actions 에러 처리 가이드의 반환 규약과 맞춘다.- AI 자가 리뷰 프롬프트로 검증 누락 엔드포인트 스캔 — 작성된 라우트 파일들을 AI에게 다시 입력해
as타입 단언,any우회, 상한 없는 배열/문자열을 찾아내도록 자동 리뷰를 실행한다. - 스키마 기반 경계값 실패 테스트 생성 및 CI 게이트화 — 정상 케이스(200)가 아니라 스키마 제약 조건을 위반하는 입력들이 모두
400을 반환하는지 검증하는 테스트 코드와 정적 규칙을 CI에 등록한다.
아래는 Node.js 22.11.0, TypeScript 5.8, Zod 3.23.8 기준의 스키마 정의와 표준 에러 응답 헬퍼 구현 예시이다.
// src/schemas/user-api.ts
import { z } from "zod";
export const CreateUserSchema = z
.object({
email: z.string().trim().email().max(254),
age: z.number().int().min(14).max(120),
roles: z.array(z.enum(["member", "editor"])).min(1).max(5),
referralCode: z.string().regex(/^[A-Z0-9]{6,12}$/).optional(),
})
.strict(); // 정의되지 않은 잉여 필드(예: isAdmin) 유입 시 즉시 실패 처리
export type CreateUserInput = z.infer<typeof CreateUserSchema>;
export function formatValidationError(error: z.ZodError) {
return {
error: {
code: "VALIDATION_ERROR",
message: "요청 입력값이 유효하지 않습니다.",
fields: error.issues.map((issue) => ({
path: issue.path.join("."),
reason: issue.code,
message: issue.message,
})),
},
};
}
API 핸들러에서는 req.json() 자체가 잘못된 JSON 구문으로 예외를 던질 수 있으므로 JSON 파싱과 safeParse를 분리해 처리한다.
// src/app/api/users/route.ts
import { CreateUserSchema, formatValidationError } from "@/schemas/user-api";
export async function POST(req: Request) {
let rawBody: unknown;
try {
rawBody = await req.json();
} catch {
return Response.json(
{ error: { code: "INVALID_JSON", message: "유효한 JSON 본문이 아닙니다." } },
{ status: 400 }
);
}
const parsed = CreateUserSchema.safeParse(rawBody);
if (!parsed.success) {
return Response.json(formatValidationError(parsed.error), { status: 400 });
}
// parsed.data는 런타임 검증이 완료된 CreateUserInput 타입
const { email, age, roles } = parsed.data;
return Response.json({ ok: true, email, age, roles }, { status: 201 });
}
AI에게 자가 코드 리뷰와 경계값 실패 테스트를 생성하게 하는 프롬프트
AI가 작성한 API는 AI가 만든 허술한 해피 패스 테스트를 쉽게 통과한다. 따라서 스키마를 기준으로 **실패해야 하는 입력(Negative Test)**을 생성하도록 아래 프롬프트를 사용한다.
[API 입력 검증 감사 및 실패 테스트 생성 프롬프트]
현재 작성된 API 핸들러와 CreateUserSchema를 아래 5가지 기준으로 감사하고, 누락된 스키마 패치와 Vitest 실패 테스트 코드를 작성해라.
감사 기준:
1. req.json(), query, params에 Zod safeParse 없이 `as` 단언이나 `any`를 사용한 곳이 있는가?
2. 모든 z.string()과 z.array()에 .max() 상한이 걸려 있는가? (DoS 방지)
3. 객체 스키마에 .strict()가 적용되어 미정의 필드 주입(Mass Assignment)을 차단하는가?
4. 검증 실패 시 내부 스택이나 DB 오류 원문 없이 표준 VALIDATION_ERROR(HTTP 400)만 반환하는가?
생성할 필수 실패 테스트 케이스 (모두 HTTP 400 및 VALIDATION_ERROR 반환 단언):
- 필수 필드(email) 누락
- 타입 불일치 (age에 문자열 "25" 전달)
- 경계값 위반 (age가 13 이하 또는 121 이상, roles 배열이 빈 배열이거나 6개 초과)
- 미정의 필드 주입 ({ ..., isAdmin: true } 전달 시 거부)
CI 파이프라인에서 검증 누락 PR을 자동 차단하는 구성
사람이 매번 코드 리뷰에서 as 단언이나 스키마 누락을 눈으로 찾지 않도록 CI에서 정적 분석과 검증 테스트를 자동 실행한다. 커스텀 AST 패턴으로 위험한 코딩 패턴을 잡는 방법은 Semgrep 기반 AI 생성 코드 보안 규칙 가이드를 결합하면 더욱 촘촘해진다.
# .github/workflows/api-validation.yml
name: API Validation Check
on:
pull_request:
paths:
- "src/app/api/**"
- "src/schemas/**"
- "tests/api/**"
jobs:
verify-api-boundary:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22.11.0
cache: npm
- run: npm ci
- name: TypeScript Strict Check
run: npx tsc --noEmit
- name: Disallow unsafe type assertions in API routes
run: npx eslint "src/app/api/**/*.ts" --rule "@typescript-eslint/no-explicit-any: error"
- name: Run Schema Boundary Tests
run: npx vitest run tests/api/validation
이 워크플로를 등록해 두면 AI로 새 API 라우트를 빠르게 찍어내더라도 런타임 스키마와 400 경계값 테스트가 함께 통과하지 않는 PR은 병합 전에 자동으로 걸러진다.
초보자가 자주 실수하는 포인트
- req.body as CreateUserInput처럼 TypeScript 타입 단언(as)만 붙이면 런타임에서도 잘못된 타입이나 음수·빈 문자열 입력이 걸러진다고 착각하는 경우
- z.string()이나 z.array()에 최대 길이(.max())를 지정하지 않아 대용량 문자열이나 수만 개 배열 요소가 그대로 DB 쿼리나 LLM 프롬프트로 전달되는 경우
- AI가 작성한 API를 검증할 때 정상 입력(200 OK) 테스트만 통과시키고 잘못된 입력에 대한 400 Bad Request 거부 테스트를 빠뜨리는 경우
체크리스트
- API 핸들러에서 as 타입 단언이나 any 없이 Zod safeParse로 Body·Query·Params를 검증하는가
- 스키마의 모든 가변 길이 필드(string, array)와 숫자(number)에 최소·최대 경계값(.min, .max)이 지정되어 있는가
- 정의되지 않은 잉여 필드를 차단하거나 걸러내는 정책(.strict() 또는 기본 strip)이 의도에 맞게 설정되었는가
- 검증 실패 시 내부 에러 객체 원본 대신 클라이언트용 표준 에러 포맷(VALIDATION_ERROR)과 400 상태 코드를 반환하는가
- 스키마 제약 조건별 실패 케이스(누락, 형식 오류, 경계값 초과)를 검증하는 자동 테스트가 CI에 포함되어 있는가
자주 묻는 질문
Zod에서 parse() 대신 safeParse()를 권장하는 이유는 무엇인가요?
parse()는 검증 실패 시 즉시 ZodError 예외를 던지므로 상위 try-catch 블록에서 DB 에러나 네트워크 예외와 뒤섞여 500 Internal Server Error로 잘못 처리되기 쉽다. 반면 safeParse()는 예외를 던지지 않고 { success: false, error } 판별 유니온 객체를 반환하므로 입력 검증 실패만 명확히 분리해 400 Bad Request 응답으로 매핑할 수 있다.
URL 쿼리 파라미터(?page=2&limit=20)처럼 모든 값이 문자열로 들어오는 입력은 어떻게 검증하나요?
쿼리 스트링이나 환경 변수는 HTTP 특성상 숫자로 보내도 런타임에 문자열('20')로 파싱된다. 이때 일반 z.number()를 쓰면 모두 타입 불일치로 실패하므로, Zod 3.20 이상에서 제공하는 z.coerce.number().int().min(1).max(100)을 사용해 강제 형변환과 범위 검증을 한 번에 처리한다.
참고 자료 · 검증 기준
- Zod Official Documentation — Basic Usage & safeParse
- TypeScript Handbook — Type Erasure & Runtime Behavior
- OWASP Top 10 for LLM Applications & GenAI Security
위 자료와 내용을 대조한 날짜: . 도구·서비스 정책은 이후 바뀔 수 있으므로 적용 전 공식 문서를 다시 확인하세요.
이 글은 실제 실무 환경 테스트 및 검증된 기술 자료를 바탕으로 작성되었으며, 환경 변화에 따라 지속적으로 갱신됩니다.