제가 현재 사용하는 statusline의 출력 예시는 이렇습니다:

1

fable 5 ~/L/M/i/Documents/PKM ⎇ main 24.8k [░░░░░░░░] 2% · ↻3h50m ↑32%  ↻4d9h ↑3% $10.32

한 줄 안에 모델명, 경로, Git 브랜치, 토큰 수, 컨텍스트 사용률, rate limit 남은 시간, 세션 비용까지 담았습니다.

statusline이란?#

Claude Code statusline은 터미널 하단에 고정 표시되는 커스텀 상태 바입니다. Claude Code가 사용자가 지정한 셸 명령을 실행하고, 그 stdout 출력을 그대로 statusline에 렌더링하는 방식으로 동작합니다.

동작 메커니즘#

Claude Code는 스크립트를 실행할 때 stdin으로 현재 세션 상태를 JSON 형태로 전달합니다. 스크립트는 이 JSON을 파싱해 원하는 값을 추출하고, stdout에 출력하면 그 내용이 statusline에 표시됩니다.

갱신 시점:

• 어시스턴트 메시지 수신 후
• /compact 완료 후
• 권한 모드 변경 시
• vim 모드 토글 시

빠른 연속 변경은 300ms 디바운스로 묶어서 한 번만 실행합니다. 스크립트가 아직 실행 중에 새 갱신이 오면 진행 중인 실행을 취소하고 새로 시작합니다.

중요: statusline은 로컬에서 실행됩니다. API 토큰을 전혀 소비하지 않습니다.

stdin으로 전달되는 주요 JSON 필드#

rate_limits는 Claude.ai Pro/Max 구독자에게만 첫 API 응답 이후 제공됩니다. 없을 수 있는 필드는 // empty나 // 0 폴백으로 방어해야 합니다.

설정 방법: 인라인 vs 스크립트 파일#

statusline 설정은 ~/.claude/settings.json의 statusLine 필드로 합니다. 중요한 점은 type은 항상 "command" 하나뿐이라는 것입니다. “직접 작성 모드”와 “스크립트 모드”가 별도로 있는 게 아니라, command 필드에 무엇을 쓰느냐의 차이입니다.

방법 A: 인라인 one-liner#

command에 셸 명령을 직접 적습니다. jq를 활용하면 간단한 표시는 한 줄로 충분합니다.

1
2
3
4
5
6

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '[\"[\", .model.display_name, \"] \", (.context_window.used_percentage // 0 | floor | tostring), \"% context\"] | join(\"\")'"
  }
}

장점: 파일을 따로 만들 필요 없이 바로 시작할 수 있습니다.
단점: 명령이 길어지면 settings.json이 지저분해지고, 색상 처리나 조건 분기를 넣기 어렵습니다.

방법 B: 스크립트 파일#

command에 스크립트 경로를 적고, 로직은 별도 파일에 작성합니다.

1
2
3
4
5
6

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/statusline.sh"
  }
}

스크립트 파일(~/.claude/statusline.sh)을 만들고 실행 권한을 부여합니다:

1

chmod +x ~/.claude/statusline.sh

장점: 로직이 길어도 관리하기 좋고, 색상·조건 분기·여러 섹션을 깔끔하게 구성할 수 있습니다. Git으로 버전 관리도 됩니다. 샘플 JSON으로 독립적인 테스트도 가능합니다.
단점: 파일을 별도로 만들고 관리해야 합니다.

섹션이 8개 이상인 경우라면 스크립트 방식이 거의 유일한 선택지입니다.

/statusline 자동 생성 헬퍼#

자연어로 설명하면 Claude Code가 스크립트를 자동 생성하고 settings.json까지 업데이트해 줍니다:

1

/statusline show model name and context percentage with a progress bar

이것은 별개의 설정 방식이 아니라, 위의 “스크립트 파일 방식”을 자동화해 주는 헬퍼입니다.

내 statusline 구성#

최종 출력 형태#

1

fable 5 ~/L/M/i/Documents/PKM ⎇ main 24.8k [░░░░░░░░] 2% · ↻3h50m ↑32%  ↻4d9h ↑3% $10.32

섹션별 구현 의도#

모델명 축약#

model.id를 sed 정규식으로 claude-sonnet-4-6 → sonnet-4.6 형태로 줄입니다. 패턴 매칭에 실패하면(새 네이밍 등) display_name을 소문자로 변환해 폴백합니다.

1
2
3
4
5
6
7
8
9

abbr=$(echo "$model_id" | sed -E \
  's/claude-([a-z]+)-([0-9]+)-([0-9]+).*/\1-\2.\3/; \
   s/claude-([a-z]+-[a-z]+)-([0-9]+)-([0-9]+).*/\1-\2.\3/')

if [ -z "$abbr" ] || [ "$abbr" = "$model_id" ]; then
  abbr=$(echo "$model_display" | sed -E \
    's/Claude //; s/ ([0-9]+)\.([0-9]+).*/\1.\2/' | \
    tr '[:upper:]' '[:lower:]')
fi

모델명이 길면 statusline이 금방 꽉 차므로 최대한 짧게 유지하는 것이 목표입니다. claude-fable-5처럼 새 네이밍은 폴백 경로를 타서 fable 5로 표시됩니다.

fish shell 스타일 경로 축약#

$HOME을 ~로 치환한 뒤, awk로 마지막 2개 세그먼트만 전체 표시하고 나머지는 첫 글자만 남깁니다.

1
2

~/Library/Mobile Documents/iCloud~md~obsidian/Documents/PKM
→ ~/L/M/i/Documents/PKM

iCloud 볼트처럼 경로가 긴 환경에서 공간을 아끼기 위한 처리입니다. fish shell에서 영감을 받았습니다.

Git 브랜치#

1
2

git_branch=$(git -C "$cwd" -c core.hooksPath=/dev/null \
  symbolic-ref --short HEAD 2>/dev/null)

-c core.hooksPath=/dev/null을 추가해 git 훅 실행을 차단합니다. statusline은 자주 호출되는데, 훅이 실행되면 의도치 않은 부작용이 생길 수 있습니다. detached HEAD 상태면 rev-parse --short HEAD로 커밋 해시를 대신 표시합니다. git 저장소가 아닌 디렉토리라면 섹션 자체를 생략합니다.

토큰 사용량#

입력 + 출력 토큰을 합산해 1,000 이상이면 24.8k처럼 k 단위 소수점 1자리로 포맷합니다.

1
2
3
4
5
6

total_tokens=$(( total_in + total_out ))
if [ "$total_tokens" -ge 1000 ]; then
  token_str=$(awk "BEGIN {printf \"%.1fk\", $total_tokens/1000}")
else
  token_str="${total_tokens}"
fi

컨텍스트 사용률 프로그레스 바#

used_percentage를 8칸 블록 바로 변환합니다. 색상은 사용률 구간별로 다르게 줍니다:

• 0~60%: green [████████]
• 61~80%: yellow
• 81%+: red

1
2
3
4
5
6
7

if [ "$pct_int" -le 60 ]; then
  bar_color="$C_GREEN"
elif [ "$pct_int" -le 80 ]; then
  bar_color="$C_YELLOW"
else
  bar_color="$C_RED"
fi

Rate limit (현재 세션·주간)#

resets_at(Unix epoch)에서 현재 시각을 빼 남은 시간을 ↻3h50m, ↻4d9h 형태로 표시하고, 사용률을 ↑32%로 붙입니다.

1
2
3
4
5
6
7
8

format_remaining() {
  _rem=$(( $1 - $(date +%s) ))
  [ "$_rem" -lt 0 ] && _rem=0
  if   [ "$_rem" -ge 86400 ]; then printf '%dd%dh' $(( _rem/86400 )) $(( _rem%86400/3600 ))
  elif [ "$_rem" -ge 3600  ]; then printf '%dh%02dm' $(( _rem/3600 )) $(( _rem%3600/60 ))
  else                             printf '%dm' $(( _rem/60 ))
  fi
}

사용률 색상은 컨텍스트 바와 동일한 60/80% 기준을 usage_color 함수로 공유해 일관성을 유지합니다. rate_limits 필드 자체가 없을 수 있으므로(API 키 직접 사용 시 등) // empty로 처리하고 필드가 없으면 rate limit 섹션을 통째로 생략합니다.

세션 비용#

cost.total_cost_usd를 소수점 2자리로 포맷해 $10.32 형태로 표시합니다. magenta 색상. 비용 필드가 없으면 섹션을 생략합니다.

1
2
3
4
5

cost_usd=$(echo "$input" | jq -r '.cost.total_cost_usd // empty')
if [ -n "$cost_usd" ]; then
  cost_str=$(awk "BEGIN {printf \"%.2f\", $cost_usd}")
  cost_part=$(printf " ${C_MAGENTA}\$%s${C_RESET}" "$cost_str")
fi

설계 원칙#

1. 가볍게: statusline은 자주 실행됩니다. 외부 의존성은 jq, awk, sed, git 정도로 제한합니다.
2. 방어적으로: 모든 필드 추출에 // empty 또는 // 0 폴백을 둡니다. 필드가 없는 환경(버전 차이, API 키 직접 사용 등)에서도 오류 없이 동작하고, 해당 섹션만 자연스럽게 생략됩니다.
3. 일관성: 색상 구간 규칙(60%/80% 경계)을 컨텍스트 바와 rate limit이 usage_color 함수로 공유합니다.

전체 스크립트#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215

#!/bin/sh
# Claude Code status line script — developer edition

input=$(cat)

# ANSI color codes
C_CYAN='\033[36m'
C_YELLOW='\033[33m'
C_GREEN='\033[32m'
C_RED='\033[31m'
C_BLUE='\033[34m'
C_MAGENTA='\033[35m'
C_RESET='\033[0m'

# ── 1. Model name (abbreviated) ──────────────────────────────────────────────
model_id=$(echo "$input" | jq -r '.model.id // ""')
model_display=$(echo "$input" | jq -r '.model.display_name // ""')

# Build abbreviated name: extract family + version number
# Examples: claude-sonnet-4-5 → sonnet-4.5, claude-opus-4-6 → opus-4.6
abbr=$(echo "$model_id" | sed -E \
  's/claude-([a-z]+)-([0-9]+)-([0-9]+).*/\1-\2.\3/; \
   s/claude-([a-z]+-[a-z]+)-([0-9]+)-([0-9]+).*/\1-\2.\3/')

# Fallback to display name if abbr didn't change or is empty
if [ -z "$abbr" ] || [ "$abbr" = "$model_id" ]; then
  abbr=$(echo "$model_display" | sed -E \
    's/Claude //; s/ ([0-9]+)\.([0-9]+).*/\1.\2/' | \
    tr '[:upper:]' '[:lower:]')
fi
[ -z "$abbr" ] && abbr="unknown"

model_part=$(printf "${C_CYAN}%s${C_RESET}" "$abbr")

# ── 2. Path (fish shell style: last 2 full, rest first-char only) ─────────────
cwd=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // ""')
if [ -n "$cwd" ]; then
  home="$HOME"
  cwd_display="${cwd#$home}"
  if [ "$cwd_display" != "$cwd" ]; then
    cwd_display="~$cwd_display"
  fi

  abbreviated=$(echo "$cwd_display" | awk '
  {
    n = split($0, segs, "/")
    # Identify prefix and actual segments
    prefix = ""
    start = 1
    if (segs[1] == "") { prefix = "/"; start = 2 }

    # Collect non-empty segments
    count = 0
    for (i = start; i <= n; i++) {
      if (segs[i] != "") {
        count++
        parts[count] = segs[i]
      }
    }

    out = prefix
    for (i = 1; i <= count; i++) {
      # Keep last 2 segments full; abbreviate the rest to first char
      if (count - i >= 2) {
        seg = substr(parts[i], 1, 1)
      } else {
        seg = parts[i]
      }
      if (out == "" || out == "/") out = out seg
      else out = out "/" seg
    }
    print out
  }')

  path_part=$(printf " ${C_YELLOW}%s${C_RESET}" "$abbreviated")
else
  path_part=""
fi

# ── 3. Git branch ────────────────────────────────────────────────────────────
git_branch=""
if [ -n "$cwd" ]; then
  git_root=$(git -C "$cwd" -c core.hooksPath=/dev/null \
    rev-parse --show-toplevel 2>/dev/null)
  if [ -n "$git_root" ]; then
    git_branch=$(git -C "$cwd" -c core.hooksPath=/dev/null \
      symbolic-ref --short HEAD 2>/dev/null)
    if [ -z "$git_branch" ]; then
      git_branch=$(git -C "$cwd" -c core.hooksPath=/dev/null \
        rev-parse --short HEAD 2>/dev/null)
    fi
    if [ -n "$git_branch" ]; then
      GIT_ICON=$(printf '\xe2\x8e\x87')
      branch_part=$(printf " ${C_GREEN}%s %s${C_RESET}" "$GIT_ICON" "$git_branch")
    fi
  fi
fi
[ -z "$git_branch" ] && branch_part=""

# ── 5. Token usage (k, 1 decimal) ────────────────────────────────────────────
total_in=$(echo "$input"  | jq -r '.context_window.total_input_tokens // 0')
total_out=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0')
total_tokens=$(( total_in + total_out ))
if [ "$total_tokens" -ge 1000 ]; then
  token_str=$(awk "BEGIN {printf \"%.1fk\", $total_tokens/1000}")
else
  token_str="${total_tokens}"
fi
token_part=$(printf " ${C_BLUE}%s${C_RESET}" "$token_str")

# ── 6. Context usage progress bar (8 blocks) + percentage ────────────────────
used_pct=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
BLOCK_FULL=$(printf '\xe2\x96\x88')
BLOCK_EMPTY=$(printf '\xe2\x96\x91')
BARS=8

if [ -n "$used_pct" ]; then
  pct_int=$(printf "%.0f" "$used_pct")
  filled=$(awk "BEGIN {n=int($used_pct*$BARS/100+0.5); if(n>$BARS)n=$BARS; print n}")
  empty=$(( BARS - filled ))

  bar=""
  i=0
  while [ "$i" -lt "$filled" ]; do
    bar="${bar}${BLOCK_FULL}"
    i=$((i + 1))
  done
  i=0
  while [ "$i" -lt "$empty" ]; do
    bar="${bar}${BLOCK_EMPTY}"
    i=$((i + 1))
  done

  # Color: 0-60% green, 61-80% yellow, 81%+ red
  if [ "$pct_int" -le 60 ]; then
    bar_color="$C_GREEN"
  elif [ "$pct_int" -le 80 ]; then
    bar_color="$C_YELLOW"
  else
    bar_color="$C_RED"
  fi

  ctx_part=$(printf " ${bar_color}[%s]${C_RESET} %s%%" "$bar" "$pct_int")
else
  empty_bar=""
  i=0
  while [ "$i" -lt "$BARS" ]; do
    empty_bar="${empty_bar}${BLOCK_EMPTY}"
    i=$((i + 1))
  done
  ctx_part=$(printf " ${C_GREEN}[%s]${C_RESET} --" "$empty_bar")%%
fi

# ── 7·8. Rate limits (5h session + 7d weekly) ────────────────────────────────
usage_color() {
  _pct=$(printf "%.0f" "$1")
  if   [ "$_pct" -le 60 ]; then printf '%s' "$C_GREEN"
  elif [ "$_pct" -le 80 ]; then printf '%s' "$C_YELLOW"
  else                           printf '%s' "$C_RED"
  fi
}

format_remaining() {
  _rem=$(( $1 - $(date +%s) ))
  [ "$_rem" -lt 0 ] && _rem=0
  if   [ "$_rem" -ge 86400 ]; then printf '%dd%dh' $(( _rem/86400 )) $(( _rem%86400/3600 ))
  elif [ "$_rem" -ge 3600  ]; then printf '%dh%02dm' $(( _rem/3600 )) $(( _rem%3600/60 ))
  else                             printf '%dm' $(( _rem/60 ))
  fi
}

session_pct=$(echo "$input"   | jq -r '.rate_limits.five_hour.used_percentage // empty')
session_reset=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')
weekly_pct=$(echo "$input"    | jq -r '.rate_limits.seven_day.used_percentage // empty')
weekly_reset=$(echo "$input"  | jq -r '.rate_limits.seven_day.resets_at // empty')

make_rate_piece() {
  _color="$1" _pct="$2" _reset="$3"
  [ -z "$_pct" ] && return
  _used=$(printf "%.0f" "$_pct")
  _ucolor=$(usage_color "$_pct")
  _time_str=""
  [ -n "$_reset" ] && _time_str=$(printf "${_color}↻%s " "$(format_remaining "$_reset")")
  printf "%s${_ucolor}↑%d%%${C_RESET}" "$_time_str" "$_used"
}

sess_piece=$(make_rate_piece "$C_CYAN"    "$session_pct" "$session_reset")
week_piece=$(make_rate_piece "$C_YELLOW"  "$weekly_pct"  "$weekly_reset")

rate_part=""
if [ -n "$sess_piece" ] && [ -n "$week_piece" ]; then
  rate_part=$(printf " · %s  %s" "$sess_piece" "$week_piece")
elif [ -n "$sess_piece" ]; then
  rate_part=$(printf " · %s" "$sess_piece")
elif [ -n "$week_piece" ]; then
  rate_part=$(printf " · %s" "$week_piece")
fi

# ── 9. Session cost (USD) ────────────────────────────────────────────────────
cost_usd=$(echo "$input" | jq -r '.cost.total_cost_usd // empty')
cost_part=""
if [ -n "$cost_usd" ]; then
  cost_str=$(awk "BEGIN {printf \"%.2f\", $cost_usd}")
  cost_part=$(printf " ${C_MAGENTA}\$%s${C_RESET}" "$cost_str")
fi

# ── Output ────────────────────────────────────────────────────────────────────
printf "%s%s%s%s%s%s%s\n" \
  "$model_part" \
  "$path_part" \
  "$branch_part" \
  "$token_part" \
  "$ctx_part" \
  "$rate_part" \
  "$cost_part"

테스트 방법#

스크립트를 수정하거나 새로 만들 때는 샘플 JSON을 파이프로 넘겨서 Claude Code를 열지 않고도 검증할 수 있습니다:

1
2
3
4
5
6
7
8
9
10
11

echo '{
  "model": {"id": "claude-sonnet-4-6", "display_name": "Sonnet 4.6"},
  "workspace": {"current_dir": "/Users/yun/projects/myapp"},
  "context_window": {"total_input_tokens": 24000, "total_output_tokens": 800, "used_percentage": 12.5},
  "cost": {"total_cost_usd": 0.42},
  "rate_limits": {
    "five_hour": {"used_percentage": 32, "resets_at": 1750000000},
    "seven_day": {"used_percentage": 3, "resets_at": 1750500000}
  },
  "session_id": "test-session-abc"
}' | bash ~/.claude/statusline.sh

마치며#

statusline 커스텀의 핵심 효용은 컨텍스트·비용·rate limit을 Claude와 대화하면서 항상 시야에 두는 것입니다. 컨텍스트가 80%를 넘으면 바 색깔이 노란색으로 바뀌고, 90%를 넘으면 빨간색이 됩니다. /compact를 언제 해야 할지 판단하거나, 요금이 얼마나 나왔는지 확인하거나, rate limit 소진 속도를 체크하는 데 유용합니다.

더 다양한 statusline 구성이 궁금하다면 커뮤니티 프로젝트인 ccstatusline이나 starship-claude도 참고할 만합니다.

이 불편함은 테스트 코드가 미숙한 탓이 아닙니다. 테스트가 어렵다는 것 자체가 설계에 대한 피드백입니다. 더 구체적으로는 캡슐화가 제대로 되지 않았다는 신호일 가능성이 높습니다.

이번 포스팅에서는 커서 기반 페이지네이션 응답 객체인 CursorPageResponse를 예시로, 생성자가 열려 있을 때 테스트가 어떻게 무너지는지, 그리고 private constructor + invoke 설계로 캡슐화를 강제했을 때 테스트가 어떻게 단순해지는지를 살펴봅니다.

CursorPageResponse 설계#

CursorPageResponse는 커서 기반 페이지네이션의 응답을 담는 객체입니다. 코드를 보면 생성자가 private으로 선언되어 있습니다.

1
2
3
4
5
6
7

data class CursorPageResponse<T> private constructor(
    val content: List<T>,
    val hasNext: Boolean,
    val hasPrev: Boolean,
    val nextCursor: T?,
    val prevCursor: T?,
)

외부에서 직접 생성자를 호출할 수 없고, companion object의 invoke 팩토리 함수를 통해서만 객체를 생성할 수 있습니다.

1
2
3
4
5
6
7
8
9

companion object {
    operator fun <T> invoke(
        content: List<T>,
        direction: CursorDirection,
        pageSize: Int,
    ): CursorPageResponse<T> {
        // ... 내부 로직
    }
}

Kotlin에서 companion object에 operator fun invoke를 정의하면 마치 생성자처럼 CursorPageResponse(...) 형태로 호출할 수 있습니다. 외부에서 보면 생성자처럼 보이지만, 실제로는 invoke 팩토리 함수를 통해 생성됩니다.

invoke 내부 로직은 다음과 같습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

operator fun <T> invoke(
    content: List<T>,
    direction: CursorDirection,
    pageSize: Int,
): CursorPageResponse<T> {
    if (content.isEmpty()) {
        return CursorPageResponse(
            content = emptyList(),
            hasNext = false,
            hasPrev = false,
            nextCursor = null,
            prevCursor = null,
        )
    }

    return if (direction.isForward) {
        // forward(FIRST/NEXT): DB에서 DESC로 조회한 결과를 그대로 사용
        val hasNext = content.size > pageSize
        val actualContent = content.take(pageSize)
        val hasPrev = direction == CursorDirection.NEXT
        CursorPageResponse(
            content = actualContent,
            hasNext = hasNext,
            hasPrev = hasPrev,
            nextCursor = if (hasNext) actualContent.last() else null,
            prevCursor = if (hasPrev) actualContent.first() else null,
        )
    } else {
        // backward(LAST/PREV): DB에서 ASC로 조회한 결과를 reversed()해서 반환
        val hasPrev = content.size > pageSize
        val actualContent = content.take(pageSize).reversed()
        val hasNext = direction == CursorDirection.PREV
        CursorPageResponse(
            content = actualContent,
            hasNext = hasNext,
            hasPrev = hasPrev,
            nextCursor = if (hasNext) actualContent.last() else null,
            prevCursor = if (hasPrev) actualContent.first() else null,
        )
    }
}

direction별로 동작 방식이 다릅니다.

applyCursorPagination이 pageSize + 1개를 조회해서 넘기면, invoke 내부에서 초과분 유무로 다음/이전 페이지 존재를 판단하고 take(pageSize)로 실제 노출할 데이터를 잘라냅니다. 커서(nextCursor, prevCursor)는 잘라낸 결과의 첫 번째 또는 마지막 항목을 저장합니다.

받는 파라미터와 저장되는 필드가 다르다#

이 설계의 핵심은 invoke가 받는 파라미터와 data class에 저장되는 필드가 다르다는 점입니다.

invoke가 받는 파라미터:

1
2
3
4
5

operator fun <T> invoke(
    content: List<T>,          // 조회된 raw 데이터 (pageSize + 1 개)
    direction: CursorDirection, // 페이지 이동 방향
    pageSize: Int,             // 페이지 크기
)

실제 data class에 저장되는 필드:

1
2
3
4
5
6
7

data class CursorPageResponse<T> private constructor(
    val content: List<T>,  // 실제 노출할 데이터 (pageSize 만큼 잘라낸 결과)
    val hasNext: Boolean,  // 다음 페이지 존재 여부
    val hasPrev: Boolean,  // 이전 페이지 존재 여부
    val nextCursor: T?,    // 다음 페이지 커서
    val prevCursor: T?,    // 이전 페이지 커서
)

파라미터 content, direction, pageSize를 받아 hasNext, hasPrev, nextCursor, prevCursor를 계산하는 핵심 로직이 invoke 내부에 캡슐화되어 있습니다. 예를 들어 다음과 같은 규칙들이 invoke 내부에서 처리됩니다.

• NEXT 방향이면 hasPrev는 항상 true
• LAST 방향이면 hasNext는 항상 false
• backward 방향(LAST, PREV)은 DB에서 ASC로 조회한 결과를 reversed()해서 반환
• pageSize + 1개를 조회한 결과에서 초과분으로 다음/이전 페이지 존재 여부 판단

이런 규칙들이 모두 invoke 안에 있기 때문에 외부에서는 이 로직을 신경 쓸 필요가 없습니다.

생성자가 열려 있다면 어떤 문제가 생길까#

만약 생성자가 public이었다면 외부에서 직접 이렇게 생성할 수 있습니다.

1
2
3
4
5
6
7
8

// 생성자가 public인 경우, 외부에서 직접 생성 가능
val response = CursorPageResponse(
    content = payments,
    hasNext = ???,      // 어떻게 계산해야 하지?
    hasPrev = ???,      // 방향에 따라 다른데...
    nextCursor = ???,   // 어떤 항목을 넣어야 하지?
    prevCursor = ???,
)

이 상황에서 발생하는 문제는 여러 가지입니다.

1. 어떤 생성자를 써야 할지 모른다

생성자와 invoke 두 경로가 모두 열려 있다면 어느 쪽을 써야 하는지 혼란이 생깁니다. 생성자를 직접 사용하면 내부 계산 로직을 거치지 않아 잘못된 상태의 객체가 만들어질 수 있습니다.

2. 객체의 핵심 로직이 외부로 새어나간다

CursorPageResponse를 생성하는 모든 곳에서 hasNext, hasPrev, nextCursor, prevCursor를 직접 계산해야 합니다. hasPrev = direction == CursorDirection.NEXT라는 규칙을 한 곳에서 구현했다면, 다른 곳에서도 동일한 규칙을 알고 구현해야 합니다. CursorPageResponse가 책임져야 할 로직이 해당 객체를 생성하는 모든 곳으로 분산됩니다.

3. 규칙 위반 객체를 만들 수 있다

더 이상 다음 페이지가 없는 상황임에도 hasNext = true로 생성하는 것을 막을 방법이 없습니다. 생성자가 열려 있으면 객체가 스스로 자신의 불변 규칙을 보장할 수 없습니다.

테스트 코드가 주는 피드백#

생성자가 열려 있을 때 발생하는 문제는 테스트를 작성하는 순간 가장 직접적으로 드러납니다. 테스트가 어렵다면, 그것은 캡슐화가 제대로 되지 않았다는 신호입니다.

테스트 준비 코드가 곧 로직 중복이다#

생성자가 public이었다면, NEXT 방향 테스트 하나를 이렇게 작성해야 합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

@Test
fun `NEXT 방향으로 다음 페이지가 있는 경우`() {
    val payments = listOf(payment1, payment2, payment3)
    val pageSize = 2

    // 테스트 작성자가 직접 계산 로직을 구현해야 한다
    val hasNext = payments.size > pageSize
    val actualContent = payments.take(pageSize)
    val hasPrev = true // NEXT 방향이므로
    val response = CursorPageResponse(
        content = actualContent,
        hasNext = hasNext,
        hasPrev = hasPrev,
        nextCursor = actualContent.last().id.toString(),
        prevCursor = actualContent.first().id.toString(),
    )

    then(response.hasNext).isTrue()
    // ...
}

테스트를 작성하다 보면 자연스럽게 이런 생각이 듭니다.

“이 hasNext 계산 로직을 내가 왜 여기서 하고 있지?”
“이건 CursorPageResponse가 알아야 하는 거 아닌가?”
“테스트마다 이 로직을 반복해서 짜는 게 맞나?”

문제는 하나의 테스트로 끝나지 않는다는 데 있습니다. FIRST, NEXT, PREV, LAST 각 방향별로, 다음 페이지 있음/없음, 이전 페이지 있음/없음 등의 경우를 모두 테스트해야 합니다. 그 결과 테스트마다 동일한 계산 로직이 반복됩니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@Test
fun `FIRST 방향으로 다음 페이지가 있는 경우`() {
    val hasNext = payments.size > pageSize       // 중복
    val actualContent = payments.take(pageSize)  // 중복
    val hasPrev = false                          // FIRST 방향이므로
    val response = CursorPageResponse(content = actualContent, hasNext = hasNext, ...)
}

@Test
fun `PREV 방향으로 이전 페이지가 있는 경우`() {
    val hasPrev = payments.size > pageSize               // 중복
    val actualContent = payments.take(pageSize).reversed() // 중복
    val hasNext = true                                   // PREV 방향이므로
    val response = CursorPageResponse(content = actualContent, hasPrev = hasPrev, ...)
}

이 로직 중복은 단순한 코드 반복이 아닙니다. CursorPageResponse 내부에 있어야 할 규칙이 테스트 코드 전반에 분산된 것입니다. 이 상태에서는 CursorPageResponse를 테스트하는 게 아니라, 테스트 작성자가 직접 그 규칙을 재구현하고 있는 셈입니다.

로직이 변경되면 테스트도 함께 깨진다#

캡슐화가 깨진 설계의 가장 큰 문제는 변경에 취약하다는 점입니다.

예를 들어 nextCursor를 항목 자체(T)가 아니라 항목의 ID(String)로 인코딩하는 방식으로 스펙이 바뀐다고 가정합니다.

1
2
3
4
5

// 변경 전: 항목 자체를 커서로
nextCursor = actualContent.last()

// 변경 후: ID를 문자열로 인코딩
nextCursor = actualContent.last().id.toString()

private constructor + invoke 설계라면 invoke 내부 한 곳만 수정하면 됩니다. 하지만 생성자가 열려 있어 각 테스트가 커서를 직접 계산하고 있다면, 이 규칙이 반영된 모든 테스트를 찾아 수정해야 합니다. 수정이 누락된 테스트는 잘못된 기댓값을 갖게 되어 테스트가 통과해도 실제 동작이 틀릴 수 있는 상황이 만들어집니다.

캡슐화 후 테스트는 어떻게 바뀌는가#

private constructor + invoke 설계에서는 테스트가 이렇게 바뀝니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

@Test
fun `NEXT - content가 pageSize 초과이면 hasNext true, hasPrev true`() {
    // given
    val content = listOf(1, 2, 3, 4) // pageSize + 1
    val pageSize = 3

    // when
    val response = CursorPageResponse(content, CursorDirection.NEXT, pageSize)

    // then
    then(response.hasNext).isTrue()
    then(response.hasPrev).isTrue()
    then(response.nextCursor).isEqualTo(3)
    then(response.prevCursor).isEqualTo(1)
}

@Test
fun `PREV - content가 pageSize 초과이면 hasPrev true, 결과는 reversed`() {
    // given
    val content = listOf(1, 2, 3, 4) // ASC로 조회된 결과 (pageSize + 1)
    val pageSize = 3

    // when
    val response = CursorPageResponse(content, CursorDirection.PREV, pageSize)

    // then
    then(response.hasPrev).isTrue()
    then(response.hasNext).isTrue()
    then(response.content).isEqualTo(listOf(3, 2, 1)) // reversed
    then(response.prevCursor).isEqualTo(3)
    then(response.nextCursor).isEqualTo(1)
}

각 테스트는 content, direction, pageSize만 넘기면 됩니다. 계산 로직은 invoke 안에 있고, 테스트는 입력과 기대 결과만 서술하는 구조가 됩니다. nextCursor 인코딩 방식이 바뀌어도 invoke 내부만 수정하면 테스트는 기댓값만 고치면 됩니다.

테스트 작성자는 CursorPageResponse의 내부 로직을 몰라도 됩니다. content, direction, pageSize를 넘기면 올바른 상태의 객체가 만들어진다는 것만 알면 됩니다.

결론#

테스트가 어렵다면 캡슐화를 의심하라. 테스트 준비 코드가 길어지거나 테스트마다 같은 계산 로직이 반복된다면, 그것은 테스트 코드의 문제가 아니라 해당 로직이 올바른 위치에 있지 않다는 신호입니다.

CursorPageResponse의 설계를 통해 확인한 것처럼, 캡슐화가 잘 된 객체는 두 가지를 보장합니다.

1. 객체는 자신의 상태를 스스로 결정한다. hasNext, hasPrev, nextCursor, prevCursor를 외부에서 주입받지 않고, invoke 내부에서 direction과 pageSize를 기반으로 스스로 계산합니다.

2. 생성 방법을 하나로 강제한다. private constructor + invoke 조합으로 외부에서는 오직 올바른 방법으로만 객체를 생성할 수 있게 합니다. 두 가지 생성 경로가 열려 있으면 어느 것을 써야 할지 혼란이 생기고, 잘못된 상태의 객체가 만들어질 여지가 생깁니다.

객체를 설계할 때 “이 로직이 정말 이 객체의 책임인가?”를 스스로에게 물어보는 것도 좋지만, 테스트를 작성하면서 느끼는 불편함 자체가 더 직접적인 피드백입니다. 테스트가 짧고 “입력 → 결과” 구조로 단순하게 작성된다면 설계가 올바른 방향이라는 증거이고, 반대라면 캡슐화를 의심해볼 시점입니다.

• Querydsl Repository Support 활용
• JPA 페이징 Performance
• Spring Batch Reader 성능 분석

이전 포스팅에서 Querydsl4RepositorySupport를 이용한 두 가지 페이지네이션 방법을 소개했습니다. 이번 포스팅에서는 해당 방법들의 한계를 짚어보고, 이를 해결하는 커서 기반 페이지네이션(applyCursorPagination)을 소개합니다.

기존 페이지네이션 방식 복습#

전통적인 페이지네이션은 limit, offset으로 부분 데이터를 가져오고, 하단의 네비게이션을 구성하기 위해 전체 카운트 쿼리를 별도로 실행하는 방식입니다.

1
2
3
4
5
6
7
8
9

-- 데이터 조회
SELECT *
FROM payment
ORDER BY id DESC
LIMIT 10 OFFSET 100;

-- 전체 카운트
SELECT COUNT(*)
FROM payment;

이 방식의 카운트 쿼리는 테이블 전체를 스캔하기 때문에 데이터가 많아질수록 부담이 커집니다.

applySlicePagination - 카운트 쿼리 없는 Slice#

그렇다면 카운트 쿼리가 반드시 필요한가? 라는 질문을 해볼 수 있습니다. 실제로 페이지 네비게이션이 있는 화면이라도, 사용자가 26페이지에 원하는 데이터가 있을 것이라고 예상하고 바로 넘어가는 경우는 거의 없습니다. 대부분 다음 페이지로 넘어가는 방식으로 탐색합니다. 이런 경우에는 굳이 무거운 카운트 쿼리 없이, 다음 데이터가 있는지 여부만 내려주는 Slice 방식이 더 효율적입니다.

1
2
3
4
5
6
7
8
9

protected fun <T> applySlicePagination(
    pageable: Pageable,
    query: Function<JPAQueryFactory, JPAQuery<T>>
): Slice<T> {
    val jpaContentQuery = query.apply(queryFactory)
    val content = querydsl!!.applyPagination(pageable, jpaContentQuery).fetch()
    val hasNext = content.size >= pageable.pageSize
    return SliceImpl(content, pageable, hasNext)
}

pageSize + 1개를 조회해서 다음 데이터 존재 여부(hasNext)만 판별하고, 카운트 쿼리는 실행하지 않습니다.

applyPagination - 코루틴 병렬 조회#

하단 전체 페이지 네비게이션이 반드시 필요한 경우라면 데이터 조회 쿼리와 카운트 쿼리를 코루틴으로 동시에 실행해서 성능을 개선할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11

protected fun <T> applyPagination(
    pageable: Pageable,
    contentQuery: Function<JPAQueryFactory, JPAQuery<T>>,
    countQuery: Function<JPAQueryFactory, JPAQuery<Long>>
): Page<T> = runBlocking {
    val jpaContentQuery = contentQuery.apply(queryFactory)
    val content = async(Dispatchers.IO) { querydsl!!.applyPagination(pageable, jpaContentQuery).fetch() as List<T> }
    val count = async(Dispatchers.IO) { countQuery.apply(queryFactory).fetchFirst() }

    PageImpl(content.await(), pageable, count.await())
}

데이터 조회에 500ms, 카운트 조회에 500ms가 걸린다면, 동기식으로는 1,000ms가 소요됩니다. 코루틴으로 병렬 실행하면 이론적으로 500ms로 단축됩니다.

1
2
3
4
5
6
7

fun findBy(amount: BigDecimal, pageable: Pageable): Page<Payment> {
    return applyPagination(
        pageable = pageable,
        contentQuery = { selectFrom(qPayment).where(qPayment.amount.gt(amount)) },
        countQuery = { select(qPayment.count()).from(qPayment).where(qPayment.amount.gt(amount)) }
    )
}

limit, offset의 근본적인 한계#

두 방식 모두 limit, offset 기반이라는 점에서 공통적인 한계가 있습니다. offset이 커질수록 조회 성능이 선형적으로 저하됩니다.

왜 offset이 느려지는가?#

보다 자세한 내용은 Spring Batch Reader 성능 분석을 참고해 주세요.

JpaPagingItemReader(offset 방식)와 QueryDslNoOffsetPagingReader(No Offset 방식)의 실측 성능을 비교하면 offset의 한계가 명확하게 드러납니다.

JpaPagingItemReader 기준으로 10만 건과 50만 건의 차이가 단순히 5배가 아니라 23배 이상 차이가 납니다. 반면 QueryDslNoOffsetPagingReader는 rows가 늘어나도 선형에 가까운 증가를 보입니다.

그래프를 보면 JpaPagingItemReader(파란색)의 수치가 너무 커서 QueryDslNoOffsetPagingReader(빨간색)의 선이 거의 보이지 않을 정도입니다. 두 리더의 성능 차이가 그만큼 크다는 것을 의미합니다. JpaPagingItemReader를 제외하고 두 리더만 비교한 그래프에서 QueryDslNoOffsetPagingReader가 얼마나 안정적인지 확인할 수 있습니다.

원인을 실행 계획으로 확인해 보겠습니다.

JpaPagingItemReader - 첫 번째 청크 (offset 0)#

1
2
3
4
5

SELECT *
FROM payment
WHERE created_at >= ?
ORDER BY created_at DESC
LIMIT 1000;

type: range로 인덱스가 정상적으로 동작합니다.

JpaPagingItemReader - 마지막 청크 (offset 4,999,000)#

1
2
3
4
5

SELECT *
FROM payment
WHERE created_at >= ?
ORDER BY created_at DESC
LIMIT 4999000, 1000;

type: ALL, 즉 풀 테이블 스캔이 발생합니다. 인덱스도 사용하지 않습니다.

왜 풀 스캔이 발생하는가?#

offset의 본질적인 문제를 이해하려면 DB가 offset을 처리하는 방식을 알아야 합니다. LIMIT 4999000, 1000은 “4,999,000번째 행부터 1,000건을 가져와라”라는 의미인데, 데이터베이스는 4,999,000번째 행이 어디 있는지 바로 알 수 없습니다. 버스에서 10번째 줄에 누가 앉아 있는지 확인하려면 앞에서부터 9줄을 직접 세어가며 확인해야 하는 것처럼, offset도 그 위치까지 도달하기 위해 앞의 데이터를 모두 읽고 버려야 합니다.

즉, LIMIT 4999000, 1000 쿼리는 결국 4,999,000건을 읽고 전부 버린 뒤, 그 다음 1,000건만 돌려주는 동작을 합니다. 실제로 반환되는 데이터는 1,000건이지만 내부적으로는 500만 건 가까운 데이터를 스캔하는 셈입니다.

여기서 옵티마이저의 비용 판단이 개입합니다. 인덱스를 통해 레코드 1건을 읽는 것은 테이블에서 직접 1건을 읽는 것보다 4~5배 비용이 발생합니다. 데이터 모수가 적을 때는 인덱스를 타는 것이 훨씬 효율적이지만, 읽어야 할 범위가 테이블 전체의 20~25%를 넘어서면 옵티마이저는 인덱스를 통해 한 건씩 찾아가는 것보다 테이블을 통째로 풀 스캔하는 것이 더 낫다고 판단합니다. 결과적으로 후반 청크에서는 인덱스가 사라지고 풀 스캔이 선택됩니다.

QueryDslNoOffsetPagingReader - 첫 번째 / 마지막 청크 비교#

No Offset 방식은 WHERE id < 마지막 조회 ID 조건으로 offset 없이 다음 데이터를 찾습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

-- 첫 번째 청크
SELECT *
FROM payment
WHERE created_at >= ?
  AND id >= 1
  AND id <= 1000
ORDER BY id ASC
LIMIT 1000;

-- 마지막 청크
SELECT *
FROM payment
WHERE created_at >= ?
  AND id >= 4999001
  AND id <= 5000000
ORDER BY id ASC
LIMIT 1000;

첫 번째 청크와 마지막 청크의 실행 계획이 동일합니다. PK 인덱스(PRIMARY)를 기준으로 범위 조회하기 때문에 offset이 누적되어도 스캔 비용이 일정하게 유지됩니다.

정리하면, offset/limit 방식은 offset이 커질수록 그 위치까지 도달하기 위한 스캔 비용이 누적되어 결국 풀 스캔으로 전환되는 구조적 한계를 가집니다. No Offset 방식은 이 문제를 커서 조건으로 원천 차단합니다.

applyCursorPagination - 커서 기반 페이지 조회#

앞서 소개한 QueryDslNoOffsetPagingReader도 커서 기반 발상을 활용하지만, 그 용도는 배치 Item Reader에 특화되어 있습니다. 데이터를 처음부터 끝까지 한 방향으로 순차 처리하는 것이 목적이기 때문에 “다음 청크”만 지원하면 충분합니다.

반면 REST API로 페이지 탐색 기능을 제공할 때는 요구사항이 다릅니다. 사용자 또는 어드민이 화면에서 다음과 같은 탐색을 요청할 수 있습니다.

• 첫 번째 페이지로 이동 (FIRST)
• 마지막 페이지로 이동 (LAST)
• 현재 페이지에서 다음 페이지로 (NEXT)
• 현재 페이지에서 이전 페이지로 (PREV)

applyCursorPagination은 이 네 가지 방향을 모두 지원하는 양방향 커서 탐색 API를 제공하기 위해 설계되었습니다.

커서 기반 페이지네이션이란#

커서 기반 페이지네이션의 핵심 아이디어는 offset을 없애는 것입니다. offset 대신 마지막으로 조회한 데이터의 ID를 커서(cursor)로 삼아 WHERE id < :cursor 조건으로 다음 데이터를 가져오는 방식입니다.

1
2
3
4
5
6
7
8
9
10
11
12

-- offset 방식 (뒤로 갈수록 느려짐)
SELECT *
FROM payment
ORDER BY id DESC
LIMIT 10 OFFSET 4990;

-- cursor 방식 (항상 동일한 실행 계획)
SELECT *
FROM payment
WHERE id < :lastId
ORDER BY id DESC
LIMIT 10;

WHERE id < :lastId는 PK 인덱스를 그대로 활용하기 때문에, 조회 위치가 어디든 실행 계획이 동일하게 유지됩니다.

클라이언트는 응답으로 받은 nextCursor 또는 prevCursor 값을 다음 요청의 cursorKey로 전달하는 방식으로 탐색을 이어갑니다. 서버는 커서 값과 방향(direction)만으로 다음 조회 범위를 결정하기 때문에, 전체 데이터 크기나 현재 페이지 번호를 유지할 필요가 없습니다.

동작 원리#

데이터가 8건(id: 1~8)이고 pageSize=2인 경우를 예로 들겠습니다.

1

전체 데이터: [8, 7, 6, 5, 4, 3, 2, 1]  (DESC 기준)

FIRST - 첫 페이지 (커서 없음):

1
2
3
4
5
6

SELECT *
FROM payment
ORDER BY id DESC
LIMIT 3;
-- pageSize + 1
-- 결과: [8, 7, 6]

• actualContent: [8, 7] (pageSize만큼 자름)
• hasNext: true (3건 > pageSize 2)
• nextCursor: “7” (마지막 항목 ID)
• hasPrev: false,
• prevCursor: null

NEXT (cursor=7):

1
2
3
4
5
6

SELECT *
FROM payment
WHERE id < 7
ORDER BY id DESC
LIMIT 3;
-- 결과: [6, 5, 4]

• actualContent: [6, 5]
• hasNext: true
• nextCursor: “5”,
• prevCursor: “6”
• hasPrev: true

NEXT (cursor=3) - 마지막 페이지:

1
2
3
4
5
6

SELECT *
FROM payment
WHERE id < 3
ORDER BY id DESC
LIMIT 3;
-- 결과: [2, 1]

• actualContent: [2, 1]
• hasNext: false (2건 ≤ pageSize 2)
• nextCursor: null
• hasPrev: true,
• prevCursor: “2”

구현#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

fun <T> applyCursorPagination(
    cursorRequest: CursorRequest,
    cursorPath: NumberPath<Long>,
    cursorSelector: (T) -> String,
    contentQuery: Function<JPAQueryFactory, JPAQuery<T>>,
): CursorPageResponse<T> {
    val direction = cursorRequest.direction
    val pageSize = cursorRequest.pageSize
    val cursorValue = cursorRequest.cursorKey?.toLong()

    val query = contentQuery.apply(queryFactory)

    when (direction) {
        CursorDirection.FIRST, CursorDirection.LAST -> Unit
        CursorDirection.NEXT -> {
            requireNotNull(cursorValue) { "Cursor key must be provided for NEXT direction" }
            query.where(cursorPath.lt(cursorValue))
        }
        CursorDirection.PREV -> {
            requireNotNull(cursorValue) { "Cursor key must be provided for PREV direction" }
            query.where(cursorPath.gt(cursorValue))
        }
    }

    query.orderBy(
        when {
            direction.isForward -> cursorPath.desc()
            else -> cursorPath.asc()
        }
    )
    query.limit((pageSize + 1).toLong())
    val content = query.fetch()
    return CursorPageResponse(
        content = content,
        direction = direction,
        pageSize = pageSize,
        encodeCursor = cursorSelector,
    )
}

contentQuery에는 기본 조회 쿼리만 전달하면 됩니다. WHERE 커서 조건, ORDER BY, LIMIT 처리는 applyCursorPagination이 담당합니다.

실제 Repository에서는 다음과 같이 사용합니다.

1
2
3
4
5
6
7
8

fun findByCursor(cursorRequest: CursorRequest): CursorPageResponse<Payment> {
    return applyCursorPagination(
        cursorRequest = cursorRequest,
        cursorPath = qPayment.id,
        cursorSelector = { it.id.toString() },
        contentQuery = { selectFrom(qPayment) }
    )
}

CursorPageResponse#

응답 객체는 팩토리 함수(invoke)를 통해 방향별 커서와 플래그를 자동으로 계산합니다.

1
2
3
4
5
6
7
8

data class CursorPageResponse<T> private constructor(
    val content: List<T>,
    val hasNext: Boolean,
    val hasPrev: Boolean,
    val nextCursor: String?,
    val prevCursor: String?,
    ...
)

backward(PREV/LAST) 방향은 DB에서 ASC로 조회한 결과를 reversed()로 뒤집어 표시 순서를 맞춥니다.

주의 사항#

contentQuery에 정렬 조건을 넣지 마세요#

applyCursorPagination은 내부에서 cursorPath를 기준으로 ORDER BY를 자동으로 추가합니다. contentQuery에 별도의 정렬 조건을 넣으면 충돌이 발생할 수 있습니다.

1
2
3
4
5

// Bad - contentQuery에 orderBy 추가
contentQuery = { selectFrom(qPayment).orderBy(qPayment.createdAt.desc()) }

// Good - 기본 조회 쿼리만
contentQuery = { selectFrom(qPayment) }

커서 기반 조회가 적합하지 않은 경우#

커서 기반 조회는 ID처럼 순차적이고 유니크한 값을 기준으로 동작합니다. 다음 경우에는 적합하지 않을 수 있습니다.

1. GROUP BY가 포함된 쿼리

GROUP BY 결과에서 ID 기준으로 커서를 잡기 애매합니다. 예를 들어 카테고리별 합계를 조회하는 경우, 집계 결과의 행에는 단일 ID가 존재하지 않아 커서의 연속성이 깨집니다.

1
2
3
4

-- ID 커서를 적용하기 어려운 쿼리
SELECT category, SUM(amount)
FROM payment
GROUP BY category;

2. ID와 다른 기준으로 정렬하는 경우

커서 기반 조회는 ID의 대소 비교로 페이지를 나눕니다. 정렬 기준이 ID와 다른 경우(예: amount DESC) 커서가 정렬 순서와 일치하지 않아 데이터 누락이나 중복이 발생할 수 있습니다.

3. 임의 페이지 이동이 필요한 경우

“26페이지로 바로 이동” 같은 임의 페이지 이동은 커서 기반으로는 지원하기 어렵습니다. 커서는 이전 페이지의 결과에서 연속적으로 이어지는 구조이기 때문입니다.

정리하면, 커서 기반 조회는 시계열 데이터를 ID 기준으로 순차 탐색하는 패턴에 가장 잘 맞습니다. 피드, 알림 목록, 거래 내역처럼 최신순으로 스크롤하는 화면이 대표적인 적합 사례입니다.

성능 테스트 데이터 셋업#

성능 측정을 위해 payment 테이블에 100만 건 데이터를 셋업합니다. Doubling 방식(INSERT INTO … SELECT)으로 초기 1행에서 20번 반복하면 2^20 = 1,048,576건을 빠르게 생성할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

-- 1. 기존 데이터 초기화
TRUNCATE TABLE payment;

-- 2. 기준 1행 삽입
INSERT INTO payment (amount, created_at, updated_at)
VALUES (500.00, '2023-01-01 00:00:00', NOW());

-- 3. 아래 INSERT를 20번 반복 실행 (매 실행마다 행 수 2배 증가)
-- 1회: 2건 / 5회: 32건 / 10회: 1,024건 / 15회: 32,768건 / 20회: 1,048,576건
INSERT INTO payment (amount, created_at, updated_at)
SELECT ROUND(RAND() * 1000, 2),
       DATE_ADD('2023-01-01 00:00:00', INTERVAL FLOOR(RAND() * 730 * 24 * 3600) SECOND),
       NOW()
FROM payment;

-- 4. 검증
SELECT COUNT(*)
FROM payment;

SELECT DATE_FORMAT(created_at, '%Y-%m') AS month,
       COUNT(*)                         AS cnt
FROM payment
GROUP BY month
ORDER BY month;

성능 비교#

데이터 셋업(1,048,576건, created_at 2023~2024년 분산)을 기준으로 limit/offset 방식과 커서 방식의 SQL을 각각 첫 번째·중간·마지막 페이지로 비교합니다. limit size는 100으로 고정합니다.

limit / offset 방식#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

-- 첫 번째 페이지 (offset 0), 소요 597 ms
SELECT *
FROM payment
ORDER BY id DESC
LIMIT 100 OFFSET 0;

-- 약 5,241 페이지 (offset ~524,000, 전체의 약 50% 지점), 소요 1,198 ms
SELECT *
FROM payment
ORDER BY id DESC
LIMIT 100 OFFSET 524000;

-- 약 8,241 페이지 (offset ~824,000, 전체의 약 79% 지점), 소요 1,639 ms
SELECT *
FROM payment
ORDER BY id DESC
LIMIT 100 OFFSET 824000;

-- 마지막 페이지 (offset ~1,048,476, 전체 끝 지점), 소요 1,995 ms
SELECT *
FROM payment
ORDER BY id DESC
LIMIT 100 OFFSET 1048476;

커서 방식#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

-- 첫 번째 페이지 (커서 없음, id 최댓값 1,310,693부터 시작), 소요 589 ms
SELECT *
FROM payment
ORDER BY id DESC
LIMIT 100;

-- 약 50% 지점 (id 약 655,000 기준), 소요 596 ms
SELECT *
FROM payment
WHERE id < 655000
ORDER BY id DESC
LIMIT 100;

-- 약 79% 지점 (id 약 281,000 기준), 소요 577 ms
SELECT *
FROM payment
WHERE id < 281000
ORDER BY id DESC
LIMIT 100;

-- 마지막 페이지 (id 약 100 기준, 끝 지점), 소요 595 ms
SELECT *
FROM payment
WHERE id < 100
ORDER BY id DESC
LIMIT 100;

성능 측정 결과#

첫 번째 페이지에서는 두 방식의 차이가 거의 없습니다. 하지만 뒤로 갈수록 격차가 급격히 벌어져 마지막 지점에서는 limit/offset이 cursor보다 3.4배 느립니다.

이 차이는 단발성 API 호출에서도 체감되지만, 전체 데이터를 순차적으로 읽어 리포트를 생성하는 배치 처리에서 더욱 치명적입니다. 예를 들어 100만 건의 결제 데이터를 페이지 단위로 모두 읽어 월별 매출 집계를 산출하는 배치를 생각해보면, limit/offset 방식은 청크가 뒤로 넘어갈수록 쿼리 1건당 소요 시간이 계속 누적되어 증가합니다. 반면 cursor 방식은 청크 위치와 무관하게 매 쿼리가 일정한 비용으로 동작하기 때문에 전체 처리 시간이 선형에 가깝게 유지됩니다.

결국 “어느 위치를 조회하든 동일한 실행 계획” 이라는 cursor의 특성이, 반복 호출이 누적되는 배치 환경에서 성능 격차를 더욱 크게 만드는 핵심 이유입니다.

마무리#

applyPagination과 applySlicePagination은 offset 기반이므로 뒤로 갈수록 쿼리 비용이 선형 이상으로 증가합니다. 실측 기준으로 첫 페이지 대비 마지막 페이지에서 3.4배 이상 느려졌고, 이 차이는 배치처럼 전체 데이터를 반복 순회하는 환경에서 청크마다 누적되어 전체 처리 시간에 직접적인 영향을 줍니다.

applyCursorPagination은 WHERE id < :cursor 조건으로 PK 인덱스를 직접 활용하기 때문에 조회 위치와 무관하게 실행 계획이 동일하게 유지됩니다. 단건 API뿐 아니라 전체 데이터를 순차적으로 읽어야 하는 배치 리포트에도 적합한 방식입니다.

세 가지 방식 모두 Querydsl4RepositorySupport를 통해 공통 함수로 제공됩니다. 임의 페이지 이동이 필요하면 applyPagination, 다음/이전 탐색만 필요하면 applySlicePagination, 대용량 순차 조회라면 applyCursorPagination을 선택하면 됩니다.

개요#

대량의 데이터를 수정해야 할 때, 일반적으로 JPA의 Dirty Checking 방식을 사용합니다. 엔티티를 조회하여 영속성 컨텍스트에 올린 뒤 필드를 변경하면 트랜잭션 커밋 시점에 변경 감지가 일어나 UPDATE 쿼리가 실행되는 방식입니다. 하지만 데이터의 양이 늘어날수록 이 방식의 처리 속도는 급격히 느려질 수 있습니다. 엔티티 수만큼 개별적인 UPDATE 쿼리가 발생하기 때문입니다.

이전 포스팅(Querydsl을 이용한 Batch Insert 성능 개선)에서 Insert 성능 개선 방법을 소개한 적이 있습니다. Update도 동일한 접근으로 해결할 수 있습니다.

이미 프로젝트에서 JPA와 Querydsl을 사용하고 있다면, 추가적인 라이브러리 도입 없이 Querydsl-SQL 모듈을 활용하여 Type-Safe하게 Batch Update를 구현할 수 있습니다. 이번 포스팅에서는 그 방법을 소개합니다.

JPA Dirty Checking의 성능 이슈#

JPA의 일반적인 Update 패턴은 엔티티를 조회하여 영속성 컨텍스트에 올린 뒤, 필드를 변경하고 트랜잭션이 커밋될 때 변경 감지(Dirty Checking)를 통해 UPDATE 쿼리를 실행하는 방식입니다.

1
2
3
4
5
6
7
8
9

@Transactional
fun updateWriters(ids: List<Long>) {
    val writers = writerRepository.findAllById(ids)
    for (writer in writers) {
        writer.name = "updated"
        writer.score = 100
        // dirty checking → 트랜잭션 커밋 시 건별 UPDATE 발생
    }
}

위 코드는 사용하기 편리하지만, 1,000개의 데이터를 수정하면 1,000번의 UPDATE 쿼리가 데이터베이스로 전송됩니다. 여기에 findAllById로 인한 SELECT 쿼리까지 더하면, 대량 수정 작업에서는 심각한 성능 저하의 원인이 됩니다.

Querydsl Batch Update 구현#

Querydsl-SQL 모듈을 사용하면 JPA 엔티티가 아닌 JDBC 레벨에서 직접 SQL을 구성하여 실행할 수 있습니다. 이를 통해 addBatch 기능을 활용한 Bulk Update를 구현할 수 있습니다.

구현 코드 예시#

SQLQueryFactory를 사용하여 Batch Update를 구현하는 방법은 다음과 같습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

@Service
class BatchInsertService(
    private val dataSource: DataSource
) {
    private val sqlQueryFactory: SQLQueryFactory by lazy {
        SQLQueryFactory(Configuration(MySQLTemplates()), dataSource)
    }

    @Transactional
    fun batchUpdate(writers: List<Writer>): Long {
        // 1. 테이블 메타데이터 정의
        val writerTable = RelationalPathBase(Writer::class.java, "writer", null, "writer")
        // 2. SQLQueryFactory (공유 인스턴스 사용)
        val update = sqlQueryFactory.update(writerTable)
        // 3. 데이터를 Batch에 추가
        for (writer in writers) {
            val id = requireNotNull(writer.id) { "Writer id must not be null" }
            update
                .set(QWriter.writer.name, writer.name)
                .set(QWriter.writer.email, writer.email)
                .set(QWriter.writer.score, writer.score)
                .set(QWriter.writer.reputation, writer.reputation)
                .set(QWriter.writer.active, writer.active)
                .where(QWriter.writer.id.eq(id))
                .addBatch() // 메모리에 쿼리 적재
        }

        // 4. 일괄 실행
        return update.execute()
    }
}

코드 설명

• RelationalPathBase: SQL 쿼리 작성을 위해 대상 테이블의 메타데이터를 정의합니다. SQLQueryFactory는 RelationalPath 타입을 요구하기 때문에, JPA 엔티티 기반의 QWriter(EntityPathBase)를 테이블 참조로 직접 사용할 수 없어 별도로 정의합니다.
• QWriter.writer.*: 컬럼 참조에는 기존에 생성된 Q클래스의 path를 그대로 활용합니다.
• addBatch(): 루프를 돌며 데이터를 즉시 UPDATE 하지 않고, JDBC의 Batch 기능을 활용하기 위해 메모리에 쿼리 파라미터들을 쌓아둡니다.
• execute(): 쌓여있는 Batch 쿼리를 데이터베이스로 한 번에 전송하여 실행합니다.

Insert와의 구조적 차이#

Batch Insert와 Batch Update는 동일한 addBatch + execute() 패턴을 사용하지만, 중요한 구조적 차이가 있습니다.

가장 중요한 차이는 where 조건입니다. where 없이 addBatch()를 호출하면 해당 UPDATE는 테이블 전체를 대상으로 실행되어 의도치 않은 전체 UPDATE가 발생할 수 있습니다. 반드시 where(QWriter.writer.id.eq(id))와 같이 대상 row를 특정해야 합니다.

또한 EntityAuditing을 통해 상속받는 id 필드는 Long? (nullable) 타입이므로, requireNotNull로 null을 방어한 뒤 사용해야 컴파일 타입 안전성이 보장됩니다.

Batch 동작 검증 방법#

addBatch를 사용하면 SQL 내용 자체는 dirty checking과 동일하게 UPDATE writer SET ... WHERE id = ? 형태입니다. 쿼리 내용만으로는 실제로 batch가 동작하는지 구분하기 어렵습니다.

실제 전송 방식의 차이는 JDBC URL에 profileSQL=true를 추가하면 로그로 확인할 수 있습니다.

1

jdbc:mysql://localhost:3306/mydb?rewriteBatchedStatements=true&logger=Slf4JLogger&profileSQL=true

케이스 1 — dirty checking (N번 통신)

1
2
3
4
5
6
7
8
9
10

[QUERY] update writer set active=1,email='email-2',name='updated'... where id=2
        [at ProxyPreparedStatement.executeUpdate]
[FETCH] [at ProxyPreparedStatement.executeUpdate]
[QUERY] update writer set active=1,email='email-3',name='updated'... where id=3
        [at ProxyPreparedStatement.executeUpdate]
[FETCH] [at ProxyPreparedStatement.executeUpdate]
[QUERY] update writer set active=1,email='email-4',name='updated'... where id=4
        [at ProxyPreparedStatement.executeUpdate]
[FETCH] [at ProxyPreparedStatement.executeUpdate]
...

executeUpdate가 건마다 호출되어 [QUERY] + [FETCH] 쌍이 건수만큼 반복됩니다. 10건이면 DB 서버로 10번 왕복합니다.

케이스 2 — addBatch (1번 통신)

1
2
3
4
5
6
7
8
9
10
11

[QUERY] update writer
set name = 'new'
where writer.id = 1;update writer
set name = 'new'
where writer.id = 2;update writer
set name = 'new'
where writer.id = 3;
...
update writer
set name = 'new'
where writer.id = 28;

[QUERY] 로그가 1개만 출력됩니다. 세미콜론으로 구분된 모든 쿼리가 하나의 패킷으로 전송되며, 28건이든 10,000건이든 DB 서버로 1번만 왕복합니다.

구분 포인트 요약

profileSQL=true만 붙이면 로그 줄 수와 메서드명만으로 의도한 대로 batch가 동작하고 있는지 즉시 확인할 수 있습니다.

성능 비교#

성능 측정 코드#

정확한 성능 측정을 위해 JPA Dirty Checking 방식과 Querydsl addBatch의 실행 시간을 각각 측정했습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

@Service
class BatchInsertService() {
    @Transactional
    fun batchUpdate(writers: List<WriterUpdate>): Long {
        val writerTable = RelationalPathBase(Writer::class.java, "writer", null, "writer")
        val update = sqlQueryFactory.update(writerTable)
        // 데이터를 Batch에 추가
        for (writer in writers) {
            val id = requireNotNull(writer.id) { "Writer id must not be null" }
            update
                .set(QWriter.writer.name, writer.name)
                .where(QWriter.writer.id.eq(id))
                .addBatch() // 메모리에 쿼리 적재
        }

        // 일괄 실행
        return update.execute()
    }
    @Transactional
    fun updateWriters(writers: List<Writer>) {
        for (writer in writers) {
            writer.name = "updated"
            writerRepository.save(writer) // dirty checking → 트랜잭션 커밋 시 건별 UPDATE 발생
        }
    }
}

@Test
fun `dirty checking update test`() {
    val rowsList = listOf(100, 200, 500, 1_000, 2_000, 5_000, 10_000)
    val iterations = 5

    rowsList.forEach { rows ->
        // 테스트 데이터 사전 삽입 (id 확보)
        val writers = writerRepository.saveAll(
            (1..rows).map { Writer(name = "name-$it", email = "email-$it") }
        ).toList()

        var totalTimeMillis = 0.0
        for (i in 1..iterations) {
            val stopWatch = StopWatch()
            stopWatch.start()
            writerService.updateWriters(writers)
            stopWatch.stop()

            if (i > 1) { // 첫 회차 제외
                totalTimeMillis += stopWatch.totalTimeMillis
            }
        }
        val averageTimeMillis = totalTimeMillis / (iterations - 1)
        println("$rows 건 dirty checking 평균 실행 시간: ${averageTimeMillis} ms")
    }
}

@Test
fun `batchUpdate test`() {
    val rowsList = listOf(100, 200, 500, 1_000, 2_000, 5_000, 10_000)
    val iterations = 5

    rowsList.forEach { rows ->
        // 테스트 데이터 사전 삽입
        val savedWriters = writerRepository.saveAll(
            (1..rows).map { Writer(name = "name-$it", email = "email-$it") }
        )

        val updates = savedWriters.map { WriterUpdate(id = it.id!!, name = "new") }

        var totalTimeMillis = 0.0
        for (i in 1..iterations) {
            val stopWatch = StopWatch()
            stopWatch.start()
            batchInsertService.batchUpdate(updates)
            stopWatch.stop()

            if (i > 1) { // 첫 회차 제외
                totalTimeMillis += stopWatch.totalTimeMillis
            }
        }
        val averageTimeMillis = totalTimeMillis / (iterations - 1)
        println("$rows 건 Querydsl Batch Update 평균 실행 시간: ${averageTimeMillis} ms")
    }
}

측정 방식 설명

• 반복 측정: 각 데이터 구간(100건 ~ 10,000건)마다 총 5회 반복하여 측정했습니다.
• Warm-up 고려: 테스트 실행 시 첫 번째 회차는 결과에서 제외했습니다. 커넥션 풀 초기화 등 초기 비용이 포함되어 결과가 왜곡되는 것을 방지하기 위함입니다.
• 평균값 산출: 첫 회차를 제외한 나머지 4회의 실행 시간을 합산하여 평균값을 산출했습니다.

성능 측정 결과#

JPA Dirty Checking과 Querydsl addBatch를 사용했을 때의 성능 차이를 비교한 결과입니다.

• bar (dirty checking): JPA save(writer)를 루프에서 건별 호출 — UPDATE N번 개별 전송
• line (add batch): Querydsl SQLQueryFactory의 addBatch — N개의 UPDATE를 1번의 네트워크 왕복으로 전송

참고: 이 측정은 애플리케이션 서버와 데이터베이스가 **동일한 로컬 환경(loopback)**에서 수행된 결과입니다. Loopback 통신은 실제 네트워크 대비 레이턴시가 거의 없는 이상적인 조건임에도 불구하고 이 정도의 성능 차이가 발생합니다. 실제 운영 환경처럼 애플리케이션 서버와 DB 서버가 별도의 네트워크에 위치한다면, 건별로 전송하는 dirty checking 방식은 네트워크 왕복 비용이 쿼리 수만큼 누적되어 성능 차이가 훨씬 더 크게 벌어질 수 있습니다.

결론#

대량의 데이터를 수정해야 하는 배치성 작업에서는 JPA의 Dirty Checking 방식보다 JDBC Batch Update를 사용하는 것이 성능 측면에서 훨씬 유리합니다.

Insert와 마찬가지로, 오직 Batch Update 성능 개선만을 위해 별도의 라이브러리를 도입하는 것은 프로젝트의 복잡도를 높일 수 있습니다. 이미 JPA와 Querydsl을 사용 중인 환경이라면, Querydsl-SQL을 활용하는 것이 추가적인 학습 곡선이나 설정의 번거로움 없이 Type-Safe하게 성능을 극대화할 수 있는 가장 효율적인 대안입니다.

Insert와 Update 모두 동일한 addBatch + execute() 패턴을 사용하지만, Update에서는 반드시 where 조건으로 대상 row를 특정해야 한다는 점을 기억하세요.

운영 환경에서 데이터 변경 이력을 추적해야 하는 경우가 자주 발생합니다. 특히 주문 정보 수정, 가맹점 수수료율 변경 등 중요한 데이터가 어떻게 변경되었는지 필드 단위로 명확하게 기록하고 확인할 수 있어야 합니다.

예를 들어, 운영자가 주문 내역에서 배송 주소만 변경했을 때, 전체 주문 데이터를 다시 저장하는 것보다 “어떤 필드가 어떻게 변경되었는지”를 명확히 기록하면 다음과 같은 이점이 있습니다:

• 변경 이력 추적이 명확해집니다
• 승인 프로세스에서 변경 내용 검토가 용이합니다
• 디버깅 및 감사(Audit) 목적으로 활용할 수 있습니다
• 데이터 롤백 시 정확한 변경 지점을 파악할 수 있습니다

이번 포스트에서는 Kotlin과 Jackson을 활용하여 복잡한 중첩 객체의 변경사항을 자동으로 추적하는 시스템을 구현하는 방법을 알아보겠습니다.

문제 상황#

다음과 같은 주문(Order) 데이터가 있다고 가정해봅시다.

변경 전 데이터#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  "order_id": "ORD123456",
  "customer": {
    "customer_id": "CUST7890",
    "name": "홍길동",
    "contact": {
      "email": "hong@example.com",
      "phone": "010-1234-5678",
      "address": {
        "street": "서울특별시 종로구",
        "city": "서울",
        "zip_code": "03000",
        "country": "KR"
      }
    }
  },
  "items": [
    {
      "product": {
        "product_id": "PROD001",
        "product_name": "노트북",
        "category": {
          "main_category": "전자제품",
          "sub_category": "컴퓨터"
        }
      },
      "quantity": 1,
      "price": 1500000
    }
  ],
  "payment": {
    "method": "신용카드",
    "transaction_id": "TXN987654321",
    "status": "완료"
  }
}

변경 후 데이터#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  "order_id": "ORD123456",
  "customer": {
    "customer_id": "CUST7890",
    "name": "홍길동",
    "contact": {
      "email": "hong@example.com",
      "phone": "010-1234-5678",
      "address": {
        "street": "서울특별시 강남구",
        "city": "서울",
        "zip_code": "03000",
        "country": "KR"
      }
    }
  },
  "items": [
    {
      "product": {
        "product_id": "PROD001",
        "product_name": "노트북",
        "category": {
          "main_category": "전자제품",
          "sub_category": "컴퓨터"
        }
      },
      "quantity": 1,
      "price": 1400000
    }
  ],
  "payment": {
    "method": "신용카드",
    "transaction_id": "TXN987654322",
    "status": "완료"
  }
}

위 두 데이터를 비교하면 다음 필드들이 변경되었습니다:

• customer.contact.address.street: “서울특별시 종로구” → “서울특별시 강남구”
• items[0].price: 1500000 → 1400000
• payment.transaction_id: “TXN987654321” → “TXN987654322”

이러한 변경사항을 자동으로 감지하고 추적하려면 어떻게 해야 할까요?

IntelliJ의 Diff 기능처럼#

IntelliJ IDE를 사용해보신 분들은 아시겠지만, 두 파일을 비교할 때 매우 직관적으로 변경 사항을 표시해줍니다.

우리가 구현하려는 시스템도 이와 유사하게 두 객체를 비교하여 변경된 필드만 추출하는 것입니다.

구현 방법#

1. 핵심 라이브러리: zjsonpatch#

JSON 객체 간의 차이를 계산하기 위해 zjsonpatch 라이브러리를 사용합니다. 이 라이브러리는 RFC 6902 JSON Patch 표준을 구현하여 두 JSON 문서의 차이를 효과적으로 계산합니다.

1
2
3
4
5

// build.gradle.kts
dependencies {
    implementation("com.flipkart.zjsonpatch:zjsonpatch:0.4.14")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
}

2. DiffComparisonManager 구현#

전체 코드는 다음과 같습니다:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

package com.example.boot3mongo

import com.fasterxml.jackson.core.JsonGenerator
import com.fasterxml.jackson.databind.JsonNode
import com.fasterxml.jackson.databind.JsonSerializer
import com.fasterxml.jackson.databind.PropertyNamingStrategies
import com.fasterxml.jackson.databind.SerializerProvider
import com.fasterxml.jackson.databind.module.SimpleModule
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
import com.flipkart.zjsonpatch.JsonDiff
import org.bson.types.ObjectId

typealias DiffValueTracker = Map<String, DiffValue<String, String>>
typealias DiffTriple = Triple<String, String, String>

object DiffComparisonManager {

    private val diffMapper = jacksonObjectMapper()
        .apply {
            registerModules(
                SimpleModule().apply {
                    propertyNamingStrategy = PropertyNamingStrategies.SNAKE_CASE
                    addSerializer(ObjectId::class.java, ObjectIdSerializer())
                }
            )
        }

    fun <T> calculateDifference(
        originItem: T,
        newItem: T
    ): DiffValueTracker {
        val originalNode = diffMapper.valueToTree<JsonNode>(originItem)
        val newNode = diffMapper.valueToTree<JsonNode>(newItem)
        val diff = JsonDiff.asJson(originalNode, newNode)
        return when {
            diff.size() > 0 -> {
                diff.mapNotNull { diffNode ->
                    val (path, originValue, newValue) = extractDiffValue(diffNode, originalNode, newNode)
                    Pair(
                        first = path,
                        second = DiffValue(originValue, newValue)
                    )
                }
                    .toMap()
            }
            else -> emptyMap()
        }
    }

    fun <T, K, S> calculateDifferences(
        originItems: List<T>,
        newItems: List<T>,
        associateByKey: (T) -> K,
        groupByKey: (T) -> S
    ): Map<S, DiffValueTracker> {
        val originalAssociate = originItems.associateBy(associateByKey)
        val newAssociate = newItems.associateBy(associateByKey)
        val changes = newAssociate.flatMap { (id, newItem) ->
            val originalItem = originalAssociate[id]
            when {
                originalItem != null -> {
                    val originalNode = diffMapper.valueToTree<JsonNode>(originalItem)
                    val newNode = diffMapper.valueToTree<JsonNode>(newItem)
                    val diffNode = JsonDiff.asJson(originalNode, newNode)

                    when {
                        diffNode.size() > 0 -> {
                            diffNode.mapNotNull { node ->
                                val (path, originValue, newValue) = extractDiffValue(node, originalNode, newNode)

                                Triple(
                                    first = groupByKey(newItem),
                                    second = path,
                                    third = DiffValue(origin = originValue, new = newValue)
                                )
                            }
                        }
                        else -> emptyList()
                    }
                }
                else -> emptyList()
            }
        }

        return changes
            .groupBy({ it.first }, { it.second to it.third })
            .mapValues { (_, value) -> value.toMap() }
    }

    private fun extractDiffValue(node: JsonNode, originalNode: JsonNode, newNode: JsonNode): DiffTriple {
        val path = node.get("path").asText().removePrefix("/")
        val originValue = originalNode.at("/$path").asText()
        val newValue = newNode.at("/$path").asText()
        return DiffTriple(path, originValue, newValue)
    }
}

data class DiffValue<out A, out B>(
    val origin: A,
    val new: B
)

class ObjectIdSerializer : JsonSerializer<ObjectId>() {
    override fun serialize(value: ObjectId, gen: JsonGenerator, serializers: SerializerProvider) {
        gen.writeString(value.toString())
    }
}

3. 코드 상세 설명#

3.1 Jackson ObjectMapper 설정#

1
2
3
4
5
6
7
8
9

private val diffMapper = jacksonObjectMapper()
    .apply {
        registerModules(
            SimpleModule().apply {
                propertyNamingStrategy = PropertyNamingStrategies.SNAKE_CASE
                addSerializer(ObjectId::class.java, ObjectIdSerializer())
            }
        )
    }

• Snake Case 변환: Kotlin의 camelCase 필드명을 JSON의 snake_case로 자동 변환합니다
• ObjectId 직렬화: MongoDB의 ObjectId를 문자열로 변환하는 커스텀 Serializer를 등록합니다
• 이를 통해 productName → product_name으로 자동 변환되어 일관된 필드명으로 추적할 수 있습니다

3.2 calculateDifference 함수#

단일 객체 간의 차이를 계산하는 핵심 함수입니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

fun <T> calculateDifference(
    originItem: T,
    newItem: T
): DiffValueTracker {
    // 1. Kotlin 객체를 JsonNode로 변환
    val originalNode = diffMapper.valueToTree<JsonNode>(originItem)
    val newNode = diffMapper.valueToTree<JsonNode>(newItem)
    
    // 2. JsonDiff로 차이 계산
    val diff = JsonDiff.asJson(originalNode, newNode)
    
    // 3. 차이가 있으면 변경 정보 추출
    return when {
        diff.size() > 0 -> {
            diff.mapNotNull { diffNode ->
                val (path, originValue, newValue) = extractDiffValue(diffNode, originalNode, newNode)
                Pair(
                    first = path,
                    second = DiffValue(originValue, newValue)
                )
            }.toMap()
        }
        else -> emptyMap()
    }
}

동작 과정:

1. 객체를 JsonNode로 변환: Kotlin 객체를 Jackson의 JsonNode로 변환하여 JSON 구조로 다룰 수 있게 합니다
2. JsonDiff 계산: JsonDiff.asJson()을 사용하여 두 JsonNode 간의 차이를 계산합니다
3. 변경 정보 추출: 각 diff node에서 경로(path), 이전 값(originValue), 새 값(newValue)을 추출합니다
4. 결과 반환: Map<String, DiffValue> 형태로 반환합니다

• Key: 필드 경로 (예: customer/contact/address/street)
• Value: DiffValue(origin, new) 객체

3.3 extractDiffValue 함수#

1
2
3
4
5
6

private fun extractDiffValue(node: JsonNode, originalNode: JsonNode, newNode: JsonNode): DiffTriple {
    val path = node.get("path").asText().removePrefix("/")
    val originValue = originalNode.at("/$path").asText()
    val newValue = newNode.at("/$path").asText()
    return DiffTriple(path, originValue, newValue)
}

• path 추출: diff node에서 변경된 필드의 경로를 추출합니다 (예: /customer/contact/address/street)
• 슬래시 제거: 경로 앞의 /를 제거하여 깔끔한 key로 만듭니다
• 값 추출: JsonNode의 at() 메서드로 해당 경로의 값을 추출합니다
• Triple 반환: (경로, 이전값, 새값)을 하나의 Triple로 반환합니다

3.4 calculateDifferences 함수 (복수 객체 처리)#

여러 객체를 비교할 때 사용하는 함수입니다.

1
2
3
4
5
6

fun <T, K, S> calculateDifferences(
    originItems: List<T>,
    newItems: List<T>,
    associateByKey: (T) -> K,      // 매칭용 키 (예: ID)
    groupByKey: (T) -> S            // 그룹화용 키
): Map<S, DiffValueTracker>

• associateByKey: 원본과 새로운 데이터를 매칭하기 위한 키 (예: orderId, productId)
• groupByKey: 결과를 그룹화하기 위한 키
• 여러 객체를 한 번에 처리하고 각 객체별 변경사항을 그룹화하여 반환합니다

테스트 코드로 검증하기#

다양한 케이스를 테스트하여 구현이 올바르게 동작하는지 확인했습니다.

1. 단일 필드 변경 감지#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@Test
fun `calculateDifference - 단일 객체의 변경 사항을 감지한다`() {
    // Given
    val originalProduct = Product(
        productId = "PROD001",
        productName = "노트북",
        category = Category("전자제품", "컴퓨터")
    )
    val newProduct = Product(
        productId = "PROD001",
        productName = "울트라 노트북",
        category = Category("전자제품", "컴퓨터")
    )

    // When
    val result = DiffComparisonManager.calculateDifference(originalProduct, newProduct)

    // Then
    then(result).hasSize(1)
    then(result["product_name"]).isNotNull
    then(result["product_name"]?.origin).isEqualTo("노트북")
    then(result["product_name"]?.new).isEqualTo("울트라 노트북")
}

결과:

1
2
3
4
5
6

{
  "product_name": {
    "origin": "노트북",
    "new": "울트라 노트북"
  }
}

2. 중첩된 객체의 변경 감지#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@Test
fun `calculateDifference - 중첩된 객체의 변경 사항을 감지한다`() {
    // Given
    val originalProduct = Product(
        productId = "PROD001",
        productName = "노트북",
        category = Category("전자제품", "컴퓨터")
    )
    val newProduct = Product(
        productId = "PROD001",
        productName = "노트북",
        category = Category("전자제품", "노트북")
    )

    // When
    val result = DiffComparisonManager.calculateDifference(originalProduct, newProduct)

    // Then
    then(result).hasSize(1)
    then(result["category/sub_category"]).isNotNull
    then(result["category/sub_category"]?.origin).isEqualTo("컴퓨터")
    then(result["category/sub_category"]?.new).isEqualTo("노트북")
}

결과:

1
2
3
4
5
6

{
  "category/sub_category": {
    "origin": "컴퓨터",
    "new": "노트북"
  }
}

중첩 객체의 필드는 category/sub_category 형태로 경로가 명확히 표시됩니다.
슬래시(/)를 구분자로 사용하여 객체의 계층 구조를 표현하므로, 어떤 깊이의 중첩 객체라도 경로만으로 정확한 위치를 파악할 수 있습니다.

3. 여러 필드 동시 변경 감지#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26