1. REST API 말고 GraphQL, 너 혹시 뭐 돼..?!

GraphQL(그래프큐엘, 이하 그큐엘)은 API를 만들 때 사용할 수 있는 쿼리 언어입니다. 페이스북 팀에서 개발한 것으로, 클라이언트 쪽 데이터를 다른 시각으로 보기 시작하면서 그큐엘을 만들기 시작했습니다.

1-1. 그 유명한 REST API, 뭐가 문제였을까?

REST 사용에서는 크게 두가지 성능 문제가 있습니다.

1. OverFetching: 필요하지 않은 데이터를 너무 많이 받아오는 문제 ⇒ 네트워크 낭비
2. UndefFetching: 필요한 데이터가 한 요청에 오지 않는 것 ⇒ 너무 많은 요청을 보낼수도!

필요한 시기에 필요한 데이터만 주고받을 수 있도록 그큐엘이 개발된 것입니다..!

예시

다음과 같은 상품 리스트를 보여주는 페이지를 만든다고 가정해봅시다! 아래 사진은 색과 분위기로 향수를 검색할 수 있게 해주는 서비스 컬퓸의 일부를 캡쳐한 것입니다. (제가 웹 개발자로 참여했습니다 ㅎㅎ)

그런데 상품 하나가 가진 데이터는 무궁무진합니다.. 브랜드명, 상품명, 상품 이미지, 용량, 가격, 향의 묘사 등등!

그런데, 상품 리스트만 보면 되는 페이지에서 제조일과 재고 수까지 모두 받는 것은 너무 낭비라는 생각이 들지 않나유!? (이게 바로 OverFetching)

마찬가지로 아래와 같은 페이지를 만들때는 모두 필요한 정보인데 말이죠! 정보가 하나라도 누락되면 안되겠네요..! (이게 바로 UndefFetching)

1-2. 그큐엘, 그래서 뭐가 좋은데?

그큐엘은 유연한 쿼리를 가진다는 것이 가장 큰 장점이라고 생각해요!

부하완화용 쿼리언어로, 질의를 위해 존재하는 언어입니다. 그렇기 때문에 하나의 엔드포인트만 정의되어있어도 원하는 형태로 바꿔가며 질의하기 좋습니다!

예를 들어, 향수의 목록을 보여줄 때는 대표이미지, 이름, 브랜드명만 요청하여 데이터를 주고 받고, 향수의 상세정보를 보여줄 때는 그 때 필요한 정보를 모두 보내거나 받을 수 있습니다. 위에서 언급한 overFetching과 underFetching의 문제를 개선할 수 있게 된 것이죠! 대박!

2. 타입 시스템

GraphQL(그래프 큐엘, 이하 그큐엘)은 typed language입니다. 그큐엘의 타입시스템을 알아야 클라와 서버를 연결해주는 스키마를 정의할 수 있습니다.

그큐엘 쿼리의 형태가 결과와 거의 일치하기 때문에 서버를 잘 모르더라도 쿼리의 반환 내용을 예측할 수 있습니다. 그래두 우리가 요청할 수 있는 데이터에 대한 정확한 설명을 역시 필수적이겠죠! ㅎㅎ

그큐엘은 대부분 모든 언어에서 사용될 수 있습니다. 특정 프로그래밍 언어의 syntax에 의존하지 않기 때문에 독자적이고 단순한 언어(“GraphQL Schema Language[그큐엘 스키마 언어]”)로 정의할 수 있습니다.

Scalar	단일 값 저장합니다.
Enum	미리 지정된 옵션의 리스트로부터 유저가 설정할 수 있는 상황을 지정합니다.
Object	어떤 값이 fetch될 수 있는지를 보여줍니다.
Query	다른 특정 타입에의 Entry point 타입입니다.
Mutation	데이터 변경을 위한 Entry point입니다.

이렇게만 봐서는 뭐라는지 모르겠네요.. 제대로 톺아봅시다!

2-1. Scalar Type

스칼라타입은 원시 타입으로, 우리가 흔히 알고 있는 타입과 매우 유사합니다. 기본적으로 그큐엘에서 제공하는 타입은 다음과 같습니다.

Int	32 bit 정수
Float	부호가 있는 소수점 값
String	UTF-8 문자 시퀀스
Boolean	True / False
ID	객체를 가져오기 위한 고유 식별자 또는 캐시의 key로 자주 사용

Int, Float, String, Boolean은 우리가 익히 알고 있는 타입으로 이해하면 되고, ID의 경우 고유 식별자를 위한 타입이라고 생각하시면 됩니다.

2-2. Enum Type

Enum 타입은 스칼라 타입과 닮아있습니다. Enum은 값이 지정된 옵션 목록에서 가져와야 하는 상황에서 유용합니다.

국내 최대 규모의 IT 벤처 창업 동아리 The SOPT의 파트를 예시로 들어보겠습니다! 30기를 기준으로 SOPT에는 기획, 디자인, 서버, 웹, iOS, 안드로이드 파트만이 존재합니다. RAMEN_PART 같은 이상한 파트가 포함되면 안된다는 점에서 enum type으로 제한하면 좋겠죠?!

enum SoptParts {
	PLAN,
  	DESIGN,
	SERVER,
	WEB,
	iOS,
	ANDROID,
}

2-3. Object Type

객체 타입은 스키마와 그룹화된 필드를 표현할 때 가장 흔하게 사용되는 타입입니다. 객체 유형 내의 각 필드는 다른 유형에 중첩되어 사용될 수 있습니다. 즉, 객체 유형은 스칼라나 객체 유형으로 구성됩니다.

그큐엘 스키마의 대부분의 기본 컴포넌트는 객체 타입으로, 서비스에서 fetch할 수 있는 객체의 종류를 나타냅니다.

가령, 그큐엘 스터디원들의 타입을 지정하면 다음과 같습니다.

type GqlMember {
	memberId: ID,
	name: String,
	latestSopt: Int,
	part: SoptParts,
	isOnDiet: Boolean,
}

3. 이것도 알아야해요!

타입이라기엔 약간 애매하고, 위에서 언급하지는 않았지만, 추가로 알아야하는 내용이 있습니다.

3-1. Non-Nullable Type

그큐엘의 타입 지정에서 요상한 느낌표!가 있는 것을 보신 적이 있을거에요! 느낌표는 해당 타입이 Null값이 될 수 없음을 의미합니다.

가령, 고유 식별자인 id가 있다면, null값이 되면 안되겠죠? 그리고 꼭 필요한 정보(가령, 이름, 파트 등)도 Non-Nullable로 지정해두면 좋습니다. 아까 그큐엘 멤버 타입을 수정해보면 다음과 같습니다.

type GqlMember {
	memberId: ID!,
	name: String!,
	// 고인물들에게는 민감한 정보일 수 있으니 최근 활동 기수는 null이 될 수 있게!
	latestSopt: Int,
	part: SoptParts!,
	isOnDiet: Boolean,
}

3-2. List Type

배열을 표현해야하는 경우도 있겠죠? 그큐엘에서 리스트를 표현하는 방법은 매우 직관적입니다.
객체, 스칼라, Enum 타입을 []로 감싸면됩니다. 참 쉽죠잉?

type GqlMemberList {
	memberList: [GqlMember],
}

3-3. ✋ 여기서 잠깐 문제!

다음의 빈칸을 채워보세요!

	null	[ ]	[ ..., null, ... ]
[String]
[String!]
[String]!
[String!]!

이 문제는 인프런 얄팍한 GraphQL과 Apollo 강의에서 추출했습니다.
정답이 궁금하신 분들은 강의를 수강해보시는 것을 추천!!

4. Query Type

query와 mutation은 스키마에서 특별하게 사용됩니다.

schema {
  query: Query
  mutation: Mutation
}

그큐엘에서의 Query는 데이터 fetch에 사용됩니다. REST-API의 GET 요청하는 것과 닮아있습니다.
다만 조금 더 심플하게 하기 위해, 클라이언트에서 서버로 Query type의 요청을 보냅니다. 그큐엘은 쿼리를 정의하기 위해 Schema Definition Language(SDL: 스키마 정의 언어)을 사용합니다.

type Query {
	member: GqlMember
}

5. Mutation Type

Mutation은 데이터의 생성(create), 수정(update), 삭제(delete)를 위한 오퍼레이션입니다. REST API에서의 PUT, POST, PATCH, DELETE와 유사합니다. query 타입은 데이터를 읽기 위한 entry point를 정의하는데, mutation의 경우 데이터 수정을 위한 entry point를 정의합니다.

어느 것이든 이름은 언제나 중요하지만, 개인적으로는 이 부분에서 이름을 잘 짓는 것이 중요하겠다는 생각을 했습니다.

6. Query & Mutation 예시 맛보기!

그래프큐엘을 공부하는 SOPT 스터디원들의 정보를 저장할 수 있는 그큐엘을 만들어보겠습니다.

스터디에 들어오기 위해서 필요한 것은 이름과 소속파트입니다. SOPT 내 스터디라서 소속파트가 불명확하다면 쉽게 들어오기는 힘듭니다.ㅠ 동명이인이 있을 수도 있으니, 스터디에 소속된 후에는 자신만의 고유한 번호를 부여합니다. 따라서 데이터베이스에 저장될 정보는 다음 내용을 필수적으로 포함합니다.

input NewGqlMember {
	id: ID!,
	name: String!,
	part: SoptParts!,
}

령이라는 새로운 멤버가 스터디에 들어오기로 했습니다! 이름과 소속파트를 적어서 api를 요청하려고 했는데, 데이터베이스에 저장될 id값이 없네요.. 새로운 멤버를 추가할 때 사용할 타입이 필요하니 input 타입을 생성해줍니다.

input NewGqlMember {
	name: String!,
	part: SoptParts!,
}

6-1. ✨ [CREATE] 멤버 추가 또는 생성

이제 고유 id를 미리 부여받지 않아도, 이름과 파트만 명확하면 우리 스터디에 들어올 수 있도록 했습니다! 이제 멤버 추가를 위한 Mutation을 지정해보면 다음과 같습니다.

type Mutation {
	addGqlMember(newInput: NewGqlMember): GqlMember,
}

arguments:
그큐엘의 객체 타입은 모두 arguments를 가질 수 있습니다. 필수값이 될 수도 있고, 옵셔널이 될 수도 있어 default값을 정하는 것도 가능합니다.

type Person {
	id: ID!
	name: String!
	length(unit: LengthUnit = METER): Float
}

해당 쿼리를 사용할 때는 NewGqlMember에 맞는 형식으로 이름과 파트를 가진 내용을 전달주면, 적절한 id값을 만들어 GqlMember에 맞는 형식으로 저장됩니다. 그리고 새로 만들어진 id를 반환합니다! 요청의 모양은 다음과 같겠쥬!

mutation {
	addGqlMember(newInput: {
		name: "ryeongE"
		part: WEB
	}) {
		id
	}
}

6-2. ✏️ [UPDATE || DELETE] 스터디원 정보 수정 또는 삭제

그런데, 갑자기 다이어트에 돌입한다거나, 소속 파트를 바꾼다거나 하는 등의 일이 생긴다면 수정을 해야하고, 그큐엘 어렵다고 쫄아서 도망가는 사람을 위해 삭제 기능도 있어야합니다. 만들어볼까유?

수정을 위해서는 id값으로 데이터를 식별하고 수정할 내용을 담습니다. 그리고 잘 수정되었음을 보여주는 결과를 반환해주어야합니다.

삭제를 위해서는 id값으로 데이터를 식별하고 삭제 후 잘 삭제되었음을 알리는 메시지를 반환해주어야합니다.

type Mutation {
	addGqlMember(newInput: NewGqlMember): GqlMember,
	updateGqlMember(id: ID!, modified: GqlMember): GqlMember,
	deleteX(id: ID!): String, // 도망가는 사람은 멤버가 아닌 X다!!
}

아 타입을 이렇게 공부해서는 뭔가 붕-뜬 느낌이죠? 다음 글(클릭)에서 예시를 들어서 잘 설명해줄테니 기다리라굿 0_<⭐

---

참고

그래프큐엘 공식문서 - 타입 시스템텍스트