GraphQL 스러운 코드는 무엇일까? 2편: 다른 표현을 위한 GraphQL에서 요청을 처리하는 방식

1편: REST와 GraphQL의 같은 의도

 

GraphQL 스러운 코드는 무엇일까? 1편: REST와 GraphQL의 같은 의도와 다른 표현

 

예제 코드: https://github.com/inspire12/blog-article-example-graphql-tutorial

GitHub - inspire12/blog-article-example-graphql-tutorial

 

1편에서는 REST와 GraphQL이 같은 목적을 서로 다른 방식으로 표현한다는 점을 살펴봤습니다.

 

이 차이를 처리하기 위해 요청을 핸들링하는 부분의 차이를 알면 좋습니다.

Controller vs Query Resolver

REST API에서는 Controller 가 HTTP 요청을 핸들링 합니다 

GraphQL API에서는 Controller 대신 Resolver 가 HTTP 요청을 받습니다. 

 

REST에서는 URL과 HTTP Method를 기준으로 Controller 메서드를 확인할 수 있습니다. (+ Swagger)

@Get(':id')
getUser(@Param('id') id: number) {
  return this.userService.getUser(id);
}

 

GraphQL에서는 요청한 필드 이름을 기준으로 Resolver를 찾을 수 있습니다. (+ playground)

@Query(() => User)
user(@Args('id') id: number) {
  return this.userService.getUser(id);
}

 

Resolver는 무엇을 기준으로 실행될까

REST에서는 Controller에 선언된 URL과 HTTP Method를 통해 실행할 메서드를 확인할 수 있습니다.

GraphQL의 Resolver는 Schema에 정의된 필드와 연결됩니다.

다음과 같은 Schema가 있다고 가정합니다.

type Query {
  user(id: Int!): User!
}

type User {
  id: Int!
  name: String!
}

여기서 Query 타입에 정의된 user 필드는 다음 Resolver와 연결됩니다.

@Query(() => User)
user(
  @Args('id', { type: () => Int }) id: number,
) {
  return this.userService.getUser(id);
}

클라이언트가 user 필드를 요청하면 GraphQL 실행 엔진은 Schema를 기준으로 해당 필드를 확인하고, 연결된 Resolver를 실행합니다.

Schema의 Query.user
        ↓
UserResolver.user()
        ↓
UserService.getUser()

Resolver가 임의로 실행되는 것이 아니라, Schema에 정의된 필드를 기준으로 실행됩니다.

GraphQL Schema란 무엇인가

GraphQL Schema는 클라이언트와 서버가 통신하기 위한 계약(Contract)입니다.

조금 더 기술적으로 표현하면

GraphQL API에서 사용할 수 있는 요청(Query, Mutation, Subscription), 타입, 입력값, 반환값을 정의하는 명세입니다.

 

GraphQL의 Operation에는 일반적으로 다음 세 가지가 있습니다.

• Query: 데이터를 조회합니다.
• Mutation: 데이터를 생성하거나 변경합니다.
• Subscription: 서버에서 발생한 변경을 지속적으로 전달받습니다.

다음 Schema를 다시 살펴보겠습니다.

type Query {
  user(id: Int!): User!
}

type User {
  id: Int!
  name: String!
}

 

이 스키마만 보고도 우리는 다음 정보를 알 수 있습니다.

• user라는 Query가 존재합니다.
• id라는 Int 타입의 인자를 받습니다.
• null은 허용하지 않습니다.
• User를 반환합니다.
• User에는 id와 name이 존재합니다.

즉, API를 호출하는 데 필요한 정보가 Schema에 정의되어 있습니다.

 

GraphQL 요청은 Schema를 기준으로 검증됩니다

Schema는 API 문서 역할만 하는 것이 아닙니다.

GraphQL 서버는 요청을 실행하기 전에 Schema를 기준으로 요청이 유효한지 검증합니다.

예를 들어 다음 요청은 정상적인 요청입니다.

query {
  user(id: 1) {
    id
    name
  }
}

반면 User 타입에 존재하지 않는 필드를 요청하면 검증 단계에서 실패합니다.

query {
  user(id: 1) {
    id
    age
  }
}

User 타입에 age 필드가 정의되어 있지 않기 때문입니다.

또한 id는 Int!로 정의되어 있으므로 문자열을 전달할 수 없습니다.

query {
  user(id: "1") {
    id
    name
  }
}

GraphQL 서버는 Resolver를 실행하기 전에 다음 내용을 확인합니다.

• 요청한 필드가 Schema에 존재하는지 확인합니다.
• 필요한 인자가 전달되었는지 확인합니다.
• 인자의 타입이 올바른지 확인합니다.
• 반환 타입에서 요청할 수 있는 필드인지 확인합니다.
• null을 허용하지 않는 값이 누락되지 않았는지 확인합니다.

검증에 실패하면 해당 Resolver는 실행되지 않습니다.

GraphQL 요청
    ↓
Schema 기준 검증
    ↓
검증 성공
    ↓
Resolver 실행

Schema는 문서이면서 동시에 요청을 검증하는 타입 시스템입니다.

REST에도 API 명세가 있고 이를 기반으로 문서화가 가능합니다

예제 코드 http://localhost:3000/swagger

Swagger를 함께 사용하면 다음 내용을 API 문서로 확인할 수 있습니다.

 

REST에도 같은 역할을 하는 개념이 존재합니다.

Controller, Request DTO, Response DTO를 통해 API의 입력과 출력을 정의할 수 있습니다.

@Get(':id')
getUser(
  @Param('id') id: number,
): Promise<UserResponse> {
  return this.userService.getUser(id);
}

class UserResponse {
  id: number;
  name: string;
}

따라서 API 명세 자체가 GraphQL만의 개념은 아닙니다.

다만 GraphQL에서는 Schema가 문서, 타입 정의, 요청 검증, Resolver 연결의 기준을 함께 담당합니다.

REST에서는 이러한 정보가 Controller, DTO, Swagger 설정 등에 나뉘어 표현될 수 있지만, GraphQL에서는 Schema를 중심으로 연결됩니다.

Playground는 Schema를 사용합니다

예제 코드 실행 후 http://localhost:3000/graphql 접속

GraphQL API를 개발할 때 Playground, GraphiQL, Apollo Sandbox와 같은 도구를 함께 사용합니다.

이 도구들은 GraphQL 요청을 작성하고 실행할 수 있는 클라이언트입니다.

query {
  user(id: 1) {
    id
    name
  }
}

REST API를 테스트할 때 사용하는 Postman이나 Swagger UI와 유사한 역할을 합니다.

다만 GraphQL Playground는 서버가 제공하는 Schema를 조회하여 다음 기능을 제공합니다.

• 사용할 수 있는 Query와 Mutation을 보여줍니다.
• 인자와 반환 타입을 보여줍니다.
• 요청 필드를 자동완성합니다.
• Schema에 없는 필드를 요청하면 오류를 표시합니다.
• 타입 간의 관계를 탐색할 수 있습니다.

GraphQL 서버
    ↓
Schema 제공
    ↓
Playground가 Schema 조회
    ↓
문서와 자동완성 구성

Playground가 Resolver 코드를 직접 분석하는 것은 아닙니다.

Schema를 조회하고, Schema에 정의된 타입과 필드를 기준으로 UI와 자동완성을 제공합니다.

이처럼 GraphQL에서는 Schema가 서버와 클라이언트 도구를 연결하는 중심 역할을 합니다.

 

REST와 GraphQL의 요청 처리 비교

역할	REST	GraphQL
요청 진입점	Controller	Resolver
작업 식별	HTTP Method와 URL	Query / Mutation 필드
입력값	Path, Query String, Body	Arguments, Input
비즈니스 로직 호출	Service 호출	Service 호출
일반적인 응답 형식	JSON	JSON
데이터 조회	Repository 또는 ORM	Repository 또는 ORM
계약 확인	Scheme + playground	RequestDTO, ResponseDTO + Swagger

 

 

그렇다면 이제 GraphQL이라는 새로운 문법이 필요했을까요? 

 

마무리

REST에서는 HTTP Method와 URL을 기준으로 Controller를 실행합니다.

GraphQL에서는 Schema에 정의된 필드를 기준으로 Resolver를 실행합니다.

REST
HTTP Method + URL → Controller

GraphQL
Schema + Field → Resolver

GraphQL에서 Schema는 클라이언트가 사용할 수 있는 타입과 필드를 정의하고, 요청을 검증하며, Resolver를 실행하기 위한 기준을 제공합니다.

Playground 역시 이 Schema를 조회하여 API 문서와 자동완성 기능을 구성합니다.

여기까지는 GraphQL 요청이 어떤 구성 요소를 거쳐 서버 코드로 연결되는지 살펴봤습니다.

하지만 GraphQL의 특징은 요청을 Resolver에 연결하는 방식에만 있지 않습니다.

GraphQL은 클라이언트가 실행할 기능뿐만 아니라 필요한 데이터의 구조까지 Query에 작성하도록 합니다.

다음 글에서는 GraphQL이 요청을 Query로 표현하는 이유를 살펴보고, 이러한 표현 방식이 Schema와 Resolver 설계에 어떤 영향을 주는지 알아보겠습니다.