필드와 디렉티브 버전 관리의 활용 사례

먼저, Gato GraphQL의 「필드 버전 관리」 기능을 설명한 가이드 필드 버전 관리를 통한 스키마 진화를 읽어 주세요.

Gato GraphQL에서는 필드와 디렉티브가 versionConstraint 인수를 받을 수 있습니다. 이를 통해 필드나 디렉티브의 특정 버전(즉, 구현)을 선택할 수 있습니다.

query GetPosts {
  posts(versionConstraint: "^1.0") {
    id
    title(versionConstraint: ">=2.1")
    excerpt @strUpperCase(versionConstraint: "~1.5.3")
  }
}Copy

필드(또는 디렉티브)는 버전이 없는 기본 구현을 가질 수도 있습니다. 이는 쿼리에서 versionConstraint가 지정되지 않은 경우에 사용됩니다.

인트로스펙션을 실행할 때는 기본 필드와 디렉티브의 데이터만 가져옵니다. 그 결과, 기본 필드나 디렉티브는 versionConstraint 인수를 지원하지 않으므로 인트로스펙션 시 이 인수가 나타나지 않습니다.

이러한 이유로, 필드 또는 디렉티브에 선택 가능한 두 개 이상의 버전이 존재한다는 것을 항상 사전에 파악해야 하며, 해당 버전 번호도 알고 있어야 합니다. 이 정보는 기본적으로 공개되지 않습니다.

그렇다면 버전 관리는 어떤 상황에서 유용할까요? 다음은 몇 가지 활용 사례입니다.

​

특정 사용자를 위한 빠른 버그 수정 제공

웹사이트에 GraphQL API가 배포되어 있고, 특정 사용자로부터 필드가 예상대로 작동하지 않는다는 불만이 접수되었다고 가정해 보겠습니다. 그런데 이 문제는 해당 사용자에게만 발생하며, 다른 누구도 문제를 경험하지 않는 것 같습니다.

문제를 파악하고 수정했지만, 모든 사람에게 변경 사항을 배포하기 전에 정상적으로 작동하는지 확인하고 싶은 경우, 버전 "1.0.1"의 새 필드 리졸버로 변경 사항을 배포하고, 문제가 있는 사용자에게 GraphQL 쿼리를 변경하여 해당 버전의 필드를 지정하도록 요청할 수 있습니다.

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

버그가 실제로 수정된 것을 확인한 후에만 코드를 기본 필드 리졸버에 복사합니다.

​

선택된 사용자에게 출시 예정 버전 테스트 요청

필드 또는 디렉티브가 버전 관리되어 있고 기본(즉, 비버전) 구현이 없는 경우, 인트로스펙션 시 전혀 표시되지 않습니다.

{
  someField
    # This directive has no default implementation,
    # so it won't appear during introspection,
    # but it can still be added in the GraphQL query
    # when providing a constraint that satisfies it
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

필드 또는 디렉티브를 배포하더라도 GraphQL API에서 표시되지 않는 상태로 유지하면서, 선택된 사용자에게 테스트를 요청할 수 있습니다. 이 경우 사용자는 쿼리에서 해당 versionConstraint 인수를 지정하여 사용해야 합니다.

승인된 후에는 버전 관리가 제거되고, 필드 또는 디렉티브가 인트로스펙션을 통해 표시되어 모든 사용자가 이용할 수 있게 됩니다.