GraphQL 쿼리 빌더의 타입 자동추론, 이름만 보고 어떻게 아나
GraphQL 쿼리를 작성하다 보면 변수를 선언할 때 $userId: ID!처럼 타입을 명시해야 합니다. 그런데 GraphQL 쿼리 빌더에 $userId라고만 입력해도 자동으로 ID!가 붙습니다. 서버 스키마를 조회한 것도 아닌데 어떻게 타입을 알았을까요? 정답은 "몰랐다"입니다 — 실제로는 변수 이름의 철자 패턴만 보고 추측하는 정규식 매칭입니다. 이 원리와 함정을 코드 기준으로 뜯어봅니다.
1. 원래는 인트로스펙션으로 타입을 알아낸다
GraphQL 서버는 보통 스키마 인트로스펙션(introspection) 기능을 제공합니다. __schema, __type 같은 내장 메타 쿼리를 서버에 보내면 사용 가능한 모든 타입·필드·인수의 정의를 JSON으로 돌려받습니다. GraphQL Playground나 Apollo Studio 같은 도구가 자동완성을 제공할 수 있는 이유가 바로 이 인트로스펙션 결과를 미리 받아두기 때문입니다. 즉 원칙적으로 타입은 "추측"하는 게 아니라 서버에 물어봐서 "확인"하는 값입니다.
2. 하지만 이 빌더는 서버에 물어보지 않는다
모두의 툴 GraphQL 쿼리 빌더는 브라우저에서만 동작하는 정적 도구라 실제 GraphQL 엔드포인트에 연결하지 않습니다. 서버도, 스키마도 없는 상태에서 인수 값에 $변수명을 입력하면 무언가 타입을 붙여야 쿼리 헤더에 query ($변수명: 타입) 선언을 채워 넣을 수 있습니다. 그래서 택한 방법이 인수 이름(key)의 철자 패턴을 정규식으로 검사해 타입을 추정하는 것입니다. 실제 inferVarType() 함수 로직은 다음과 같습니다.
| 검사 순서 | 정규식 조건 | 추론 타입 |
|---|---|---|
| 1 | /id$/i — 이름이 "id"로 끝남 | ID! |
| 2 | /^(is|has)[A-Z_]/i 또는 /^(active|enabled|disabled)$/i | Boolean! |
| 3 | /^(count|limit|offset|page|number|num|amount|qty|quantity|year|month|day|age)$/i (전체 일치) | Int! |
| 4 | 위 셋에 모두 해당하지 않음 | String! |
중요한 건 이 검사가 인수 값이 아니라 인수 이름(key)에 대해서만 이뤄지고, 그마저도 값이 $로 시작하는 변수일 때만 실행된다는 점입니다. 리터럴 값 "1"이나 true를 그냥 입력하면 이 로직은 아예 작동하지 않습니다.
3. 정확히 어디서 오분류가 나는가
1번 규칙 /id$/i는 "필드 이름이 id로 끝나면"이 아니라 문자열 마지막 두 글자가 우연히 i, d인 모든 단어에 걸립니다. "userId"뿐 아니라 "paid", "valid", "grid", "avoid" 같은 흔한 영단어도 전부 이 조건을 통과해 ID!로 오추론됩니다. 실제로는 불리언이거나 문자열이어야 할 값이 관례적 명명 패턴 하나 때문에 잘못된 타입으로 굳어지는 것입니다.
| 변수 이름 | 정규식 판정 근거 | 실제 도구 출력 | 원래 의도한 타입 |
|---|---|---|---|
| userId | "id"로 끝남 → 규칙 1 | ID! | ID! (정상) |
| valid | "lid"의 마지막 두 글자가 "id" → 규칙 1 | ID! | Boolean! (의도와 불일치) |
| paid | 마지막 두 글자 "id" → 규칙 1 | ID! | Boolean! (의도와 불일치) |
| isActive | "is"+대문자 시작 → 규칙 2 | Boolean! | Boolean! (정상) |
| title | 어느 규칙에도 안 걸림 → 기본값 | String! | String! (정상) |
규칙 2와 3은 상대적으로 안전한 편입니다. Boolean 규칙은 접두사(is/has) 뒤에 대문자 또는 밑줄이 와야만 매치되도록 앵커링(^)되어 있고, Int 규칙은 전체 문자열이 정확히 일치(^...$)해야 하므로 부분 일치로 인한 오탐이 없습니다. 문제는 유일하게 $(문자열 끝) 앵커만 걸고 ^ 시작 앵커를 걸지 않은 규칙 1뿐입니다.
4. 실무에서는 어떻게 대응해야 하나
이 빌더로 빠르게 뼈대를 잡은 뒤에는 생성된 쿼리 상단의 변수 선언부만 눈으로 한 번 검산하는 습관이 필요합니다. 특히 인수 이름이 "id"로 끝나는 흔한 영단어(paid, valid, grid, avoid, solid 등)라면 자동 추론 결과가 100% 신뢰할 수 없다고 보고 직접 타입을 고쳐 쓰는 게 안전합니다. 실제 프로덕션 스키마의 정확한 타입이 필요하다면 이 도구 대신 서버 인트로스펙션 결과나 JSON 스키마 검증기로 별도 확인하는 편이 낫고, 생성된 쿼리 문법 자체를 정리하고 싶다면 GraphQL Formatter를 함께 쓰는 것을 권장합니다.
자주 묻는 질문
Q. 이 도구가 실제 GraphQL 서버 스키마를 조회하나요?
A. 아니요. 완전히 브라우저에서만 동작하는 정적 도구라 어떤 서버에도 연결하지 않습니다. 타입은 인수 이름의 철자 패턴만 보고 정규식으로 추정한 값입니다.
Q. 리터럴 값("1", true 등)을 입력해도 타입 추론이 일어나나요?
A. 아니요. 타입 추론 로직은 인수 값이 $로 시작하는 변수일 때만 실행됩니다. 리터럴 값은 추론 대상이 아닙니다.
Q. "paid"나 "valid" 같은 이름은 왜 ID!로 잘못 추론되나요?
A. ID! 판정 규칙이 "이름이 정확히 id인 경우"가 아니라 "이름의 마지막 두 글자가 i, d인 경우"를 검사하기 때문입니다. 우연히 id로 끝나는 영단어는 모두 이 조건에 걸립니다.
Q. Boolean이나 Int 추론 규칙도 같은 문제가 있나요?
A. 상대적으로 덜합니다. Boolean 규칙은 is/has 접두사 뒤에 대문자·밑줄이 와야만 매치되고, Int 규칙은 문자열 전체가 정확히 일치해야 하므로 부분 일치로 인한 오탐 확률이 낮습니다.
Q. 오추론된 타입을 고치려면 어떻게 하나요?
A. 생성된 쿼리 텍스트영역은 읽기 전용이 아니라 그대로 복사해 직접 수정할 수 있는 출력입니다. 변수 선언부의 타입 문자열만 원하는 값으로 바꿔서 사용하면 됩니다.