GraphQL API 병합 요청 체크리스트

GitLab GraphQL API는 상당한 복잡성을 가지고 있으므로 GraphQL 변경 사항을 포함하는 병합 요청은 GraphQL에 익숙한 사람에 의해 검토되어야 합니다. @gitlab-org/graphql-experts 그룹에서 MR에서 또는 Slack의 #f_graphql 채널(GitLab 팀 멤버만 가능)을 통해 누군가를 멘션할 수 있습니다.

GraphQL 쿼리는 다음을 위해 검토되어야 합니다.

  • 하위 호환성 (breaking changes)
  • 인가(authorization)
  • 성능

검토 기준

이 목록은 모두를 포함하는 것은 아닙니다.

샘플 쿼리를 포함한 설명

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

하위 호환성 확인 (완전한 폐기 주기 후에만)

MR에서 변경 사항을 확인하세요.

기능이 실험으로 표시된 경우, 폐기 기간 없이 즉시 변경 사항을 적용할 수 있습니다.

자세한 내용은 폐기 및 제거 프로세스를 참조하세요.

다중 버전 호환성

다중 버전 호환성이 보장되었는지 확인하세요. 일반적으로 동일한 GraphQL 기능에 대한 프론트엔드 및 백엔드 코드는 동일한 릴리스에서 배포되지 않아야 합니다.

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

기술적 작성 검토

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

변경 로그

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

프레임워크 사용

GraphQL은 여러 부분이 움직이는 프레임워크입니다. 프레임워크를 따르는 것이 중요합니다.

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

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

인가

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

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

성능

다음을 확인하세요:

적절한 유형 사용

예를 들어:

  • 루비 Time 및 DateTime 개체에 대한 TimeType.
  • id 필드에 대한 전역 식별자

자세한 내용은 유형을 참조하세요.

적절한 복잡성

쿼리 복잡성은 쿼리의 비용을 어떻게 정량화하는 방법입니다. 쿼리 복잡성 제한은 스키마의 상수로 정의됩니다. 리졸버나 타입이 호출하기 어려운 경우, 쿼리 복잡성이 해당 상황을 반영하는지 확인해야 합니다.

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

테스트

  • 리졸버(단위) 스펙은 요청(통합) 스펙을 선호하여 비활성화되었습니다.
  • 우리 프레임워크의 많은 측면은 resolve 방법 이외이므로 요청 스펙은 그들이 올바르게 작동하는 유일한 방법입니다.
  • 모든 GraphQL 변경 MR은 이상적으로 API 스펙에 대한 변경을 가져야 합니다.

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