[GraphQL/Apollo Server] directives 파헤치기 - @deprecated @skip @include

오늘 설명드릴 내용은, Apollo Server에서 제공하는 directives의 기본적인 설명과 각 directive 사용법입니다.

앞으로 apollo federation의 directives까지 확장해서 시리즈로 제작해볼 예정입니다. 😁

 

Apollo Server에서 directives의 역할

apollo server에서 쓰이는 directives는 스키마나 동작(operation)의 완성도를 더 높여주기 위해 사용합니다.

client와 더욱 쉽게 소통할 수 있도록 하는 도구로써의 역할이에요. 그래서 꼭 필수로 구현할 필요는 없는 기능이기도 합니다!

 

directives 기본 규칙

1. 항상 GraphQL의 directives에는 앞에 '@' 이 친구가 붙습니다. GraphQL에서 골뱅이를 만났다면 오! 얜 지시자구나! 하시면 됩니다.

2. directives은 argument를 갖고있을 수 있습니다. (directive마다 갖고 있는 argument가 다름)

3. directives는 필드 or type 선언이 끝난 후 맨 뒤에 붙습니다.

4. directives는 graphQL이 지원하는 위치에만 선언해야 동작합니다. (필드, 타입 등등)

 

@deprecated

directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE

 

더 이상 사용하지 않음을 표시합니다.

field, argument, input field, enum type에서 해당 지시자를 사용할 수 있습니다.

동작은 하지만 이제는 사용되지 않을 때 사용하는 지시어입니다. 스키마의 하위호환성을 지키기 위해 사용될 수 있겠네요!argument로는 reason을 받을 수 있고, 내용을 써주면 사용하는 client가 어떤 이유로 deprecated되었는지 더 쉽게 파악이 가능합니다.

 

#example
enum MyEnum {
  # ENUM_VALUE
  OLD_VALUE @deprecated(reason: "Use `NEW_VALUE`.")
  NEW_VALUE
}

 

 

@skip

directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

@skip은 if가 true라면, resolved되지 않습니다.

resolved되지 않는다는 의미는 값을 가져오지 않는다는 의미입니다.

이 지시자는 스키마가 아니라 쿼리나 뮤테이션을 날릴 때 쓰입니다!

#example
query ($skipTitle: Boolean!) {
  queryPost {
    id
    title @skip(if: $skipTitle)
    text
  }
}

#example2
query ($foo: Boolean = true, $bar: Boolean = false) {
  field @skip(if: $foo) {
    subfieldA
  }
  field @skip(if: $bar) {
    subfieldB
  }
}

 

@include

directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

@include는 skip과 아주 유사한 기능입니다.

if가 true일때만, resolved됩니다.

이 지시자 역시 스키마보단 쿼리나 뮤테이션 날릴 때 필드에서 쓰입니다!

#example
query myQuery($someTest: Boolean) {
  experimentalField @include(if: $someTest)
}

#example2
query ($includeAuthor: Boolean!) {
  queryPost {
    id
    title
    text
    author @include(if: $includeAuthor) {
        id
        name
    }
  }
}

 

 

요렇게, GraphQL에서 기본적으로 제공하는 directives에 대해서 알아봤습니다.

평소에 @skip과 @include는 써본적이 없어서 이런 directive가 있는 줄도 몰랐는데, 개발하면서 요 두가지 지시자를 어떻게 활용하면 잘 활용할 수 있을지 생각하며 개발해봐야겠습니다.

 

오늘도 읽어주셔서 감사합니다! 😊

 

 

 

reference

Directives

GraphQL

 

@skip and @include Directives - GraphQL