프론트엔드의 혼돈에서 질서로

Source: Dev.to

작동 방식

• 백엔드가 마이크로서비스용 GraphQL 스키마를 업데이트합니다.
• 프론트엔드가 최신 스키마를 가져와 쿼리/뮤테이션을 생성하고 타입을 재생성합니다.
• 모든 파괴적 변경은 프론트엔드 빌드 전에 감지됩니다.

이 접근 방식은 백엔드 쿼리와 응답 사이의 모든 불일치를 프론트엔드 빌드 시점에 감지하게 해 주어, 런타임에 도달하기 훨씬 전에 문제를 발견할 수 있습니다.

설정 방법

타입 생성을 통합하려면 프로젝트에 다음 의존성을 추가합니다:

• @graphql-codegen/cli
• @graphql-codegen/typescript
• @graphql-codegen/typescript-document-nodes
• @graphql-codegen/typescript-operations

타입 생성 및 업데이트는 GraphQL Code Generator용 YAML 파일을 통해 구성합니다.

로컬 스키마에서 타입 생성

# Should existing files be overwritten after generation
overwrite: true
generates:
  # Path to the generated output
  src/generated/schema.graphql.ts:
    # Path to the GraphQL schema
    schema: ./graphql-schema/schema.graphql
    # GraphQL documents (queries/mutations) to parse in the project
    documents: src/**/*.graphql
    plugins:
      - typescript
      - typescript-operations
      - typescript-document-nodes

인트로스펙션 엔드포인트에서 타입 생성

overwrite: true
generates:
  src/generated/introspection.graphql.ts:
    # GraphQL endpoint URL
    schema: "http://localhost:4000/graphql"
    documents: "src/**/*.graphql"
    plugins:
      - typescript
      - typescript-operations
      - typescript-document-nodes

생성 실행

package.json에 편리한 스크립트를 정의합니다:

{
  "scripts": {
    "codegen:schema": "npx graphql-codegen --config codegen-schema.yml",
    "codegen:introspection": "npx graphql-codegen --config codegen-introspection.yml"
  }
}

사용 예시

GraphQL 쿼리

query GetOpportunities($request: GetOpportunitiesRequestInput!) {
  opportunities(request: $request) {
    statusCode
    message
    data {
      contractNumber
      creationDate
    }
  }
}

타입‑안전 변수와 쿼리 실행 (TypeScript)

// Type-safe variables
const variables: GetOpportunitiesThemesQueryVariables = {
  providerId: test1,
  keycloakUserId: test2,
};

// Query using Apollo (example from the project)
this.apollo
  .watchQueryWithService('accreditationService', {
    query: GetOpportunitiesThemes,
    variables,
  });

결론

GraphQL Code Generator와 엄격한 백엔드 배포 워크플로우를 함께 사용하면 프론트엔드 팀이 백엔드 변경 사항과 동기화된 상태를 유지할 수 있고, 빌드 시점에 불일치를 잡아내며, 수동 디버깅을 크게 줄일 수 있습니다.

이 접근 방식은 SDL 기반 워크플로우와 인트로스펙션 기반 워크플로우 모두에 적용 가능하며, 다수의 마이크로서비스를 가진 프로젝트에서도 잘 확장됩니다.

자신의 프로젝트에 이 설정을 적용해 보고, 의견이나 대안적인 접근 방식을 공유해 주세요!