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는 GitLab 팀 멤버만을 대상으로 Deep Dive를 진행했습니다 (https://gitlab.com/gitlab-org/create-stage/issues/1). 이 Deep Dive에서는 특정 도메인 지식을 공유하여 향후에 이 코드베이스의 일부에서 작업할 수 있는 모든 사람들에게 도움이 되도록 했습니다. YouTube에서 녹화본, Google 슬라이드, 그리고 PDF로 슬라이드 보기에서 확인할 수 있습니다. 이 심층 분석에서 다룬 모든 내용은 GitLab 11.9 기준으로 정확했으며, 특정 세부 사항은 해당 릴리스 이후에 변경될 수 있지만, 여전히 좋은 입문 자료로 사용될 수 있을 것입니다.

GraphiQL

GraphiQL은 기존 쿼리를 테스트할 수 있는 대화형 GraphQL API 탐색 도구입니다. 아무 GitLab 환경에서도 https://<your-gitlab-site.com>/-/graphql-explorer에서 접근할 수 있습니다. 예를 들면, GitLab.com의 GraphiQL 탐색 도구입니다.

GraphQL 변경사항을 검토하는 병합 요청

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

GraphQL 파일을 수정하거나 엔드포인트를 추가하는 병합 요청을 검토하라는 요청을 받으면 우리의 GraphQL 검토 가이드를 살펴보십시오.

GraphQL 로그 읽기

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

인증

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

또한 쿼리 문자열에 private_token을 추가하거나 HTTP_PRIVATE_TOKEN 헤더를 추가하는 것이 가능합니다.

제한 사항

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

최대 페이지 크기

기본적으로 연결은 페이지 당 최대 레코드 수를 정의한 값보다 많이 반환할 수 없습니다. 개발자는 연결을 정의할 때 사용자 정의 최대 페이지 크기를 지정할 수 있습니다.

최대 복잡성

복잡성에 대한 설명은 클라이언트용 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

또는 resolver 클래스에서 확장을 적용할 수 있습니다: 

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

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

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

호환되지 않는 변경 사항

GitLab GraphQL API는 버전 없음을 사용하므로 개발자는 중지 및 제거 프로세스에 익숙해져야 합니다.

호환되지 않는 변경 사항은 다음과 같습니다:

  • 필드, 인수, enum 값 또는 뮤테이션의 제거 또는 이름 변경.
  • 인수의 유형 또는 유형 이름 변경. 인수의 유형은 변수 사용 시 클라이언트에 의해 선언되며, 변경 시 기존 유형 이름을 사용하는 쿼리는 API에서 거부됩니다.
  • JSON 직렬화 값을 변경하는 경우 필드 또는 enum 값의 스칼라 유형. 예를 들어, JSON String에서 JSON Number로의 변경 또는 String의 형식을 변경하는 경우입니다. 객체 유형의 변경은 모든 스칼라 유형 필드가 여전히 동일한 방식으로 직렬화되는 한 허용됩니다.
  • 필드 또는 리졸버의 복잡성 또는 복잡성 배수 변경.
  • 필드를 _nullable_에서 (null: false) nullable로 변경하는 경우 (null: true), Nullable fields에서 설명된 바와 같습니다.
  • 인수를 선택적(required: false)에서 필수(required: true)로 변경하는 경우.
  • 연결의 최대 페이지 크기 변경.
  • 쿼리 복잡성 및 깊이의 전역 제한을 낮추는 것.
  • 이전에 허용되었던 제한을 초과하는 쿼리에 이르게 하는 기타 변경 사항.

항목을 폐기하는 방법에 대한 세부 내용은 스키마 항목의 폐기 섹션을 참조하십시오.

호환되지 않는 변경 사항의 면제

GraphQL API 호환되지 않는 변경 사항 면제 문서를 참조하십시오.

글로벌 식별자

GitLab GraphQL API는 글로벌 식별자(Global IDs) (예: "gid://gitlab/MyObject/123")를 사용하며 절대로 데이터베이스 기본 키 ID를 사용하지 않습니다.

글로벌 식별자는 캐싱 및 클라이언트 측 라이브러리에서의 검색을 위한 규칙입니다.

또한 다음을 참조하십시오:

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

  • 값이 GlobalID인지 확인합니다.
  • 사용자 코드에 전달하기 전에 GlobalID로 구문 분석합니다.
  • 객체 유형의 종류(예: GlobalIDType[Project])마다 파라미터화될 수 있으며 이는 더 나은 검증과 보안을 제공합니다.

새로운 인수 및 결과 유형에 대해 이 유형을 사용하는 것을 고려하십시오. 이 유형은 부모 유형이나 상위 유형과 매개변수화될 수 있으며(예: GlobalIDType[Issuable] vs GlobalIDType[Issue]) 더 넓은 범위의 객체를 허용하는 방법으로 사용할 수 있음을 기억하십시오.

최적화

기본적으로 GraphQL은 적극적으로 N+1 문제를 최소화하지 않는 한 N+1 문제를 도입하는 경향이 있습니다.

안정성과 확장성을 위해 쿼리가 N+1 성능 이슈에 영향을 받지 않도록 보장해야 합니다.

다음은 GraphQL 코드를 최적화하는 데 도움이 되는 도구 목록입니다:

  • Look ahead를 사용하여 쿼리에서 선택된 필드에 기반하여 데이터를 사전 로드할 수 있습니다.
  • 일괄 처리를 사용하여 데이터베이스 쿼리를 하나의 문으로 묶어 일괄로 처리할 수 있습니다.
  • BatchModelLoader는 레코드를 ID로 조회하고 일괄 처리를 활용하는 권장 방법입니다.
  • before_connection_authorization를 사용하여 유형 권한 검사에 특정한 N+1 문제를 해결할 수 있습니다.
  • 최대 필드 호출 수 제한을 사용하여 최적화가 향상되지 않는 경우 데이터를 반환하는 횟수를 제한할 수 있습니다.

개발 중에 N+1 문제 확인하는 방법

N+1 문제는 다음과 같은 기능을 개발 중에 확인할 수 있습니다:

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

유형

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

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

graphql_name 'Issue'

field :iid, GraphQL::Types::ID, null: true
field :title, GraphQL::Types::String, null: true

# 이 `field`를 확장한 우리가 정의한 메서드도 있습니다
markdown_field :title_html, null: true
field :description, GraphQL::Types::String, null: true
markdown_field :description_html, null: true

각 유형에 이름을 부여합니다 (이 경우 Issue).

iid, title 및 description은 스칼라 GraphQL 유형입니다. iid는 GraphQL::Types::ID로, 고유한 ID를 나타내는 특별한 문자열 유형입니다. title과 description은 일반적인 GraphQL::Types::String 유형입니다.

이전 스칼라 유형인 GraphQL:ID, GraphQL::INT_TYPE, GraphQL::STRING_TYPE, GraphQL:BOOLEAN_TYPE, 및 GraphQL::FLOAT_TYPE은 더 이상 허용되지 않습니다. GraphQL::Types::ID, GraphQL::Types::Int, GraphQL::Types::String, GraphQL::Types::Boolean, 및 GraphQL::Types::Float을 사용하십시오.

GraphQL API를 통해 모델을 노출할 때, app/graphql/types에서 새 유형을 만들어 수행합니다. 또한 스칼라 데이터 유형에 대한 사용자 정의 GraphQL 데이터 유형을 선언할 수도 있습니다 (예: TimeType).

유형에서 속성을 노출할 때, 정의 내부의 로직을 최소한으로 유지하도록 합니다. 대신 어떠한 로직이라도 프레젠터로 이동하는 것을 고려하십시오: 

class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end

기존의 프레젠터를 사용할 수도 있지만, GraphQL에 특화된 새 프레젠터를 만들 수도 있습니다.

프레젠터는 필드로 해결된 개체와 컨텍스트를 사용하여 초기화됩니다.

Nullable 필드

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

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

non-nullable 필드는 필수이고 미래에 선택 사항이 되기 매우 적고 계산이 간단한 경우에만 사용해야 합니다. 예시로 id 필드가 있습니다.

non-nullable GraphQL 스키마 필드는 개체 유형 뒤에 느낌표(!)로 표시됩니다. gitlab_schema.graphql 파일의 예시는 다음과 같습니다: 

  id: ProjectID!

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

  errors: [String!]!

더 많은 정보:

전역 ID 노출

GitLab에서 사용하는 전역 ID 사용에 따라 노출할 때 항상 데이터베이스 기본 키 ID를 전역 ID로 변환합니다.

id라는 이름의 모든 필드가 자동으로 변환됩니다 개체의 전역 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은 커서 기반 페이징을 사용하여 항목의 컬렉션을 노출합니다. 이는 클라이언트에게 많은 유연성을 제공함과 동시에 백엔드에서 다양한 페이징 모델을 사용할 수 있도록 합니다.

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

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

이는 프로젝트의 처음 2개 파이프라인과 관련된 페이지네이션 정보를 반환하며, 내림차순으로 정렬됩니다. 반환된 데이터는 다음과 같습니다: 

{
  "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)를 추가합니다. 기본 키는 기본 테이블에서 사용할 수 있어야 합니다.

바로 가기 필드

때로 “바로 가기 필드”를 구현하는 것이 간단해 보일 수 있습니다. 매개 변수가 전달되지 않으면 리졸버가 컬렉션의 첫 번째를 반환하도록 하는 것이 아닌 기능이 app/graphql/gitlab_schema.rb에 정의된 허용된 최대 레코드 수보다 많은 레코드가 필요한 경우 max_page_size 인수를 변경하는 것이 좋습니다. 위험:

앞서 언급한 것처럼 허용된 최대 레코드 수를 높이는 대신 기본 값은 GraphQL API가 성능을 유지하도록하기 위해 설정되었으므로 프런트엔드 클라이언트나 제품 요구 사항을 변경하여 페이지 당 레코드 수가 많이 필요하지 않도록하는 것이 좋습니다.

예: 

field :tags,
  Types::ContainerRepositoryTagType.connection_type,
  null: true,
  description: '컨테이너 저장소의 태그',
  max_page_size: 20

필드 복잡성

GitLab GraphQL API는 복잡성(complexity) 점수를 사용하여 지나치게 복잡한 쿼리를 제한합니다. 복잡성은 우리 클라이언트 문서에서 설명되어 있습니다.

기본적으로 필드는 쿼리의 복잡성 점수에 1을 추가합니다. 이는 필드에 대한 사용자 지정 복잡성(complexity) 값을 제공함으로써 변경할 수 있습니다.

개발자는 서버에서 데이터를 반환하는 데 더 많은 작업(work)_을 유발하는 필드에 대해 더 높은 복잡성을 지정해야 합니다. 대부분의 경우에서 적은 또는 거의 _작업(work) 없이 반환될 수 있는 데이터를 나타내는 필드, 예를 들어 대부분의 경우에서 id 또는 title과 같은 필드는 복잡성은 0으로 지정할 수 있습니다.

calls_gitaly

리졸버가 Gitaly를 호출할 수 있는 필드는 리졸버가 해당 필드를 사용할 때 calls_gitaly: true를 전달함으로써 표시해야 합니다.

예: 

field :blob, type: Types::Snippets::BlobType,
      description: '스니펫 blob',
      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:에 올바른 값을 전달합니다.

유형의 권한 노출

현재 사용자가 리소스에 대해 가지고 있는 권한을 노출하기 위해 expose_permissions를 호출하여 리소스에 대한 권한을 나타내는 별도의 유형을 전달할 수 있습니다.

예: 

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

권한 유형은 리소스의 권한을 나타내는 BasePermissionType을 상속받으며 몇 가지 도우미 메서드를 포함하며 권한을 반드시 논-nullable 부울 값으로 노출하는 것을 허용하는 메서드가 포함되어 있습니다. 

class MergeRequestPermissionsType < BasePermissionType
  graphql_name 'MergeRequestPermissions'

  present_using MergeRequestPresenter

  abilities :admin_merge_request, :update_merge_request, :create_note

  ability_field :resolve_note,
                description: '병합 요청에서 논의를 해결할 수 있는지 나타냅니다.'
  permission_field :push_to_source_branch, method: :can_push_to_source_branch?
end

기능 플래그

당신은 GraphQL에서 기능 플래그를 구현하여 다음을 토글할 수 있습니다:

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

이것은 당신의 선호 및 상황에 따라 리졸버, 유형 또는 모델 메소드에서도 수행될 수 있습니다.

참고: 기능 플래그로 보호되는 항목은 항목을 알파로 표시하는 것도 추천됩니다. 이것은 공개 GraphQL API의 소비자들에게 해당 필드가 아직 사용되어서는 안 된다는 신호를 보냅니다. 당신은 또한 이러한 알파 항목을 언제든지 변경하거나 제거할 수 있고, 이를 폐기할 필요 없이 할 수 있습니다. 플러그가 제거되면 “릴리스”를 통해 알파 속성을 제거하여 해당 스키마 아이템을 공개 상태로 만들 수 있습니다.

기능 플래그 항목에 대한 설명

스키마 항목의 값을 또는 동작을 토글하기 위해 기능 플래그를 사용할 때 항목의 description는 반드시:

  • 값 또는 동작이 기능 플래그에 의해 토글될 수 있다고 명시해야 합니다.
  • 기능 플래그의 이름을 지정해야 합니다.
  • 기능 플래그가 비활성화되었을 때(또는 더 적합하면 활성화되었을 때) 필드가 반환하는 것이나 동작을 명시해야합니다.

기능 플래그 사용 예시

기능 플래그가 있는 필드

필드 값은 기능 플래그 상태에 따라 토글됩니다. 기능 플래그가 비활성화되면 null을 반환하는 것이 일반적으로 사용됩니다. 

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와의 역 호환성을 유지합니다.

필드, 인자, 열거 형 값, 또는 변이를 제거하는 대신 이들은 _폐기되어야(deprecated)_합니다.

그런 다음 GitLab 폐기 프로세스에 따라 향후 릴리스에서 스키마의 폐기된 부분을 제거할 수 있습니다.

GraphQL에서 스키마 항목을 폐기하려면:

  1. 항목에 대한 폐기 이슈를 생성합니다.
  2. 스키마에서 항목을 폐기로 지정합니다.

또한, 다음을 참고하세요:

폐기 이슈 생성

모든 GraphQL 폐기는 추적을 위해 폐기Deprecations 이슈 템플릿을 사용하여 생성해야합니다.

폐기 이슈에 다음 두 가지 라벨을 적용하십시오:

  • ~GraphQL
  • ~deprecation

항목을 폐기로 지정

필드, 인자, 열거 값, 및 뮤테이션은 deprecated 속성을 사용하여 폐기됩니다. 속성의 값은 다음과 같은 Hash입니다:

  • reason - 폐기의 이유
  • milestone - 필드가 폐기된 마일스톤

예시: 

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

Deprecation reason style guide

Deprecation이유는 필드, 인수 또는 enum 값이 대체되기 때문일 경우, reason은 대체 사항을 나타내야 합니다. 예를 들어, 다음은 대체된 필드에 대한 reason입니다: 

`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

필드, 인수 또는 enum 값이 대체되지 않는 경우, 설명적인 deprecation reason을 제공해야 합니다.

전역 ID를 사용하지 않음

전역 ID를 생성하고 구문 분석하기 위해 rails/globalid 젬을 사용하므로, 전역 ID는 모델 이름과 결합됩니다. 모델을 이름을 변경하면 해당 모델의 전역 ID도 변경됩니다.

전역 ID가 스키마의 인수 유형으로 사용된다면, 전역 ID의 변경은 일반적으로 호환되지 않는 변경을 구성할 것입니다.

이전 전역 ID 인수를 사용하는 클라이언트를 계속 지원하기 위해 Gitlab::GlobalId::Deprecations에 deprecation을 추가합니다.

참고: 만약 전역 ID가 필드로만 노출된 경우, 우리는 이를 사용하지 않아도 됩니다. 전역 ID가 필드에서 표현되는 방식의 변경은 하위 호환성이 있는 것으로 간주됩니다. 클라이언트가 이러한 값들을 구문 분석하지 않는 것으로 기대합니다. 이 값들은 불투명한 토큰으로 처리되어야 하며, 그 안에 있는 구조는 우연한 것으로 보고 의존해서는 안 된다고 예상합니다.

예시 시나리오:

이 예시 시나리오는 이 병합 요청을 기반으로 합니다.

모델 PrometheusService를 Integrations::Prometheus로 이름을 변경하려고 합니다. 이전 모델 이름은 인수로 사용되는 전역 ID 유형을 생성하는 데 사용됩니다: 

# Mutations::UpdatePrometheus:

argument :id, Types::GlobalIDType[::PrometheusService],
              required: true,
              description: "변형할 통합의 ID."

클라이언트는 PrometheusServiceID로 이름 지어진 "gid://gitlab/PrometheusService/1"와 같은 전역 ID 문자열을 input.id 인수로 전달하여 변형을 호출합니다: 

mutation updatePrometheus($id: PrometheusServiceID!, $active: Boolean!) {
  prometheusIntegrationUpdate(input: { id: $id, active: $active }) {
    errors
    integration {
      active
    }
  }
}

우리는 모델 이름을 Integrations::Prometheus로 변경하고, 그 다음에 코드베이스를 새 이름으로 업데이트합니다. 변형을 업데이트할 때, 새 이름에 따라 Types::GlobalIDType[]로 변경된 모델을 전달합니다: 

# Mutations::UpdatePrometheus:

argument :id, Types::GlobalIDType[::Integrations::Prometheus],
              required: true,
              description: "변형할 통합의 ID."

이것은 변형에 대한 호환되지 않는 변경을 일으킬 것입니다. 이제 API는 "gid://gitlab/PrometheusService/1"와 같이 id 인수를 전달하거나 쿼리 서명에서 PrometheusServiceID 유형을 지정하는 클라이언트를 거부합니다.

클라이언트가 변형과 상호 작용을 계속할 수 있도록 하려면, Gitlab::GlobalId::Deprecations의 DEPRECATIONS 상수를 편집하여 새로운 Deprecation을 배열에 추가합니다: 

DEPRECATIONS = [
  Gitlab::Graphql::DeprecationsBase::NameDeprecation.new(old_name: 'PrometheusService', new_name: 'Integrations::Prometheus', milestone: '14.0')
].freeze

그런 다음 우리 일반적인 deprecation process를 따릅니다. 나중에 이전 인수 스타일을 지원을 제거하기 위해 Deprecation을 제거합니다: 

DEPRECATIONS = [].freeze

Deprecation 기간 동안, API는 인수 값에 대해 다음 형식 중 하나를 허용합니다:

  • "gid://gitlab/PrometheusService/1"
  • "gid://gitlab/Integrations::Prometheus/1"

또한, API는 인수에 대한 쿼리 서명에서 다음 유형을 허용합니다:

  • PrometheusServiceID
  • IntegrationsPrometheusID

참고: 이 예시에서 이전 유형(PrometheusServiceID)을 사용하는 쿼리는 API에서 유효하고 실행 가능하다고 봅니다. 그러나 검증 도구는 이를 유효하지 않다고 간주합니다. 검증 도구는 우리가 @deprecated 지시문 외부의 특수한 방법을 사용하는 것을 폐기하고 있기 때문에 이를 유효하지 않다고 간주합니다.

문서에 이전 전역 ID 스타일이 이제 폐기되었다는 것이 언급되어 있습니다.

Alpha로 표시된 마크 스키마 항목

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

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

참고: 새로운 항목만 Alpha로 표시하세요. 이미 공개된 항목은 Alpha로 표시하지 마십시오.

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

예: 

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

마찬가지로 app/graphql/types/mutation_type.rb에서 변이를 전체로 Alpha로 표시할 수도 있습니다. 

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

Alpha GraphQL 항목은 GraphQL 폐기를 활용하는 사용자 정의 GitLab 기능입니다. Alpha 항목은 GraphQL 스키마에서 폐기된 것으로 표시됩니다. 폐기된 스키마 항목과 마찬가지로 대화형 GraphQL 탐색기(GraphiQL)에서 Alpha 필드를 테스트할 수 있습니다. 그러나 GraphiQL 자동완성 편집기는 폐기된 필드를 제안하지 않음을 유의하세요.

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

열거형

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

열거형 값을 사용한 경우에는 스키마 항목을 폐기할 수 있습니다.

레일즈 열거형에서 동적으로 GraphQL 열거형 정의

만약 GraphQL 열거형이 레일즈 열거형에서 지원되는 경우, 레일즈 열거형을 사용하여 동적으로 GraphQL 열거형 값을 정의하는 것을 고려해보십시오. 이렇게 하면 GraphQL 열거형 값이 레일즈 열거형 정의에 바인딩되므로 레일즈 열거형에 값이 추가되면 GraphQL 열거형이 자동으로 변경됩니다.

예: 

module Types
  class IssuableSeverityEnum < BaseEnum
    graphql_name 'IssuableSeverity'
    description '사건 심각도'

    ::IssuableSeverity.severities.each_key do |severity|
      value severity.upcase, value: severity, description: "#{severity.titleize} severity."
    end
  end
end

JSON

GraphQL로 반환할 데이터가 JSON으로 저장된 경우, 가능한 경우에는 계속해서 GraphQL 유형을 사용해야 합니다. 실제로 구조화되지 않은 경우에만 GraphQL::Types::JSON 유형을 사용하도록 해야 합니다.

JSON 데이터의 구조가 다양하지만 알려진 가능한 구조 집합 중 하나인 경우 union을 사용하십시오. 이러한 경우를 위해 사용된 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를 사용할 수 있습니다. 예를 들어: 

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

모든 설명은 반드시 마침표(.)로 끝나야 합니다.

부울

부울 필드(GraphQL::Types::Boolean)의 경우수행하는 작업을 설명하는 동사로 시작하십시오. 예를 들어: 

이슈가 비밀임을 나타냅니다.

필요한 경우 기본값을 제공하십시오. 예를 들어: 

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

정렬된 열거체

정렬을 위한 열거체들은 'Values for sorting {x}.'으로 설명되어야 합니다. 예를 들어: 

컨테이너 저장소를 정렬하는데 사용되는 값들.

Types::TimeType 필드 설명

Types::TimeType GraphQL 필드의 경우, 속성의 형식이 Date가 아닌 Time임을 알려주기 위해 timestamp라는 단어를 포함해야 합니다.

예를 들어: 

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인 해시맵입니다.

구독 티어 뱃지

만일 필드나 매개변수가 다른 필드들보다 더 높은 구독 티어에서 사용 가능하다면, 티어 뱃지를 인라인으로 추가하십시오.

예를 들어: 

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

권한 부여

참조: GraphQL 권한 부여

리졸버

우리는 응용 프로그램이 응답을 제공하는 방식을 정의하기 위해 resolvers를 사용합니다. resolvers는 app/graphql/resolvers 디렉토리에 저장됩니다. 해당 리졸버는 해당하는 객체를 검색하기 위한 실제 구현 논리를 제공합니다.

필드에 표시할 객체를 찾기 위해, app/graphql/resolvers에 리졸버를 추가할 수 있습니다.

인자는 mutation과 같이 리졸버 내에서 정의될 수 있습니다. 인자에 대한 정보는 Arguments 섹션을 참조하십시오.

수행할 쿼리의 양을 제한하기 위해 BatchLoader를 사용할 수 있습니다.

리졸버 작성

우리의 코드는 주로 finder와 서비스를 감싸는 얇은 선언적 래퍼여야 합니다. 인자 목록을 반복할 수도 있으며 이를 관심사에 추출할 수도 있습니다. 대부분의 경우에는 상속보다는 합성을 선호합니다. 리졸버를 컨트롤러처럼 다루십시오: 리졸버는 다른 애플리케이션 추상화를 구성하는 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

동일한 리졸버 클래스를 두 곳에서 사용할 수는 있지만, 동일한 리졸버 객체를 직접 재사용해서는 안됩니다. 리졸버의 라이프사이클은 프레임워크에 의해 권한 부여, 준비 및 해결이 조정되며 각 단계에서 lazy values가 반환되어 배치 기회를 활용할 수 있습니다. 응용 프로그램 코드에서 리졸버나 뮤테이션을 인스턴스화해서는 안됩니다.

대신, 코드 재사용의 단위는 대부분의 경우 응용 프로그램의 나머지 부분과 같습니다:

  • 쿼리 내에서 데이터를 찾는 finder들.
  • 작업을 적용하는 뮤테이션 내의 서비스.
  • 쿼리에 특화된 로더(배치 처리가 가능한 finder)들.

변이에서 배치 처리는 절대 하지 않아도 됩니다. 변이는 연속적으로 실행되므로 배치 처리 기회가 없습니다. 모든 값은 요청됨과 동시에 즉시 평가되므로 배치 처리가 불필요한 오버헤드입니다. 다음을 작성 중이면:

  • Mutation이라면 객체를 직접 조회하십시오.
  • Resolver 또는 BaseObject의 메서드를 작성 중이라면 배치 처리를 허용하려고 하는 것입니다.

에러 처리

리졸버는 적절하게 변환된 최상위 오류로 발생한 오류를 발생시킬 수 있습니다. 예상되는 모든 오류는 포착되어 적절한 GraphQL 오류로 변환되어야 합니다 (자세한 내용은 Gitlab::Graphql::Errors 참조). 처리되지 않은 모든 오류는 억제되고 클라이언트가 내부 서비스 오류 메시지를 수신합니다.

하나의 특별한 경우는 권한 오류입니다. REST API에서는 사용자가 액세스 권한이 없는 리소스에 대해 404 Not Found를 반환합니다. GraphQL에서의 동일한 동작은 모든 없는 또는 무단으로 사용할 수 없는 리소스에 대해 null을 반환하는 것입니다. 쿼리 리졸버는 권한이 없는 리소스에 대해 오류를 발생시키지 않아야 합니다.

이에 대한 근거는 클라이언트는 레코드의 부재와 액세스할 수 없는 레코드가 있는 것을 구별할 수 없어야 한다는 것입니다. 그렇게 하면 숨겨야 할 정보가 유출되는 보안 취약점이 됩니다.

대부분의 경우에는 이에 대해 걱정할 필요가 없습니다. 이는 authorize DSL 호출로 선언하는 리졸버 필드 권한 부여에 의해 올바르게 처리됩니다. 그러나 더 사용자 정의 된 작업이 필요한 경우에는 기억하세요. current_user가 액세스할 수 없는 개체를 해결할 때 전체 필드가 null로 해결되어야 합니다.

리졸버 유도

(BaseResolver.single 및 BaseResolver.last 포함)

일부 사용 사례에 대해 우리는 다른 리졸버에서 리졸버를 유도할 수 있습니다. 이에 대한 주요 사용 사례는 모든 항목을 찾는 리졸버와 특정 항목을 찾는 다른 리졸버입니다. 이를 위해 편리한 메서드를 제공합니다:

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

올바른 단수형 유형은 컬렉션 유형에서 추론되므로 여기서 type을 정의할 필요가 없습니다.

이러한 메서드를 사용하기 전에 다음이 간단하게 될 수 있는지 고려하세요:

  • 자체 인수를 정의하는 또 다른 리졸버를 작성합니다.
  • 쿼리를 추상화하는 concern을 작성합니다.

BaseResolver.single을 너무 자유롭게 사용하는 것은 안티 패턴입니다. 아무런 의미 없는 필드로 이어질 수 있으며, 예를 들어 아무런 인수가 제공되지 않은 경우 첫 번째 MR을 반환하는 Project.mergeRequest 필드와 같은 것이 발생할 수 있습니다. 컬렉션 리졸버에서 단일 리졸버를 유도할 때마다 보다 제한적인 인수가 있어야 합니다.

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

  • 적어도 하나의 인수를 정의(또는 재정의)합니다.
  • 옵셔널 필터를 필수로 만듭니다.

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

BatchLoading

GraphQL BatchLoader를 참조하십시오.

Resolver#ready?의 올바른 사용

리졸버에는 프레임워크의 일부로 의도된 두 가지 공개 API 메소드, #ready?(**args)와 #resolve(**args),이 있습니다. #resolve를 호출하지 않고 세팅, 유효성 검사 또는 일찍 반환하는 데 #ready?를 사용할 수 있습니다.

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

  • 상호 배타적 인수를 유효성 검사하는 경우
  • 결과가 불가능한 경우 Relation.none을 반환하는 경우
  • 이를 위해 초기화된 인스턴스 변수를 설정하는 경우 (그러나 이에 대해 게으르게 초기화된 메소드를 고려하십시오)

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

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

이러한 이유로 리졸버를 호출할 때마다 (리졸버는 재사용 가능하다고 볼 수 없으므로 주로 테스트에서), resolve를 호출하기 전에 ready? 메소드를 호출하고 부울 플래그를 확인하세요! 예시는 이곳의 GraphqlHelpers에서 볼 수 있습니다.

Negated 인수

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

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

중복된 인수 정의를 피하려면 이러한 인수를 재사용 가능한 모듈 (또는 중첩된 경우 클래스)에 배치할 수 있습니다. 또는 도우미 리졸버 메소드를 추가할 수 있습니다.

메타데이터

리졸버를 사용할 때, 리졸버는 필드 메타데이터의 SSoT (Single Source of Truth)로 기능하고 있을 수 있습니다. 필드 이름을 제외한 모든 필드 옵션은 리졸버에 선언할 수 있습니다. 이러한 옵션에는 다음이 포함됩니다:

  • type (필수 - 모든 리졸버는 타입 어노테이션을 포함해야 합니다)
  • extras
  • description
  • Gitaly 어노테이션 (calls_gitaly!)

예시: 

module Resolvers
  MyResolver < BaseResolver
    type Types::MyType, null: true
    extras [:lookahead]
    description 'Retrieve a single MyType'
    calls_gitaly!
  end
end

부모 객체를 자식 Presenter에 전달

가끔은 자식 컨텍스트에서 필드를 계산하기 위해 해결된 쿼리 부모에 액세스해야 할 때가 있습니다. 일반적으로 부모는 parent로써 Resolver 클래스에서만 사용 가능합니다.

자식 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: 'My field description.'

  field :resolver_field, resolver: SomeTypeResolver

  # In SomeTypeResolver

  extras [:parent]
  type SomeType, null: true
  description 'My field description.'

  3. 프리젠터 클래스에서 필드 메소드를 선언하고 parent 키워드 인수를 허용하도록 하세요. 이 인수에는 부모 GraphQL 컨텍스트가 포함되므로 부모 객체에 액세스하려면 parent[:parent_object] 또는 리졸버에서 사용한 키를 사용해야 합니다. 

      # in ChildPresenter
  def my_computing_method(parent:)
    # 여기서 `parent[:parent_object]`로 무언가 수행
  end

  # In SomeTypeResolver

  def resolve(parent:)
    # ...
  end

실제 사용 예시는 이 MR에서 IterationPresenter에 scopedPath와 scopedUrl을 추가한 내용을 참고하세요.

뮤테이션

변이는 저장된 값들을 변경하거나 동작을 일으키는 데 사용됩니다. 마찬가지로 GET 요청은 데이터를 수정해서는 안 되며, 일반적인 GraphQL 쿼리에서는 데이터를 수정할 수 없습니다. 그러나 뮤테이션에서는 데이터를 수정할 수 있습니다.

뮤테이션 작성

뮤테이션은 app/graphql/mutations에 저장되며, 이상적으로는 해당하는 리소스 당 그룹화되어 있으며, 서비스와 유사합니다. 이들은 Mutations::BaseMutation을 상속해야 합니다. 뮤테이션에서 정의된 필드는 뮤테이션의 결과로 반환됩니다.

뮤테이션 업데이트 정밀도

GitLab의 서비스 중심 아키텍처는 대부분의 뮤테이션에서 Create, Delete 또는 Update 서비스를 호출합니다. 예를 들어 UpdateMergeRequestService처럼 Update 뮤테이션에서는 객체의 한 측면만 업데이트하고 싶을 수도 있으므로 정밀도가 높은 뮤테이션이 필요할 수 있습니다. 예시로 MergeRequest::SetDraft와 같습니다.

정밀도가 높은 뮤테이션과 굵은 뮤테이션을 모두 가질 수 있지만, 너무 많은 정밀도가 높은 뮤테이션은 유지 관리, 코드 이해, 테스트의 조직적인 문제를 일으킬 수 있음을 인지해야 합니다. 각 뮤테이션에는 기술적 부채를 유발할 수 있는 새 클래스가 필요합니다. 이는 스키마가 매우 커져 사용자가 스키마를 탐색하기 어렵게 만드는 것을 의미합니다. 또한 각 새 뮤테이션은 테스트(느린 요청 통합 테스트 포함)가 필요하므로 뮤테이션 추가는 테스트 스위트를 느리게 만듭니다.

변경 사항을 최소화하기 위해:

  • 가능한 경우 기존 뮤테이션인 MergeRequest::Update 등을 사용합니다.
  • 기존 서비스를 굵은 뮤테이션으로 노출합니다.

정밀도가 높은 뮤테이션이 더 적합한 상황:

  • 특정 권한이 필요한 속성을 수정하는 경우 또는 다른 전문화된 논리가 필요한 경우.
  • 상태 기계와 유사한 전이(이슈 잠금, MR 병합, 에픽 종료 등)를 노출하는 경우.
  • 중첩된 속성을 수용하는 경우(자식 객체의 속성을 수용하는 경우).
  • 뮤테이션의 의미가 명확하고 간결하게 표현될 수 있는 경우.

추가 맥락은 issue #233063를 확인하세요.

네이밍 규칙

각 뮤테이션은 GraphQL 스키마에서 뮤테이션의 이름인 graphql_name을 정의해야 합니다.

예시: 

class UserUpdateMutation < BaseMutation
  graphql_name 'UserUpdate'
end

graphql-ruby 젬의 1.13 버전에서 변경 사항으로, graphql_name은 타입 이름이 올바르게 생성되도록 클래스의 첫 번째 줄이어야 합니다. Graphql::GraphqlNamePosition 코프는 이를 강요합니다. 추가 맥락은 issue #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 메서드는 키워드 인자로써 뮤테이션의 인자를 받습니다. 여기서 리소스를 수정하는 서비스를 호출할 수 있습니다.

그런 다음 resolve 메서드는 뮤테이션에서 정의된 필드와 동일한 필드 이름을 가진 해시를 반환해야 합니다. 예를 들어, Mutations::MergeRequests::SetDraft는 merge_request 필드를 정의합니다. 

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

이는 이 뮤테이션에서 resolve로부터 반환된 해시가 다음과 같아야 함을 의미합니다: 

{
  # 수정된 MR은 이것이므로 필드에서 정의된 유형에 포장되겠습니다
  merge_request: merge_request,
  # 뮤테이션에 권한 부여 후 실패하면 문자열 배열
  # `errors_on_object` 도우미는 `errors.full_messages`를 수집합니다
  errors: errors_on_object(merge_request)
}

뮤테이션 마운팅

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

module Types
  class MutationType < BaseObject
    graphql_name 'Mutation'

    include Gitlab::Graphql::MountMutation

    mount_mutation Mutations::MergeRequests::SetDraft
  end
end

MergeRequestsSetDraft라는 필드를 생성하여 Mutations::MergeRequests::SetDraft를 해결(resolve)하도록 합니다.

리소스 승인

뮤테이션 내에서 리소스를 승인하려면, 먼저 다음과 같이 뮤테이션에 필요한 권한을 제공합니다. 

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: { .. }
    }
  }
}

실패 (사용자에게 관련있는 경우)

사용자에게 영향을 주는 오류가 발생했습니다. 이러한 경우를 _뮤테이션 에러_라고 합니다.

생성(create) 뮤테이션의 경우 일반적으로 반환할 thing이 없습니다.

업데이트(update) 뮤테이션의 경우 thing의 현재 실제 상태를 반환합니다. 개발자는 thing 인스턴스에서 #reset를 호출하여 이를 보장해야 할 수 있습니다. 

{
  data: {
    doTheThing: {
      errors: ["thing에 접근할 수 없습니다"],
      thing: { .. }
    }
  }
}

이러한 예는 다음과 같습니다.

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

이상적으로는 사용자가 여기까지 도달하지 못하도록 방지해야 하지만, 도달한다면 문제가 무엇인지 이해하고 그 의도를 달성하기 위해 무엇을 할 수 있는지 알아야 하므로, 실패한 이유를 알려야 합니다. 예를 들어, 요청을 다시 시도해야 할 수도 있습니다.

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

실패 (사용자에게 관련없는 경우)

하나 이상의 복구 불가능한 오류가 최상위 레벨에 반환될 수 있습니다. 이들은 대부분 시스템 또는 프로그래밍 문제로, 대부분 개발자가 알아야 하는 문제입니다. 이 경우 data가 없습니다. 

{
  errors: [
    {"message": "argument error: expected an integer, got null"},
  ]
}

이것은 뮤테이션 도중에 오류를 발생시켰을 때 발생합니다. 우리의 구현에서 인수 오류 및 유효성 검사 오류 메시지가 클라이언트로 반환되며, 다른 StandardError 인스턴스는 catch되어 로깅되고 메시지가 "Internal server error"로 설정되어 클라이언트에 제공됩니다. 세부 내용은 GraphqlController를 참조하세요.

이러한 오류는 다음과 같습니다.

  • GraphQL 구문 오류, 예를 들어 Int 대신 String이 전달되었거나 필수 인수가 존재하지 않은 경우 등.
  • 스키마 오류, 예를 들어 null이 아닌 필드에 대한 값을 제공할 수 없는 경우 등.
  • 시스템 오류: 예를 들어 Git 저장소 예외 또는 데이터베이스 사용 불가능

사용자는 정상적인 사용 과정에서 이러한 오류를 발생시킬 수 없어야 합니다. 이러한 유형의 오류는 내부적으로 처리되어 특정한 세부 사항은 사용자에게 표시되어서는 안됩니다.

뮤테이션이 실패했음을 사용자에게 알리는 것이 필요하지만, 그 원인을 알려줄 필요는 없습니다. 왜냐하면 사용자가 그러한 오류를 일으키지 않았고 해결할 수 있는 방법이 없기 때문이지만, 뮤테이션을 다시 시도할 수 있는 옵션을 제공할 수는 있습니다.

에러 분류

변이를 작성할 때, 에러 상태가 어떤 두 가지 범주 중 하나에 속하는지에 대해 인식해야 하며 (이에 대한 확신을 검증하기 위해 프런트엔드 개발자들과 의사 소통해야 함), 여기에 대해 커뮤니케이션해야 합니다. 이는 _사용자_의 요구와 _클라이언트_의 요구를 구별하는 것을 의미합니다.

사용자가 알아야 하는 경우에만 에러를 잡습니다.

사용자가 알아야 하는 경우, 관련된 에러 정보를 전달하고 목적을 봉사하는지 확인하기 위해 프런트엔드 개발자와 소통하세요.

또한 프런트엔드 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(Enterprise Edition) 변이 사용하지 않게 만들기

EE 변이는 동일한 프로세스를 따라야 합니다. 머지 리퀘스트 과정의 예제로써 머지 리퀘스트 !42588를 읽어보세요.

구독

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

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

참고: 현재 GraphiQL은 Action Cable 클라이언트를 지원하지 않기 때문에 구독을 테스트할 수 없습니다.

구독 작성

Types::SubscriptionType 아래의 모든 필드는 클라이언트가 구독할 수 있는 구독입니다. 이러한 필드는 Subscriptions::BaseSubscription의 하위 클래스인 구독 클래스와 함께 정의되어야 하며 app/graphql/subscriptions에 저장되어야 합니다.

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

이 클래스는 초기 구독 요청 및 후속 업데이트 중에 실행됩니다. 이에 대한 자세한 내용은 GraphQL Ruby 가이드에서 확인할 수 있습니다.

권한 부여

초기 구독과 후속 업데이트가 승인되도록 하기 위해 구독 클래스의 #authorized? 메서드를 구현해야 합니다.

사용자가 승인되지 않은 경우, unauthorized! 도우미를 호출하여 실행이 중지되고 사용자가 구독 해지될 수 있도록 해야 합니다. false를 반환하면 응답을 삭제하지만 업데이트가 발생했음을 누출합니다. 이 누출은 GraphQL gem의 버그로 인한 것입니다.

구독 트리거

구독을 트리거하기 위해 GraphqlTriggers 모듈 아래에 메서드를 정의해야 합니다. 애플리케이션 코드에서 직접 GitlabSchema.subscriptions.trigger를 호출하지 마십시오. 이렇게 하면 다른 인수와 개체로 구독을 트리거하지 않고 단일한 참 소스를 갖게 되며, 구독을 트리거합니다.

페이지네이션 구현

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

인수

리졸버 또는 변이의 인수는 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을 허용하고 싶다면 기본값으로 교체하도록 설정할 수 있습니다: 

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

더 자세한 내용은 Validation, Nullability, Default Values을 참조하세요.

Keywords

각 GraphQL argument는 변경 제출의 #resolve 메서드로 키워드 인자로 전달됩니다.

예시: 

def resolve(my_arg:)
  # 변경 제출 실행 ...
end

Input Types

graphql-ruby는 인자를 input type으로 래핑합니다.

예를 들어, mergeRequestSetDraft 뮤테이션 은 이러한 인자를 정의합니다 (일부는 상속을 통해): 

argument :project_path, GraphQL::Types::ID,
         required: true,
         description: "병합 요청이 속한 프로젝트."

argument :iid, GraphQL::Types::String,
         required: true,
         description: "병합 요청의 IID."

argument :draft,
         GraphQL::Types::Boolean,
         required: false,
         description: <<~DESC
           병합 요청을 초안으로 설정할지 여부.
         DESC

이러한 인자는 우리가 지정한 3가지 인자와 clientMutationId로 자동으로 MergeRequestSetDraftInput이라는 input type을 생성합니다.

Object 식별자 인자

객체를 식별하는 인자는 다음과 같아야 합니다:

  • 객체가 경로를 가지고 있다면 전체 경로 또는 IID를 사용합니다.
  • 다른 객체는 객체의 Global 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.'

Global ID 객체 식별자 인자

다음은 discussionToggleResolve 뮤테이션의 예시입니다: 

argument :id, Types::GlobalIDType[Discussion],
         required: true,
         description: '논의의 Global ID.'

또한 Global IDs 폐기도 참조하세요.

Sort 인자

정렬 인자는 가능한 경우 enum type을 사용하여 사용 가능한 정렬 값 집합을 설명해야 합니다.

Enum은 Types::SortEnum을 상속하여 일부 공통 값들을 상속할 수 있습니다.

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

TITLE_ASC

또한 정렬 enums의 설명 스타일 가이드도 참조하세요.

다음은 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 객체를 다루는 모든 필드 및 인자의 유형으로 사용되어야합니다.

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

  • Ruby의 Time 및 DateTime 객체를 표준화된 ISO-8601 형식의 문자열로 변환하여 사용될 때, 해당 유형을 이용하는 우리의 GraphQL 필드.
  • ISO-8601 형식의 시간 문자열을 Ruby Time 개체로 변환하여 사용될 때, 해당 유형을 이용하는 우리의 GraphQL 인수.

이를 통해 우리의 GraphQL API는 시간을 표현하고 시간 입력을 처리하는 표준화된 방법을 가질 수 있습니다.

예시: 

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

테스팅

변이 및 리졸버를 테스트할 때, 단위 테스트로 호출하는 대신 전체 GraphQL 요청을 단위로 고려하십시오. 이렇게 함으로써 의존성 업그레이드가 더욱 어려워지는 프레임워크와의 강한 결합을 피할 수 있습니다.

다음을 해야합니다:

  • 리졸버 및 변이에 대한 단위 테스트 대신 요청 스펙 사용을 선호하십시오. 이는 GitlabSchema.execute를 통해 전체 API 엔드포인트를 거치거나 직접 호출하는 것을 포함합니다.
  • GraphqlHelpers#resolve 및 GraphqlHelpers#resolve_field 대신 GraphqlHelpers#execute_query 및 GraphqlHelpers#run_with_clean_state 사용을 선호하십시오.

예시: 

# Good:
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 })

단위 테스트 작성 (사용 중단)

경고: 전체 GraphQL 요청으로 테스트할 수 있는 것은 단위 테스트를 피하십시오.

단위 테스트를 작성하기 전에 다음 예를 검토하십시오:

통합 테스트 작성

통합 테스트는 GraphQL 쿼리 또는 변이의 전체 스택을 확인하고 spec/requests/api/graphql에 저장됩니다.

속도를 위해 GitlabSchema.execute를 직접 호출하거나 테스트 중인 유형만 포함하는 작은 테스트 스키마를 활용하십시오.

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

  • 변이가 실제로 스키마에서 쿼리 가능한지 (변동형이 MutationType에 마운트되었는지).
  • 리졸버나 변이에 의해 반환된 데이터가 정확히 반환 유형과 일치하고 오류 없이 해결됨.
  • 인수가 올바르게 굴반하여 필드가 올바르게 직렬화되는지

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

  • 인수 또는 스칼라의 유효성 검사가 올바르게 적용되었는지.
  • 리졸버나 변이의 #ready? 메서드의 로직이 올바르게 적용되었는지.
  • 인수의 default_value가 올바르게 적용되었는지.
  • 개체가 성공적으로 해결되었으며 N+1 문제가 없는지.

쿼리를 추가할 때, 쿼리가 유효한 결과를 렌더링하는지 테스트하는 a working graphql query that returns data 및 a working graphql query that returns no data 공유 예를 사용할 수 있습니다.

쿼리를 추가하고 있는 쿼리에 모든 가능한 필드를 포함하는 쿼리를 렌더링하는 테스트를 추가하는 것이 더 간단해집니다.

페이지네이션 및 정렬을 지원하는 쿼리에 필드를 추가하는 경우, 세부 정보는 테스트를 참조하십시오.

GraphQL 변이 요청을 테스트하려면, GraphqlHelpers는 두 가지 도우미를 제공합니다: graphql_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)

# { id => global_id_of(issue) }를 포함하는 해시임을 확인합니다
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)}

  • double('query', schema: nil) 또는 GraphqlHelpers#query_double(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)  # 다른 사용자를 사용하여 거짓 양성을 피합니다
    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. 리졸버가 준비 프록을 사용하는 인수를 받는 경우(TimeFrameArguments를 수락하는 리졸버 등), arg_style: :internal_prepared 매개변수를 resolve 메서드에 전달해야 합니다. 이렇게 하면 코드가 인수를 문자열과 정수로 변환하고 정상적으로 준비 프록을 호출하도록 보장합니다. 예를 들어, 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

      추가적인 주의할 점은 리졸버 인수로 열거형을 전달하는 경우 내부 표현 대신 외부 표현을 사용해야 한다는 것입니다. 예를 들어: 

      # 좋음
resolve_group_iterations({ search: search, in: ['CADENCE_TITLE'] })

# 나쁨
resolve_group_iterations({ search: search, in: [:cadence_title] })

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

Query flow 및 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 Analyzers 및 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를 사용하십시오.