GraphQL 인트로스펙션

GraphQL 인트로스펙션 (Introspection)

GraphQL API가 어떤 타입·필드를 제공하는지 궁금할 때, 문서를 찾는 대신 API 스스로에게 물어볼 수 있어요. 이걸 가능하게 하는 게 인트로스펙션(introspection) 시스템이에요. 개발 도구(GraphiQL 등)도 이 메커니즘으로 스키마를 읽고 자동완성·문서 브라우저를 만들어요.

출처: https://graphql.org/learn/introspection/

가장 단순한 예는 __typename 메타 필드예요. Union 타입을 리턴하는 필드에서 실제로 어떤 타입이 왔는지 알고 싶을 때 선택 집합에 넣으면, 구현이 그 타입의 이름을 문자열로 돌려줘요. 이 필드는 명시적으로 추가할 필요 없이 GraphQL 구현이 항상 제공해요.

스키마 전체를 살펴보려면 query 루트 타입에 항상 있는 __schema 필드를 조회하면 돼요.

{
  __schema {
    types {
      name
      kind
    }
  }
}

여기서 나오는 타입은 세 부류로 나뉘어요. 내가 정의한 타입(Query, Human, Episode...), 내장 스칼라(Boolean/Float/ID/Int/String), 그리고 더블 언더스코어로 시작하는 인트로스펙션 시스템 타입(__Schema, __Type, __Field...)이에요.

특정 타입의 필드를 보려면 __type(name: "Droid")를 조회해요. 이때 필드 타입의 name이 비어 보이는 경우가 있는데, 그건 Non-Null(NON_NULL)이나 List(LIST) 같은 래퍼 타입이라 그래요. 그 안의 실제 타입을 보려면 ofType을 따라가면 돼요. 마지막으로 description을 조회하면 스키마에 달아 둔 문서를 그대로 읽을 수 있어서, 문서 브라우저나 풍부한 IDE 경험을 만들 수 있어요. 다만 인트로스펙션은 스키마 구조를 전부 드러내기 때문에, 운영 환경에서는 보통 비활성화해요.

더 알아보기