GraphQL with Rails — REST를 넘어서

전통적인 REST API는 여전히 강력하지만, 프론트엔드가 복잡해지고 데이터 요구가 다양해질수록 한계가 드러납니다.
이제는 하나의 요청으로 필요한 데이터만 정확하게 가져오는 GraphQL이 주목받고 있죠.
Rails에서도 graphql-ruby를 통해 쉽게 GraphQL 서버를 구축할 수 있습니다.

이번 글에서는 Rails에 GraphQL을 적용해보고, REST와의 차이점과 실전 구현 예시까지 소개할게요.

---

🌐 GraphQL이란?

GraphQL은 Facebook이 개발한 데이터 질의 언어로, “필요한 데이터를 정확하게 요청”할 수 있게 해줍니다.

• 하나의 요청으로 다양한 리소스를 조회할 수 있음
• 오버페칭(over-fetching), 언더페칭(under-fetching) 문제 해결
• 엄격한 타입 시스템 기반으로 자동 문서화 및 검증

---

🚀 1. Rails에 GraphQL 설치

$ bundle add graphql
$ bin/rails generate graphql:install

이 명령으로 GraphQLController, app/graphql 디렉토리, 그리고 /graphql 엔드포인트가 생성됩니다.

---

📄 2. 타입 정의 및 쿼리 만들기

Post 타입 만들기

$ bin/rails generate graphql:object Post

# app/graphql/types/post_type.rb
module Types
  class PostType < Types::BaseObject
    field :id, ID, null: false
    field :title, String, null: false
    field :content, String, null: true
  end
end

쿼리 정의하기

# app/graphql/types/query_type.rb
field :posts, [Types::PostType], null: false

def posts
  Post.all
end

---

🧪 3. GraphiQL로 테스트하기

개발 모드에서는 http://localhost:3000/graphql에서 GraphiQL IDE를 사용할 수 있어요.

예시 쿼리

query {
  posts {
    id
    title
  }
}

REST에서는 /posts로 호출하고, 응답 전체를 받아야 했지만
GraphQL에서는 원하는 필드만 명시적으로 지정해서 받습니다.

---

🆚 REST와 GraphQL 비교

기준	REST	GraphQL
요청 구조	엔드포인트별 고정	하나의 /graphql 엔드포인트
데이터 양 조절	불가능 (모든 필드 수신)	가능 (필드 선택 가능)
네트워크 요청 수	여러 번 필요	한 번에 여러 리소스 요청 가능
버전 관리	v1, v2로 API 분리	필드 단위 변경 가능

---

🧩 4. Mutation 예시 (데이터 생성)

$ bin/rails generate graphql:mutation CreatePost

# app/graphql/mutations/create_post.rb
module Mutations
  class CreatePost < BaseMutation
    argument :title, String, required: true
    argument :content, String, required: false

    type Types::PostType

    def resolve(title:, content:)
      Post.create(title: title, content: content)
    end
  end
end

GraphQL 쿼리

mutation {
  createPost(input: { title: "GraphQL", content: "It's awesome" }) {
    id
    title
  }
}

---

📦 실전 팁

• graphql-ruby는 batch loading, pagination도 지원
• relay 지원도 가능
• API 문서 없이도 스키마 기반으로 자동 문서화됨

---

🎯 마치며

GraphQL은 초기에는 약간 생소할 수 있지만, 일단 익숙해지면 매우 강력한 도구가 됩니다.
특히 프론트엔드와 협업할 때 유연성과 효율이 극대화되죠.
Rails에서도 공식적으로 강력한 지원을 하고 있으니, 꼭 한 번 실험적으로라도 도입해보세요.