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

회사에서 GraphQL 기반의 서버-클라이언트 통신을 적극적으로 사용하고 있습니다.

 

GraphQL은 REST와 다른 타입 시스템과 요청 문법을 가진 API 기술입니다. 서버-클라이언트 통신에서 널리 사용되는 REST API와는 철학부터 요청을 표현하는 방식까지 큰 차이가 있습니다.

그러나 GraphQL을 처음 문서나 책으로 접하면 이 차이점(혁신점)에만 몰두한 나머지, 사실은 같은 문제를 다른 방식으로 표현하고 있다는 점을 놓치기 쉽습니다.

 

두 방식 모두 클라이언트가 서버의 데이터와 기능을 사용하도록 연결한다는 목적이 있기 때문에, 공통점도 많습니다.

저는 처음 GraphQL을 공부할 때 책으로 먼저 접했습니다. 그러다 보니 GraphQL이 기존 웹 API와는 전혀 다른 새로운 통신 시스템인 것처럼 느껴졌습니다. 그래서 실제 개발에서 쓸 때 약간의 삽질을 했던 기억이 있습니다. 오히려 REST API와 닮은 부분을 발견하고 나서야 GraphQL을 제대로 이해하기 시작했다는 생각이 들었습니다. 결국 새로운 기술도 친숙함에서 시작해야 더 빠르게 이해할 수 있는 것 같습니다. 

 

그래서 이번 GraphQL 관련 시리즈를 적어보면서 다음과 같은 흐름으로 글을 써보려고 합니다. 

• 친숙함 느끼기 
  • REST에서도 마주하고 해결했던 문제들
• 차이점 받아들이기
  • GraphQL에서 접근한 해결방식과 철학 이해하기

GraphQL에서 자주 이야기되는 문제들 가운데에는 REST API에서도 마주할 수 있고, REST 방식 안에서 해결할 수 있는 것들이 많습니다

N+1, 데이터 오버페칭, 도메인 경계와 같은 문제들은 GraphQL에서만 발생하거나 GraphQL로만 해결할 수 있는 문제가 아니기 때문입니다.

 

"REST의 한계를 GraphQL이 해결했다" 는 말은 틀렸습니다.
GraphQL은 새로운 문제를 해결하는 기술이라기보다, 기존 HTTP API를 다른 철학과 문법으로 표현한 기술입니다.

 

graphql 을 배우는 첫 단계: 친숙함부터 느끼기 

REST, GraphQL 도 결국 같은 목적(서버-클라이언트 간의 통신)입니다. 그렇기에 개발자가 실제로 하는 일도 크게 다르지 않습니다. 

글의 내용을 코드로도 확인할 수 있도록 GitHub에 예제 코드를 올렸습니다.

https://github.com/inspire12/blog-article-example-graphql-tutorial

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

 

둘 다 CRUD를 한다 

단순한 CRUD를 구현한다면 서버 내부의 애플리케이션 로직은 REST API와 GraphQL에서 크게 다르지 않을 수 있습니다.

// REST (controller)
@Get(':id')
getUser(id) {
    return userService.getUser(id);
}

// GraphQL (resolver)
@Query()
user(id) {
    return userService.getUser(id);
}

 

위와 같이 일반적으로 Service 레이어를 따로 빼서 쓰는 레이어드 아키텍처에서 만약 REST로 쓰다가 GraphQL로 마이그레이션을 한다면 보는 것처럼 Service 레이어와 그 밑의 레이어들은 그대로 사용할 수 있습니다. 

 

GraphQL 을 배우는 두번째 단계: 같은 기능, 다른 표현

코드 레벨에서는 보면 비슷하지만 실제 요청을 하는 문법과 표현은 다릅니다 .

 

GraphQL에서 데이터를 요청하는 방식 

REST는 URL과 HTTP Method(GET, POST 등) 를 사용합니다.

GET /users/1

 

반면 GraphQL API에서는 리소스별 URL마다 Controller 메서드를 연결하기보다, 하나의 GraphQL 엔드포인트로 요청을 전달합니다.

 

// 모든 요청은 일반적으로 이 엔드포인트로 전달됩니다.
POST /graphql

클라이언트는 해당 엔드포인트에 GraphQL 쿼리를 전달하여 필요한 데이터와 필드를 요청합니다.

 

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

REST는 자원 중심으로 표현합니다. 그래서 URL로 요청을 위한 엔드포인트를 정의할 때 명사를 쓰고, 동사를 쓰지 않습니다. (동사는 HTTP Method로 표현합니다)

반면 GraphQL은 무엇을 받고 싶은지 를 표현하는 질의 언어 형태로 요청을 합니다. 

 

데이터를 처리하는 방식 

이때 클라이언트는 GraphQL 스키마에 정의된 필드와 인자를 사용해 쿼리를 작성합니다. 서버에서는 요청된 필드에 연결된 Resolver가 실행되어 필요한 데이터를 조회합니다.

 

이렇게 요청 방식은 다르지만, 서버 내부에서는 두 요청이 같은 애플리케이션 로직으로 연결될 수 있습니다.

REST Controller ─┐
                 ├─ UserService ─ Repository(Prisma) ─ Database
GraphQL Resolver ┘

따라서 GraphQL을 처음 학습할 때는 완전히 새로운 서버 구조로 접근하기보다, 기존 웹 API의 요청 진입점과 표현 방식이 바뀐 것으로 시작하는 편이 이해하기 쉽습니다.

 

GraphQL에서 요청에 응답하는 방식 

요청을 표현하는 방식이 달라지는 만큼, 응답을 표현하는 방식에도 차이가 있습니다.

 

REST

// REST 응답 데이터
{
  "id":1,
  "name":"영학"
}

 

GraphQL

// GraphQL 질의
query {
  user(id:1){
    id
    name
  }
}

 

실제 응답은 GraphQL 응답 규격에 따라 data 객체 내부에 반환됩니다.

// 실제 GraphQL 응답 데이터
{ 
  "data": {
    "user": { 
        "id": 1,
        "name": "영학" 
     } 
   }
 }

 

이 둘다 json 포맷으로 진행을 합니다. GraphQL은 이 부분이 한번 래핑된 형태로 사용되지만, GraphQL 역시 HTTP에서는 일반적으로 JSON 응답을 사용합니다.. 

 

마무리

GraphQL을 처음 배울 때는 이를 완전히 새로운 통신 구조로 받아들이기보다, 기존 API가 다루던 문제를 다른 문법과 철학으로 표현한 것으로 이해하는 편이 좋습니다.

 

GraphQL이 해결하는 문제는 낯설지 않습니다. 낯선 것은 그 문제를 표현하는 방식입니다.

물론 표현 방식이 달라진 만큼, 이를 지원하는 서버의 구성 요소와 요청 처리 방식도 달라집니다. 

 

다음 글에서는 REST API의 요청 진입점이 GraphQL에서 Resolver로 어떻게 표현되는지, 스키마와 서버 코드는 어떻게 연결되는지, 그리고 Playground와 같은 개발 도구는 어떤 역할을 하는지 살펴보겠습니다.