GraphQL Resolver에서 발생한 타입 불일치 이슈 정리

 

 

이번 문제는 GraphQL 스키마에 선언된 타입과 Resolver가 실제로 반환하는 값의 타입이 서로 다를 때 발생하는 전형적인 타입 불일치(Type Mismatch) 이슈였습니다.

1. 스키마(Schema) 정의

GraphQL SDL에서 특정 필드를 다음과 같이 선언했다고 가정해 보겠습니다.

type ExampleType {
  date: String!
}

스키마의 의도는 명확합니다.
date 필드는 반드시 문자열(String) 이여야 하며, null도 허용하지 않습니다.

---

2. 문제의 원인: Resolver가 다른 타입을 반환

문제는 Resolver에서 스키마와 다른 형태의 값을 반환할 때 발생합니다.

예를 들어:

// ❌ 문제를 일으킨 예시
date: { year: 2025, month: 11 }

스키마는 String을 기대하지만, Resolver는 객체를 반환하고 있습니다.
GraphQL은 스키마와 응답의 타입을 비교하며, 타입이 다르면 즉시 직렬화(serialization) 단계에서 에러를 발생시킵니다.

즉:

• 스키마: String
• 실제 반환값: { year: number, month: number }

→ 타입 불일치 오류 발생

---

3. GraphQL 타입 시스템의 동작 방식

GraphQL은 다음 규칙을 매우 엄격하게 지킵니다.

• Resolver가 반환하는 실제 값은 반드시 스키마에 선언된 타입과 일치해야 한다.
• String 타입에는 문자열만 들어갈 수 있다.
• 객체(Object), 배열(Array), 숫자(Number) 등 다른 값이 들어오면 직렬화 불가.

따라서 스키마와 반환 타입이 불일치하면 런타임에서 즉시 오류가 발생합니다.

---

4. 프레임워크별 예시

Apollo Server / GraphQL.js 기준

// ❌ 잘못된 예: 스키마는 String을 기대하지만 객체가 반환됨
date: () => ({ year: 2025, month: 11 })

// ✅ 올바른 예: 스키마 타입에 맞게 문자열로 직렬화
date: () => "2025-11"

NestJS GraphQL 기준

NestJS를 사용하더라도 원리는 동일합니다.
Resolver 레이어에서 String 타입을 선언했다면, 응답 전에 값을 문자열로 가공해야 합니다.

예:

// date 필드를 문자열로 변환
return {
  date: `${year}-${month}`,
};

---

5. 결론

이번 이슈의 원인은 다음 한 줄로 요약할 수 있습니다.

스키마에서 String으로 정의된 필드에 객체를 반환하며 발생한 GraphQL 타입 불일치 문제

GraphQL은 타입 일관성을 매우 중요하게 다루기 때문에,
스키마 → Resolver → 실제 응답
이 세 단계의 타입이 항상 일치하도록 유지해야 오류를 방지할 수 있습니다.

---