koa-graphql에서 graphql-http로의 이전 가이드

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

Koa.js와 GraphQL API를 사용하는 개발자, 특히 koa-graphql에서 graphql-http로의 이전이 필요한 상황에서 실무적 도움이 필요한 분들에게 유용합니다.

핵심 요약

• koa-graphql은 비공식적으로 유지보수 중단되었고, graphql-http로 대체되어야 합니다.
• graphql-http는 기본 기능이 간소화되어 있음으로 인해 customErrorFn, graphiql, context 관리 등 기존 기능을 수동으로 구현해야 합니다.
• Ruru를 활용하여 graphiql을 구현하고, getGraphQLHttpHeaders 함수로 context의 headers를 안정적으로 처리할 수 있습니다.

섹션별 세부 요약

1. 이전 배경 및 이유

• koa-graphql은 더 이상 활발히 유지보수가 되지 않아, graphql-http로의 이전이 권장됩니다.
• graphql-http는 GraphQL over HTTP를 위한 최소한의 구현으로, 추가 기능은 수동으로 구현해야 합니다.
• Yoga는 보다 완전한 기능을 제공하지만, graphql-http만으로도 충분히 구현 가능합니다.

2. `koa-graphql` 제거 및 `graphql-http` 설치

• pnpm un koa-graphql으로 koa-graphql을 완전히 제거하고, pnpm i graphql-http로 설치합니다.
• createHandler를 사용하여 schema와 context를 정의하고, context에서 user 정보를 JWT 토큰을 통해 추출합니다.

3. `context` 및 `headers` 처리

• get-context.ts에서 RequestGraphQLContext 타입을 정의하고, get-graphql-http-headers.ts에서 headers.get을 사용해 authorization 헤더를 안정적으로 처리합니다.
• ctx.headers.get은 함수/문자열/배열 형식을 모두 지원하며, 이를 통해 authToken을 추출합니다.

4. `graphiql` 및 오류 처리

• graphiql은 Ruru를 사용하여 개발 환경에서만 활성화하고, package.json에 npx ruru -SP -p 3001 -e 스크립트를 추가합니다.
• error handling middleware를 구현하여 GraphQLError를 캐치하고, logEnvironments에 따라 개발 환경에서 오류 스택을 출력합니다.

5. 이전 효과 및 성능 개선

• graphql-http는 2.2KB(minified), 1.0KB(Gzip)로, koa-graphql의 2987.3KB(minified), 840.9KB(Gzip)보다 약 1300배 작음.
• GitHub 저장소에서 이전 과정 및 react-router v7과의 호환성 예시를 확인할 수 있습니다.

결론

• graphql-http로의 이전은 경량성과 유지보수성 향상에 유리하며, Ruru와 수동 오류 처리를 통해 기능을 보완할 수 있습니다.
• getGraphQLHttpHeaders 함수와 error handling middleware 구현은 필수이며, graphiql은 Ruru를 통해 간단히 활성화 가능합니다.