Prisma 타입 오류로 빌드가 막힐 때 체크할 것

처음부터 정답을 맞히려고 하지 않는다

Prisma를 사용하면서 TypeScript 타입 오류로 빌드가 막힐 때가 있다. 처음부터 모든 타입을 완벽하게 맞히려고 하면, 오히려 확인해야 할 것들이 더 많아져서 시간이 길어진다. 작은 범위에서부터 타입 오류의 원인을 찾아야 한다.

타입 안정성 문제의 핵심은 단편적인 에러 메시지가 아니라, 데이터가 실제 어떤 형태로 전달되는지 확인하는 것이다. Prisma query 결과, optional 필드, null 가능성을 함께 추적해야 타입을 올바르게 정의할 수 있다.

먼저 타입 오류 메시지를 읽는다

TypeScript 타입 오류를 해결하려면, 에러 메시지가 정확히 무엇을 지적하는지 파악해야 한다:

• 먼저 볼 값: 기대하는 타입과 실제 타입
• 함께 비교할 값: 정상적인 Prisma 쿼리 결과와의 비교
• 남겨둘 기록: 타입 정의, 쿼리 코드, 응답 데이터

실제 응답을 먼저 확인한다

Prisma 쿼리를 실행했을 때 실제로 어떤 데이터가 반환되는지 보지 않고서는 올바른 타입을 정의할 수 없다. console.log로 실제 응답을 출력해보거나, Prisma Studio를 사용해서 데이터를 직접 확인하는 게 빠르다:

npm run build
npx tsc --noEmit

이 명령들로 빌드 오류와 타입 검증 오류를 명확히 볼 수 있다.

Optional 필드를 놓치지 않는다

Prisma에서 select나 include를 사용할 때, optional 필드가 없을 수 있다. 데이터베이스 스키마에서 optional 필드를 선택하지 않으면 그 필드는 undefined가 되는데, 타입 정의에 이를 반영해야 한다.

타입 가드를 활용한다

Optional 필드나 null 가능성이 있는 데이터를 다룰 때, 타입 가드를 사용하면 런타임 에러를 방지하고 타입 안정성을 높일 수 있다:

if (data?.field !== undefined) {
  // 안전하게 사용할 수 있음
}

단계별로 검증한다

같은 타입 문제가 반복되는 것을 방지하려면 확인 순서를 고정한다:

1. 원래 타입 오류가 같은 곳에서 다시 나타나는지 확인한다
2. Prisma 쿼리 결과와 타입 정의의 불일치를 명확히 설명할 수 있는지 확인한다
3. 빌드와 실행 모두에서 오류가 없는지 최종 확인한다

다음을 위해 기록한다

Prisma 타입 오류를 해결한 후, 어떤 필드가 optional이었는지, 어떻게 타입을 정의했는지 정리해두면 비슷한 오류가 생겼을 때 빠르게 대응할 수 있다.