GitLab GraphQL API 스타일 가이드

이 문서는 GitLab GraphQL API의 스타일 가이드를 설명합니다.

비전

우리는 GraphQL API가 GitLab과의 프로그래밍적 상호작용의 주요 수단이 되기를 원합니다. 이를 위해 REST API에서 가능한 모든 것이 GraphQL API에서도 가능해야 합니다.

이러한 비전을 실현하기 위해 프론트엔드는 새로운 기능에 대해 REST API 대신 GraphQL을 사용해야 합니다. GraphQL API는 버전이 없습니다.

REST API를 폐기할 계획은 없습니다. 병렬로 두 개의 API를 지원하는 기술적 부담을 줄이기 위해 가능한 한 두 API가 공통 구현을 공유해야 합니다.

GitLab이 GraphQL을 구현하는 방법

우리는 Robert Mosolgo가 작성한 GraphQL Ruby gem을 사용합니다. 게다가 GraphQL Pro의 구독이 있습니다. 자세한 내용은 GraphQL Pro 구독을 참조하세요.

모든 GraphQL 쿼리는 단일 엔드포인트로 직접 전달됩니다 (app/controllers/graphql_controller.rb#execute), 이는 /api/graphql에서 API 엔드포인트로 노출됩니다.

심층 탐구

2019년 3월, Nick Thomas는 Deep Dive(깃랩 팀 멤버 전용: https://gitlab.com/gitlab-org/create-stage/issues/1)를 진행했습니다 깃랩 GraphQL API에서 도메인 특화 지식을 공유하기 위해, 미래에 이 코드베이스에서 작업할 수 있는 누구에게나 일반적으로 적용될 수 있는 좋은 소개 자료입니다. 여기서 YouTube에서 녹화본 및 Google 슬라이드와 PDF에서 찾을 수 있습니다. 특정 세부 정보가 그 이후로 변경되었을 수 있지만 여전히 좋은 소개 자료로서 기능할 것입니다.

GraphiQL

GraphiQL은 기존 쿼리를 실험해볼 수 있는 상호작용적인 GraphQL API 탐색기입니다. 어떠한 GitLab 환경에서도 https://<your-gitlab-site.com>/-/graphql-explorer에서 액세스할 수 있습니다. 예를 들면, GitLab.com의 경우입니다.

GraphQL 변경과 Merge Request 검토

GraphQL 프레임워크에는 주의할 사항이 있으며, 해당 도메인 전문 지식이 요구됩니다.

GraphQL 파일을 수정하거나 엔드포인트를 추가하는 Merge Request을 검토하도록 요청된 경우, GraphQL 리뷰 가이드를 살펴보세요.

GraphQL 로그 읽기

GraphQL 요청의 로그를 검사하고 GraphQL 쿼리의 성능을 모니터링하는 팁은 GraphQL 로그 읽기 가이드를 참조하세요.

인증

인증은 현재 GraphqlController를 통해 이루어지며, 현재 이는 Rails 애플리케이션과 동일한 인증을 사용합니다. 따라서 세션을 공유할 수 있습니다.

쿼리 문자열에 private_token을 추가하거나 HTTP_PRIVATE_TOKEN 헤더를 추가할 수도 있습니다.

제한

GraphQL API에는 몇 가지 제한 사항이 있으며, 이 중 일부는 개발자에 의해 재정의될 수 있습니다.

최대 페이지 크기

기본적으로 connections는 페이지당 최대 레코드 수를 정의한 app/graphql/gitlab_schema.rb 에서 반환할 수 있습니다.

개발자는 연결을 정의할 때 사용자 정의 최대 페이지 크기를 지정할 수 있습니다.

최대 복잡성

복잡성은 클라이언트를 대상으로하는 API 페이지에 설명되어 있습니다.

필드는 기본적으로 쿼리의 복잡성 점수에 1이 추가되지만, 개발자는 필드를 정의할 때 사용자 정의 복잡성을 지정할 수 있습니다.

쿼리의 복잡성 점수는 쿼리 복잡성를 위해 쿼리될 수 있습니다.

요청 시간 초과

요청은 30초 후에 시간 초과됩니다.

최대 필드 호출 횟수 제한

일부 경우에는 여러 부모 노드에서 특정 필드의 평가를 방지하고 N+1 쿼리 문제를 발생시키고 최적의 해결책이 없는 경우를 방지하는 것이 필요할 수 있습니다. 이것은 고려 사항의 마지막 수단으로 고려되어야 합니다.

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

# 이 사용법은 예상대로입니다.
query {
  project {
    environments
  }
}

# 이 사용법은 예상대로 아닙니다.
# N+1 쿼리 문제를 발생시킵니다. EnvironmentsResolver는 GraphQL 페이지네이션 대신 GraphQL 배치로더를 사용할 수 없습니다.
query {
  projects {
    nodes {
      environments
    }
  }
}

이를 방지하기 위해 필드에 Gitlab::Graphql::Limit::FieldCallCount 확장을 사용할 수 있습니다. 

# 이는 `environments` 필드의 최대 1회 호출을 허용합니다. 필드가 하나 이상의 노드에서 평가될 경우
# 오류가 발생합니다.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end

또는 리졸버 클래스에 확장을 적용할 수 있습니다. 

module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end

이 제한을 추가할 때 영향받는 필드의 description도 업데이트되었는지 확인하세요. 예를 들어, 

field :environments,
      description: '프로젝트의 환경입니다. 이 필드는 한 번의 요청으로 하나의 프로젝트에 대해서만 해결될 수 있습니다.'

패치 변경 사항

GitLab GraphQL API는 버전이 없습니다 따라서 개발자는 폐기 및 제거 프로세스에 대해 자세히 알아야 합니다.

파괴적인 변경은 다음과 같습니다:

  • 필드, 인수, 열거 유형 값 또는 뮤테이션을 제거하거나 이름을 바꾸는 경우
  • 인수의 유형 또는 유형 이름을 변경하는 경우. 인수의 유형은 변수를 사용할 때 클라이언트에 의해 선언되며, 변경 시, 이전 유형 이름을 사용하는 쿼리는 API에서 거부될 수 있습니다.
  • 필드 또는 열거 유형의 JSON으로의 직렬화 방식에 변경이 있는 경우. 예를 들면, JSON 문자열에서 JSON 숫자로의 변경 또는 문자열의 형식이 변경되는 경우입니다.
  • 필드 또는 복잡성 해결 프로그램에 대한 복잡성 추가
  • 필드를 not nullable(null: false)에서 nullable(null: true)로 변경하는 경우, Nullable fields에서 설명한 대로
  • 인수를 선택 사항(required: false)에서 필수(required: true)로 변경하는 경우
  • 연결의 최대 페이지 크기를 변경하는 경우
  • 쿼리 복잡성 및 깊이에 대한 전역 제한을 낮추는 경우
  • 이전에 허용되던 제한적인 쿼리가 제한에 부딪힐 수 있는 다른 모든 사항

항목을 폐기하는 방법에 대한 자세한 내용은 스키마 항목 폐기 섹션을 참조하세요.

note: The markdown document can be long, keep the translation in the same format and DO NOT eliminate the parts that are not translated. Be aware of the remaining translation.

Breaking change exemptions

GraphQL API breaking change exemptions documentation을(를) 참조하세요.

Global IDs

GitLab GraphQL API는 Global ID(예: "gid://gitlab/MyObject/123")를 사용하며, 데이터베이스 기본 키 ID를 결코 사용하지 않습니다.

Global ID는 클라이언트 측 라이브러리에서 캐싱 및 검색에 사용되는 규칙입니다.

또한 다음을 참조하세요:

우리는 Types::GlobalIDType이라는 사용자 정의 스칼라 타입을 사용하여 값이 GlobalID일 때 입력 및 출력 인수의 유형으로 사용해야 합니다. 이 타입을 사용하는 이점은 다음과 같습니다.

  • 값이 GlobalID인지를 유효성 검사합니다.
  • 사용자 코드에 전달하기 전에 GlobalID로 구문 분석합니다.
  • 오브젝트 유형에 매개변수를 적용할 수 있으며(예: GlobalIDType[Project]), 이는 더 나은 유효성 검사와 보안을 제공합니다.

새로운 인수 및 결과 유형에는 이러한 유형을 사용하는 것을 고려해 보세요. 이 유형은 관련 사항이나 상위 유형을 매개변수화할 수 있으므로, GlobalIDType[Issuable] 대신 GlobalIDType[Issue]와 같이 더 넓은 범위의 객체를 허용할 수 있습니다.

최적화

GraphQL의 경우, 활발하게 최적화 작업을 수행하지 않으면 N+1 문제가 발생하는 경향이 있습니다.

안정성과 확장성을 위해 쿼리가 N+1 성능 문제에 노출되지 않도록 보장해야 합니다.

다음은 GraphQL 코드를 최적화하는 데 도움이 되는 도구 디렉터리입니다.

  • Look ahead는 쿼리에서 선택된 필드에 기반하여 데이터를 사전로드할 수 있습니다.
  • Batch loading은 데이터베이스 쿼리를 일괄로 준비하여 하나의 명령문으로 실행할 수 있도록 합니다.
  • BatchModelLoader는 ID를 조회하는 권장 방법으로, 일괄 로드를 활용할 수 있습니다.
  • before_connection_authorization는 type authorization 권한 확인과 관련된 N+1 문제를 해결할 수 있습니다.
  • 최대 필드 호출 수 제한은 최적화가 개선되지 않는 경우에 데이터를 반환할 수 있는 필드 호출 수를 제한할 수 있도록 합니다.

개발 단계에서 N+1 문제 확인하는 방법

N+1 문제는 다음 방법으로 기능을 개발하는 중에 발견될 수 있습니다.

  • 콜렉션 데이터를 반환하는 GraphQL 쿼리를 실행하는 동안 development.log을 추적합니다. Bullet가 도움이 될 수 있습니다.
  • GitLab UI에서 쿼리를 실행하는 경우 성능 바를 관찰합니다.
  • 기능과 관련하여 N+1 문제가 없음(또는 제한적)을 단언하는 요청 사양을 추가합니다.

필드

유형

우리는 코드 우선 스키마를 사용하며, 루비에서 모든 유형을 선언합니다.

예를 들어, app/graphql/types/project_type.rb: 

graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true

각 유형에 이름을 지정합니다(이 경우 Project).

full_path와 name은 스칼라 GraphQL 유형입니다. full_path는 GraphQL::Types::ID이며(언제 GraphQL::Types::ID를 사용해야 하는지 참조), name은 일반 GraphQL::Types::String 유형입니다. 스칼라 데이터 유형(예: TimeType)에 대한 사용자 지정 GraphQL 데이터 유형을 선언할 수도 있습니다.

GraphQL API를 통해 모델을 노출할 때는 app/graphql/types에 새 유형을 생성하여 이를 수행합니다.

유형 내부에서 로직을 최소한으로 유지하고자 할 때, 필드를 노출할 때 내부에 논리를 가능한 한 적게 유지하십시오. 대신 프레젠터로 모든 로직을 이동하는 것이 좋습니다.

예를 들어, Types::MergeRequestType의 경우: 

class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter
  
  name 'MergeRequest'
end

기존 프레젠터를 사용할 수도 있지만, GraphQL을 위해 새 프레젠터를 만들 수도 있습니다.

프레젠터는 필드에서 반환된 객체와 컨텍스트를 사용하여 초기화됩니다.

Nullable 필드

GraphQL은 필드를 “nullable” 또는 “non-nullable”로 지정할 수 있습니다. 전자는 지정된 유형의 값 대신 null이 반환될 수 있다는 것을 의미합니다. 일반적으로 다음과 같은 이유로 nullable 필드를 non-nullable 필드 대신 사용하는 것이 좋습니다.

  • 데이터가 필수에서 선택 사항으로 전환하는 것이 일반적이며, 그 반대의 경우도 마찬가지입니다.
  • 필드가 선택적이 될 가능성이 없더라도 쿼리 시에 필드가 사용 가능하지 않을 수 있습니다.
    • 예를 들어, blob의 content는 Gitaly에서 조회해야 할 수 있습니다.
    • content가 nullable이면 전체 쿼리를 실패시키지 않고 부분 응답을 반환할 수 있습니다.
  • 버전이 없는 스키마에서 non-nullable 필드를 nullable 필드로 변경하는 것은 어려울 수 있습니다.

Non-nullable 필드는 필수적이고 미래에 선택적이 되기 힘들며 간단하게 계산할 수 있는 경우에만 사용해야 합니다. 예로 id 필드가 있습니다.

Non-nullable GraphQL 스키마 필드는 개체 유형 뒤에 느낌표(!)가 있는 객체 유형입니다. 다음은 gitlab_schema.graphql 파일의 예입니다. 

  id: ProjectID!

다음은 non-nullable GraphQL 배열의 예입니다. 

  
  errors: [String!]!

추가 읽기:

Global IDs 노출

GitLab이 Global IDs를 사용하는 규칙과 일치하도록, 노출되는 모든 필드의 이름이 id인 경우, 해당 필드는 자동으로 변환됩니다. 객체의 Global ID로 변환됩니다.

id라는 이름을 가진 필드가 아닌 경우, 매뉴얼으로 변환해야 합니다. 이를 위해 Gitlab::GlobalID.build를 사용하거나, GlobalID::Identification 모듈을 혼합한 객체에서 #to_global_id를 호출할 수 있습니다.

예를 들어, Types::Notes::DiscussionType를 사용한 예는 다음과 같습니다. 

field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end

GraphQL::Types::ID를 사용해야 하는 경우

GraphQL::Types::ID를 사용하면 해당 필드는 JSON 문자열로 직렬화되는 GraphQL ID 유형이 됩니다. 그러나 ID는 클라이언트에서 특별한 의미를 갖습니다. GraphQL 사양에서 다음과 같이 명시하고 있습니다.

ID 스칼라 타입은 고유 식별자를 나타내며, 종종 객체를 다시 가져오거나 캐시의 키로 사용됩니다.

GraphQL 사양은 ID의 고유성 범위가 어떻게되어야 하는지를 명확히하지 않습니다. GitLab에서는 ID가 최소한 유형명별로 고유해야 한다고 결정했습니다. 유형명은 Types:: 클래스의 graphql_name입니다. 예를 들어 Project 또는 Issue가 있습니다.

이에 따라,

  • Project.fullPath는 그 API 전체에 해당 fullPath를 가진 다른 Project가 없기 때문에 ID여야 합니다. 또한 해당 필드가 식별자이기 때문입니다.
  • Issue.iid는 API 전체에서 동일한 iid를 가진 많은 Issue 유형이 있을 수 있기 때문에 ID가 아니어야 합니다. 이 필드를 ID로 취급하는 것은 클라이언트가 다른 프로젝트의 Issue 캐시를 가지고 있는 경우 문제가 될 수 있습니다.
  • 일반적으로 Project.id는 ID가 될 자격이 있습니다. 해당 ID 값으로 하나의 Project만 있기 때문입니다.
    • 다만 우리는 데이터베이스 ID 값 대신 Global ID 유형을 사용하므로 이를 Global ID로 타입을 지정하게 됩니다.

다음은 이를 요약한 표입니다.

필드 목적 GraphQL::Types::ID 사용 여부
Full path 사용
데이터베이스 ID 사용 안 함
IID 사용 안 함

markdown_field

markdown_field는 field를 감싸는 도우미 메서드로 항상 렌더링된 Markdown을 반환하는 필드에 사용해야 합니다.

이 도우미는 GraphQL 쿼리의 컨텍스트를 사용하여 기존 MarkupHelper를 사용하여 모델의 Markdown 필드를 렌더링합니다.

도우미에 사용 가능한 현재 사용자가 볼 수 없는 리소스에 대한 링크를 삭제하기 위해 도우미에 컨텍스트를 제공해야 합니다.

HTML을 렌더링하는 것은 쿼리를 유발할 수 있으므로 이러한 필드의 복잡성은 기본값보다 5가 높아집니다.

Markdown 필드 도우미는 다음과 같이 사용할 수 있습니다. 

markdown_field :note_html, null: false

이렇게 하면 모델의 Markdown 필드 note를 렌더링하는 필드가 생성됩니다. method: 인수를 추가하여 재정의할 수 있습니다. 

markdown_field :body_html, null: false, method: :note

기본적으로 이 필드에는 다음과 같은 설명이 지정됩니다.

note의 GitLab Flavored Markdown 렌더링

description: 인수를 전달하여이를 재정의할 수 있습니다.

연결 유형

note
구현의 구체적인 내용은 페이지네이션 구현을 참조하십시오.

GraphQL은 커서 기반 페이지네이션을 사용하여 항목 컬렉션을 노출합니다. 이는 클라이언트에게 많은 유연성을 제공하면서도 백엔드가 다른 페이지네이션 모델을 사용할 수 있도록 합니다.

리소스의 컬렉션을 노출하기 위해 연결 유형을 사용할 수 있습니다. 이는 배열을 기본 페이지네이션 필드로 래핑합니다. 예를 들어 프로젝트-파이프라인에 대한 쿼리는 다음과 같이 보일 수 있습니다. 

query($project_path: ID!) {
  project(fullPath: $project_path) {
    pipelines(first: 2) {
      pageInfo {
        hasNextPage
        hasPreviousPage
      }
      edges {
        cursor
        node {
          id
          status
        }
      }
    }
  }
}

이는 프로젝트의 첫 번째 2개 파이프라인과 관련된 페이지네이션 정보를 반환하며 ID 내림차순으로 정렬됩니다. 반환된 데이터는 다음과 같이 보일 것입니다. 

{
  "data": {
    "project": {
      "pipelines": {
        "pageInfo": {
          "hasNextPage": true,
          "hasPreviousPage": false
        },
        "edges": [
          {
            "cursor": "Nzc=",
            "node": {
              "id": "gid://gitlab/Pipeline/77",
              "status": "FAILED"
            }
          },
          {
            "cursor": "Njc=",
            "node": {
              "id": "gid://gitlab/Pipeline/67",
              "status": "FAILED"
            }
          }
        ]
      }
    }
  }
}

다음 페이지를 가져오려면 마지막으로 알려진 요소의 커서를 전달할 수 있습니다. 

query($project_path: ID!) {
  project(fullPath: $project_path) {
    pipelines(first: 2, after: "Njc=") {
      pageInfo {
        hasNextPage
        hasPreviousPage
      }
      edges {
        cursor
        node {
          id
          status
        }
      }
    }
  }
}

일관된 정렬을 보장하기 위해 주요 키에 대한 순서를 추가합니다. 주요 키는 일반적으로 id이므로 관계의 끝에 order(id: :desc)를 추가합니다. 기본 테이블에 기본 키가 있어야 합니다.

바로 가기 필드

가끔은 “바로 가기 필드”를 구현하는 것이 간단해 보일 수 있습니다. 예를 들어, 매개변수가 전달되지 않는다면 컬렉션의 첫 번째를 반환하는 “바로 가기 필드”를 구현하는 것이 간단해 보일 수 있습니다. 이러한 “바로 가기 필드”는 유지 관리 오버헤드를 초래하므로 권장되지 않습니다. 이러한 필드는 정식 필드와 동기화되어야 하며 정식 필드가 변경되면 이러한 필드를 폐기하거나 수정해야 합니다. 그 외의 강력한 이유가 없다면 프레임워크가 제공하는 기능을 사용하십시오.

예를 들어, latest_pipeline 대신 pipelines(last: 1)을 사용하십시오.

페이지 크기 제한

기본적으로 API는 연결에서 페이지당 최대 레코드 수로 정의된 수의 레코드를 반환하며 클라이언트가 제한 인수(first: 또는 last:)를 제공하지 않는 경우 페이지당 기본 레코드 수도 반환합니다.

max_page_size 인수를 사용하여 연결에 대한 다른 페이지 크기 제한을 지정할 수 있습니다.

caution
GraphQL API의 성능을 유지하기 위해 기본값이 설정되어 있기 때문에 max_page_size를 높이는 대신 프론트엔드 클라이언트나 제품 요구 사항을 변경하는 것이 좋습니다.

예를 들어: 

field :tags,
  Types::ContainerRepositoryTagType.connection_type,
  null: true,
  description: '컨테이너 리포지터리의 태그',
  max_page_size: 20

필드 복잡성

GitLab GraphQL API는 쿼리의 복잡성을 제한하기 위해 복잡성 점수를 사용합니다. 복잡성에 대한 설명은 대부분의 경우 작업 없이 반환될 수 있는 데이터를 나타내는 필드에 대해 0의 복잡성을 부여받을 수 있도록 함으로써 적히고 있습니다. 작업이 많이 필요한 데이터를 나타내는 필드에 대해 서버에 의해 수행되는 더 많은 작업을 일으키는 필드에 대해 더 높은 복잡성을 명시해주어야 합니다.

기본적으로 필드는 쿼리의 복잡성 점수에 1을 추가합니다. 필드의 복잡성을 제공하기 위해 사용자 지정 복잡성 값을 제공함으로써 재정의할 수 있습니다.

calls_gitaly

Potential to perform a Gitaly call when resolving must be marked as such by passing calls_gitaly: true removing field _when defining it.

예를 들어: 

field :blob, type: Types::Snippets::BlobType,
      description: '스니펫 블랍',
      null: false,
      calls_gitaly: true

이는 필드의 complexity 점수를 1만큼 증가시킵니다.

리졸버가 Gitaly를 호출하는 경우 BaseResolver.calls_gitaly!로 등록할 수 있습니다. 이렇게 하면이 리졸버를 사용하는 필드에 자동으로 calls_gitaly: true가 전달됩니다.

예를 들어: 

class BranchResolver < BaseResolver
  type ::Types::BranchType, null: true
  calls_gitaly!
  
  argument name: ::GraphQL::Types::String, required: true
  
  def resolve(name:)
    object.branch(name)
  end
end

그런 다음 BranchResolver를 사용할 때 calls_gitaly:에 올바른 값을 얻을 수 있습니다.

유형에 대한 권한 노출

리소스의 권한을 사용자에게 노출하려면 리소스의 권한을 나타내는 별도의 유형을 전달할 수 있습니다.

예를 들어: 

module Types
  class MergeRequestType < BaseObject
    expose_permissions Types::MergeRequestPermissionsType
  end
end

권한 유형은 BasePermissionType을 상속하며 리소스에 대한 권한을 나타내는 몇 가지 도우미 메서드를 포함하고 있습니다. 이를 통해 권한을 non-nullable 부울로 노출시킬 수 있는 일부 헬퍼 메서드가 포함되어 있습니다. 

class MergeRequestPermissionsType < BasePermissionType
  graphql_name 'MergeRequestPermissions'
  
  present_using MergeRequestPresenter
  
  abilities :admin_merge_request, :update_merge_request, :create_note
  
  ability_field :resolve_note,
                description: '유저가 MR의 논의를 해결할 수 있는지 나타냅니다.'
  permission_field :push_to_source_branch, method: :can_push_to_source_branch?
end
  • permission_field: graphql-ruby의 field 메서드와 동일한 방식으로 작동하지만 기본 설명 및 유형을 설정하고 non-nullable로 만듭니다. 이러한 옵션은 여전히 인수로 추가하여 재정의할 수 있습니다.
  • ability_field: 정책에서 정의된 권한을 노출합니다. permission_field와 동일하게 작동하며 동일한 인수를 재정의할 수 있습니다.
  • abilities: 정책에서 정의된 여러 권한을 노출할 수 있습니다. 이러한 필드들은 모두 기본 설명이 있는 non-nullable 부울이어야 합니다. 
...중략...


## 피처 플래그

GraphQL에서 [피처 플래그](../development/feature_flags/index.md)를 구현하여 다음을 전환할 수 있습니다.

- 필드의 반환 값.
- 인자 또는 뮤테이션의 동작.

이는 선호도 및 상황에 따라 리졸버, 타입 또는 모델 메소드에서 수행할 수 있습니다.

NOTE:
피처 플래그가 활성화되어 있는 동안 항목을 알파 상태로 [표시하는 것이 권장됩니다](#mark-schema-items-as-alpha).
이것은 공개 GraphQL API를 이용하는 소비자에게 해당 필드가 아직 사용되어서는 안 된다는 신호를 보냅니다.
또한 "알파" 속성을 없애면 "릴리즈"하면서 알파 속성을 없알 수 있게 됩니다.

### 피처 플래그가 있는 항목에 대한 설명

스키마 항목의 값을 또는 동작을 전환하는 데 피처 플래그를 사용할 때, 항목의 `설명`은 다음을 해야 합니다.

- 해당 값 또는 동작이 피처 플래그에 의해 전환될 수 있다는 것을 명시합니다.
- 피처 플래그의 이름을 지정합니다.
- 피처 플래그가 비활성화되어 있는 경우 (또는 더 적합한 경우에는 활성화되어 있는 경우) 필드가 반환하는 내용이나 동작을 명시합니다.

### 피처 플래그 사용 예시

#### 피처 플래그가 있는 필드

피처 플래그 상태에 따라 필드 값이 전환됩니다. 피처 플래그가 비활성화되어 있는 경우 `null`을 반환하는 것이 일반적인 사용법입니다.

```ruby
field :foo, GraphQL::Types::String, null: true,
      alpha: { milestone: '10.0' },
      description: '`my_feature_flag` 피처 플래그가 비활성화되어 있는 경우 `null`을 반환하는' \
                   '일부 테스트 필드입니다.'

def foo
  object.foo if Feature.enabled?(:my_feature_flag, object)
end

피처 플래그가 있는 인자

피처 플래그 상태에 따라 인자가 무시되거나 값이 변경될 수 있습니다. 피처 플래그가 비활성화되어 있는 경우 인자가 무시되는 것이 일반적인 사용법입니다. 

argument :foo, type: GraphQL::Types::String, required: false,
         alpha: { milestone: '10.0' },
         description: '`my_feature_flag` 피처 플래그가 비활성화되어 있는 경우 무시되는' \
                      '일부 테스트 인자입니다.'

def resolve(args)
  args.delete(:foo) unless Feature.enabled?(:my_feature_flag, object)
  # ...
end

피처 플래그가 있는 뮤테이션

피처 플래그 상태로 인해 수행할 수 없는 뮤테이션이 회복할 수 없는 뮤테이션 오류로 처리됩니다. 이 오류는 최상위 수준에서 반환됩니다. 

description '`my_feature_flag` 피처 플래그가 비활성화되어 있는 경우 객체를 변형하지 않습니다.'

def resolve(id: )
  object = authorized_find!(id: id)
  
  raise_resource_not_available_error! '`my_feature_flag` 피처 플래그가 비활성화되었습니다.' \
    if Feature.disabled?(:my_feature_flag, object)
  # ...
end

스키마 항목의 퇴화

GitLab GraphQL API는 버전이 없으며, 이는 각 변경 사항에 대해 이전 버전의 API와의 하위 호환성을 유지한다는 것을 의미합니다.

필드, 인자, 열거 유형 값 또는 뮤테이션을 삭제하는 대신, 해당 항목을 _퇴화_시키는 것이 요구됩니다.

스키마의 퇴화된 부분은 이후 GitLab 퇴화 과정에 따라 향후 릴리스에서 제거될 수 있습니다.

GraphQL에서 스키마 항목을 퇴화시키려면:

  1. 퇴화 이슈를 생성합니다.
  2. 스키마에 있는 항목을 퇴화로 표시합니다.

또한 NOTE:

퇴화 이슈 생성

GraphQL 퇴화에는 추적 및 제거를 위해 Deprecations 이슈 템플릿을 사용하여 퇴화 이슈가 생성되어야 합니다.

다음 두 가지 라벨을 퇴화 이슈에 추가하세요:

  • ~GraphQL
  • ~deprecation

항목을 퇴화로 표시

필드, 인자, 열거값 및 뮤테이션을 퇴화속성을 사용하여 퇴화합니다. 이 속성의 값은 다음과 같습니다:

  • reason - 퇴화된 이유.
  • milestone - 필드가 퇴화된 마일스톤.

예시: 

field :token, GraphQL::Types::String, null: true,
      deprecated: { reason: '토큰을 통한 로그인이 제거되었음', milestone: '10.0' },
      description: '로그인을 위한 토큰입니다.'

퇴화되는 사항의 설명은 유지되어야 하며, 퇴화되었다는 멘션을 업데이트해서는 안 됩니다. 대신 이유가 설명에 추가됩니다.

퇴화 이유 스타일 가이드

퇴화의 이유가 필드, 인자 또는 열거 값이 대체되거나 퇴화된 이유인 경우, 이유는 대체 사항을 나타내어야 합니다. 예를 들어 다음은 대신되는 필드에 대한 이유입니다: 

`otherFieldName`을 사용하세요

예시: 

field :designs, ::Types::DesignManagement::DesignCollectionType, null: true,
      deprecated: { reason: '`designCollection`을 사용하세요', milestone: '10.0' },
      description: '이 이슈와 연관된 디자인입니다.',

module Types
  class TodoStateEnum < BaseEnum
    value 'pending', deprecated: { reason: 'PENDING을 사용하세요', milestone: '10.0' }
    value 'done', deprecated: { reason: 'DONE을 사용하세요', milestone: '10.0' }
    value 'PENDING', value: 'pending'
    value 'DONE', value: 'done'
  end
end

퇴화되는 필드, 인자 또는 열거값이 대체되지 않는 경우 설명적인 퇴화 이유를 제공해야 합니다.

전역 ID 퇴화

우리는 rails/globalid 젬을 사용하여 Global ID를 생성하고 구문 분석하여 모델 이름에 결합합니다. 모델 이름을 바꾸면 해당 Global ID도 변경됩니다.

스키마의 어디에서든지 Global ID를 인수 유형으로 사용하면, 기존 Global ID의 변경이 일반적으로 파괴적인 변경으로 간주됩니다.

이전 Global ID 인수를 계속 지원하려면 Gitlab::GlobalId::Deprecations에 퇴화를 추가합니다.

note
Global ID가 필드로만 노출된 경우에는 퇴화시킬 필요가 없습니다. Global ID가 필드의 표현 방식이 백워드 호환성을 가지고 있다고 생각합니다. 클라이언트가 이러한 값을 구문 분석하지 않을 것으로 예상되며, 이러한 값에서의 어떠한 구조도 우연인 것으로 판명되며 의존하지 않아야 합니다.

예시 시나리오:

이 예시 시나리오는 이 Merge Request를 기반으로 합니다.

PrometheusService라는 모델을 Integrations::Prometheus로 이름을 변경할 예정입니다. 이전 모델 이름을 사용하여 PrometheusServiceID로 명명된 Global ID 유형을 생성합니다. 이는 쿼리 서명에서 args.input.id인자로 PrometheusServiceID라는 이름으로 인식됩니다.

우리는 모델을 Integrations::Prometheus로 이름을 변경하고 코드베이스를 새 이름으로 업데이트합니다. 그후 뮤테이션을 업데이트하려면 새 이름에 대한 Global ID를 전달합니다.

이것은 Types::GlobalIDType[]에 Integrations::Prometheus로 이름을 전달하기 때문에 뮤테이션에 사용하는 방법이 파괴적인 변경을 초래합니다. API는 클라이언트를 거부합니다.

이전 인수 스타일을 계속 지원하기 위해 DEPRECATIONS 상수를 Gitlab::GlobalId::Deprecations에 추가하고 새 Deprecation을 배열에 추가합니다.

이후 퇴화 과정을 따릅니다.

추후에 이전 인수 스타일을 지원하는 것을 제거하기 위해서는 Deprecation을 제거하세요.

이 과정 동안 API는 인수값을 "gid://gitlab/PrometheusService/1" 또는 "gid://gitlab/Integrations::Prometheus/1" 포맷으로 모두 허용합니다.

쿼리 서명에서는 두 인자값 유형을 모두 허용합니다:

  • PrometheusServiceID
  • IntegrationsPrometheusID
note
이 예시에서 PrometheusServiceID을 사용하는 쿼리는 API에 의해 유효하고 실행가능하지만, 유효성 검사 도구는 이를 잘못된 것으로 간주하고 있습니다. 때문에 이를 퇴화되는 디렉티브 이외의 방법으로의 퇴화를 사용하기 때문에 유효성 검사 도구가 이것을 인식하지는 않습니다.

이 문서에서는 이전 Global ID 스타일이 퇴화된 것으로 언급합니다.

Alpha로 스키마 항목 표시하기

GraphQL 스키마 항목(필드, 매개변수, 열거값 및 뮤테이션)을 Alpha로 표시할 수 있습니다.

Alpha로 표시된 항목은 폐기 과정에서 제외되며 언제든 주의 없이 제거할 수 있습니다. Alpha로 표시된 항목은 변경 대상이며 공개 사용 준비가 되지 않은 경우에 사용합니다.

note
새로운 항목만 Alpha로 표시하세요. 이미 공개된 항목을 Alpha로 표시하지 마십시오.

스키마 항목을 Alpha로 표시하려면 alpha: 키워드를 사용해야 합니다. Alpha 항목이 소개된 milestone:을 제공해야 합니다.

예를 들어: 

field :token, GraphQL::Types::String, null: true,
      alpha: { milestone: '10.0' },
      description: '로그인용 토큰.'

마찬가지로, 전체 뮤테이션을 Alpha로 표시하려면 app/graphql/types/mutation_type.rb에서 뮤테이션이 마운트된 위치를 업데이트하세요: 

mount_mutation Mutations::Ci::JobArtifact::BulkDestroy, alpha: { milestone: '15.10' }

Alpha GraphQL 항목은 GraphQL 폐기 기능을 활용하는 기능이며, 이러한 항목은 GraphQL 스키마에서 폐기된 것으로 나타납니다. 모든 폐기된 스키마 항목과 마찬가지로 Alpha 필드를 대화형 GraphQL 탐색기(GraphiQL)에서 테스트할 수 있습니다. 그러나 GraphiQL 자동완성 편집기는 폐기된 필드를 제안하지 않습니다.

이 항목은 생성된 GraphQL 설명서와 해당 GraphQL 스키마 설명에서 Alpha로 표시됩니다.

열거형(Enum)

GitLab GraphQL 열거형은 app/graphql/types에 정의됩니다. 새로운 열거형을 정의할 때 다음 규칙이 적용됩니다:

  • 값은 대문자여야 합니다.
  • 클래스 이름은 Enum 문자열로 끝나야 합니다.
  • graphql_name은 Enum 문자열을 포함해서는 안됩니다.

예를 들어: 

module Types
  class TrafficLightStateEnum < BaseEnum
    graphql_name 'TrafficLightState'
    description '신호등 상태'
    
    value 'RED', description: '운전자는 정지해야 합니다.'
    value 'YELLOW', description: '안전한 경우에만 운전자가 정지해야 합니다.'
    value 'GREEN', description: '운전자가 출발하거나 계속 운전할 수 있습니다.'
  end
end

루비의 클래스 속성을 위한 열거형인 경우 대문자 값에 적응하는 value: 옵션을 제공할 수 있습니다.

다음 예에서:

  • OPENED의 GraphQL 입력은 'opened'로 변환됩니다.
  • 'opened'의 루비 값은 GraphQL 응답에서 "OPENED"로 변환됩니다. 
module Types
  class EpicStateEnum < BaseEnum
    graphql_name 'EpicState'
    description 'GitLab epic의 상태'
    
    value 'OPENED', value: 'opened', description: '열린 Epic.'
    value 'CLOSED', value: 'closed', description: '닫힌 Epic.'
  end
end

열거값은 스키마 항목을 폐기하는데 사용할 수 있습니다.

Rails 열거형에서 동적으로 GraphQL 열거형 정의

GraphQL 열거형이 Rails 열거형에서 지원되는 경우, Rails 열거형을 사용하여 동적으로 GraphQL 열거형 값을 정의하는 것이 좋습니다. 이렇게 하면 GraphQL 열거형 값이 Rails 열거형 정의에 바인딩되어, 값이 Rails 열거형에 추가되면 GraphQL 열거형이 자동으로 변경됩니다.

예: 

module Types
  class IssuableSeverityEnum < BaseEnum
    graphql_name 'IssuableSeverity'
    description '사건 심각도'
    
    ::IssuableSeverity.severities.each_key do |severity|
      value severity.upcase, value: severity, description: "#{severity.titleize} 심각도."
    end
  end
end

JSON

GraphQL에서 반환될 데이터가 JSON으로 저장될 때 가능한 경우에는 계속해서 GraphQL 유형을 사용해야 합니다. JSON 데이터의 구조가 다양하지만 알려진 가능한 구조 집합 중 하나일 경우, union을 사용하세요. 이러한 목적으로 인용된 교회 및 연합 사용 예시는 !30129에서 찾을 수 있습니다.

필요한 경우 필드 이름은 hash_key: 키워드를 사용하여 해시 데이터 키에 매핑할 수 있습니다.

예를 들어, 다음과 같은 JSON 데이터가 제공되는 경우: 

{
  "title": "내 차트",
  "data": [
    { "x": 0, "y": 1 },
    { "x": 1, "y": 1 },
    { "x": 2, "y": 2 }
  ]
}

다음과 같은 방식으로 GraphQL 유형을 사용할 수 있습니다: 

module Types
  class ChartType < BaseObject
    field :title, GraphQL::Types::String, null: true, description: '차트 제목.'
    field :data, [Types::ChartDatumType], null: true, description: '차트 데이터.'
  end
end

module Types
  class ChartDatumType < BaseObject
    field :x, GraphQL::Types::Int, null: true, description: '차트 데이터의 x축 값.'
    field :y, GraphQL::Types::Int, null: true, description: '차트 데이터의 y축 값.'
  end
end

설명

모든 필드 및 매개변수는 설명이 있어야 합니다.

필드 또는 매개변수의 설명은 description: 키워드를 사용하여 제공합니다. 예를 들어: 

field :id, GraphQL::Types::ID, description: '이슈의 ID.'
field :confidential, GraphQL::Types::Boolean, description: '이슈가 비밀인지를 나타냅니다.'
field :closed_at, Types::TimeType, description: '이슈가 종료된 시각.'

필드 및 매개변수의 설명은 다음에서 볼 수 있습니다:

설명 양식 가이드

언어 및 구두점

필드 및 매개변수를 설명하는 데 있어서 가능한 경우, 가능한 경우 {x} of the {y}를 사용하며, 여기서 {x}가 설명하는 항목이고, {y}가 적용되는 리소스인 경우 사용합니다. 예를 들어: 

이슈의 ID.

에픽의 작성자.

오름차순 또는 검색을 하는 매개변수의 경우, 적절한 동사로 시작합니다. 문맥상으로 가능한 경우, the given 또는 the specified 대신 this를 사용하여 지정된 값에 대해 간결하게 표현할 수 있습니다. 예를 들어: 

이 기준으로 이슈를 정렬합니다.

일관성과 간결함을 위해 설명을 ‘The’ 또는 ‘A’로 시작하지 마십시오.

모든 설명 뒤에 마침표(.)를 찍습니다.

부울

부울 필드(GraphQL::Types::Boolean)의 경우, 그 기능을 설명하는 동사로 시작합니다. 예를 들어: 

이슈가 비밀인지를 나타냅니다.

필요한 경우 기본값을 제공합니다. 예를 들어: 

이슈를 비밀로 설정합니다. 기본값은 거짓입니다.

정렬 열거형

정렬을 위한 열거형의 경우 '정렬하는 값 {x}에 대한 값.'으로 설명합니다. 예를 들어: 

컨테이너 리포지터리를 정렬하기 위한 값.

Types::TimeType 필드 설명

Types::TimeType GraphQL 필드의 경우에는 timestamp 단어를 포함해야 합니다. 이렇게 하면 포맷이 Date가 아닌 Time임을 알 수 있습니다.

예를 들어: 

field :closed_at, Types::TimeType, description: '이슈가 닫힌 시각.'

copy_field_description 도우미

때로는 두 설명이 항상 동일하도록 하고 싶을 때가 있습니다. 예를 들어, 유형 필드 설명을 변경 인수와 동일하게 유지하기 위해 둘 다 같은 속성을 나타낼 때입니다.

설명을 제공하는 대신, copy_field_description 도우미를 사용하여 유형 및 필드 이름을 전달하여 설명을 복사할 수 있습니다.

예시: 

argument :title, GraphQL::Types::String,
          required: false,
          description: copy_field_description(Types::MergeRequestType, :title)

문서 참조

가끔은 설명에서 외부 URL을 참조하고 싶을 때가 있습니다. 이를 더 쉽게 만들고 생성된 참조 문서에 적절한 마크업을 제공하기 위해 필드에 see 속성을 제공합니다. 예를 들어: 

field :genus,
      type: GraphQL::Types::String,
      null: true,
      description: '분류의 유속.',
      see: { 'Wikipedia page on genera' => 'https://wikipedia.org/wiki/Genus' }

이것은 우리 문서에서 다음과 같이 렌더링됩니다: 

분류의 유속. 참조: [Wikipedia page on genera](https://wikipedia.org/wiki/Genus)

여러 문서 참조를 제공할 수 있습니다. 이 속성의 구문은 키가 텍스트 설명이고 값이 URL인 HashMap입니다.

구독 티어 뱃지

필드나 인수가 다른 필드보다 높은 구독 티어에서 사용 가능한 경우, 티어 뱃지를 인라인으로 추가합니다.

예를 들어: 

description: '**(ULTIMATE ALL)** 사용자 정의 템플릿의 전체 경로.'

승인

참조: GraphQL 승인

리졸버

app/graphql/resolvers 디렉터리에 저장된 _리졸버_를 사용하여 애플리케이션이 응답을 제공하는 방식을 정의합니다. 리졸버는 해당하는 객체를 검색하는 실제 구현 로직을 제공합니다.

필드에 표시할 객체를 찾기 위해 필드에 리졸버를 추가할 수 있습니다. 리졸버와 동일한 방식으로 resolver에 인수를 정의할 수 있습니다. BatchLoader를 사용하여 성능을 제한할 수 있습니다.

리졸버 작성

우리의 코드는 일반적으로 위임자 및 서비스 주변의 가는 선언적 래퍼가 되어야 합니다. 인수 디렉터리을 반복하거나 이들을 고려하여 추출할 수 있습니다. 상속보다는 구성이 선호됩니다. 리졸버를 컨트롤러처럼 다루세요: 리졸버는 다른 응용 프로그램 추상화체를 구성하는 DSL이어야 합니다.

예를 들어: 

class PostResolver < BaseResolver
  type Post.connection_type, null: true
  authorize :read_blog
  description '블로그 글, 선택적으로 이름으로 필터링됩니다.'
  
  argument :name, [::GraphQL::Types::String], required: false, as: :slug
  
  alias_method :blog, :object
  
  def resolve(**args)
    PostFinder.new(blog, current_user, args).execute
  end
end

리졸버 클래스를 두 곳의 동일한 리졸버 필드에서 사용할 수는 있지만, 리졸버 개체를 직접 재사용해서는 안 됩니다. 리졸버는 풍부한 라이프사이클이 있으며 권한 부여, 준비 및 해결이 프레임워크에 의해 조화롭게 이루어지며 각 단계에서 지연 값이 반환되어 일괄 처리 기회를 활용할 수 있습니다. 응용 프로그램 코드에서 리졸버나 변형을 절대로 인스턴스화해서는 안 됩니다.

대신 코드 재사용의 단위는 응용 프로그램의 나머지 부분과 매우 유사합니다:

  • 데이터 조회를 위한 쿼리에서는 조회기.
  • 작업 적용을 위한 변형에서는 서비스.
  • (일괄처리를 인식하는) 로더는 쿼리에 특화됩니다.

변형에서 일괄 처리를 사용할 이유는 없습니다. 변형은 연속적으로 실행되므로 일괄 처리 기회가 없습니다. 모든 값은 요청시 즉시 평가되므로 일괄 처리가 불필요한 오버헤드입니다. 만약 다음 내용을 작성하고 있다면:

  • Mutation이면 객체를 직접 검색하세요.
  • Resolver 또는 BaseObject의 메서드이면 일괄 처리를 허용해야 합니다.

오류 처리

리졸버는 적절한 경우 상위 수준의 오류로 변환되는 오류를 발생할 수 있습니다. 예상되는 모든 오류는 적절한 GraphQL 오류로 변환되어야 합니다. (Gitlab::Graphql::Errors 참조) 예상되지 않은 모든 오류는 억제되고 클라이언트는 내부 서비스 오류 메시지를 수신합니다.

허가 오류는 특별한 경우입니다. REST API에서는 사용자가 액세스 권한이 없는 리소스에 대해404 Not Found를 반환합니다. GraphQL에서의 동등한 동작은 모든 결여된 또는 미인가된 리소스에 대해 null을 반환하는 것입니다. 쿼리 리졸버는 인가되지 않은 리소스에 대해 오류를 발생해서는 안 됩니다.

이에 대한 근거는 클라이언트가 기록의 결여와 액세스할 수 없는 기록 간의 차이를 구별하지 못해야 한다는 것입니다. 이렇게 하면 정보를 숨겨야 하는 보안 취약점이 발생합니다.

대부분의 경우에는 신경 쓸 필요가 없지만, 이는 authorize DSL 호출로 선언된 리졸버 필드 권한 부여에 의해 올바르게 처리됩니다. 그러나 더 사용자 정의해야 하는 경우에는, 현재 사용자가 액세스할 수 없는 개체에 직면하면 전체 필드를 null로 해결해야 한다는 것을 기억하세요.

파생 리졸버

(BaseResolver.single 및 BaseResolver.last 포함)

일부 사용 사례에 대해서는 다른 리졸버에서 리졸버를 파생시킬 수 있습니다. 이 작업의 주요 사용 사례는 모든 항목을 찾는 리졸버와 하나의 특정 항목을 찾는 리졸버입니다. 이에 따라 편리한 메서드를 제공합니다:

  • 첫 번째 항목을 선택하는 새로운 리졸버를 구성하는 BaseResolver.single.
  • 마지막 항목을 선택하는 리졸버를 구성하는 BaseResolver.last.

정확한 단수 형식은 컬렉션 유형에서 유추되므로 여기서 유형을 정의할 필요가 없습니다.

이러한 메서드를 사용하기 전에, 모두 가급적 간단하게 다른 리졸버를 작성하는지 고려해보세요.

BaseResolver.single을 지나치게 자유롭게 사용하는 것은 안티-패턴입니다. 예를 들어, 인수가 없으면 첫 번째 MR을 반환하는 Project.mergeRequest 필드와 같은 말이 안 되는 필드로 이어질 수 있습니다. 컬렉션 리졸버에서 단일 리졸버를 유도할 때마다 더 제한적인 인수가 있어야 합니다.

이를 가능하게 하려면, 단일 리졸버를 사용자 정의하는 when_single 블록을 사용하세요. 모든 when_single 블록은 다음과 같아야 합니다:

  • 적어도 하나의 인수를 정의(또는 재정의)해야 합니다.
  • 선택적 필터를 필수 필터로 만들어야 합니다.

예를 들어, 존재하는 선택적 인수를 재정의하고 유형을 변경해서 필수로 만드는 방법으로 이를 수행할 수 있습니다: 

class JobsResolver < BaseResolver
  type JobType.connection_type, null: true
  authorize :read_pipeline
  
  argument :name, [::GraphQL::Types::String], required: false
  
  when_single do
    argument :name, ::GraphQL::Types::String, required: true
  end
  
  def resolve(**args)
    JobsFinder.new(pipeline, current_user, args.compact).execute
  end

여기서는 파이프라인 작업을 가져오기 위한 리졸버가 있습니다. name 인수는 디렉터리을 가져올 때는 선택적이지만 단일 작업을 가져올 때는 필수입니다.

여러 인수가 있고 둘 다 필수 필드로 만들 수 없다면 준비 조건을 추가하기 위해 블록을 사용할 수 있습니다: 

class JobsResolver < BaseResolver
  alias_method :pipeline, :object
  
  type JobType.connection_type, null: true
  authorize :read_pipeline
  
  argument :name, [::GraphQL::Types::String], required: false
  argument :id, [::Types::GlobalIDType[::Job]],
           required: false,
           prepare: ->(ids, ctx) { ids.map(&:model_id) }
  
  when_single do
    argument :name, ::GraphQL::Types::String, required: false
    argument :id, ::Types::GlobalIDType[::Job],
             required: false
             prepare: ->(id, ctx) { id.model_id }
    
    def ready?(**args)
      raise ::Gitlab::Graphql::Errors::ArgumentError, 'Only one argument may be provided' unless args.size == 1
    end
  end
  
  def resolve(**args)
    JobsFinder.new(pipeline, current_user, args.compact).execute
  end

그런 다음 이러한 resolver를 필드에서 사용할 수 있습니다: 

# PipelineType에서

field :jobs, resolver: JobsResolver, description: '모든 작업.'
field :job, resolver: JobsResolver.single, description: '단일 작업.'

해석기 최적화

선행 검토

전체 쿼리는 실행 중에 미리 알려져 있으므로, 우리는 선행 검토를 활용하여 쿼리를 최적화하고, 필요한 연관 관계를 일괄 처리할 수 있습니다. N+1 성능 문제를 피하고자 해결자에 선행 검토 지원을 추가하는 것을 고려해보세요.

일반적인 선행 검토 사용 사례(자식 필드를 요청할 때 연관 관계를 미리로드하는)를 지원하려면, LooksAhead를 포함시킬 수 있습니다. 예를 들어: 

# 속성이 `[child_attribute, other_attribute, nested]`인 `MyThing` 모델을 가정합니다.
# 여기서 nested는 `included_attribute`라는 속성을 가집니다.
class MyThingResolver < BaseResolver
  include LooksAhead
  
  # `resolve(**args)`를 정의하는 대신, `resolve_with_lookahead(**args)`를 구현합니다.
  def resolve_with_lookahead(**args)
    apply_lookahead(MyThingFinder.new(current_user).execute)
  end
  
  # 항상 미리로드되어야 하는 항목을 나열합니다:
  # 예를 들어, 어떤 이유로든 항상 child_attribute가 필요한 경우(인가 중에),
  # 여기에 포함시킬 수 있습니다.
  def unconditional_includes
    [:child_attribute]
  end
  
  # 특정 필드가 선택된 경우 포함되어야 하는 항목을 나열합니다:
  def preloads
    {
        field_one: [:other_attribute],
        field_two: [{ nested: [:included_attribute] }]
    }
  end
end

기본적으로 #preloads에서 정의된 필드는 쿼리에서 해당 필드가 선택된 경우 사전로드됩니다. 경우에 따라, 너무 많이 사전로드하거나 잘못된 콘텐츠를 피하기 위해 더 정교한 제어가 필요할 수 있습니다.

위의 예제를 확장하여, 특정 필드가 함께 요청된 경우 다른 연관 관계를 사전로드하기 원할 수 있습니다. 이는 #filtered_preloads를 오버라이드하여 수행할 수 있습니다: 

class MyThingResolver < BaseResolver
  # ...
  
  def filtered_preloads
    return [:alternate_attribute] if lookahead.selects?(:field_one) && lookahead.selects?(:field_two)
    
    super
  end
end

LooksAhead 관련이 또한 중첩된 GraphQL 필드 정의를 기준으로 연관 관계를 사전로드하는 데 기본 지원을 제공합니다. WorkItemsResolver가 여기에 대한 좋은 예시입니다. nested_preloads는 해시를 반환하도록 정의하는 메소드로, preloads 메소드와 달리 각 해시 키의 값은 사전로드할 연관 관계 리스트가 아닌 다른 해시입니다. 따라서 이전 예제에서 nested_preloads를 이렇게 오버라이드할 수 있습니다: 

class MyThingResolver < BaseResolver
  # ...
  
  def nested_preloads
    {
      root_field: {
        nested_field1: :association_to_preload,
        nested_field2: [:association1, :association2]
      }
    }
  end
end

실제 사용 사례에 대한 예시는 다음과 같습니다. ResolvesMergeRequests를 참조하세요.

before_connection_authorization

before_connection_authorization 훅은 해결자들이 타입 인가 권한 확인으로부터 발생하는 N+1 문제를 해결하는 데 도움이 될 수 있습니다.

before_connection_authorization 메소드는 해결된 노드와 현재 사용자를 받습니다. 블록 내에서 ActiveRecord::Associations::Preloader 또는 Preloaders:: 클래스를 사용하여 타입 인가 확인을 위해 데이터를 사전로드할 수 있습니다.

예시: 

class LabelsResolver < BaseResolver
  before_connection_authorization do |labels, current_user|
    Preloaders::LabelsPreloader.new(labels, current_user).preload_all
  end
end

Batch로딩

GraphQL BatchLoader를 참조하세요.

Resolver#ready?의 올바른 사용

해결자에는 프레임워크의 일부로서 두 가지 공개 API 메소드인 #ready?(**args)와 #resolve(**args)가 있습니다. #ready?를 사용하여 #resolve를 호출하지 않고 설정 또는 일찍 반환하는 데 사용할 수 있습니다.

#ready?를 사용하는 좋은 이유는 다음과 같습니다:

  • 미리 알고 있는 경우 결과가 불가능한 경우 Relation.none을 반환합니다.
  • 단순히 초기화 인스턴스 변수 설정과 같은 설정을 수행합니다 (이 경우 느리게 초기화된 메소드를 고려하세요).

구현에서 Resolver#ready?(**args)는 다음과 같이 (Boolean, early_return_data)를 반환해야 합니다: 

def ready?(**args)
  [false, '대신 이를 사용하세요']
end

이에 따라, 테스트(주로 프레임워크 추상화 해결자는 재사용할 수 있는 것으로 간주되어서는 안 되므로 조회자 대신 사용되어야 합니다. 찾는 사람은 우선입니다)에서 해결자를 호출할 때 #ready? 메소드를 호출하고 resolve를 호출하기 전에 불리언 플래그를 확인하도록 항상 기억하세요! 이에 대한 예시는 우리의 GraphqlHelpers에서 확인할 수 있습니다.

인수 유효성 검사를 위해서, validators를 사용하는 것이 #ready?보다 우선합니다.

부정된 인수

부정된 필터는 일부 리소스를 필터링할 수 있습니다(예: bug 레이블이 있는 모든 이슈를 찾지만 bug2 레이블이 할당되어 있지 않은 모든 이슈를 찾습니다). not 인수는 부정된 인수를 전달하는 우선 구문입니다: 

issues(labelName: "bug", not: {labelName: "bug2"}) {
  nodes {
    id
    title
  }
}

당신은 자신의 타입이나 해결자에서 negated 도우미를 사용할 수 있습니다. 예를 들어: 

extend ::Gitlab::Graphql::NegatableArguments

negated do
  argument :labels, [GraphQL::STRING_TYPE],
            required: false,
            as: :label_name,
            description: '배열 레이블 이름. 모든 해결된 Merge Request이 이러한 레이블을 갖지 않아야 합니다.'
end

메타데이터

해결자를 사용할 때, 해결자는 필드 메타데이터의 SSoT로서 사용될 수 있고 그래야 합니다. 이들 필드 옵션(필드 이름 이외)들은 모두 해결자에 선언할 수 있습니다.

  • type (필수 - 모든 해결자는 타입 어노테이션을 포함해야 합니다)
  • extras
  • description
  • Gitaly 주석 (calls_gitaly! 사용)

예시: 

module Resolvers
  MyResolver < BaseResolver
    type Types::MyType, null: true
    extras [:lookahead]
    description '단일 MyType 검색'
    calls_gitaly!
  end
end

부모 객체를 자식 Presenter에 전달

가끔은 자식 컨텍스트에서 해결된 쿼리 부모에 액세스해야 할 수 있습니다. 일반적으로 부모는 해결자 클래스의 parent로만 사용할 수 있습니다.

Presenter 클래스에서 부모 객체를 찾는 방법:

  1. 해결자의 resolve 메소드에서 GraphQL context에 부모 객체를 추가합니다: 

      def resolve(**args)
    context[:parent_object] = parent
  end

  2. 해결자나 필드가 parent 필드 컨텍스트를 요구하도록 선언합니다. 예를 들어: 

      # in ChildType
  field :computed_field, SomeType, null: true,
        method: :my_computing_method,
        extras: [:parent], # 필수
        description: '내 필드 설명.'
     
  field :resolver_field, resolver: SomeTypeResolver
     
  # SomeTypeResolver 안에서
     
  extras [:parent]
  type SomeType, null: true
  description '내 필드 설명.'

  3. Presenter 클래스에서 필드의 메소드를 선언하고 parent 키워드 인수를 받도록 합니다. 이 인수는 부모 GraphQL 컨텍스트를 포함하므로, 부모 객체에 액세스하기 위해 parent[:parent_object] 또는 해결자의 Resolver에서 사용한 키로 액세스해야 합니다: 

      # in ChildPresenter
  def my_computing_method(parent:)
    # 여기서 `parent[:parent_object]`로 무언가를 수행하세요.
  end
     
  # In SomeTypeResolver
     
  def resolve(parent:)
    # ...
  end

실제 사용 사례에 대한 예시는 IterationPresenter에 scopedPath 및 scopedUrl을 추가한 MR를 참조하세요.

변이

변이는 저장된 값의 변경 또는 동작을 트리거하기 위해 사용됩니다. GET 요청이 데이터를 수정하면 안 되는 것과 마찬가지로 우리는 일반 GraphQL 쿼리에서 데이터를 수정할 수 없습니다. 하지만 변이에서는 데이터를 수정할 수 있습니다.

변이 빌드

변이는 주로 리소스 별로 그룹화된 app/graphql/mutations에 저장되며, 이를테면 우리의 서비스와 유사하게 그룹화될 것입니다. 이들은 Mutations::BaseMutation을 상속해야 합니다. 변이에 정의된 필드는 변이의 결과로 반환됩니다.

변이 업데이트 정밀도

GitLab의 서비스 지향 아키텍처는 대부분의 변이가 Create, Delete 또는 Update 서비스를 호출한다는 의미이며, 예를 들어 UpdateMergeRequestService와 같은 것입니다. 업데이트 변이의 경우 객체의 한 측면만 업데이트할 수 있도록 세밀하게 제어된 변이, 예를 들어 MergeRequest::SetDraft와 같은 것이 필요할 수 있습니다.

세밀하게 제어된 변이와 거친 변이 모두 가져도 괜찮지만, 세밀하게 제어된 변이가 너무 많으면 유지보수, 코드 가독성 및 테스트에 조직적 문제를 일으킬 수 있음을 인지해야 합니다. 각 변이에 새로운 클래스가 필요하며, 이는 기술적 부채로 이어질 수 있습니다. 또한 스키마가 매우 커지면 사용자가 스키마를 탐색하기 어려울 수 있습니다. 또한 새로운 각 변이에는 테스트(느린 요청 통합 테스트 포함)가 필요하기 때문에 변이를 추가함으로써 테스트 스위트가 느려집니다.

변경 사항을 최소화하려면:

  • 가능한 경우 MergeRequest::Update와 같은 기존 변이를 사용하십시오.
  • 거친 변이로서 기존 서비스를 노출하십시오.

세밀하게 제어된 변이가 적합한 경우:

  • 특정 권한이 필요한 속성 수정
  • 상태 기계와 유사한 전이 노출(이슈 잠금, MR Merge, 에픽 종료 등)
  • 중첩된 속성 수락(자식 객체에 대한 속성 수락)
  • 변이의 의미가 명확하고 간결하게 표현될 수 있는 경우

추가 맥락은 이슈 #233063에서 확인하십시오.

명명 규칙

각 변이는 GraphQL 스키마에서 변이의 이름인 graphql_name을 정의해야 합니다.

예시: 

class UserUpdateMutation < BaseMutation
  graphql_name 'UserUpdate'
end

1.13 버전의 graphql-ruby 젬에서 변경 사항이 있어서 graphql_name은 타입 이름이 올바르게 생성되도록 클래스의 첫 번째 줄에 있어야 합니다. Graphql::GraphqlNamePosition 콥이 이를 강제합니다. 추가 맥락은 이슈 #27536에서 확인하십시오.

우리의 GraphQL 변이 이름은 역사적으로 일관성이 없지만, 새로운 변이 이름은 {리소스}{액션} 또는 {리소스}{액션}{속성} 규칙을 따라야 합니다.

새 리소스를 만들 변이는 동사 Create를 사용해야 합니다.

예시:

  • CommitCreate

데이터 수정 변이에는 다음을 사용해야 합니다:

  • 동사 Update
  • 더 적합하다면 Set, Add, 또는 Toggle과 같은 도메인별 동사

예시:

  • EpicTreeReorder
  • IssueSetWeight
  • IssueUpdate
  • TodoMarkDone

데이터 제거 변이에는 다음을 사용해야 합니다:

  • Destroy가 아닌 동사 Delete
  • 더 적합하다면 Remove와 같은 도메인별 동사

예시:

  • AwardEmojiRemove
  • NoteDelete

변이 명명에 대한 조언이 필요한 경우 Slack #graphql 채널에서 피드백을 요청하십시오.

필드

가장 일반적인 상황에서 변이는 다음 2개의 필드를 반환해야 합니다:

  • 수정된 리소스
  • 작업을 수행할 수 없는 이유를 설명하는 오류 디렉터리. 변이가 성공하면 이 디렉터리은 비어 있을 것입니다.

새로운 변이를 Mutations::BaseMutation에서 상속함으로써 errors 필드가 자동으로 추가됩니다. clientMutationId 필드도 추가되며, 클라이언트가 단일 요청에서 여러 수정을 수행할 때 이를 식별하는 데 사용할 수 있습니다.

resolve 메서드

리졸버 작성과 유사하게, 변이의 resolve 메서드는 주석 인수로 변이의 인수를 받아들입니다. 여기서 리소스를 수정하는 서비스를 호출할 수 있습니다.

resolve 메서드는 수정된 리소스에 대한 필드 이름과 동일한 이름의 해시를 반환해야 합니다. 또한 errors 배열을 포함해야 합니다. 예를 들어, Mutations::MergeRequests::SetDraft은 merge_request 필드를 정의합니다.

예시: 

field :merge_request,
      Types::MergeRequestType,
      null: true,
      description: "The merge request after mutation."

이는 이 변이의 resolve에서 반환된 해시가 다음과 같아야 함을 의미합니다. 

{
  # 수정된 Merge Request, 이것은 해당 필드에 정의된 타입으로 래핑될 것입니다.
  merge_request: merge_request,
  # 인증 이후 변이에 실패한 경우 문자열 배열
  # `errors_on_object` 도우미는 `errors.full_messages`를 수집합니다
  errors: errors_on_object(merge_request)
}

변이 마운팅

변이를 사용할 수 있게 하려면 graphql/types/mutation_type에 저장된 변이 타입에서 정의해야 합니다. mount_mutation 도우미 메서드는 변이의 GraphQL 이름을 기반으로 필드를 정의합니다.

예시: 

module Types
  class MutationType < BaseObject
    graphql_name 'Mutation'
    
    include Gitlab::Graphql::MountMutation
    
    mount_mutation Mutations::MergeRequests::SetDraft
  end
end

Mutations::MergeRequests::SetDraft를 해결하도록 mergeRequestSetDraft이라는 필드를 생성합니다.

리소스 인가

변이 내에서 리소스를 승인하려면 변이에 필요한 권한을 다음과 같이 제공해야 합니다: 

module Mutations
  module MergeRequests
    class SetDraft < Base
      graphql_name 'MergeRequestSetDraft'
      
      authorize :update_merge_request
    end
  end
end

그런 다음 resolve 메서드에서 authorize!를 호출하여 권한을 검증할 리소스를 전달할 수 있습니다.

또는 변이에서 객체를 로드하는 find_object 메서드를 추가할 수 있습니다. 이를 통해 authorized_find! 도우미 메서드를 사용할 수 있습니다.

사용자가 작업을 수행할 수 없는 경우 또는 객체를 찾을 수 없는 경우 resolve 메서드에서 raise_resource_not_available_error!를 호출하여 Gitlab::Graphql::Errors::ResourceNotAvailable를 발생시켜야 합니다.

변이에서의 오류

변이에 대한 오류 데이터의 관행을 따르는 것을 권장합니다. 이는 오류를 처리할 수 있는 사용자에 의해 이들이 관련된 사람에 의해 명시하는 오류를 구별합니다.

주요 포인트:

  • 모든 변이 응답에는 errors 필드가 있어야 합니다. 실패 시 이를 채워야 하며, 성공 시 이를 채우는 것이 좋습니다.
  • 오류를 볼 필요가 있는 사람: 사용자 또는 개발자
  • 클라이언트는 변이 수행 시 항상 errors 필드를 요청해야 합니다.
  • 오류는 사용자에게는 항상 $root.errors (최상위 오류) 또는 $root.data.mutationName.errors (변이 오류)에보고될 수 있습니다. 위치는 이 오류가 어떤 종류이며 어떤 정보를 보유하고 있는지에 달려 있습니다.
  • 변이 필드는 null: true여야 합니다

예시에 따르면 doTheThing 변이는 errors: [String] 및 thing: ThingType으로 응답하는 경우를 고려합니다. thing의 구체적인 성격은 이 예시에서 중요하지 않으므로 오류에 관해서만 고려합니다.

변이 응답이 가질 수 있는 세 가지 상태는 다음과 같습니다:

성공

행복한 경우에는 기대한 페이로드와 함께 오류가 발생할 수 있지만, 모든 것이 성공했다면 errors는 비어 있는 배열이어야 합니다. 왜냐하면 사용자에게 알릴 문제가 없기 때문입니다. 

{
  data: {
    doTheThing: {
      errors: [] // 성공했을 경우, 일반적으로 이 배열은 비어 있을 것입니다.
      thing: { .. }
    }
  }
}

실패 (사용자 관련)

사용자에게 영향을 미치는 오류가 발생했습니다. 이러한 것을 _변이 오류_라고 합니다.

생성 변이에서 일반적으로 반환할 thing은 없습니다.

업데이트 변이에서 thing의 현재 실제 상태를 반환합니다. 개발자는 thing 인스턴스에 대해 #reset를 호출하여 이 작업이 수행되도록 해야 할 수 있습니다. 

{
  data: {
    doTheThing: {
      errors: ["물건에 닿을 수 없습니다"],
      thing: { .. }
    }
  }
}

이에는 다음이 포함됩니다.

  • 모델 유효성 오류: 사용자는 입력을 변경해야 할 수 있습니다.
  • 권한 오류: 사용자는 이 작업을 할 수 없다는 사실을 알아야 하며 권한을 요청하거나 로그인해야 할 수 있습니다.
  • 사용자의 조치를 방해하는 응용 프로그램 상태의 문제 (예: Merge 충돌 또는 잠긴 리소스).

이상적으로는 사용자가 여기까지 오는 것을 방지해야 하지만, 만약 그들이 오게 된다면 실패의 이유와 그들의 의도를 달성하기 위해 할 수 있는 것을 이해할 수 있도록 무엇이 잘못되었는지 알려주어야 합니다. 예를 들어, 요청을 다시 시도하는 것만으로 충분할 수도 있습니다.

변이 데이터와 함께 복구 가능한 오류를 반환하는 것이 가능합니다. 예를 들어, 사용자가 10개의 파일을 업로드하고 그 중 3개가 실패하고 나머지는 성공했을 경우, 실패한 것에 대한 오류를 사용자에게 제공할 수 있으며, 성공 정보와 함께 사용자에게 제공할 수 있습니다.

실패 (사용자와 관련 없음)

하나 이상의 복구할 수 없는 오류가 상위 수준에서 반환될 수 있습니다. 이것들은 사용자가 거의 또는 전혀 제어할 수 없는 것으로, 주로 시스템 또는 프로그래밍 문제로 인해 발생할 수 있습니다. 이러한 경우에는 data가 없습니다: 

{
  errors: [
    {"message": "인수 오류: 정수가 예상되었지만 null을 받았습니다."},
  ]
}

이것은 변이 중에 오류를 발생시키는 것입니다. 우리의 구현에서는 인수 오류와 유효성 오류의 메시지가 클라이언트로 반환되며, 다른 모든 StandardError 인스턴스는 잡혀서 기록되고 메시지가 "내부 서버 오류"로 설정되어 클라이언트에 제공됩니다. 자세한 내용은 GraphqlController를 참조하십시오.

이러한 것들은 다음과 같은 프로그래밍 오류를 나타냅니다.

  • GraphQL 구문 오류: 예상되는 문자열대신에 정수가 전달되었거나 필요한 인수가 존재하지 않는 경우와 같은 경우입니다.
  • 스키마 오류: 예를 들어, 필수가 아닌 필드에 대한 값이 제공할 수 없는 경우와 같은 경우입니다.
  • 시스템 오류: 예를 들어, Git 리포지터리 예외 또는 데이터베이스 가용성과 같은 경우입니다.

사용자는 보통 사용 중에 이러한 오류를 발생시키지 못해야 합니다. 이러한 오류 카테고리는 내부적으로 취급되어야 하며 구체적인 세부 정보로 사용자에게 표시되어서는 안됩니다.

변이가 실패하는 경우 사용자에게 실패했음을 알려줘야 하지만, 왜 실패했는지는 알려줄 필요가 없습니다. 왜냐하면 사용자가 그것을 유발할 수 없으며, 그것을 고칠 수 있는 것이 없습니다. 다만 변이를 다시 시도할 수 있는 것을 제안할 수는 있습니다.

오류 분류

우리가 변이를 작성할 때, 오류 상태가 어느 카테고리에 속하는지에 대해 의식해야 하며(그리고 이에 대해 frontend 개발자들과 소통해야 합니다). 이는 사용자의 필요성을 _client_의 필요성과 구분하는 것을 의미합니다.

사용자가 알아야 할 오류가 아니라면 해당 오류를 catch해서는 안 됩니다.

사용자가 알아야 한다면 frontend 개발자들과 소통하여 돌려주는 오류 정보가 관련이 있고 목적을 제공하는지 확인해야 합니다.

또한 frontend GraphQL 가이드를 참조하세요.

별칭 지정 및 변이 폐기

#mount_aliased_mutation 도우미를 사용하여 MutationType에서 변이의 이름을 다른 이름으로 별칭 지정할 수 있습니다.

예를 들어, FooMutation이라는 변이를 BarMutation으로 별칭 지정하는 경우: 

mount_aliased_mutation 'BarMutation', Mutations::FooMutation

이를 통해 변이의 이름을 바꾸고 이전 이름을 계속 지원할 수 있습니다. 이것은 deprecated 인수와 결합될 때 사용됩니다.

예: 

mount_aliased_mutation 'UpdateFoo',
                        Mutations::Foo::Update,
                        deprecated: { reason: 'fooUpdate를 사용하세요', milestone: '13.2' }

폐기된 변이는 Types::DeprecatedMutations에 추가되어야 하며 Types::MutationType의 단위 테스트에서 테스트되어야 합니다. 이와 관련된 메서드와 폐기된 별칭 변이의 테스트 방법에 대한 예제로 !34798를 참조할 수 있습니다.

EE 변이 폐기

EE 변이는 동일한 프로세스를 따라야 합니다. Merge request 프로세스의 예에 대해서는 merge request !42588을 참조하세요.

구독

우리는 구독을 사용하여 업데이트를 클라이언트에 밀어넣습니다. 이를 위해 Action Cable implementation을 사용하여 웹소켓을 통해 메시지를 전달합니다.

클라이언트가 구독할 때, 우리는 그들의 쿼리를 Puma 워커의 메모리에 저장합니다. 그런 다음 구독이 트리거되면 Puma 워커는 저장된 GraphQL 쿼리를 실행하고 결과를 클라이언트에게 밀어넣습니다.

note
우리는 현재 GraphiQL이 지원하지 않는 Action Cable 클라이언트가 필요하기 때문에 GraphiQL을 사용하여 구독을 테스트할 수 없습니다.

구독 작성

Types::SubscriptionType 아래의 모든 필드는 클라이언트가 구독할 수 있는 구독입니다. 이러한 필드들은 Subscriptions::BaseSubscription의 하위 클래스이자 app/graphql/subscriptions에 저장되어 있는 구독 클래스가 필요합니다.

구독하고자 하는 인수와 반환되는 필드는 구독 클래스에서 정의됩니다. 동일한 인수와 동일한 필드를 반환하는 경우 여러 필드가 같은 구독 클래스를 공유할 수 있습니다.

이 클래스는 초기 구독 요청 및 후속 업데이트 중에 실행됩니다. 이에 대해 더 자세히 읽어보려면 GraphQL Ruby 가이드를 읽어보세요.

권한

초기 구독 및 후속 업데이트가 인증될 수 있도록 구독 클래스의 #authorized? 메서드를 구현해야 합니다.

사용자가 인가되지 않은 경우, 실행이 중단되고 사용자가 구독이 취소됩니다. false를 반환하는 경우 응답이 적색 처리되지만 업데이트가 발생한다는 정보가 유출됩니다. 이 유출은 GraphQL gem의 버그로 인한 것입니다.

구독 트리거

GraphqlTriggers 모듈 아래의 메서드를 정의하여 구독을 트리거합니다. 애플리케이션 코드에서 직접 GitlabSchema.subscriptions.trigger를 호출하지 않도록하여 니가한 근원 소스를 갖고 구독을 다른 인수와 객체로 트리거하지 않도록 합니다.

페이지네이션 구현

자세한 정보는 GraphQL 페이지네이션을 참조하십시오.

인수

resolver 또는 변이에 대한 인수는 argument를 사용하여 정의됩니다.

예: 

argument :my_arg, GraphQL::Types::String,
         required: true,
         description: "인수에 대한 설명"

널 가능성

인수는 required: true로 표시될 수 있으며, 이는 값이 존재하고 null이 아니어야 함을 의미합니다. 필수 인수의 값이 null일 수 있는 경우 required: :nullable 선언을 사용하세요.

예: 

argument :due_date,
         Types::TimeType,
         required: :nullable,
         description: '이슈에 대한 원하는 마감일. null이면 마감일이 제거됨.'

위의 예시에서 due_date 인수는 주어져야 하지만, GraphQL 사양과 달리 값이 null일 수 있습니다. 이를 통해 단일 변이에서 마감일을 ‘취소’하거나 새로운 변이를 생성하는 대신에 마감일을 제거할 수 있습니다. 

{ due_date: null } # => 허용
{ due_date: "2025-01-10" } # => 허용
{  } # => 유효하지 않음 (주어지지 않음)

Nullability and required: false

만약 인수가 required: false로 표시된 경우, 클라이언트는 값을 null로 보낼 수 있습니다. 이는 종종 바람직하지 않습니다.

인수가 선택적이지만 null이 허용되지 않는 경우, 유효성을 검증하여 null을 전달하면 오류가 발생하도록합니다. 

argument :name, GraphQL::Types::String,
         required: false,
         validates: { allow_null: false }

또는, null이 허용되지 않을 때 null을 기본 값으로 대체하려면 다음을 사용할 수 있습니다. 

argument :name, GraphQL::Types::String,
         required: false,
         default_value: "No Name Provided",
         replace_null_with_default: true

자세한 내용은 검증, Nullability, 기본값을 참조하세요.

상호 배타적인 인수

인수는 상호 배타적으로 표시될 수 있으며, 동시에 제공되지 않도록 보장합니다. 나열된 인수 중 하나 이상이 제공될 때, 최상위 오류가 추가됩니다.

예시: 

argument :user_id, GraphQL::Types::String, required: false
argument :username, GraphQL::Types::String, required: false

validates mutually_exclusive: [:user_id, :username]

키워드

정의된 각 GraphQL argument는 변형(mutation)의 #resolve 메서드로 전달됩니다. 키워드 인수로.

예시: 

def resolve(my_arg:)
  # 변형 수행 ...
end

입력 유형

graphql-ruby는 인수를 입력 유형으로 래핑합니다.

예를 들어, mergeRequestSetDraft 변형 은 이러한 인수를 정의합니다 (일부는 상속을 통해): 

argument :project_path, GraphQL::Types::ID,
         required: true,
         description: "Merge Request이 속한 프로젝트."

argument :iid, GraphQL::Types::String,
         required: true,
         description: "Merge Request의 IID."

argument :draft,
         GraphQL::Types::Boolean,
         required: false,
         description: <<~DESC
           Merge Request을 드래프트로 설정할지 여부.
         DESC

이러한 인수는 우리가 지정한 3개의 인수와 clientMutationId로 자동으로 입력 유형인 MergeRequestSetDraftInput을 생성합니다.

객체 식별자 인수

객체를 식별하는 인수는 다음과 같이 사용되어야 합니다.

  • 전체 경로 또는 IID가 있는 경우에는 전체 경로 또는 IID를 사용합니다.
  • 기타 모든 객체에 대해서는 객체의 전역 ID를 사용합니다. 일반적인 데이터베이스 기본 키 ID를 사용하지 마십시오.

전체 경로 객체 식별자 인수

과거에 우리는 전체 경로 인수의 명명에 일관성이 없었지만, 다음과 같이 인수의 이름을 지정하는 것을 선호합니다.

  • 프로젝트 전체 경로의 경우 project_path
  • 그룹 전체 경로의 경우 group_path
  • 네임스페이스 전체 경로의 경우 namespace_path

ciJobTokenScopeRemoveProject 변형에서의 예시: 

argument :project_path, GraphQL::Types::ID,
         required: true,
         description: 'CI 작업 토큰 범위가 속한 프로젝트.'

IID 객체 식별자 인수

객체의 IID를 해당 부모 project_path 또는 group_path와 함께 사용합니다. 예를 들어: 

argument :project_path, GraphQL::Types::ID,
         required: true,
         description: '이슈가 속한 프로젝트.'

argument :iid, GraphQL::Types::String,
         required: true,
         description: '이슈의 IID.'

전역 ID 객체 식별자 인수

discussionToggleResolve 변형에서의 예시: 

argument :id, Types::GlobalIDType[Discussion],
         required: true,
         description: '토론의 전역 ID.'

또한 전역 ID 폐기를 참조하십시오.

정렬 인수

정렬 인수는 가능한 경우 열거형 유형을 사용하여 사용 가능한 정렬 값 집합을 설명해야 합니다.

열거형은 Types::SortEnum에서 상속될 수 있습니다.

열거형 값은 {PROPERTY}_{DIRECTION} 형식을 따라야 합니다. 예를 들어: 

TITLE_ASC

또한 정렬 열거형에 대한 설명 스타일 가이드를 참조하십시오.

ContainerRepositoriesResolver의 예시: 

# Types::ContainerRepositorySortEnum:
module Types
  class ContainerRepositorySortEnum < SortEnum
    graphql_name 'ContainerRepositorySort'
    description '컨테이너 리포지터리를 정렬하는 데 사용되는 값들'
    
    value 'NAME_ASC', '이름을 오름차순으로.', value: :name_asc
    value 'NAME_DESC', '이름을 내림차순으로.', value: :name_desc
  end
end

# Resolvers::ContainerRepositoriesResolver:
argument :sort, Types::ContainerRepositorySortEnum,
          description: '컨테이너 리포지터리를이 기준으로 정렬합니다.',
          required: false,
          default_value: :created_desc

GitLab 사용자 정의 스칼라

Types::TimeType

Types::TimeType 은 Ruby Time 및 DateTime 객체를 다루는 모든 필드와 인수에 대해 사용되어야 합니다.

해당 유형은 사용자 정의 스칼라 로, 다음을 수행합니다:

  • 우리의 GraphQL 필드 유형으로 사용될 때 Ruby의 Time 및 DateTime 객체를 표준화된 ISO-8601 형식의 문자열로 변환합니다.
  • 본격적으로 포맷된 ISO-8601 시간 문자열을 GraphQL 인수 유형으로 사용할 때 Ruby Time 객체로 변환합니다.

이로써 우리의 GraphQL API는 시간을 제시하고 시간 입력을 처리하는 표준화된 방법을 갖게 됩니다.

예시: 

field :created_at, Types::TimeType, null: true, description: '이슈가 생성된 타임스탬프.'

전역 ID 스칼라

모든 전역 ID는 사용자 정의 스칼라입니다. 이들은 추상 스칼라 클래스에서 동적으로 생성됩니다.

테스트

변형 및 리졸버를 테스트할 때 전체 GraphQL 요청을 단위로하는 것이 좋습니다. 이렇게 하면 의존성 업그레이드가 훨씬 어려워지기 때문에 프레임워크와의 강한 결합을 피할 수 있습니다.

다음을 준수해야합니다:

  • 리졸버 및 변형에 대한 단위 테스트가 아닌 GraphQL 요청 스펙을 선호합니다(전체 API 엔드포인트를 사용하거나 GitlabSchema.execute를 통해 직접 실행).
  • GraphqlHelpers#resolve 및 GraphqlHelpers#resolve_field 대신 GraphqlHelpers#execute_query 및 GraphqlHelpers#run_with_clean_state을 선호합니다.

예시: 

# 좋은 예:
gql_query = %q(some query text...)
post_graphql(gql_query, current_user: current_user)
# 또는:
GitlabSchema.execute(gql_query, context: { current_user: current_user })

# 사용하지 않음: 피하십시오
resolve(described_class, obj: project, ctx: { current_user: current_user })

유닛 테스트 작성(사용 중단)

caution
만약 동일한 것을 전체 GraphQL 요청으로 테스트할 수 있다면 유닛 테스트를 피하십시오.

유닛 테스트를 만들기 전에 다음 예제를 검토하십시오:

통합 테스트 작성

통합 테스트는 ‘spec/requests/api/graphql’에 저장되며 GraphQL 쿼리나 뮤테이션을 위한 전체 스택을 확인합니다.

속도를 고려하여 직접 GitlabSchema.execute를 호출하거나 테스트할 타입만 포함하는 작은 테스트 스키마를 사용하는 것을 고려하십시오.

그러나 데이터가 반환되는 전체 요청 통합 테스트는 다음을 확인합니다:

  • 뮤테이션이 실제로 스키마에서 쿼리 가능한지( ‘MutationType’에 마운트되었는지).
  • 리졸버나 뮤테이션에 의해 반환된 데이터가 필드의 반환 유형과 일치하여 오류 없이 해석되는지.
  • 입력에서 인수가 올바르게 변환되며, 출력에서 필드가 올바르게 직렬화되는지.

통합 테스트는 또한 전체 스택을 호출하기 때문에 다음을 검증할 수 있습니다:

  • 인수나 스칼라의 검증이 올바르게 적용되는지.
  • 리졸버나 뮤테이션의 #ready? 메소드의 로직이 올바르게 적용되는지.
  • 인수의 default_value이 올바르게 적용되는지.
  • 객체가 성공적으로 해결되고 N+1 문제가 없는지.

쿼리를 추가할 때, 쿼리가 유효한 결과를 렌더링하는지 테스트하는 것에 사용할 수 있는 데이터를 반환하는 실제 graphql 쿼리와 데이터를 반환하지 않는 실제 graphql 쿼리의 공통 예제를 사용할 수 있습니다.

GraphqlHelpers#all_graphql_fields_for 헬퍼를 사용하여 모든 가능한 필드를 포함한 쿼리를 작성할 수 있습니다.

쿼리에 사용 가능한 모든 필드를 포함하는 테스트를 추가하는 데 직관적으로 더 쉽습니다.

페이징 및 정렬을 지원하는 쿼리에 필드를 추가하고 있는 경우 자세한 내용은 Testing을 방문하십시오.

GraphQL 뮤테이션 요청을 테스트하려면, GraphqlHelpers는 두 가지 헬퍼를 제공합니다: mutation은 뮤테이션의 이름 및 뮤테이션을 위한 입력 값을 가져온 후, 뮤테이션 쿼리 및 준비된 변수를 반환합니다.

그런 다음, 이 구조체를 post_graphql_mutation 헬퍼에 전달하여 GraphQL 클라이언트가 하는 것과 같은 올바른 매개변수로 요청을 게시할 수 있습니다.

뮤테이션의 응답에 액세스하려면, graphql_mutation_response 헬퍼를 사용할 수 있습니다.

이러한 헬퍼들을 사용하여 다음과 같은 스펙을 작성할 수 있습니다: 

let(:mutation) do
  graphql_mutation(
    :merge_request_set_wip,
    project_path: 'gitlab-org/gitlab-foss',
    iid: '1',
    wip: true
  )
end

it 'returns a successful response' do
   post_graphql_mutation(mutation, current_user: user)
   
   expect(response).to have_gitlab_http_status(:success)
   expect(graphql_mutation_response(:merge_request_set_wip)['errors']).to be_empty
end

테스트 팁과 트릭

  • GraphqlHelpers 지원 모듈의 메소드에 익숙해지십시오. 이러한 메소드 중 많은 메소드가 GraphQL 테스트 작성을 쉽게 만듭니다.

  • GraphqlHelpers#graphql_data_at 및 GraphqlHelpers#graphql_dig_at와 같은 탐색 헬퍼를 사용하여 결과 필드에 액세스하십시오. 예를 들어: 

    result = GitlabSchema.execute(query)
  
mr_iid = graphql_dig_at(result.to_h, :data, :project, :merge_request, :iid)

  • 결과와 일치하도록 GraphqlHelpers#a_graphql_entity_for을 사용할 수 있습니다. 예를 들어: 

    post_graphql(some_query)
  
# 프로젝트, 이슈, 노드에 포함 된 해시임을 확인합니다.
expect(graphql_data_at(:project, :issues, :nodes))
  .to contain_exactly(a_graphql_entity_for(issue))
  
# 추가 필드는 메소드 이름 또는 값으로 전달될 수 있습니다.
expect(graphql_data_at(:project, :issues, :nodes))
  .to contain_exactly(a_graphql_entity_for(issue, :iid, :title, created_at: some_time))

  • GraphqlHelpers#empty_schema를 직접 생성하는 대신 빈 스키마를 생성할 수 있습니다. 예를 들어: 

    # 좋은 예
let(:schema) { empty_schema }
  
# 나쁜 예
let(:query_type) { GraphQL::ObjectType.new }
let(:schema) { GraphQL::Schema.define(query: query_type, mutation: nil)}

  • GraphqlHelpers#query_double(schema: nil) 또는 double('query', schema: nil)를 사용하십시오. 예를 들어: 

    # 좋은 예
let(:query) { query_double(schema: GitlabSchema) }
  
# 나쁜 예
let(:query) { double('Query', schema: GitlabSchema) }

  • 거짓 긍정적인 결과를 피하십시오:

    post_graphql의 current_user: 인수를 사용하여 사용자를 인증하면 해당 사용자에 대한 요청에서 첫 번째 요청보다 후속 요청에서 더 많은 쿼리가 생성됩니다. N+1 쿼리를 피하기 위해 QueryRecorder를 사용하여 테스트하는 경우 각 요청에 대해 다른 사용자를 사용하십시오.

    아래 예제는 N+1 쿼리를 피하기 위한 테스트를 보여줍니다: 

    RSpec.describe 'Query.project(fullPath).pipelines' do
  include GraphqlHelpers
    
  let(:project) { create(:project) }
    
  let(:query) do
    %(
      {
        project(fullPath: "#{project.full_path}") {
          pipelines {
            nodes {
              id
            }
          }
        }
      }
    )
  end
    
  it 'avoids N+1 queries' do
    first_user = create(:user)
    second_user = create(:user)
    create(:ci_pipeline, project: project)
      
    control_count = ActiveRecord::QueryRecorder.new do
      post_graphql(query, current_user: first_user)
    end
      
    create(:ci_pipeline, project: project)
      
    expect do
      post_graphql(query, current_user: second_user)  # N+1 쿼리를 피하려면 다른 사용자를 사용하십시오.
    end.not_to exceed_query_limit(control_count)
  end
end

  • app/graphql/types의 폴더 구조를 흉내내십시오:

    예를 들어, app/graphql/types/ci/pipeline_type.rb에 있는 Types::Ci::PipelineType의 필드에 대한 테스트는 디렉터리을 가져오는 쿼리에 관계없이 spec/requests/api/graphql/ci/pipeline_spec.rb에 저장되어야 합니다.

  • GraphqlHelpers#resolve를 사용하여 리졸버를 테스트할 때 리졸버의 인수는 두 가지 방법으로 처리할 수 있습니다.

    1. 리졸버 스펙의 95%는 루비 객체를 사용하는 인수를 사용하며, GraphQL API를 사용하면 문자열과 정수만 사용됩니다. 이것은 대부분의 경우에 잘 작동합니다.

    2. 리졸버에 prepare 프로크를 사용하는 인수(예: TimeFrameArguments를 받는 리졸버)가 있는 경우, arg_style: :internal_prepared 매개변수를 resolve 메소드에 전달해야 합니다. 이것은 인수를 문자열과 정수로 변환하고 일반 인수 처리를 통해 정확하게 prepare 프로크를 호출하도록 코드에 알려줍니다. 예를 들어, iterations_resolver_spec.rb에서: 

      def resolve_group_iterations(args = {}, obj = group, context = { current_user: current_user })
  resolve(described_class, obj: obj, args: args, ctx: context, arg_style: :internal_prepared)
end

      추가적으로, 리졸버 인수로 enum을 전달하는 경우 내부 표현 대신 외부 표현을 사용해야 합니다. 예를 들어: 

      # 좋은 예
resolve_group_iterations({ search: search, in: ['CADENCE_TITLE'] })
     
# 나쁜 예
resolve_group_iterations({ search: search, in: [:cadence_title] })

    :internal_prepared의 사용은 GraphQL gem 업그레이드를 위한 연결로 추가되었습니다. 리졸버를 직접 테스트하는 것은 eventually be removed되고, 리졸버/뮤테이션에 대한 유닛 테스트는 이미 deprecated되었습니다.

쿼리 플로 및 GraphQL 인프라에 대한 참고 사항

GitLab의 GraphQL 인프라는 lib/gitlab/graphql에서 찾을 수 있습니다.

Instrumentation은 쿼리 실행을 감싸는 기능입니다. Instrumentation 클래스를 사용하는 모듈로 구현됩니다.

예: Present 

module Gitlab
  module Graphql
    module Present
      #... 일부 코드 상단 ...
      
      def self.use(schema_definition)
        schema_definition.instrument(:field, ::Gitlab::Graphql::Present::Instrumentation.new)
      end
    end
  end
end

Query Analyzer에는 쿼리를 실행하기 전에 검증하는 일련의 콜백이 포함되어 있습니다. 각 필드는 분석기를 통과하고 최종 값도 사용할 수 있습니다.

Multiplex queries는 여러 쿼리를 하나의 요청으로 보낼 수 있게 합니다. 이를 통해 서버로 보내는 요청의 수를 줄일 수 있습니다. (GraphQL Ruby에서 제공하는 사용자 정의 Multiplex Query Analyzer 및 Multiplex Instrumentation도 있습니다).

쿼리 제한

쿼리 및 변이는 깊이, 복잡성 및 재귀로 제한되어 있어 과도하거나 악의적인 쿼리로부터 서버 리소스를 보호합니다. 이러한 값을 기본값으로 설정하고 필요에 따라 특정 쿼리에서 재정의할 수 있습니다. 복잡성 값은 개별 객체마다 설정할 수 있으며 최종 쿼리 복잡성은 반환되는 객체 수에 따라 결정됩니다. 이것은 Gitaly 호출이 필요한 비용이 많이 드는 객체에 사용할 수 있습니다.

예를 들어 리졸버 내 조건부 복잡성 메서드: 

def self.resolver_complexity(args, child_complexity:)
  complexity = super
  complexity += 2 if args[:labelName]
  
  complexity
end

복잡성에 관한 자세한 내용은 다음을 참조하십시오. GraphQL Ruby 설명서.

문서 및 스키마

저희의 스키마는 app/graphql/gitlab_schema.rb에 위치해 있습니다. 자세한 내용은 스키마 참조를 참조하십시오.

생성된 GraphQL 문서는 스키마가 변경될 때 업데이트해야 합니다. GraphQL 문서 및 스키마 파일을 생성하는 방법에 대한 정보는 스키마 문서 업데이트를 참조하십시오.

독자들을 돕기 위해 GraphQL API 문서에 새 페이지를 추가해야 합니다. 지침은 GraphQL API 페이지를 참고하십시오.

변경 로그 항목 포함

모든 클라이언트 향 수정 사항 반드시 변경 로그 항목을 포함해야 합니다.

게으름

성능 관리를 위한 GraphQL에만 있는 중요한 기술 중 하나는 게으름 값을 사용하는 것입니다. 게으름 값은 결과의 약속을 나타내어 나중에 실행될 동작을 허용하여 쿼리 트리의 다른 부분에서 쿼리를 일괄 처리할 수 있게 합니다. 저희 코드에서 게으름 값의 주요 예는 GraphQL BatchLoader입니다.

게으름 값을 직접 관리하려면 Gitlab::Graphql::Lazy를 읽으시고 특히 Gitlab::Graphql::Laziness를 살펴보세요. 여기에는 게으름 생성 및 제거의 기본 작업을 도와주는 #force 및 #delay가 포함되어 있습니다.

게으름 값을 강제로 처리하지 않고 다루기 위해 Gitlab::Graphql::Lazy.with_value를 사용하십시오.