GraphQL API 스타일 가이드

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

비전

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

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

REST 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 GraphQL API에 대한 심층 분석을 진행했습니다. 이는 향후 이 코드베이스의 일부에 작업할 수 있는 누구와도 도메인 특화 지식을 공유하기 위한 것이었습니다. YouTube 녹화본과 Google 슬라이드 및 PDF에서 찾아볼 수 있습니다. 이 심층 분석에서 다룬 모든 내용은 GitLab 11.9를 기준으로 정확했으며, 해당 릴리스 이후에도 특정 세부 사항이 변경되었을 수 있지만 여전히 좋은 소개 자료로 활용될 것입니다.

GraphiQL

GraphiQL은 기존 쿼리를 실험할 수 있는 대화형 GraphQL API 탐색기입니다. https://<your-gitlab-site.com>/-/graphql-explorer에서 GitLab 환경 어디에서나 액세스할 수 있습니다. 예를 들어, GitLab.com에 대한 탐색기를 확인할 수 있습니다.

GraphQL 변경 사항을 검토하는 Merge Request

GraphQL 프레임워크에는 주의해야 할 몇 가지 특별한 사항이 있고, 도메인 전문 지식이 필요합니다.

만약 GraphQL 파일을 수정하거나 엔드포인트를 추가하는 Merge Request을 검토하라는 요청을 받는다면, 우리의 GraphQL 검토 가이드를 살펴보세요.

GraphQL 로그 읽기

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

인증

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

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

제한 사항

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

최대 페이지 크기

기본적으로 연결은 페이지당 최대 레코드 수를 정의한 app/graphql/gitlab_schema.rb에 따라 동작합니다.

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

최대 복잡성

복잡성은 클라이언트용 API 페이지에서 설명되어 있습니다.

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

쿼리의 복잡성 점수는 쿼리에 대해 직접 쿼리할 수 있습니다.

요청 시간 초과

요청은 30초 후에 타임아웃됩니다.

최대 필드 호출 수 제한

특정 필드의 여러 부모 노드에서의 평가를 방지하려는 경우가 있습니다. 이는 N+1 쿼리 문제를 일으키고 최적의 해결책이 없는 경우입니다. 이는 사전 로드를 위해 lookahead 사용 또는 배치 사용과 같은 방법이 고려된 후에 마지막 수단의 옵션이어야 합니다.

예를 들어: 

# 이 사용은 예상대로 동작합니다.
query {
  project {
    environments
  }
}

# 이 사용은 기대치에 맞지 않습니다.
# 이것은 N+1 쿼리 문제를 발생시킵니다. EnvironmentsResolver는 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에서 거부됩니다.
  • 필드나 enum 값의 스칼라 유형을 변경하는 경우, 이로 인해 값이 JSON으로 직렬화되는 방식이 변경됩니다. 예를 들어 JSON 문자열에서 JSON 숫자로 변경되거나 문자열의 형식이 변경되는 경우를 말합니다. 다른 객체 유형으로의 변경은 해당 객체의 모든 스칼라 유형 필드가 동일한 방식으로 직렬화되는 한 허용됩니다.
  • 복잡성을 증가시키는 필드 또는 리졸버의 복잡성 배수를 변경합니다.
  • 필드를 _null_이 아닌(null: false)에서 null 가능한(null: true)로 변경합니다. null 가능 필드에서 설명한 것처럼 논의됩니다.
  • 인수를 선택적인 것(required: false)에서 필요한 것(required: true)으로 변경합니다.
  • 연결의 최대 페이지 크기를 변경합니다.
  • 쿼리 복잡성 및 깊이의 전역 제한을 낮춥니다.
  • 이전에 허용되던 제한을 초과하는 쿼리 결과로 이어질 수 있는 기타 사항.

항목을 폐지하는 방법은 스키마 항목 폐지 섹션을 참조하세요.

호환되지 않는 변경 사항 예외

GraphQL API 호환되지 않는 변경 사항 예외 문서를 참조하세요.

글로벌 ID

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

글로벌 ID는 클라이언트 측 라이브러리에서 캐시 및 검색에 사용되는 관행입니다.

더 자세한 내용은 아래를 참조하세요:

우리는 사용자 코드에 입력 및 출력 인수의 유형으로 Types::GlobalIDType와 같은 사용자 정의 스칼라 유형을 사용해야 합니다. 이러한 유형의 장점은 다음과 같습니다:

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

새로운 인수 및 결과 유형에 대해 이 유형을 사용하는 것을 고려해보세요. 관련이 있는 경우 더 넓은 범위의 객체를 수락하려면 이 유형을 관심사 또는 상위 유형과 매개변수화할 수 있습니다(예: GlobalIDType[Issuable] 대 GlobalIDType[Issue]).

최적화

기본적으로 GraphQL은 N+1 문제를 도입하는 경향이 있으므로 최소화하려는 노력을 활발히 해야 합니다.

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

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

  • 사전 확인은 쿼리에서 선택된 필드에 따라 데이터를 미리 로드할 수 있도록 합니다.
  • 배치 로딩은 데이터베이스 쿼리를 함께 묶어 하나의 문으로 실행할 수 있게 합니다.
  • BatchModelLoader는 일괄 로딩을 활용하기 위해 레코드를 조회하는 권장 방식입니다.
  • 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 전용 새로운 프리젠터를 만드는 것도 가능합니다.

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

널 가능한 필드

GraphQL은 필드를 “nullable(널 가능)” 또는 “non-nullable(널 불가능)”로 지정할 수 있습니다. 전자는 지정된 유형의 값 대신 null이 반환될 수 있음을 의미합니다. 일반적으로, 특정 이유로 인해 널 불가능 필드를 사용해야 하는 경우를 제외하고 널 가능한 필드를 사용하는 것이 좋습니다.

  • 데이터가 필수로 필요한 것에서 선택 사항으로 전환되고 다시 필수로 필요한 것으로 변경되는 것이 일반적입니다.
  • 필드가 선택적으로 변환될 가능성이 없더라도 쿼리 시간에 available(사용 가능)하지 않을 수 있습니다.
    • 예를 들어, blob의 내용은 Gitaly에서 조회해야 할 수 있습니다.
    • 내용이 널 가능하면 전체 쿼리를 실패시키지 않고 partial(부분)한 응답을 반환할 수 있습니다.
  • 버전 없는 스키마에서 널 불가능 필드에서 널 가능한 필드로 변경하는 것은 어려울 수 있습니다.

널 불가능 필드는 필드가 필수일 때, 미래에 선택 사항이 되기 매우 불가능하고 직접적으로 계산하기 쉬울 때에만 사용해아 합니다. 예로, id 필드가 있습니다.

널 불가능 GraphQL 스키마 필드는 느낌표 !로 끝나는 객체 유형입니다. 여기에는 gitlab_schema.graphql 파일에서의 예가 있습니다: 

  id: ProjectID!

다음은 널 불가능한 GraphQL 배열의 예입니다: 

  errors: [String!]!

추가 읽어보기:

전역 ID 노출

GitLab이 Global IDs를 사용하는 것에 따라, 데이터베이스 기본 키 ID를 노출할 때는 항상 Global ID로 변환해야 합니다.

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

연결 유형

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는 페이지당 반환되는 레코드의 최대 수를 지정된 app/graphql/gitlab_schema.rb 에 정의된 값으로 반환합니다. 클라이언트가 제한 인수(first: 또는 last:)를 제공하지 않는 경우, 이 값은 페이지당 반환되는 기본 레코드 수입니다.

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

caution
GraphQL API가 성능을 유지하기 위해 기본값이 설정되었으므로 max_page_size를 높이는 대신에 프런트엔드 클라이언트나 제품 요구 사항을 변경하는 것이 더 좋습니다.

예를 들어: 

field :tags,
  Types::ContainerRepositoryTagType.connection_type,
  null: true,
  description: 'Tags of the container repository',
  max_page_size: 20

필드 복잡성

GitLab GraphQL API는 지나치게 복잡한 쿼리를 수행하는 것을 제한하기 위해 복잡성 점수를 사용합니다. 복잡성은 클라이언트 설명서에서 설명되어 있습니다.

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

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

calls_gitaly

해당하는 필드를 해결할 때 Gitaly 호출을 수행할 수 있는 잠재력이 있는 필드는 정의될 때 calls_gitaly: true를 field에 전달하여 표시해야 합니다.

예: 

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

이러한 작업은 필드의 복잡성 점수를 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에서 상속을 받으며 리소스에 대한 권한을 노출하는 데 도움이 되는 몇 가지 도우미 메서드를 포함합니다: 

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

피처 플래그

피처 플래그를 구현하여 GraphQL에서 다음을 토글할 수 있습니다:

  • 필드의 반환 값입니다.
  • 인수 또는 변형의 동작입니다.

이는 귀하의 선호 및 상황에 따라 해결자, 유형 또는 모델 메서드에서 수행할 수 있습니다.

note
피처 플래그로 설정되는 항목에 대해 Alpha로 표시하는 것이 좋습니다. 이렇게 하면 공개 GraphQL API의 소비자들에게 해당 필드가 아직 사용되어서는 안 된다는 신호를 보냅니다. 또한 언제든지 Alpha 항목을 변경하거나 제거할 수 있으며 이를 폐기할 필요가 없습니다. 플래그가 제거되면 “Alpha” 속성을 제거하여 해당 항목을 공개 상태로 변경할 수 있습니다.

피처 플래그 항목에 대한 설명

스키마 항목의 값을 또는 동작을 토글하기 위해 피처 플래그를 사용할 때, 항목의 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와의 하위 호환성을 유지합니다.

필드, 인수, 열거 유형 값 또는 변형을 제거하는 대신 이를 _폐지_해야 합니다.

스키마의 폐지된 부분은 GitLab 폐지 프로세스에 따라 향후 릴리스에서 제거될 수 있습니다.

GraphQL에서 스키마 항목을 폐지하려면 다음을 수행하세요:

  1. 항목에 대한 폐지 문제를 만드십시오(#폐지-문제-만들기).
  2. 스키마에서 항목을 폐지합니다(#항목을-폐지로-표시).
note

폐지 문제 만들기

모든 GraphQL 폐지에는 해당 폐지를 추적하고 제거하는 Deprecations` 이슈 템플릿을 사용하여 만들어야합니다.

폐지 문제에 다음 두 레이블을 적용하십시오.

  • ~GraphQL
  • ~폐지

항목을 폐지로 표시

필드, 인수, 열거 값 및 변형은 deprecated 속성을 사용하여 폐지됩니다. 해당 속성의 값은 다음과 같은 해시로 구성됩니다.

  • 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 젬을 사용하여 전역 ID를 생성하고 구문 분석하므로 해당 ID는 모델 이름에 결합됩니다. 모델을 이름을 변경하면 해당 전역 ID도 변경됩니다.

만약 전역 ID를 스키마의 인수 유형으로 사용한다면, 전역 ID의 변경은 일반적으로 호환성이 없을 수도 있습니다.

이전 전역 ID 인수를 사용하는 클라이언트를 계속 지원하려면 Gitlab::GlobalId::Deprecations에 폐지를 추가하십시오.

note
전역 ID가 필드로서 노출만 된다면, 해당 필드를 폐지할 필요가 없습니다. 전역 ID의 표현 방식이 하위 호환성이 있는 것으로 간주됩니다. 클라이언트가 이러한 값들을 구문 분석하지 않을 것으로 예상됩니다. 이들은 불투명한 토큰으로 취급되어야 하며, 그 구조는 우연한 것이며 의존해서는 안 됩니다.

예시 시나리오:

이 예시 시나리오는 이 Merge Request에 기반합니다.

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"과 같은 인수를 거부합니다. 또는 쿼리 서명에서 PrometheusServiceID로 인수 유형을 지정합니다.

클라이언트가 변이와 변경 없이 계속 상호 작용할 수 있도록, Gitlab::GlobalId::Deprecations의 DEPRECATED 상수를 편집하고 새 Deprecation을 배열에 추가합니다. 

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

그런 다음 일반적인 폐지 프로세스를 따릅니다. 나중에 이전 인수 스타일을 제거하려면 Deprecation을 제거하십시오. 

DEPRECATIONS = [].freeze

폐지 기간 동안 API는 인수 값에 다음 형식을 허용합니다.

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

또한 아래 유형을 인수에 대한 쿼리 서명에서 허용합니다.

  • PrometheusServiceID
  • IntegrationsPrometheusID
note
이 예에서 이전 유형(PrometheusServiceID)을 사용하는 쿼리는 유효하지만 API는 사용가능하나 유효하지 않은 것으로 간주합니다. 이유는 @deprecated 지시문 외부 메소드의 사용을 폐지하기 때문에 유효성 검사 도구가 해당 지식을 갖고 있지 않기 때문입니다.

문서는 이전 전역 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: '로그인용 토큰.'

이와 유사하게 app/graphql/types/mutation_type.rb에서 뮤테이션 전체를 Alpha로 표시할 수 있습니다. 

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

Alpha GraphQL 항목은 GraphQL 폐지를 활용하는 사용자 지정 GitLab 기능입니다. Alpha 항목은 GraphQL 스키마에서 폐지됐음으로 표시됩니다. 폐지된 스키마 항목처럼 Alpha 필드를 대화형 GraphQL 탐색기(GraphiQL)에서 테스트할 수 있습니다. 그러나 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

RUBY에서 대문자 문자열이 아닌 클래스 속성에 대한 열거를 제공할 경우 value: 옵션을 제공할 수 있습니다.

다음 예제에서:

  • RUBY에 대한 OPENED의 입력이 GraphQL 응답에서'opened'로 변환됩니다.
  • RUBY 값 '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

열거 값은 deprecated 키워드를 사용하여 폐지될 수 있습니다.

레일스 열거로부터 동적으로 GraphQL 열거 정의

당신의 GraphQL 열거가 레일스 열거에서 지원된다면 레일스 열거를 동적으로 정의하여 GraphQL 열거 값 정의를 고려해야 합니다. 그렇게 함으로써, RUBY 열거에 값이 추가되면 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을 사용하십시오. 이러한 목적으로 union의 사용 예는 !30129입니다.

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

예를 들어, 다음 JSON 데이터가 제공될 때: 

{
  "title": "My chart",
  "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: '이슈가 닫힌 시간.'

열거할 수 있는 필드와 매개변수의 설명은 다음에서 볼 수 있습니다:

설명 양식 안내

언어와 구두점

필드와 매개변수를 설명할 때 가능한 {y}의 {x}를 사용하여 설명합니다. 여기서 {x}는 설명하려는 항목이고, {y}는 해당 항목이 적용되는 리소스입니다. 예를 들어: 

이슈의 ID.

완결된 에픽의 저자.

정렬하거나 검색하는 매개변수는 적절한 동사로 시작하세요. 지정된 값이라는 것을 나타내기 위해 간결하게 this 대신 주어진이나 지정된을 사용할 수 있습니다. 예를 들어: 

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

일관성 및 간결성을 위해 설명을 The나 A로 시작하지 마십시오.

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

부울

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

이슈가 비밀로 표시되는지를 나타냅니다.

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

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

정렬 열거형

정렬을 위한 열거형은 설명으로 '값을 정렬하기 위한 {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: { '속에 대한 위키피디아 문서' => 'https://ko.wikipedia.org/wiki/속' }

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

분류된 속과입니다. 참고: [속에 대한 위키피디아 문서](https://ko.wikipedia.org/wiki/속)

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

구독 티어 뱃지

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

예를 들어: 

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

권한 부여

참조: GraphQL 권한 부여

리졸버

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

필드에 표시할 객체를 찾기 위해 리졸버에 인수를 정의할 수 있습니다. 인수 섹션을 참조하세요.

쿼리 실행에 필요한 쿼리 수를 제한하기 위해 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

동일한 리졸버 클래스를 두 개 이상의 다른 위치에서 사용할 수 있지만, 리졸버 객체를 직접 재사용하면 안 됩니다. 리졸버는 인가, 준비 및 해결이 프레임워크에 의해 조율되며 각 스테이지에서 지연 값을 반환할 수 있습니다. 응용 프로그램 코드에서 리졸버나 뮤테이션을 절대로 인스턴스화해서는 안 됩니다.

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

  • 데이터 조회를 위한 쿼리에서 파인더.
  • 작업을 적용하기 위한 뮤테이션의 서비스.
  • 쿼리에 특화된 로더(배치 인식 파인더).

뮤테이션에서 배치 사용할 이유는 절대 없습니다. 뮤테이션은 시리즈로 실행되므로 배치 기회가 없습니다. 모든 값은 즉시 평가되므로 배치는 불필요한 오버헤드입니다. 다음을 작성 중이라면:

  • 뮤테이션, 그대로 객체를 찾아보세요.
  • 리졸버 또는 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

그리고 필드에 이 리졸버를 사용할 수 있습니다: 

# 부서 유형

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

Resolver 최적화

Look-Ahead

실행 중에 전체 쿼리가 미리 알려져 있으므로 쿼리를 최적화하고 필요한 연관 관계를 일괄로 로드할 수 있습니다. N+1 성능 문제를 피하기 위해 리졸버에 lookahead 지원을 추가해보세요.

일반적인 lookahead 사용 사례에 대한 지원을 활성화하려면(예: 자식 필드가 요청될 때 연관 관계를 사전로드), LooksAhead를 포함할 수 있습니다. 예를 들면: 

# 'MyThing' 속성을 가진 모델 `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
  
  # 항상 사전로드해야 하는 항목을 나열합니다.
  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 concern은 또한 중첩된 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

BatchLoading

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, 'have this instead']
end

그러므로 리졸버를 호출할 때(주로 프레임워크 추상화인 리졸버는 재사용 가능한 것으로 간주되어서는 안 되며, finders가 우선되어야 합니다), resolve를 호출하기 전에 ready? 메서드를 호출하고 불리언 플래그를 확인해야 합니다! 이에 대한 예시는 우리의 GraphqlHelpers를 참조하세요.

부정된 인수

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

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

메타데이터

리졸버를 사용할 때, 필드 메타데이터의 단일 지점으로 제공함으로써 필드 옵션을 선언할 수 있습니다(필드 이름을 제외한 모든 것).

  • type(필수 - 모든 리졸버는 타입 주석을 포함해야 함)
  • extras
  • description
  • Gitaly 주석 (calls_gitaly!로)

예시: 

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

부모 객체를 자식 Presenter에 전달하기

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

Presenter 클래스에서 부모 객체를 찾으려면 다음을 수행하세요.

  1. 부모 객체를 GraphQL context에 추가하십시오. 이는 Resolver의 resolve 메서드에서 수행됩니다. 

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

  2. Resolver 또는 필드에서 parent 필드 컨텍스트가 필요하다고 선언하십시오. 예를 들어: 

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

  3. Presenter 클래스에서 필드 메서드를 선언하고 parent 키워드 인수를 수신하도록 하십시오. 이 인수에는 부모 GraphQL context가 포함되므로, Resolver에서 사용한 키로 부모 객체에 액세스해야 합니다. 

      # in ChildPresenter
  def my_computing_method(parent:)
    # 여기서 `parent[:parent_object]`로 작업 수행
  end
     
  # In SomeTypeResolver
     
  def resolve(parent:)
    # ...
  end

실제 사용 사례에 대한 예는 이 MR에서 IterationPresenter에 scopedPath와 scopedUrl을 추가한 것을 확인하십시오.

Mutations

변이(mutations)는 저장된 값을 변경하거나 작업을 트리거하는 데 사용됩니다. GET 요청은 데이터를 수정해서는 안 되는 것과 같이, 우리는 일반적인 GraphQL 쿼리에서는 데이터를 수정할 수 없습니다. 그러나 변이에서는 데이터를 수정할 수 있습니다.

변이 작성

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

변이 업데이트 정밀도

GitLab의 서비스 중심 아키텍처는 대부분의 변이가 Create, Delete 또는 Update 서비스를 부르는 것을 의미합니다. 예를 들어 UpdateMergeRequestService 등이 있습니다. Update 변이의 경우, 객체의 한 측면만 업데이트할 수도 있으므로, 정밀하게 변이만 필요할 수도 있습니다. 예를 들어 MergeRequest::SetDraft와 같이 하나의 측면만 업데이트하려는 경우입니다.

정밀 변이와 그럭저럭한 변이 모두 가질 수 있지만, 너무 많은 정밀 변이는 유지보수, 코드 이해도 및 테스트에서 조직적인 도전과 관련될 수 있다는 점을 인식해야 합니다. 각 변이에는 새로운 클래스가 필요하며, 이는 기술적 부채를 야기할 수 있습니다. 또한 스키마가 매우 커지게 되므로 사용자가 스키마를 찾기 어려워질 수 있습니다. 또한 각 새로운 변이에는 테스트(느린 요청 통합 테스트 포함)가 필요하기 때문에, 변이를 추가함으로써 테스트 스위트가 느려집니다.

변화를 최소화하기 위해 다음을 지키십시오.

  • 가능한 경우 기존 변이(예: MergeRequest::Update) 사용.
  • 이미 있는 서비스를 정밀하지 않은 변이로 노출.

정밀하지 않은 변이보다 정밀한 변이가 더 적절한 경우:

  • 특정 권한 또는 다른 전문적인 로직이 필요한 속성을 수정할 때.
  • 상태 기계와 같은 전환을 노출하는 경우(이슈 잠금, MR Merge, 에픽 종료 등).
  • 중첩 속성을 허용하는 경우(자식 객체에 대한 속성을 허용하는 경우).
  • 변이의 의미를 명확하고 간결하게 표현할 수 있는 경우.

자세한 내용은 이슈 #233063을 참조하십시오.

명명 규칙

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

예시: 

class UserUpdateMutation < BaseMutation
  graphql_name 'UserUpdate'
end

graphql-ruby gem의 1.13 버전의 변경으로 인해 graphql_name은 타입 이름이 올바르게 생성되도록 보장하기 위해 클래스의 첫 번째 줄이어야합니다. 이를 위해 Graphql::GraphqlNamePosition 규칙을 적용합니다. 자세한 내용은 이슈 #27536를 참조하십시오.

우리의 GraphQL 변이 이름은 역사적으로 일관성이 없었지만, 새로운 변이 이름은 관습적으로 {리소스}{동작} 또는 {리소스}{동작}{속성} 패턴을 따르어야 합니다.

새로운 리소스를 생성하는 변이는 동사 Create를 사용해야 합니다.

예시:

  • CommitCreate

데이터를 업데이트하는 변이는 다음을 사용해야합니다.

  • 동사 Update.
  • 더 적합한 경우에는 Set, Add, 또는 Toggle과 같은 도메인별 동사.

예시:

  • EpicTreeReorder
  • IssueSetWeight
  • IssueUpdate
  • TodoMarkDone

데이터를 제거하는 변이는 Destroy가 아닌 동사 Delete를 사용해야 합니다.

예시:

  • 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: "변이 후의 MR(Merge Request)."

따라서, 이 변이에서 resolve에서 반환된 해시는 다음과 같아야합니다. 

{
  # 수정된 MR(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

mergeRequestSetDraft라는 필드를 생성하고 Mutations::MergeRequests::SetDraft를 해결해야 합니다.

자원 권한 부여

변이 내에서 자원을 인가하려면 먼저 변이에서 필요한 권한을 제공해야 합니다. 다음과 같이 변이에서 필요한 권한을 제공합니다: 

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: ["the thing을(를) 만질 수 없습니다"],
      thing: { .. }
    }
  }
}

이에는 다음과 같은 예가 포함됩니다:

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

이상적으로는 사용자가 이토록 멀리까지 가지 않도록 하지만, 가게된 경우에는 잘못된 부분과 의도를 이해할 수 있도록 사용자에게 무엇이 잘 못되었는지, 실패의 이유 및 의도에 도달하기 위해 어떻게 할 수 있는지 알려줘야 합니다. 예를 들어, 요청을 다시 시도하기만 하면 되는 경우가 있을 수 있습니다.

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

실패 (사용자에게 무관)

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

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

이는 변이 도중에 오류를 발생시키는 것으로부터 발생합니다. 우리의 구현에서는 인수 오류 및 유효성 오류의 메시지가 클라이언트로 반환되며 다른 모든 StandardError 인스턴스는 catch되어 로깅되며 메시지가 "내부 서버 오류"로 설정된 채로 클라이언트에 표시됩니다. 자세한 내용은 GraphqlController를 참조하십시오.

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

  • GraphQL 구문 오류, 예를 들어 Int가 String으로 전달되거나 필수 인수가 제공되지 않은 경우.
  • 스키마 오류, 예를 들어 사용할 수 없는 필드에 대한 값을 제공할 수 없는 경우.
  • 시스템 오류: 예를 들어 Git 리포지터리 예외 또는 데이터베이스 이용 불가.

사용자는 보통 일반적인 사용에서 이러한 오류를 유발시킬 수 없어야 합니다. 이러한 종류의 오류는 내부적으로 처리되어 사용자에게 구체적인 세부 정보로 표시되어서는 안 되며 내부적으로 유지되어야 합니다.

변이 실패시 사용자에게는 알려주어야 하지만 그 이유를 알려주어야 하는 것은 아니지만 사용자가 그것을 발생시킬 수 없으며 그것을 고칠 수 있는 것도 없으나 변이를 다시 시도할 수 있는 기회를 제공할 수 있습니다.

에러 유형 분류

변이를 작성할 때, 에러 상태가 두 가지 범주 중 어디에 속하는지 고려해야 합니다(및 이에 대해 프론트엔드 개발자와 의사 소통하여 가정을 검증해야 합니다). 이는 _사용자_의 요구와 _클라이언트_의 요구를 구별하는 것을 의미합니다.

사용자가 그것에 대해 알아야 할 필요가 없는 한 에러를 절대로 catch하지 마십시오.

만약 사용자가 그것을 알아야 한다면, 프론트엔드 개발자와 소통하여 다시 보내는 에러 정보가 관련이 있고 목적을 제공하는지 확인하세요.

또한, 프론트엔드 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의 단위 테스트에서 테스트되어야 합니다. Merge Request !34798는 폐기된 별칭 변이를 테스트하는 방법을 포함하여 이에 대한 예로 참조할 수 있습니다.

EE 변이 폐기

EE 변이는 동일한 과정을 따라야 합니다. Merge Request 프로세스의 예시로는 Merge Request!42588를 읽어보세요.

구독

우리는 구독을 사용하여 클라이언트에게 업데이트를 push합니다. 우리는 메시지를 웹소켓을 통해 전달하기 위해 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 pagination을 참조하세요.

인수

리졸버 또는 변이의 인수는 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" } # => 허용
{  } # => 무효 (주어지지 않음)

무효성 및 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: "제공된 이름이 없음",
         replace_null_with_default: true

추가 자세한 내용은 유효성 검사, 무효성 및 기본값을 참조하세요.

키워드

정의된 각 GraphQL argument는 변이의 #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 (객체에 있는 경우)
  • 모든 다른 객체에 대해 객체의 글로벌 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: '논의의 글로벌 ID입니다.'

글로벌 ID 사용 중단도 참조하십시오.

정렬 매개변수

정렬 매개변수는 가능한 경우 enum 타입을 사용하여 사용 가능한 정렬 값 집합을 설명해야 합니다.

일반적으로 Types::SortEnum에서 상속된 enum이어야 합니다.

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

TITLE_ASC

또한 정렬 enum에 대한 설명 스타일 가이드도 참조하십시오.

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 형식의 문자열로 변환합니다.
  • 우리의 GraphQL 인수 타입으로 사용될 때 ISO-8601 형식의 시간 문자열을 Ruby Time 객체로 변환합니다.

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

예시: 

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

테스트

뮤테이션 및 리졸버를 테스트할 때, 프레임워크에 대한 의존성을 줄이기 위해 전체 GraphQL 요청을 단위로 테스트하는 것이 좋습니다. 이렇게 하면 프레임워크와의 강한 의존성을 피할 수 있어 의존성 업그레이드가 더 어려워지는 것을 방지할 수 있습니다.

다음을 해야 합니다:

  • 리졸버 및 뮤테이션의 단위 테스트 대신 전체 API 엔드포인트를 사용하여 요청 스펙을 선호하십시오(GitlabSchema.execute 또는).
  • GraphqlHelpers#execute_query 및 GraphqlHelpers#run_with_clean_state를GraphqlHelpers#resolve 및 GraphqlHelpers#resolve_field 대신 사용하십시오.

예: 

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

단위 테스트 작성 (폐기됨)

caution
전체 GraphQL 요청으로 테스트할 수 있는 경우 단위 테스트를 작성하는 것을 피하십시오.

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

통합 테스트 작성

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

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

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

  • 뮤테이션이 실제로 스키마에서 쿼리 가능한지(MutationType에 마운트됨) 확인합니다.
  • Resolver 또는 뮤테이션에 의해 반환된 데이터가 올바른지 및 오류 없이 해결되는지 확인합니다.
  • 인수가 입력시 올바르게 변환되는지, 및 필드가 출력시 올바르게 직렬화되는지 확인합니다.

통합 테스트는 또한 다음 사항을 검증할 수 있습니다. 왜냐하면 전체 스택을 호출하기 때문입니다:

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

쿼리를 추가할 때, 데이터를 반환하는 작동하는 GraphQL 쿼리 및 데이터를 반환하지 않는 작동하는 GraphQL 쿼리 공유 예제를 사용하여 쿼리가 유효한 결과를 렌더링하는지 테스트할 수 있습니다.

GraphqlHelpers#all_graphql_fields_for 도우미를 사용하여 사용 가능한 모든 필드를 포함하는 쿼리를 구성할 수 있습니다. 이는 쿼리에서 가능한 모든 필드를 렌더링하는 테스트를 추가하는 데 더 직접적인 방법을 제공합니다.

페이징 및 정렬을 지원하는 쿼리에 필드를 추가하는 경우 세부 정보에 대한 자세한 내용은 테스트 중 페이지네이션을 참조하십시오.

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)
  
# 이슈의 global_id_of(id)를 포함하는 해시인지 검사합니다
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)  # false positive를 피하기 위해 다른 사용자를 사용합니다
    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를 사용할 때와 달리 Ruby 객체를 사용하는 인수를 사용합니다. 대부분의 경우에 이는 잘 작동합니다.

    2. 리졸버가 prepare proc을 사용하는 인수를 사용하는 경우(예: 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 업그레이드를 위한 다리 역할로 추가되었습니다. 리졸버/뮤테이션에 대한 직접적인 테스트는 최종적으로 제거될 것이며, 리졸버/뮤테이션에 대한 단위 테스트 작성은 이미 사라지고 있습니다

쿼리 흐름 및 GraphQL 인프라에 관한 노트

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

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

예: Present 

module Gitlab
  module Graphql
    module Present
      #... some code above...
      
      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 documentation를 참조하세요.

문서 및 스키마

저희 스키마는 app/graphql/gitlab_schema.rb에 위치합니다. 자세한 내용은 스키마 참조를 확인하세요.

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

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

변경 로그 항목 포함

모든 클라이언트를 대상으로 하는 변경 사항은 반드시 변경 로그 항목을 포함해야 합니다.

지연 처리

GraphQL에서 성능을 관리하기 위한 중요한 기법 중 하나는 lazy(지연 처리) 값을 사용하는 것입니다. Lazy 값은 결과의 약속을 나타내며, 그들의 작업이 후에 실행될 수 있도록 허용함으로써 쿼리 트리의 다른 부분에서 쿼리를 일괄 처리할 수 있습니다. 저희 코드에서 lazy 값을 사용하는 주요 예시는 GraphQL BatchLoader입니다.

지연 처리 값을 직접 관리하려면 Gitlab::Graphql::Lazy를 참조하고 특히 Gitlab::Graphql::Laziness를 확인하세요. 이것에는 laziness의 생성 및 제거의 기본 작업을 구현하는 데 도움이 되는 #force 및 #delay가 포함되어 있습니다.

강제로 지연 값을 처리하지 않고 다루려면 Gitlab::Graphql::Lazy.with_value를 사용하세요.