Go GraphQL DataLoader 직접 구현하기
배경
GraphQL을 쓰다 보면 거의 반드시 만나는 게 N+1 쿼리다. 목록을 가져온 뒤 각 항목의 자식 자원을 같이 응답하려고 하면, 부모 N개가 있을 때 자식 조회가 N번 발생한다.
query {
users(first: 50) {
edges {
node {
id
name
badges { # 사용자별로 1번씩, 총 50번
name
tier
}
}
}
}
}GraphQL 서버는 부모 자원에 대한 자식 필드 리졸버를 독립적으로 호출하기 때문에, 자식 리졸버에서 그냥 DB 쿼리를 부르면 50번 도는 게 자연스럽다.
DataLoader는 이 문제를 해결하는 패턴이다. “같은 요청 안에서 같은 종류의 자식 조회 호출을 모아서 한 번에 batch 처리하라” 는 게 핵심.
이 글에서는 외부 dataloader 라이브러리 없이 표준 라이브러리(sync, time, context)만으로 dataloader를 직접 짠다. 동작 원리를 이해하면 라이브러리를 가져다 쓸 때도 어디를 조심해야 할지 보인다.
요구사항
만들 dataloader는 이렇게 동작해야 한다.
- Batch: 짧은 시간 동안(예: 1ms) 들어온 호출을 모아서 한 번에 fetch.
- Dedup: 같은 요청에서 같은 키로 여러 번 호출되면 한 번만 fetch.
- Cache: 같은 요청 안에서 같은 키 재호출은 캐시 히트.
- Request scope: 요청 간 캐시를 공유하지 않는다. 객체는 참조와 진행 중인 타이머·fetch가 해제된 뒤 GC 대상이 된다.
- Cancellation:
ctx.Done()이 닫히면 호출자가 즉시 빠져나올 수 있어야 한다. - Race-free: 동시에 여러 고루틴이
Load해도 안전.
구조
핵심 자료구조는 세 가지.
type LoaderConfig[K comparable, V any] struct {
MaxBatch int
Wait time.Duration
Fetch func(context.Context, []K) (map[K]V, error)
}
type Loader[K comparable, V any] struct {
config LoaderConfig[K, V]
ctx context.Context // HTTP 요청 수명. 개별 Load의 취소와 분리한다.
cache map[K]*request[V] // 완료 결과와 실행 중인 조회를 함께 공유한다.
batch *batch[K, V]
mu sync.Mutex
}
type batch[K comparable, V any] struct {
requests map[K]*request[V]
}
type request[V any] struct {
result V
err error
done chan struct{}
}
func NewLoader[K comparable, V any](ctx context.Context, cfg LoaderConfig[K, V]) *Loader[K, V] {
if cfg.MaxBatch < 1 || cfg.Wait < 0 || cfg.Fetch == nil {
panic("invalid loader config")
}
return &Loader[K, V]{
ctx: ctx, config: cfg, cache: make(map[K]*request[V]),
}
}cache는 키별 완료 신호를 저장해 배치가 실행 중이어도 같은 조회를 공유한다.batch.requests는 다음 fetch에 전달할 키와 대기 결과를 담는다.- 결과를 쓴 뒤
done을 닫으면 대기자가 결과를 읽을 수 있다.
Load — 호출 측 진입점
Load는 (1) 캐시 확인, (2) 배치에 등록, (3) 결과 대기를 한다.
func (l *Loader[K, V]) Load(ctx context.Context, key K) (V, error) {
var zero V
if err := ctx.Err(); err != nil { return zero, err }
if err := l.ctx.Err(); err != nil { return zero, err }
l.mu.Lock()
req, exists := l.cache[key]
if !exists {
req = &request[V]{done: make(chan struct{})}
l.cache[key] = req
if l.batch == nil {
l.batch = &batch[K, V]{requests: make(map[K]*request[V])}
b := l.batch
time.AfterFunc(l.config.Wait, func() { l.dispatch(b) })
}
l.batch.requests[key] = req
}
b := l.batch
shouldDispatch := b != nil && len(b.requests) >= l.config.MaxBatch
l.mu.Unlock()
if shouldDispatch { go l.dispatch(b) }
select {
case <-req.done:
return req.result, req.err
case <-ctx.Done():
return zero, ctx.Err()
case <-l.ctx.Done():
return zero, l.ctx.Err()
}
}세 가지 디테일.
time.AfterFunc(Wait, dispatch): 첫 키가 들어온 시점부터 타이머를 시작한다. 이미 배치가 있으면 새로 만들지 않는다.- size-based dispatch: 배치가 기준 크기(예: 100개)에 도달하면 비동기 실행을 예약한다. lock을 다시 잡기 전 키가 더 들어올 수 있으므로 이 예제의 MaxBatch는 엄격한 상한은 아니다. 큰 응답에서는 타이머만 기다리면 너무 느리기 때문에 둘 다 둔다.
select로 취소 대기 지원:req.done만 기다리면 요청이 취소돼도 fetch가 끝날 때까지 묶여 있다. ctx와 함께 select 하면 fetch 완료를 기다리지 않고 반환할 수 있다. 완료와 취소가 동시에 준비되면 select는 취소를 우선하지 않는다.
dispatch — 한 번만 실행되어야 한다
타이머 만료와 배치 사이즈 도달이 동시에 발생하면 둘 다 dispatch를 호출할 수 있다. 두 번 실행되면 같은 fetch가 중복 호출된다.
func (l *Loader[K, V]) dispatch(b *batch[K, V]) {
l.mu.Lock()
if l.batch != b {
l.mu.Unlock()
return
}
l.batch = nil
keys := make([]K, 0, len(b.requests))
for k := range b.requests { keys = append(keys, k) }
l.mu.Unlock()
results, err := l.config.Fetch(l.ctx, keys)
l.mu.Lock()
defer l.mu.Unlock()
for key, req := range b.requests {
req.result = results[key]
req.err = err
if err != nil { delete(l.cache, key) }
close(req.done)
}
}핵심은 두 가지.
l.batch != b가드: 이미 dispatch된 배치는 다시 처리하지 않는다.- lock-fetch-lock 패턴: fetch는 외부 호출이므로 lock을 풀고 한다. lock을 들고 fetch하면 다른 Load 호출이 모두 막힌다.
Request scope — 미들웨어로 주입
dataloader는 요청마다 새로 만든다. 싱글턴으로 두면 요청 간 캐시가 섞여 stale 데이터가 남거나, 메모리가 계속 증가한다.
type contextKey string
const loaderKey contextKey = "badge-loader"
func Middleware(svc BadgeService, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
loader := NewLoader(r.Context(), LoaderConfig[int, []Badge]{
MaxBatch: 100,
Wait: time.Millisecond,
Fetch: svc.GetByUserIDs,
})
ctx := context.WithValue(r.Context(), loaderKey, loader)
next.ServeHTTP(w, r.WithContext(ctx))
})
}리졸버에서는 다음과 같이 쓴다.
func (r *userResolver) Badges(ctx context.Context, obj *User) ([]Badge, error) {
loader, ok := ctx.Value(loaderKey).(*Loader[int, []Badge])
if !ok {
// 미들웨어 미부착 — fallback
byID, err := r.svc.GetByUserIDs(ctx, []int{obj.ID})
if err != nil { return nil, err }
return byID[obj.ID], nil
}
return loader.Load(ctx, obj.ID)
}Service 쪽 batch fetch
fetch는 키를 묶어 조회해야 한다. DB 파라미터 제한 등으로 청크를 나눌 수 있지만 키마다 개별 조회하면 N+1 절감 효과가 사라진다.
func (s *badgeService) GetByUserIDs(ctx context.Context, userIDs []int) (map[int][]Badge, error) {
if len(userIDs) == 0 {
return map[int][]Badge{}, nil
}
badges, err := s.repo.ListByUserIDs(ctx, userIDs)
if err != nil {
return nil, err
}
out := make(map[int][]Badge, len(userIDs))
for _, uid := range userIDs {
out[uid] = []Badge{} // 누락 키도 빈 슬라이스 보장
}
for _, b := range badges {
out[b.UserID] = append(out[b.UserID], b)
}
return out, nil
}out[uid] = []Badge{}로 미리 채워두면, 결과에 없는 키는 null 대신 []로 응답된다.
테스트
dataloader는 동시성 코드라 race 테스트가 거의 필수다.
func TestLoader_BatchAndDedup(t *testing.T) {
var fetchCount atomic.Int32
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
loader := NewLoader(ctx, LoaderConfig[int, string]{
MaxBatch: 10,
Wait: time.Minute,
Fetch: func(ctx context.Context, keys []int) (map[int]string, error) {
fetchCount.Add(1)
out := make(map[int]string, len(keys))
for _, k := range keys {
out[k] = fmt.Sprintf("v%d", k)
}
return out, nil
},
})
var wg sync.WaitGroup
for i := range 50 {
wg.Add(1)
go func(k int) {
defer wg.Done()
v, err := loader.Load(ctx, k%10)
if err != nil || v != fmt.Sprintf("v%d", k%10) {
t.Errorf("key=%d err=%v v=%q", k, err, v)
}
}(i)
}
wg.Wait()
if got := fetchCount.Load(); got != 1 {
t.Errorf("fetch should run once, got %d", got)
}
}예제는 서로 다른 키 10개가 모이면 dispatch하므로 짧은 타이머 안에 모든 goroutine이 실행된다고 가정하지 않는다. 실행 중 중복 Load와 호출자 취소도 별도로 테스트해야 한다.
검증 명령은 go test -race -count=20 ./dataloader/...다. 동시성 버그는 한 번 통과한다고 안전한 게 아니라 반복 실행으로 노출 가능성을 높인다.
이 구현은 오류를 캐시하지 않으며, Fetch가 누락한 키는 V의 zero value로 처리한다. 데이터 없음과 오류를 구분해야 한다면 키별 결과 타입을 추가한다. 같은 요청 안에서 mutation 이후 다시 읽을 때는 캐시 무효화도 필요하다. Fetch는 요청 context 취소를 준수해야 하며, panic 복구와 엄격한 배치 상한은 이 예제에서 생략했다.
정리
- 이 구현은 batch + dedup + cache + request-scope를 사용한다. 캐시를 끄는 등 다른 정책도 가능하므로 라이브러리 설정을 확인한다.
- lock 안에서 외부 IO 하지 않기. dispatch에서 fetch는 lock을 풀고 한다.
- dispatch 조건을 확인한다. 크기 조건만으로 기다리면 적은 요청이 끝나지 않을 수 있다. 타이머와 조합하거나 명시적 flush를 제공한다.
- request-scope는 미들웨어로 강제한다. 싱글턴 dataloader는 사고의 원천이다.
- fallback 경로를 만들어둔다. 미들웨어가 안 붙은 환경에서도 죽지 않게.
graph-gophers/dataloader 같은 라이브러리를 가져다 쓰면 위 동작이 잘 정리된 API로 제공된다. 다만 cache 유효 범위, dispatch 트리거 조건, ctx 캔슬 처리 등은 라이브러리마다 디테일이 다르니 한 번은 직접 짜보고 쓰는 걸 권한다.