본문으로 건너뛰기
· backend · 6분 읽기

Go GraphQL 스택: ent + gqlgen + entgql로 코드 생성 중심 API 만들기

GraphQL API를 Go로 만들 때 가장 귀찮은 건 반복 코드다. DB 스키마 정의하고, GraphQL 스키마 정의하고, resolver 작성하고, 페이지네이션 로직 구현하고. 타입 하나 추가할 때마다 네 곳을 고쳐야 한다.

이 글은 GraphQL을 쓰기로 결정한 팀을 위한 구현 가이드다. 아직 GraphQL이 필요한지 판단 중이라면 GraphQL vs REST 2026을 먼저 보라. 복수 클라이언트, 심각한 over/under-fetching, 복잡한 중첩 데이터 없이 REST로 충분한 경우가 많다.

ent, gqlgen, entgql 조합은 이 문제를 코드 생성으로 해결한다. ent 스키마에서 공통 타입과 접근 코드를 생성하고, 공개 API 계약과 업무 resolver는 별도로 구현한다. 각 도구의 역할과 연결 방식, 그리고 Relay Connection 기반 페이지네이션까지 정리해봤다.

세 가지 도구, 각자의 역할

ent: 스키마가 곧 코드

ent는 Go용 엔티티 프레임워크다. 스키마를 Go 코드로 정의하고, 거기서 타입 안전한 CRUD 코드를 생성한다.

go
// ent/schema/todo.go
package schema

import (
    "time"

    "entgo.io/ent"
    "entgo.io/ent/schema/edge"
    "entgo.io/ent/schema/field"
)

type Todo struct {
    ent.Schema
}

func (Todo) Fields() []ent.Field {
    return []ent.Field{
        field.Text("text").NotEmpty(),
        field.Time("created_at").Default(time.Now).Immutable(),
        field.Enum("status").
            Values("IN_PROGRESS", "COMPLETED").
            Default("IN_PROGRESS"),
        field.Int("priority").Default(0),
    }
}

func (Todo) Edges() []ent.Edge {
    return []ent.Edge{
        edge.To("children", Todo.Type).
            From("parent").
            Unique(),
    }
}

go generate를 실행하면 ent/ 디렉토리에 타입 안전한 클라이언트 코드가 생성된다. client.Todo.Create().SetText("할 일").Save(ctx) 같은 빌더 패턴으로 DB를 조작한다. SQL을 직접 쓸 일이 거의 없다.

핵심은 스키마가 단일 진실 공급원(Single Source of Truth)이라는 점이다. 필드 타입, 유효성 검사, 관계. 모든 게 이 스키마 파일에서 나온다.

gqlgen: 스키마 퍼스트 GraphQL

gqlgen은 Go의 GraphQL 서버 라이브러리다. graphql-go나 다른 대안도 있지만, gqlgen이 Go 생태계에서 사실상 표준이다.

핵심 특징:

  • 스키마 퍼스트. .graphql 파일에 스키마를 먼저 정의하고, 거기서 Go 코드를 생성한다
  • 타입 안전. 생성된 resolver 인터페이스가 컴파일 타임에 타입을 보장한다
  • autobind. Go 타입과 GraphQL 타입이 이름이 같으면 자동으로 바인딩된다
yaml
# gqlgen.yml
schema:
  - ent.graphql
  - todo.graphql

resolver:
  layout: follow-schema
  dir: .

autobind:
  - myapp/ent
  - myapp/ent/todo

models:
  ID:
    model:
      - github.com/99designs/gqlgen/graphql.IntID
  Node:
    model:
      - myapp/ent.Noder

entgql: 둘을 잇는 브릿지

entgql은 ent와 gqlgen을 연결하는 도구다. ent 스키마에 어노테이션을 붙이면:

  1. ent 스키마에서 GraphQL 스키마를 자동 생성한다
  2. Relay Node 인터페이스를 구현한다
  3. Relay Connection (cursor-based pagination)을 자동 생성한다
  4. 필드 컬렉션으로 N+1 문제를 해결한다
  5. 트랜잭셔널 뮤테이션을 지원한다

한마디로, ent 스키마를 정의하면 GraphQL API 기본 구조가 자동 생성된다.

실전: 프로젝트 셋업

1단계: ent 스키마에 GraphQL 어노테이션 추가

go
// ent/schema/todo.go
func (Todo) Annotations() []schema.Annotation {
    return []schema.Annotation{
        entgql.RelayConnection(),
        entgql.QueryField(),
        entgql.Mutations(entgql.MutationCreate()),
    }
}

entgql.RelayConnection()이 핵심이다. 이 한 줄로 TodoConnection, TodoEdge, PageInfo 타입이 자동 생성된다.

entgql.QueryField()는 Query 필드를 생성한다. entgql.Mutations(entgql.MutationCreate())는 생성용 input 타입과 SetInput 지원을 만들며, mutation 필드 자체는 별도로 선언한다. 다음 예제에는 entgo.io/ent/schema와 entgo.io/contrib/entgql import가 필요하다.

graphql
# todo.graphql
type Mutation {
  createTodo(input: CreateTodoInput!): Todo!
}

2단계: entgql 확장 설정

go
// ent/entc.go
//go:build ignore

package main

import (
    "log"

    "entgo.io/contrib/entgql"
    "entgo.io/ent/entc"
    "entgo.io/ent/entc/gen"
)

func main() {
    ex, err := entgql.NewExtension(
        entgql.WithSchemaGenerator(),
        entgql.WithSchemaPath("ent.graphql"),
        entgql.WithConfigPath("gqlgen.yml"),
    )
    if err != nil {
        log.Fatalf("creating entgql extension: %v", err)
    }
    if err := entc.Generate("./ent/schema", &gen.Config{},
        entc.Extensions(ex),
    ); err != nil {
        log.Fatalf("running ent codegen: %v", err)
    }
}

WithSchemaGenerator()가 ent 스키마를 읽어서 ent.graphql 파일을 생성한다. WithConfigPath로 gqlgen 설정 파일 위치를 알려주면, 코드 생성 시 gqlgen과의 타입 바인딩도 자동으로 처리된다.

3단계: 코드 생성 실행

go
// generate.go
package myapp

//go:generate go run -mod=mod ./ent/entc.go
//go:generate go run -mod=mod github.com/99designs/gqlgen
bash
go generate .

이 한 번의 명령으로:

  • ent가 DB 클라이언트 코드를 생성하고
  • entgql이 GraphQL 스키마(ent.graphql)를 생성하고
  • gqlgen이 resolver 인터페이스와 타입 바인딩 코드를 생성한다

4단계: Resolver 구현

다음은 핵심 resolver 본문이다. 앞의 설정 외에 모듈 초기화, 도구 의존성 버전 고정, 서버와 Resolver의 client 필드 설정이 필요하다. 정렬 인자는 아래의 OrderField 어노테이션을 적용한 뒤 생성되는 계약을 기준으로 한다.

go
// ent.resolvers.go
func (r *queryResolver) Todos(
    ctx context.Context,
    after *ent.Cursor, first *int,
    before *ent.Cursor, last *int,
    orderBy *ent.TodoOrder,
) (*ent.TodoConnection, error) {
    return r.client.Todo.Query().
        Paginate(ctx, after, first, before, last,
            ent.WithTodoOrder(orderBy),
        )
}

페이지네이션, 정렬, 커서 처리. 전부 Paginate 메서드 하나에 담겨 있다. 직접 구현했다면 수백 줄은 됐을 로직이다.

뮤테이션도 마찬가지:

go
func (r *mutationResolver) CreateTodo(
    ctx context.Context, input ent.CreateTodoInput,
) (*ent.Todo, error) {
    return r.client.Todo.Create().SetInput(input).Save(ctx)
}

SetInput이 GraphQL input 타입의 모든 필드를 ent 빌더에 자동으로 매핑한다.

Relay Connection: 왜 cursor인가

offset의 한계

전통적인 페이지네이션은 LIMIT 20 OFFSET 40 같은 방식이다. 간단하지만 문제가 있다.

  • 데이터 변경에 취약하다. 2페이지를 보는 도중 새 데이터가 추가되면 3페이지에서 이전에 본 항목이 다시 나온다
  • 페이지가 뒤로 갈수록 느려진다. OFFSET 10000이면 DB가 앞의 10000행을 읽고 버린 뒤 결과를 돌려준다
  • 무한 스크롤에 부적합하다. 모바일 앱이나 실시간 피드에서는 “몇 페이지”라는 개념 자체가 맞지 않다

cursor 기반 페이지네이션

Relay Connection 스펙은 cursor를 기준으로 “이 지점 이후의 N개”를 요청하는 방식이다.

graphql
query {
  todos(first: 10, after: "opaqueCursor", orderBy: {direction: DESC, field: CREATED_AT}) {
    edges {
      node {
        id
        text
        status
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

각 edge는 node(실제 데이터)와 cursor(해당 위치의 불투명 토큰)를 가진다. pageInfo는 다음/이전 페이지 존재 여부와 경계 커서를 알려준다.

ID 오름차순이면 WHERE id > cursor_id ORDER BY id LIMIT 10 같은 keyset 조건을 사용할 수 있다. 다른 필드로 정렬한다면 정렬 값과 고유 키의 복합 경계를 사용하고 이에 맞는 인덱스를 검토한다. Relay 스펙 자체가 DB 구현이나 keyset 사용을 강제하지는 않는다.

OffsetCursor
구현 난이도쉽다상대적으로 복잡하다
데이터 변경 시위치 이동으로 중복/누락 가능정렬 키 변경 등에서는 중복/누락 가능
대량 데이터큰 offset의 건너뛰기 비용적절한 인덱스로 건너뛰기 비용 절감
특정 페이지 이동가능불가 (순차 탐색만)
무한 스크롤부적합적합

entgql이 자동 생성하는 것들

ent 스키마에 entgql.RelayConnection()을 붙이면, 다음이 자동으로 만들어진다:

GraphQL 타입:

graphql
type TodoConnection {
  edges: [TodoEdge]
  pageInfo: PageInfo!
  totalCount: Int!
}

type TodoEdge {
  node: Todo
  cursor: Cursor!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: Cursor
  endCursor: Cursor
}

Go 코드:

  • ent.TodoConnection 구조체
  • ent.TodoEdge 구조체
  • ent.Cursor 타입
  • Todo.Query().Paginate() 메서드
  • 정렬 옵션 (ent.WithTodoOrder)

직접 구현하면 타입 정의, 커서 인코딩/디코딩, 쿼리 빌딩, 정렬 처리 등을 전부 작성해야 한다. entgql은 이걸 어노테이션 한 줄로 끝낸다.

정렬 필드 추가

정렬 가능한 필드는 어노테이션으로 지정한다:

go
func (Todo) Fields() []ent.Field {
    return []ent.Field{
        field.Text("text").NotEmpty().
            Annotations(entgql.OrderField("TEXT")),
        field.Time("created_at").Default(time.Now).Immutable().
            Annotations(entgql.OrderField("CREATED_AT")),
        field.Enum("status").Values("IN_PROGRESS", "COMPLETED").
            Annotations(entgql.OrderField("STATUS")),
        field.Int("priority").Default(0).
            Annotations(entgql.OrderField("PRIORITY")),
    }
}

이렇게 하면 orderBy: {direction: DESC, field: PRIORITY} 같은 정렬이 바로 동작한다. 필터와 정렬을 함께 만족하는 인덱스를 검토하고 실행 계획을 확인한다. 인덱스 유무만으로 모든 쿼리의 실행 방식을 단정할 수는 없다.

N+1 문제 해결

GraphQL의 고질적 문제인 N+1을 entgql은 필드 컬렉션으로 완화한다. 클라이언트가 요청한 필드를 분석해서, 필요한 edge를 자동으로 eager-loading한다.

graphql
query {
  todos(first: 100) {
    edges {
      node {
        text
        children {
          text
        }
      }
    }
  }
}

이 쿼리를 실행하면 entgql이 내부적으로 WithChildren() eager-load를 추가한다. 단순한 목록과 한 단계 관계 조회에서는 목록 조회와 children 일괄 조회로 구성할 수 있다. totalCount, 별칭·인자가 다른 관계와 커스텀 resolver에 따라 쿼리 수가 달라지므로 로그로 확인한다. 1-depth edge에서는 DataLoader 없이 N+1이 해결된다. 다만 깊은 중첩 관계에서는 여전히 추가 최적화가 필요할 수 있다.

트랜잭셔널 뮤테이션

entgql은 GraphQL 뮤테이션을 자동으로 트랜잭션으로 감쌀 수 있다.

go
srv := handler.NewDefaultServer(todo.NewSchema(client))
srv.Use(entgql.Transactioner{TxOpener: client})

Transactioner를 적용한 mutation에서는 아래처럼 context의 트랜잭션 클라이언트를 사용해야 한다. 별도의 전역 client나 외부 API 호출은 이 DB 트랜잭션에 포함되지 않는다. 오류 발생 시 해당 DB 변경을 롤백하는 범위로 이해해야 한다.

go
func (r *mutationResolver) CreateTodo(ctx context.Context, input ent.CreateTodoInput) (*ent.Todo, error) {
    client := ent.FromContext(ctx)
    return client.Todo.Create().SetInput(input).Save(ctx)
}

ent.FromContext(ctx)로 트랜잭션 클라이언트를 꺼내서 쓰면 된다.

코드 생성의 트레이드오프

장점단점
보일러플레이트페이지네이션, CRUD, 타입 매핑 자동 생성생성 코드가 수천 줄. 이해하려면 시간 투자 필요
타입 안전성컴파일 타임에 잡히는 오류가 많다없음
일관성모든 엔티티가 같은 패턴을 따른다특수한 케이스에서 패턴을 깨기 어렵다
스키마 동기화선언한 타입 매핑을 재생성으로 동기화ent 스키마에 의존적. ent를 벗어나면 수동 관리
러닝커브패턴을 익히면 생산성이 높다ent + gqlgen + entgql 세 도구를 동시에 이해해야 한다
디버깅없음생성 코드 안에서 버그가 터지면 추적이 어렵다
커스터마이징없음기본 패턴에서 벗어나는 요구사항은 우회가 필요하다

코드 생성이 지원하는 패턴 밖의 업무 로직은 직접 구현해야 한다. ent + gqlgen + entgql 조합은 CRUD 중심의 API에서는 생산성이 압도적이다. 하지만 복잡한 비즈니스 로직이 resolver에 많이 들어가거나, GraphQL 스키마를 세밀하게 제어해야 하는 경우에는 생성 코드 밖에서 직접 구현해야 하는 부분이 늘어난다.

프로젝트 초기에 이 스택을 선택할 때의 기준:

  • 엔티티가 10개 이상이고 CRUD가 대부분이다 → 강력 추천
  • 복잡한 커스텀 resolver가 많다 → gqlgen만 쓰는 게 나을 수 있다
  • 팀이 ent에 익숙하지 않다 → 러닝커브 감안하고 시작하거나, 작은 서비스에서 먼저 시도

전체 흐름 요약

ent 스키마 정의
    ↓ go generate
ent 클라이언트 코드 생성 (CRUD, 마이그레이션)
    ↓ entgql
GraphQL 스키마 자동 생성 (ent.graphql)
    ↓ gqlgen
Resolver 인터페이스 + 타입 바인딩 생성
    ↓
Resolver 구현 (대부분 1~3줄)

스키마 하나가 DB부터 API까지 전 계층에 적용된다. 각 도구는 자기 영역만 책임지고, 어노테이션으로 연결된다. 모듈 간 경계가 명확하기 때문에 한 도구를 교체해도 다른 도구에 미치는 영향이 작다.

참고 자료

공유하기 X LinkedIn

관련 글