백엔드 GraphQL API 가이드

백엔드 GraphQL API 가이드 관련 내용을 설명합니다.

이 문서는 GitLab GraphQL API 의 백엔드를 구현하는 엔지니어를 위한 스타일과 기술 가이드를 담고 있습니다. REST API와의 관계 # GraphQL 및 REST API 섹션 을 참고합니다. 버전 관리 # GraphQL API는 버전이 없습니다 . 다중 버전 호환성 # GraphQL API에는 버전이 없지만, 업데이트 간 하위 호환성 과 그로 인해 발생할 수 있는 인시던트(예: 일부 사용자에게 사이드바가 로드되지 않은 사례 )를 고려해야 합니다. 완화 방법 # 인시던트 위험을 줄이려면 GitLab Self-Managed와 GitLab Dedicated에서 @gl_introduced 디렉티브를 사용해 노드가 도입된 GitLab 마일스톤을 태그합니다. 백엔드는 태그된 마일스톤을 자체 마일스톤 (패치를 제외한 GitLab 버전의 major.minor)과 비교하여 노드를 어떻게 처리할지 결정합니다. 태그된 마일스톤과 백엔드 마일스톤 비교 동작 백엔드보다 이전 필드가 반드시 존재해야 합니다. 필드가 없으면 undefinedField 오류가 발생합니다. 백엔드의 마일스톤 또는 그 이후 스키마에 필드가 있으면 정상적으로 리졸브되고, 없으면 null 을 반환합니다. 백엔드는 버전 문자열만으로는 마일스톤 도중에 필드가 존재하는지 알 수 없습니다. GitLab.com은 -pre 빌드를 실행하고 CI는 오래된 머지 리퀘스트 브랜치를 실행하므로, 두 백엔드가 같은 마일스톤을 보고하더라도 그중 하나에만 필드가 있을 수 있습니다. 그래서 백엔드 자체 마일스톤일 때는 오류 대신 null 로 대체합니다. 오타가 있거나 제거된 필드는 백엔드가 태그된 마일스톤을 지나갈 때까지만 null 을 반환하고, 그 이후에는 다시 오류가 발생합니다. 새 필드에는 해당 머지 리퀘스트가 머지되는 마일스톤을 태그합니다. 예를 들어 19.4 마일스톤을 태그한 필드는 다음과 같습니다. newField @gl_introduced ( version : "19.4.0" ) 이 필드는 다음과 같이 동작합니다. 백엔드 버전 결과 19.3.x null 19.4.0-pre, 필드의 MR 배포됨 정상 값 19.4.0-pre, 필드의 MR 배포되지 않음 null 19.5.x, 필드 존재 정상 값 19.5.x, 필드 제거되었거나 철자가 틀림 undefinedField 오류 이 디렉티브는 태그된 노드의 전체 하위 트리에 적용됩니다. 백엔드가 태그된 노드를 제거하면 그 안의 어떤 것도 검증하지 않습니다. 하위 트리 안의 알 수 없는 필드나 타입은 오류 대신 null 을 반환합니다. @gl_introduced 디렉티브는 모든 필드에 사용할 수 있습니다. 예를 들어 다음과 같습니다. fragment otherFieldsWithFuture on Namespace { webUrl otherFutureField @gl_introduced ( version : "99.9.9" ) } query namespaceWithFutureFields { futureField @gl_introduced ( version