GitLab GraphQL API는 상당히 복잡하므로 GraphQL 변경이 포함된 머지 리퀘스트는 GraphQL에 익숙한 사람이 리뷰해야 합니다. MR에서 @gitlab-org/graphql-experts 그룹을 멘션하거나 Slack의 #f_graphql 채널로 요청할 수 있습니다(GitLab 팀원만 이용 가능).

GraphQL 쿼리는 다음 관점에서 리뷰해야 합니다.

• 브레이킹 체인지
• 인가
• 성능

리뷰 기준#

아래 목록이 전부는 아닙니다.

샘플 쿼리가 포함된 설명#

설명에 설정 방법과 함께 샘플 쿼리가 포함되어 있는지 확인합니다. 로컬 GDK 인스턴스의 GraphiQL에서 쿼리를 실행해 봅니다.

브레이킹 체인지 없음(전체 지원 중단 사이클을 거친 경우는 예외)#

MR에 브레이킹 체인지가 있는지 확인합니다.

기능이 실험으로 표시되어 있다면 지원 중단 기간 없이 즉시 브레이킹 체인지를 적용할 수 있습니다.

자세한 내용은 지원 중단 및 제거 프로세스를 참고합니다.

멀티버전 호환성#

멀티버전 호환성이 보장되는지 확인합니다. 일반적으로 같은 GraphQL 기능의 프론트엔드 코드와 백엔드 코드를 같은 릴리스에 함께 출시할 수 없다는 뜻입니다.

자세한 내용은 여러 버전 호환성을 참고합니다.

테크니컬 라이팅 리뷰#

생성된 API 문서가 변경되면 테크니컬 라이터의 리뷰가 필요합니다.

변경 로그#

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

프레임워크 사용#

GraphQL은 구성 요소가 많은 프레임워크입니다. 프레임워크를 그대로 따르는 것이 중요합니다.

• 프레임워크의 내부 요소를 수동으로 호출하지 않습니다. 예를 들어 실행 중에 리졸버를 직접 인스턴스화하지 말고 프레임워크가 처리하도록 둡니다.
• MyResolver.single처럼 리졸버를 서브클래싱할 수 있습니다(리졸버 파생 참고).
• 인자 로직이 복잡하다면 ready? 메서드를 사용합니다(resolver#ready의 올바른 사용 참고).
• 인자 검증이 복잡하다면 prepare 메서드를 사용합니다(전처리 참고).

자세한 내용은 리졸버 가이드를 참고합니다.

인가#

인가가 적절히 이루어지는지, 스펙에서 authorize :some_ability를 테스트하는지 확인합니다.

자세한 내용은 인가 가이드를 참고합니다.

성능#

다음을 확인합니다.

• N+1 문제를 점검했고, 가능한 경우 최적화로 N+1을 제거했습니다.
• 지연 평가를 적절히 사용했습니다.

프론트엔드 GraphQL 프래그먼트 변경#

MR 이 app/assets/, ee/app/assets/, app/graphql/queries/ 아래의 .graphql 파일을 변경할 때 이 절을 적용합니다. N+1 쿼리 위험이 있는지 다음을 확인합니다.

• 프래그먼트가 중첩 연관 관계를 새로 추가하면 쿼리 깊이를 추적합니다. 예를 들어 workflows 목록 안의 workflow 선택 안에 있는 checkpoints 선택이 그렇습니다. 루트 필드부터 전체 쿼리 경로를 따라가며 각 단계가 페이지네이션되거나 배치 로드되는지 확인합니다.
• 목록 안의 목록 패턴을 주의합니다. 목록 타입에 사용되면서 하위 목록까지 가져오는 프래그먼트는 N+1의 강한 신호입니다. 예를 들어 세션에서 워크플로, 워크플로에서 체크포인트로 이어지는 경우입니다. 리졸버가 로드를 배치로 처리하지 않으면 부모 레코드마다 하위 레코드를 위한 쿼리가 따로 실행됩니다.
• 차단 요건: 새 필드에 백엔드 배치 로딩이 있는지 확인합니다. 리졸버나 타입에서 BatchLoader::GraphQL을 찾습니다. 또한 부모 리졸버가 해당 필드에 대한 preloads 또는 unconditional_includes 항목과 함께 LooksAhead를 포함하는지 확인합니다. 둘 다 없다면 머지 전에 MR에 배치 로딩을 추가해야 합니다.
• 차단 요건: 대응하는 request 스펙에 QueryRecorder 커버리지가 있는지 확인합니다. 리졸버 경로에 대응하는 스펙을 spec/requests/api/graphql/ 또는 ee/spec/requests/api/graphql/ 아래에서 찾습니다. 새 필드를 포함하는 expect { ... }.not_to exceed_query_limit(N) 같은 단언이 있는지 확인합니다. 레코드가 하나면 N+1 이 드러나지 않으므로, 픽스처가 부모 레코드를 둘 이상 생성하는지 확인합니다. 단언이나 다중 레코드 픽스처가 없다면 머지 전에 MR에서 스펙을 추가하거나 고쳐야 합니다.
• MR을 열기 전에 로컬에서 퍼포먼스 바나 development.log로 예상치 못한 쿼리 수를 확인합니다.

적절한 타입 사용#

예를 들면 다음과 같습니다.

• Ruby Time 및 DateTime 객체에는 TimeType을 사용합니다.
• id 필드에는 Global ID를 사용합니다.

자세한 내용은 타입을 참고합니다.

적절한 복잡도#

쿼리 복잡도는 쿼리 비용이 어느 정도일지 수치로 나타내는 방법입니다. 쿼리 복잡도 한도는 스키마에 상수로 정의되어 있습니다. 리졸버나 타입을 호출하는 비용이 크다면 쿼리 복잡도가 이를 반영하도록 해야 합니다.

자세한 내용은 최대 복잡도, 필드 복잡도, 쿼리 한도를 참고합니다.

테스트#

• 리졸버(단위) 스펙은 지원이 중단되었고 request(통합) 스펙을 사용합니다.
• 프레임워크의 많은 부분이 resolve 메서드 바깥에 있으며, 이들이 제대로 동작하는지 확인하는 방법은 request 스펙뿐입니다.
• GraphQL 변경 MR에는 가급적 API 스펙 변경이 함께 있어야 합니다.

자세한 내용은 테스트 가이드를 참고합니다.