S4) Unit 6. [API] GraphQL

📣  GraphQL

𝟭. GraphQL 이란?

✔️ Facebook에서 처음으로 개발했고, 오픈 소스로 제공된 쿼리 언어

➰ Graph + Query Language

➰ Query Language 중에서도 Server API 를 통해 정보를 주고받기 위해 사용하는 Query Language

 

𝟮. 왜 GraphQL 를 사용할까?

✔️ GraphQL은 REST API 방식의 고정된 자원이 아닌 클라이언트 요청에 따라 유연하게 자원을 가져올 수 있다.

➰ GraphQL에서는 모든 데이터가 그래프 형태로 연결되어 있다고 전제한다.

➰ 이를 통해 GraphQL은 클라이언트 요청에 따라 유연하게 트리 구조의 JSON 데이터를 응답으로 전송할 수 있다.

 

𝟯. GraphQL로 그래프 순회

✔️ 그래프로 표현하게 되면 우리가 가지고 있는 데이터의 조각들이나 나타내고자 하는 엔티티(책, 혹은 저자) 간의 관계를 나타낼 수 있다.

➰ 엔티티 : 사물의 구조나 상태, 동작 등을 모델로 표현하는 경우, 그 모델의 구성요소

도서 목록 시스템 구축을 위한 그래프

➰ 그래프를 그릴 수 있게 된다면, GraphQL을 사용해 트리를 추출할 수 있다.

➰ 기본적으로 트리는 방향성은 존재하나 사이클은 존재하지 않는 비순환 그래프 => 동일한 노드로 돌아올 수 없다.

 

✔️ 그래프에서 트리 추출하는 방법

query {
	책(ISBN이 "9780674430006") {
		책 이름
		저자 {
			이름
		}
	}
}

// 위의 그래프에서 실행할 수 있는 쿼리

// 위 쿼리로 요청을 보내면 

{
	책 : {
		책 이름 : "GraphQL은 어렵지 않다",
		저자 : [
			{ 이름 : "김코딩"},
			{ 이름 : "박해커"},
		]
	}
}

// 이렇게 쿼리가 돌아온다.

1. ISBN 번호를 사용해서 선택한 '책' 노드에서 시작한다.

2. GraphQL은 중첩된 각 필드로 표시된 간선을 따라 그래프를 탐색하기 시작한다.

3. 쿼리 내 중첩된 “책 이름” 필드를 통해 책의 제목이 있는 노드로 이동한다.

4. “저자”로 레이블이 지정된 “책”의 간선을 따라가 “저자” 노드를 가져오고, 각 저자의 “이름"을 얻어온다.

GraphQL로 쿼리한 것을 트리 구조로 도식화

➰ GraphQL은 트리 구조로 쿼리 결과를 받기 위해 그래프를 탐색하는 쿼리 언어

 

𝟰. GraphQL의 특징

1️⃣ GraphQL은 HTTP를 통해 API 서버로 요청을 보내고 응답을 받는다.

2️⃣ 응답을 받을 시, 데이터 결과를 JSON 형식으로 받는다.

3️⃣ GraphQL은 서버 개발자가 작성한 각 필드에 대응하는 resolver 함수로 각 필드의 데이터를 조회할 수 있다.

4️⃣ GraphQL은 GraphQL 라이브러리가 조회 대상 schema가 유효한지 검사한다.

---

📣  GraphQL vs REST API

Q. 이미 REST API라는 방법론이 존재하고 있음에도 불구하고 왜 GraphQL이 탄생했을까?

𝟭. REST API의 한계

1️⃣ Overfetch :  필요 없는 데이터까지 제공한다.

2️⃣ Underfetch: endpoint 가 필요한 정보를 충분히 제공하지 못한다.

➰ 클라이언트는 필요한 정보를 모두 확보하기 위하여 추가적인 요청을 보내야 한다.3️⃣ 클라이언트 구조 변경 시 엔드포인트 변경 또는 데이터 수정이 필요하다.

➰ REST API에서는 자원의 크기와 형태를 서버에서 결정하기 때문에 클라이언트가 직접 데이터의 형태를 결정할 수 없다.

➰ 만약 클라이언트에서 필요한 데이터의 내용이 변할 경우 다른 endpoint를 통해 변경된 데이터를 가져오거나 수정 해야한다.

 

𝟮. REST API와 GraphQL의 다른점

(왼) REST API / (오) GraphQL

1️⃣ REST API는 Resource에 대한 형태 정의와 데이터 요청 방법이 연결되어 있지만, GraphQL에서는 Resource에 대한 형태 정의와 데이터 요청이 완전히 분리되어 있다.

2️⃣ REST API는 Resource의 크기와 형태를 서버에서 결정하지만, GraphQL에서는 Resource에 대한 정보만 정의하고, 필요한 크기와 형태는 클라이언트 단에서 요청 시 결정한다.

3️⃣ REST API는 URI가 Resource를 나타내고 Method가 작업의 유형을 나타내지만, GraphQL에서는 GraphQL Schema가 Resource를 나타내고 Query, Mutation 타입이 작업의 유형을 나타낸다.

4️⃣ REST API는 여러 Resource에 접근하고자 할 때 여러 번의 요청이 필요하지만, GraphQL에서는 한번의 요청에서 여러 Resource에 접근할 수 있다.

5️⃣ REST API에서 각 요청은 해당 엔드포인트에 정의된 핸들링 함수를 호출하여 작업을 처리하지만, GraphQL에서는 요청 받은 각 필드에 대한 resolver를 호출하여 작업을 처리한다.

 

𝟯. GraphQL의 장점

1️⃣ 하나의 endpoint 요청

➰ /graphql이라는 하나의 endpoint 로 요청을 받고 그 요청에 따라 query , mutation을 resolver 함수로 전달해서 요청에 응답한다.

➰ 모든 클라이언트 요청은 POST 메소드를 사용한다.

2️⃣ No under & overfetching

➰ 여러 개의 endpoint 요청을 할 필요없이 하나의 endpoint에서 쿼리를 이용해 원하는 데이터를 정확하게 API에 요청하고 응답으로 받을 수 있다.

3️⃣ 강력한 playground

➰ graphql 서버를 실행하면 playground라는 GUI를 이용해 resolver 와 schema 를 한 눈에 보고 테스트 할 수 있다.

4️⃣ 클라이언트 구조 변경에도 지장이 없다.

➰ 클라이언트 구조가 바뀌어도 필요한 데이터를 결정하고 받는 주체가 클라이언트이기 때문에 서버에 지장이 없다

➰  클라이언트에서는 무슨 데이터가 필요한 지에 대해서만 요구사항을 쿼리로 작성하면 된다.

 

𝟰. GraphQL의 단점

1️⃣ REST API에 친숙한 개발자의 경우 GraphQL를 학습하는 데 시간이 필요하다.

2️⃣ 캐싱이 REST보다 훨씬 복잡하다.

➰ HTTP에선 각 메소드에 따라 캐싱이 구현되어 있지만 GraphQL에선 POST 메소드만을 이용해 요청을 보내기 때문에 각 메소드에 따른 캐싱을 지원받을 수 없다.

➰ 이를 보완하기 위해 Apollo 엔진의 캐싱과 영속 쿼리 등이 등장했다.

3️⃣ 고정된 요청과 응답만 필요할 경우에는 Query 로 인해 요청의 크기가 RESTful API 의 경우보다 더 커진다.

---

📣  GraphQL 구조

𝟭. 쿼리(query, 데이터 조회)

✔️ 필드(field)

{
  hero {
    name
  }
}
// hero의 name을 쿼리

{
  "data": {
    "hero": {
      "name": "R2-D2"
    }
  }
}

// 쿼리를 실행했을 때의 결과

---------------------------------------------------------------

{
  hero {
    name
    # 이런 식으로 GraphQL 내에서 주석도 작성할 수 있습니다.
    friends {
      name
    }
  }
}

// 히어로의 이름과 히어로의 친구 이름을 같이 쿼리

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

// 히어로의 이름과 히어로의 친구의 이름이 조회되어 나온다.

➰ 필드의 name은 String 타입을 반환한다.

➰ 쿼리와 결과가 정확하게 같은 모양을 하고 있음을 확인할 수 있는데, 이 부분은 GraphQL에 있어서 필수적이다.

➰ GraphQL은 서버에 요청했을 때 예상했던 대로 돌려받고, 서버는 GraphQL을 통해 클라이언트가 요구하는 필드를 정확히 알 수 있기 때문이다.

 

➰ 두 번째 예시처럼 원하는 필드를 중첩하여 쿼리하는 것도 가능하다.

➰ friends 필드는 배열을 반환한다.

➰ GraphQL 쿼리는 관련 객체 및 필드를 순회할 수 있기 때문에 고전적인 REST API에서 그랬듯이 다양한 endpoint를 만들어 각기 요청을 보내는 대신 클라이언트가 하나의 요청을 보냄으로써 관련 데이터를 가져올 수 있다.

 

✔️ 전달인자(Arguments)

➰ 필드에 인수를 전달하는 부분을 추가하게 되면 쿼리의 필드 및 중첩된 객체들에 전달하여 원하는 데이터만 받아올 수 있다.

{
  human(id: "1000") {
    name
    height
  }
}

// id가 1000인 human의 name과 height를 쿼리

{
  "data": {
    "human": {
      "name": "Luke Skywalker",
      "height": 1.72
    }
  }
}
// 쿼리 결과

➰ id가 1000인 human의 이름과 키를 쿼리해 올 수 있다.

➰ REST API를 이용한다면 ?id=1000 이거나 /1000(/:id)일 때와 같은 목적으로 쿼리할 수 있다.

 

✔️ 별명(Aliases)

➰ 필드 이름을 중복해서 사용할 수 없으므로, 필드 이름을 중복으로 사용해서 쿼리를 해야 할 때는 별명을 붙여서 쿼리 해야한다.

{
  hero(episode: EMPIRE) {
    name
  }
  hero(episode: JEDI) {
    name
  }
}

// 중복 쿼리는 불가능

{
  empireHero: hero(episode: EMPIRE) {
    name
  }
  jediHero: hero(episode: JEDI) {
    name
  }
}
// 앞에 알아볼 수 있는 별명을 붙여주면 쿼리할 수 있다.

{
  "data": {
    "empireHero": {
      "name": "Luke Skywalker"
    },
    "jediHero": {
      "name": "R2-D2"
    }
  }
}

// 쿼리 결과

➰ 다른 이름으로 별명을 지정하면 한 번의 요청으로 두 개의 결과를 모두 얻을 수 있다.

 

✔️ 오퍼레이션 네임(Operation name)

➰ 위 예시들에서는 쿼리와 쿼리 네임을 모두 생략하는 축약형 구문을 사용했지만, 실제 앱에서는 코드를 모호하지 않게 작성하는 것이 중요하다.

query HeroNameAndFriends {
  hero {
    name
    friends {
      name
    }
  }
}

// query keyword와 query name을 작성한다.

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

➰ 위 예시의 query는 오퍼레이션 타입이며, 오퍼레이션 타입에는 query 뿐만 아니라 mutation, subscription, describes 등이 있다.

➰ 쿼리를 약식으로 작성하지 않는 한 이런 오퍼레이션 타입은 반드시 필요하다.

➰ 오퍼레이션 네임을 작성할 때는 오퍼레이션 타입에 맞는 이름으로 작성하는 것이 좋다.

 

✔️ 변수(Variables)

➰ 위 예시들에서는 고정된 인수를 받아 쿼리했지만, 실제 앱을 사용할 때는 고정된 인수를 받는 것보다는 동적으로 인수를 받아 쿼리하는 경우가 많다.

➰ 변수는 그런 인수들을 동적으로 받고 싶을 때 사용한다.

query HeroNameAndFriends($episode: Episode) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}

➰ 오퍼레이션 네임 옆에 변수를 $변수 이름: 타입 형태 로 정의한다.

 

𝟮. 뮤테이션(mutation, 데이터 수정)

✔️ GraphQL은 서버측 데이터를 수정하기도 한다.

➰ mutation이라는 키워드를 사용하여 서버 측 데이터를 수정한다.

mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
  }
}

 

𝟯. 스키마/타입(Schema/Type)

✔️ 스키마의 가장 기본적인 구성 요소는 서비스에서 가져올 수 있는 객체의 종류, 그리고 포함하는 필드를 나타내는 객체 유형이다.

type Character {
  name: String!
  appearsIn: [Episode!]!
  // !가 붙는다면 이 필드는 nullable하지 않고 반드시 값이 들어온다는 의미
  // 이것을 붙여 쿼리한다면 반드시 값을 받을 수 있을 것이라고 예상 할 수 있다.
  // 여기선 이 배열에 null 값을 허용하지 않으므로 항상 0개 이상의 요소를 포함한 배열을 기대할 수 있다.
}

➰ Character는 GraphQL 객체 타입(필드가 있는 타입)이다.

    ㄴ 스키마에 있는 대부분의 타입은 객체 타입

➰ name 과 appearIn 은 Character 타입의 필드이다.

    ㄴ name 과 appearIn 은 GraphQL 쿼리의 Character 타입 어디서든 사용할 수 있는 필드

➰ String은 내장된 스칼라 타입 중 하나이다.

    ㄴ 단일 스칼라 객체로 확인되는 유형이며 쿼리에서 하위 선택을 가질 수 없다.

    ㄴ 스칼라 타입에는 ID, Int도 있다.

 

𝟰. 리졸버(Resolver)

✔️ 요청에 대한 응답을 결정해주는 함수로, GraphQL의 여러 가지 타입 중 Query, Mutation, Subscription과 같은 타입의 실제 일하는 방식(로직)을 작성한다.

const db = require("./../db")
const resolvers = {
  Query: { // **Query :** 저장된 데이터 가져오기 (REST 에 GET 과 비슷합니다.)
		getUser: async (_, { email, pw }) => {
			db.findOne({
				where: { email, pw }
			}) ... // 실제 디비에서 데이터를 가져오는 로직을 작성합니다. 
			...
		}
  },
  Mutation: { // **Mutation :** 저장된 데이터 수정하기 ( Create , Update , Delete )
		createUser: async (_, { email, pw, name }) => {
			...
		}
  }
  Subscription: { // **Subscription :** 실시간 업데이트
    newUser: async () => {
      ...
		}
  }
};

➰ GraphQL에서는 데이터를 가져오는 구체적인 과정을 직접 구현해야 하므로 이와 같은 작업은 Resolver가 담당한다.