GraphQL API Merge Request 체크리스트

GitLab GraphQL API는 상당한 복잡성을 가지고 있기 때문에 GraphQL 변경 사항을 포함하는 Merge Request은 GraphQL에 익숙한 사람에 의해 검토되어야 합니다. @gitlab-org/graphql-experts 그룹에서 MR 또는 Slack의 #f_graphql 채널(GitLab 팀 멤버만 이용 가능)을 통해 해당 사람에게 연락할 수 있습니다.

GraphQL 쿼리는 다음과 같이 검토되어야 합니다:

  • 파괴적인 변화(breaking changes)
  • 인가(authorization)
  • 성능

검토 기준

이것은 모든 사항을 다 포함하는 디렉터리은 아닙니다.

샘플 쿼리가 포함된 설명

설명에 설정 지침을 포함한 샘플 쿼리가 포함되어 있는지 확인하세요. GraphiQL에서 해당 쿼리를 로컬 GDK 인스턴스에서 실행해 보세요.

파괴적인 변화 없음(패권 강제 폐기 주기 이후)

MR을 파괴적인 변화에 대해 확인하세요.

만일 기능이 실험으로 표시된 경우, 폐기 기간 없이 즉시 파괴적인 변화를 줄 수 있습니다.

자세한 정보는 폐기 및 제거 프로세스를 참조하세요.

다중 버전 호환성

다중 버전 호환성이 보장되었는지 확인하세요. 이는 일반적으로 동일한 GraphQL 기능의 프론트엔드 및 백엔드 코드가 동일한 릴리즈에 포함되어서는 안 된다는 것을 의미합니다.

자세한 내용은 다중 버전 호환성을 참조하세요.

기술적 문서 검토

생성된 API 문서에 대한 변경은 기술 작성자 검토가 필요합니다.

변경 로그

실험으로 표시되지 않은 공개적인 변경 사항은 변경 로그 항목이 필요합니다.

프레임워크 사용

GraphQL은 많은 부분이 함께 동작하는 프레임워크입니다. 프레임워크가 따라지도록 하는 것이 중요합니다.

  • 프레임워크 부분을 매뉴얼으로 호출하지 마세요. 예를 들어 실행 중에 리졸버를 인스턴스화하지 마세요. 대신 프레임워크가 그 역할을 하도록 하세요.
  • MyResolver.single과 같이 리졸버를 하위 클래스화할 수 있습니다(리졸버 파생 참조: deriving resolvers).
  • 더 복잡한 인수 로직에 대해 ready? 메서드를 사용하세요(리졸버#ready의 올바른 사용 참조: correct use of resolver#ready).
  • 더 복잡한 인수 유효성 검사에 대해 prepare 메서드를 사용하세요(사전 처리 참조: Preprocessing).

자세한 내용은 리졸버 가이드를 참조하세요.

인가

적절한 인가가 따라지고 authorize :some_ability가 스펙에서 테스트되었는지 확인하세요.

자세한 내용은 인가 가이드를 참조하세요.

성능

다음을 보장하세요:

적절한 타입 사용

예를 들어:

  • 루비 Time 및 DateTime 객체에 대해 TimeType 사용
  • id 필드에 대해 전역 식별자(Global IDs) 사용

자세한 내용은 타입을 참조하세요.

적절한 복잡성

쿼리 복잡성은 쿼리가 얼마나 비싼지 수량화하는 방법입니다. 쿼리 복잡성 제한은 스키마의 상수로 정의됩니다. 리졸버나 타입이 호출하기 비싼 경우, 쿼리 복잡성이 그에 맞게 반영되도록 보장해야 합니다.

자세한 내용은 최대 복잡성, 필드 복잡성 및 쿼리 제한을 참조하세요.

테스트

  • 리졸버(단위) 스펙은 요청(통합) 스펙으로 대체되었습니다.
  • 프레임워크의 많은 측면이 resolve 메서드 외부에 있으며, 요청 스펙은 그들이 올바르게 동작하는 유일한 방법입니다.
  • 모든 GraphQL 변경 MR은 이상적으로 API 스펙에 대한 변경을 가져야 합니다.

자세한 내용은 테스트 가이드를 참조하세요.