wo_dbs

2GB 서버를 지키는 가장 싼 방법 Rate Limiter 도입기

재윤 — Sat, 4 Jul 2026 14:03:09 +0900

저희 서비스에 요청률 제한을 넣으며 어디에, 어떤 알고리즘으로, 초과 시 어떻게 결정한 기록입니다. 그리고 실제로 부하를 걸어 검증한 글입니다.

1. 왜 넣게 되었는가

통합 검색을 개선하는 과정에서 조회를 최적화해도 동시 요청이 많아지면 결국 응답이 느려진다는 걸 체감했습니다.

(관련 글: https://wo-dbs.tistory.com/419)

통합 검색에서는 다음과 같이 SLO를 세웠었습니다.

DAU 1,000 규모(피크 동시 약 50명)에서, 통합검색을 p95 700ms 이내로 SLI 95% 이상 유지

개선 한 후 동시 접속자를 30 → 110명을 5분간 램프업하여 부하 테스트를 했을 때 요청은 전부 성공했지만 동시 사용자가 늘수록 응답이 점점 느려졌습니다.

동시 VU	SLI	상태
30	~100%	여유
50	~99.5%	양호
70	~97%	저하 시작
90	~86%	저하
110	~57%	붕괴

SLO 목표는 SLI 95%이상이었습니다. 피크로 예상하는 동시 50명까진 99.5%로 여유롭게 만족하고 70명까지도 97%로 버팁니다. 하지만 90명에서 86%로 SLO선을 깨고 110명에선 57%까지 추락하였습니다.

병목은 통합 검색의 LIKE 쿼리였습니다. 인덱스를 타지 못하는 LIKE '%keyword%'가 캐시에 올라온 행을 CPU로 훑으며 문자열을 하나씩 비교하다 보니 동시 요청이 늘수록 CPU 부하가 그만큼 커졌습니다. (자세한 분석은 위 글에 있습니다.)

병목은 통합 검색의 LIKE 쿼리였습니다. 인덱스를 타지 못하는 LIKE '%keyword%'가 캐시에 올라온 행을 CPU로 훑으며 문자열을 하나씩 비교하다 보니, 동시 요청이 늘수록 CPU 부하가 그만큼 커졌습니다. (자세한 분석은 위 글에 있습니다.)

실제로 이 부하 구간에서 CPU는 100%까지 완전히 포화됐습니다.

결론은 초과 트래픽은 하나의 API만 느려지는 것이 아니라 전체를 끌어내리게 됩니다. CPU를 나눠 쓰는 만큼 정상 범위의 사용자까지 같이 느려지고, 스파이크 한 번이 모두의 SLO를 깨게 됩니다.

그래서 Rate Limiter를 도입해, 감당 가능한 범위를 넘는 트래픽을 앞단에서 걸러 SLI를 지키기로 했습니다.

2. 어디에 넣을까

Rate Limiter를 넣을 수 있는 위치는 요청이 지나는 경로 마다 있습니다.

핵심 원칙은 요청은 뒤로 갈 수록 비싸다는 것입니다.

같은 요청 하나라도 어디까지 도달했다가 거절되느냐에 따라 이미 소모한 자원이 완전히 다릅니다.

현재 서버는 다음과 같이 구성되었습니다.

클라이언트 → NGINX → Spring → PostgreSQL

각 위치에서의 트레이드 오프를 생각해본다면 다음과 같았습니다.

NGINX에서 거절 → 가장 쌉니다. NGINX에 하게 된다면 초과 요청에 429만 돌려주면 끝이라, JVM 스레드도 DB 커넥션도 건드리지 않습니다.
Spring까지 도달 → 이미 톰캣 스레드 하나를 점유합니다. 스레드 풀은 유한한데 요청 파싱, 필터 체인, JWT 인증을 다 거친 뒤라 거절해도 그 비용은 이미 지불한 상태입니다.
PostgreSQL까지 도달 → 가장 비쌉니다. DB 커넥션 풀의 한 자리를 잡게 됩니다

즉 요청이 깊이 들어갈 수록 더 자원을 소모합니다 그래서 NINGX에서 진행하기로 하였습니다.

또한, 어떤 기준으로 셀 것인지도 고민해보았습니다.

IP 기준 → NGINX에서 바로 적용하기 쉽다는 장점이 있지만 하나의 공유기나 회사 네트워크처럼 여러 같은 IP를 사용하는 경우 정상 사용자들이 함께 제한될 수 있었습니다. 또한, 공격자가 여러 IP를 바꿔가며 요청하면 IP 기준 제한을 우회할 수도 있습니다.
사용자 ID 기준 → 정확하게 제한할 수 있다는 장점이 있습니다. 하지만 사용자 ID를 알기 위해서 Spring까지 들어와야합니다.

현재 목적은 서버 자원을 최대한 앞단에서 보호하는 것이라고 생각했습니다. 그래서 우선 NGINX에서 처리할 수 있는 IP 기준을 적용하기로 하였습니다.

3. 어떤 알고리즘으로 제한할 것인가?

알고리즘 후보를 놓고 비교했습니다.

알고리즘	특징	판단
Fixed Window	구현 쉬움, 경계에서 최대 2배 통과	허점 때문에 제외
Sliding Log	가장 정확, 메모리 큼	저사양엔 과함
Sliding Counter	정확·가벼움 절충	좋지만 NGINX 기본 아님
Leaky Bucket	출력 평탄화, NGINX limit_req 기본	채택
Token Bucket	버스트 허용	nodelay로 유사 효과

NGINX limit_req는 내부적으로 Leaky Bucket입니다. 여기에 burst와 nodelay를 얹으면 정상적인 순간 버스트는 통과시키고 지속적인 남용만 막는 형태가 됩니다.

이 부분이 중요한 이유는 실제 앱이 켜지는 순간 프로필, 목록 등 API 여러 개를 동시에 호출합니다 이걸 초당 1개로 딱 잘라보리면 정상 사용자가 막히게 됩니다. nodelay로 버스트 한도 내 요청을 즉시 통과시키되 그 한도를 넘겨 계속 때리는 트래픽만 차단하도록 생각했습니다.

# http 블록: IP당 존 정의 (10m ≈ 16만 IP 추적)
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

server {
    # 일반 API
    location /api/ {
        limit_req zone=api burst=20 nodelay;
        limit_req_status 429;
        proxy_pass http://spring_upstream;
    }

    # 헬스체크 및 메트릭은 제한에서 제외
    location /actuator/ {
        proxy_pass http://spring_upstream;
    }
}

rate=10r/s - 장기 평균 허용 속도
burst=20 - 순간 몰림 20개까지 큐 허용
nodelay - 버스트분을 지연 없이 즉시 통과 (Token Bucket처럼)
limit_req_status 429 - 초과 시 기본 503 대신 429 반환

4. 초과하면 어떻게?

초과할 경우 HTTP 429 Too Many Requests 반환하도록 하였습니다. 503의 반환을 생각하였지만 서버 장애가 일어났다기 보다 요청이 그저 많다고 보여주는 게 더 좋다고 생각했습니다

또한, Retry-After 헤더로 언제 재시도할 수 있는지 알려주는 방면을 생각해보았고 health 및 정적 리소스는 제외시켰습니다.

429 카운트 메트릭으로 수집해서 얼마나 어느 엔드포인트에서 걸리는지 모니터링도 구축하였습니다. 그 후 임계값(rate/burst)을 튜닝을 할 수 있다고 생각하였습니다.

5. 테스트 - 실제로 부하를 걸어 검증

1장의 부하 테스트에서 CPU가 100%까지 포화됐던 것을, 이번엔 NGINX rate limit(IP당 10r/s, burst 20)을 건 상태로 같은 스크립트를 그대로 돌려 비교했습니다. k6는 한 대(= IP 하나)에서 쏘므로, 이 테스트는 곧 단일 클라이언트가 폭주하는 시나리오입니다.

항목	제한 전	제한 후
시스템 CPU (2 vCPU)	100% 포화	~10–25% (idle 50–90%)
통과(200) 요청 p95	962 ms (SLO 초과)	137 ms (SLO 안 ✓)
통과(200) 요청 p95	962 ms (SLO 초과 ✗)	137 ms (SLO 안 ✓)
429 (차단)	0	99.6%
메모리	574 MiB	573 MiB (동일)

폭주한 요청의 99.6%를 NGINX가 429로 컷하자 인덱스 없는 LIKE 스캔이 애초에 DB까지 도달하지 못했습니다. 그 결과 CPU가 포화에서 풀리고(idle 0% → 50~90%), 제한을 통과한 요청은 p95 137ms로 SLO(700ms) 한참 안쪽에서 응답했습니다.

즉 1차의 "전부 받아서 다 같이 962ms로 느려지기"가, 2차에서는 "초과는 429로 버리고, 통과분은 137ms로 빠르게" 로 바뀌었습니다. Rate Limiter가 SLO를 지켜내었습니다.

Rate Limiter

재윤 — Sat, 4 Jul 2026 13:59:30 +0900

1. Rate Limiter란

정해진 시간 안에 허용되는 요청 수를 제한하는 장치입니다.

목적으로는 다음과 같습니다.

남용/DDoS 방어, 서버 자원 보호(특히 2GB 같은 저사양)
공정한 사용(한 유저가 자원 독점 방지)
비용 제어(외부 API 호출량 등)

그러면 위 목적으로 사용하되 분명히 알아야할 것이 있습니다.

rate limiter가 요청이 왔을 때 어떤 걸로 카운터를 셀 것인가.
이 요청에 대해 통과를 시킬까 막을까에 대한 수학적 방법 == 알고리즘
알고리즘 코드가 어느 서버/ 어느 층에서 도느냐. 즉, 요청이 지나가는 경로 중 어디에 rate limiter를 심을 것이냐

→ 그래서 Rate Limiter를 도입할 때는 다음과 같은 문장이 완성되어야합니다

[3번. NGINX 에서] [1번. IP 기준으로] [2번. Token Bucket 방식으로] 분당 10개 제한한다

1,2,3번에 대한 각각 부분을 좀 더 세밀하게 공부해도록 하겠습니다.

무엇을 기준으로 셀까? (Key)

분당 10개 제한이라고 하였을 때 누구/무엇의 10개냐를 정하는 것입니다. 카운터를 무슨 단위로 묶을지.

기준(key)	의미	쓰는 곳
IP 주소	이 IP에서 온 요청을 셈	NGINX 기본, 익명 트래픽
유저 ID	로그인한 이 사람 요청을 셈	로그인 후 API
API 키	이 키(외부 개발자)로 온 요청	공개 API
IP + 엔드포인트	이 IP가 /login에 온 것만 셈	로그인 brute-force 방어

이 기준이 중요한 이유는 기준을 잘못 잡으면 엉뚱하게 막히게 됩니다. 예를 들어서

IP로만 세면 → 회사/카페 같은 IP 쓰는 100명이 한 덩어리로 묶여 억울하게 차단.
유저 ID로 세면 → 정확하지만 로그인 안 한 요청(회원가입, 로그인 자체)은 유저ID가 없어서 못 셈.

그래서 상황마다 key를 다르게 구분하는 것도 생각을 해봐야합니다. 로그인 전엔 IP, 로그인 후엔 유저 ID형태

어떤 알고리즘으로 셀까

어떻게 세느냐" 의 방식입니다. 이 알고리즘들은 크게 5가지 정도가 있습니다. 이 알고리즘들은 같은 분당 10개라도 세는 방식에 따라 동작이 달라집니다.

각 알고리즘들을 공부해보았습니다. 전부 분당 5개 허용 기준으로 공부해보았습니다.

Fixed Window Counter (고정 윈도우)

시간을 고정 구간으로 쪼개고, 구간마다 카운터를 세는 방법입니다.

[10:00:00~10:00:59] 카운터=0 → 요청마다 +1, 5 넘으면 거부
[10:01:00~10:01:59] 카운터=0으로 리셋

장점은 구현 초간단 (Redis INCR + EXPIRE 한 줄)하고, 메모리 소비량이 작습니다.

단점으로는 정말 치명적인 문제가 있습니다. 구간 경계에서 최대 2배까티 통과할 수 있는 경계 문제(burst at boundary)가 있습니다.

10:00:59 에 5개  +  10:01:00 에 5개
→ 실제로 1초 사이에 10개가 몰림 (한도 5인데!)

이 알고리즘은 시간을 딱 잘린 구간으로 나누고 구간이 바뀌면 카운터를 0으로 리셋합니다. 경계문제는 실제 흐르는 시간이 아니라 시계의 정각 기준으로 돌리게 됩니다.

구간 A: [10:00:00 ~ 10:00:59]   카운터 A
구간 B: [10:01:00 ~ 10:01:59]   카운터 B  ← 10:01:00 되는 순간 0으로 리셋

카운터 A와 B는 서로를 전혀 모릅니다. A가 5개를 다 썼든, 말든, B는 10:01:00에 0에서 시작합니다.

그러면 타임라인으로

시각        요청   구간   카운터        판정
─────────────────────────────────────────────
10:00:57    1개    A     A=1           통과
10:00:58    1개    A     A=2           통과
10:00:59    3개    A     A=3,4,5       통과 (A 꽉 참)
─────────── 10:01:00 정각, 카운터 리셋! ───────────
10:01:00    3개    B     B=1,2,3       통과 (B 새 구간!)
10:01:01    2개    B     B=4,5         통과 (B 꽉 참)

각 구간만 보면 A도 5개, B도 5개로 규칙을 지켰습니다. 하지만

문제의 핵심은 “구간 경계를 걸친 실제 시간 창”입니다.

10:00:57 ~ 10:01:01 이라는 실제 연속된 5초를 보면

A에서 5개 (10:00:57~59) + B에서 5개 (10:01:00~01) = 10개

어떤 연속된 1분(예: 10:00:30~10:01:29)을 잘라봐도 최대 10개가 들어올 수 있습니다. 한도는 5인데 실제론 2배(10개)가 통과해버린 것입니다.

즉, 규칙은 분당 5개인데 구간 경계 근처에 몰아치면 짧은 시간에 2배를 뚫을 수 있습니다.

쉽게 말하면 시간을 자르는 방식이 2가지 종류이기 때문입니다.

A: 알고리즘이 자르는 창 - 시계 정각 기준으로 고정
B: 실제로 우리가 지키고 싶은 창 - 아무 60초

Fixed Window는 A로만 검사하는데 B는 어느 구간을 봤을 때 한도를 넘을 수 있다느 것입니다.

그러면 이 문제가 왜 심각하냐면 이 알고리즘은 정각~정각 사이 5개만 보장합니다. 근데 공격자가 B방식으로 (정각을 걸쳐서) 자르면 10개가 잡히게 됩니다. 즉 알고리즘은 A로 5개 지켰다고 하는데 실제 세상에서는 10개가 들어온 것입니다.

그래서 Fixed Window는 자기가 정한 위치(정각)에서만 5개를 보장하고 다른 위치(경계 걸침)에선 최대 10개가 되는 걸 못 습니다.

Sliding Window Log (슬라이딩 로그)

모든 요청의 타임스탬프를 리스트로 저장하는 방식입니다. 매 요청마다 지금부터 1분 이내 개수를 셉니다.

요청 올 때: 1분 지난 타임스탬프 제거 → 남은 개수 < 5 면 허용하고 현재시각 기록

장점은 가장 정확하고 Fixed Window에서 나온 경계 문제가 없습니다.

하지만 단점으로는 요청마다 타임스탬프를 다 저장해야하기에 메모리를 많이 먹습니다. 초당 수천 요청이면 폭팔할 수도 있습니다. 구현은 Redis Sorted Set으로 구현할 수 있지만 비용이 비싸게 됩니다.

또한, 추가적인 단점으로는 clock skew(시계 오차)가 있습니다.

분산처리에서는 각 서버의 시계가 완벽히 똑같지 않습니다. NTP로 맞추어도 수십~수백ms씩 차이가 날 수 있습니다.

Spring #1 시계: 10:00:00.000
Spring #2 시계: 10:00:00.300   ← 300ms 빠름

Sliding Window Log는 지금부터 1분 이내 타임스탬프를 세는데 이 지금(현재시각)과 저장되는 타임스탬프를 누가 찍느냐가 문제가 됩니다.

만약 각 인스턴스가 자기 로컬 시계로 타임스탬프를 찍어서 Redis에 넣으면

#1이 찍은 10:00:59.900  과  #2가 찍은 10:01:00.100
→ 실제론 #2 시계가 빨라서 진짜 순서가 뒤바뀔 수도
→ "1분 이내" 판정이 인스턴스마다 미묘하게 달라짐

이것이 창 경계 계산이 어긋나서 한도를 살짝 초과 통과시키거나, 반대로 억울하게 일찍 거부할 수도 있습니다.

해결책으로는 시계를 하나로 통일할 수 있습니다. 즉, 단일 시계 하나를 기준으로 삼는 방법입니다.

Redis 자신의 시간을 쓴다. 이 방법은 제일 흔한 방법입니다.
NTP로 서버 시계 동기화 → 오차를 줄이지만 0으로 만들진 못한다. == 보조 방법
작은 오차는 그냥 감수

Sliding Window Counter (슬라이딩 카운터)

Fixed Window의 가벼움과 Sliding Log의 정확함을 합친 버전입니다. 즉, 현재 윈도우 + 이전 윈도우 카운터를 가중 평균한 것입니다.

현재 윈도우 진행률이 30%라면:
추정치 = 이전윈도우_카운트 × (1 - 0.3) + 현재윈도우_카운트
       = 이전 5개 × 0.7 + 현재 2개 = 5.5 → 5 초과 → 거부

예시를 들어 한 번 자세하게 보겠습니다.

카운터를 2개 유지하게 됩니다. → 이전 구간, 현재 구간

이전 윈도우 [10:00:00~10:00:59]  카운트 = 5
현재 윈도우 [10:01:00~10:01:59]  카운트 = 2
지금 시각 = 10:01:18   → 현재 윈도우 18초 지남 = 진행률 30%

이 알고리즘의 목표는 지금 기준 뒤로 60초를 보는 것입니다.

지금이 10:01:18이니

진짜 보고 싶은 창 = [10:00:18 ~ 10:01:18]  (딱 60초)

이 60초 창을 그림으로 보면 두 구간에 거려있습니다

이전 윈도우                     현재 윈도우
[10:00:00 ────────── 10:00:59][10:01:00 ──── 10:01:18 ──── 10:01:59]
          |◄── 겹침 (70%) ──►||◄─ 겹침(30%) ─►|
       10:00:18                            10:01:18

이전 윈도우의 뒤쪽 70% (10:00:18~10:00:59)가 겹침
현재 윈도우의 앞쪽 30% (10:01:00~10:01:18)가 겹침

문제는 이전 윈도우 요청이 언제 왔는지 모릅니다.

→ 이전 윈도우에 5개가 왔다는 거는 알 수 있지만 그게 앞에 몰렸는지 뒤에 몰렸는지에 대한 기록이 없습니다.. 그래서 고르게 퍼져 있다고 가정합니다.

고르게 퍼졌다면 겹치는 70% 구간엔 5개 중 70%인 3.5개가 있다고 추정합니다.

이전 윈도우 기여분 = 5 × 0.7 = 3.5

현재 윈도우 2개는 지금 창 안에 확실히 있으니 그대로

현재 윈도우 기여분 = 2

추정치 = 3.5 + 2 = 5.5 → 한도 5 초과 → 거부

공식을 정리하면 다음과 같습니다.

추정치 = 이전카운트 × (1 - 진행률) + 현재카운트

(1-진행률)이 왜 이전 윈도우 가중치냐면 현재 윈도우가 진행될 수록 60초 차으이 꼬리가 이전 윈도우 밖으로 빠져나가서 겹치는 부분이 점점 줄어들게 됩니다.

진행률 0%  (10:01:00): 창 = [10:00:00~10:01:00] → 이전 윈도우 전체 겹침 → 가중치 1.0
진행률 30% (10:01:18): 이전 윈도우 70% 겹침       → 가중치 0.7
진행률 50% (10:01:30): 이전 윈도우 50% 겹침       → 가중치 0.5
진행률 100%(10:01:59): 이전 윈도우 0% 겹침         → 가중치 0.0

즉 시간이 갈수록 이전 윈도우의 영향력이 선형적으로 사라집니다. 그게 1 - 진행률 입니다.

장점으로는 메모리가 적고 경계 문제는 대두분 해결 됩니다. 보통 NGINX, 대형 서비스가 실제로 많이 쓰는 방법입니다.

단점으로는 근사치라 100% 정확하지는 않다는 것입니다.

Token Bucket (토큰 버킷)

이 알고리즘은 버킷에 토큰이 일정 속도로 채워지고, 요청은 토큰 1개를 소모하게 됩니다. 토큰이 없으면 거부하게 됩니다.

버킷 용량 = 5 (최대 저장)
채우는 속도 = 분당 5개 (12초에 1개)

- 요청 오면 토큰 1개 소모
- 안 쓰면 토큰이 쌓임(최대 5까지) → 잠깐 몰리는 burst 허용
- 비어 있으면 거부

조금 더 자세하게 본다면 비유부터 하자면 동전 저금통이라고 볼 수 있습니다. (위 예제를 좀 더 분석)

12초 마다 동전(토큰) 1개가 저금통에 자동으로 떨어집니다.
저금통은 최대 5개까지만 담깁니다. (넘치면 버려짐)
요청 1개 = 동전 1개 꺼내 쓰기 동전 옶으면 거부

안 쓰고 놔두면 동전이 5개까지 쌓이며 그러면 그 수간 5개를 한 번에 꺼내 쓸 수 있습니다. 이것이 brust입니다.

타임라인으로 보다면 다음과 같습니다.

시각      이벤트              토큰 잔량    판정
──────────────────────────────────────────────
10:00:00  시작 (가득)          5
          ...1분간 아무 요청 없음...  (충전돼도 5가 max라 그대로)
10:01:00  토큰 = 5 (꽉 참)     5

10:01:00  요청 1              5→4        통과
10:01:00  요청 2              4→3        통과
10:01:00  요청 3              3→2        통과   ← 같은 순간에
10:01:00  요청 4              2→1        통과      5개가
10:01:00  요청 5              1→0        통과   ← 한꺼번에 통과! (burst)
10:01:00  요청 6              0          거부 (토큰 없음)

10:01:12  (12초 경과, +1 충전) 0→1
10:01:12  요청 7              1→0        통과

10:01:00에 동시에 5개가 몰렸지만 다 통과했습니다. 평소에 안 써서 토큰 5개를 쌓여뒀기 때문이죠. 하지만 6번째는 즉시 거부 그리고 그 뒤론 12초에 1개씩만 통과하게 됩니다.

2개의 파라미터가 각각 뭘 정하는지 본다면

Token Bucket은 이 두 개로 움직입니다.

파라미터	의미	위 예시
충전 속도 (refill rate)	장기 평균 허용 속도	12초당 1개 = 분당 5개
버킷 용량 (capacity)	한 번에 몰아칠 수 있는 최대량 (burst 크기)	5개

충전 속도는 길게 보면 결국 이 속도로 수렴한다를 정하게 됩니다. 버스트로 5개 써버려도 그 후엔 12초당 1개 페이스로 강제됩니다.
용량은 얼마나 몰아칠 수 있나를 정하게 됩니다. 용량이 크면 큰 버스트 허용 작으면 빡빡하게 진행 됩니다.

장점은 현실 트래픽은 뚝뚝 끊겨서 요청이 몰려옵니다 예를 들어

사용자가 앱을 켜는 순간 API 5~6개 동시에 호출(프로필 + 알림 + 목록..)
평소엔 조용하다가 이 순간만 확 몰리게 됩니다.

초당 1개로 딱 자르는 (leaky bucket 식 - 밑에서 하게 됩니다) 방식이면 이 정상적인 앱 켜기도 막혀서 사용자 경험이 나빠집니다. Token Bucket은 평소 안 쓴 토큰을 쌓아뒀다가 이 순간 버트스를 허용하니 정상 사용자는 매끄럽게 쓰고, 지속적인 남용만 막습니다.

또 다른 장점으로는 상태가 토큰수/시각 2개뿐이라 가볍습니다.

사용되는 곳들은 bucket4j(자바), AWS API Gateway, Stripe 등. NGINX limit_req의 burst 옵션이 이 개념입니다.

Leaky Bucket (리키 버킷)

이 알고리즘은 요청을 큐에 넣고 일정 속도로만 처리하는 방법입니다. 큐가 다 차면 거부하게 됩니다

큐 처리 속도 = 12초에 1개 (분당 5개)
요청 → 큐에 쌓임 → 일정 속도로 빠져나감 → 큐 꽉 차면 거부

비유로 하면 바닥에 구멍 뚫린 양동이 입니다.

위에서 물(요청)이 아무 속도로나 쏟아져 들어오게 되빈다.
바닥 구멍으로는 항상 일정한 속도로만 물이 빠져나가게 됩니다(12초 1개)
양동이가 넘치면(큐가 꽉 차면) 그 물은 버려집니다.(거부)

들어오는 건 들쭉날쭉해도, 나가는 건 무조건 일정합니다.

타임라인으로 보면 (처리속도 12초당 1개, 큐 용량 5)

시각      들어옴   큐 상태          나감(처리)     비고
─────────────────────────────────────────────────────────
10:00:00  5개 몰림  [■■■■■] (5/5)    -            5개가 확 들어와 큐에 쌓임
10:00:00  +1개      큐 꽉참!          -            → 거부 (넘침)

10:00:12  -        [■■■■_] (4/5)    1개 처리   12초마다
10:00:24  -        [■■■__] (3/5)    1개 처리   1개씩
10:00:36  -        [■■___] (2/5)    1개 처리   일정하게
10:00:48  -        [■____] (1/5)    1개 처리   빠져나감
10:01:00  -        [_____] (0/5)    1개 처리

10:00:00에 5개가 동시에 몰렸지만, 실제 처리는 12초 간격으로 하나씩 나가게 됩니다. 요청들은 큐에서 기다렸다가 순서대로 처리됩니다. 6번째는 큐가 꽉 차서 거부.

즉 출력이 완벽하게 평탄합니다. 아무리 몰려와도 뒷단 예를 들어 Spring/DB엔 항상 12초에 1개씩 전달됩니다.

Token Bucket과의 결정적 차이는

	Token Bucket	Leaky Bucket
양동이에 든 것	토큰(허가증)	요청(대기열)
요청 처리	토큰 있으면 즉시 통과, 없으면 거부	큐에 넣고 기다렸다가 일정속도로 처리
지연(대기)	없음 (통과 아니면 거부)	있음 (큐에서 대기)
출력 모양	버스트 가능 (쌓인 토큰만큼 순간 폭발)	항상 평탄 (일정 속도)
성격	버스트 허용	버스트 평탄화(흡수)

그림으로

입력:          ●●●●● (5개 동시에)

Token Bucket:  ●●●●● ────────    ← 쌓인 토큰으로 5개 즉시 통과, 그 후 거부/대기
Leaky Bucket:  ● ─ ● ─ ● ─ ● ─ ● ← 5개를 일정 간격으로 하나씩 흘려보냄

Token: 지금 몰아쳐도 돼(토큰 있으면). 대신 순간 부하는 뒷단이 감당해야 함.
Leaky: 몰아쳐도 뒷단엔 일정하게만 갈게. 대신 요청들은 기다려야 함(지연).

즉 Token은 응답이 빠른 대신 뒷단에 순간 부하, Leaky는 뒷단이 편한 대신 요청에 지연이 생기게 됩니다. 트레이드오프가 반대입니다.

NGINX limit_req에 매핑이 되게 됩니다. NGINX가 딱 이 Leaky Bucket 방식입니다.

limit_req_zone $binary_remote_addr zone=api:10m rate=5r/m;

location /api/ {
    limit_req zone=api burst=5;          # ← 큐 용량 = 5
}

rate=5r/m = 구멍에서 빠지는 속도 (12초당 1개).
burst=5 = 큐(양동이) 크기. 초과분을 5개까지 대기시킴.
큐 넘으면 → 503/429 거부.

nodelay 옵션의 의미:

limit_req zone=api burst=5 nodelay;

nodelay 없으면: burst 요청을 큐에 넣고 천천히(12초 간격) 처리 → 요청이 지연됨(순수 leaky).
nodelay 있으면: burst 한도 내 요청을 기다리게 하지 않고 즉시 통과시킴 → 이 순간만은 Token Bucket처럼 동작. (대신 토큰 자리는 여전히 rate 속도로 회복)

실무에서는 burst=N nodelay을 많이 쓴다고 합니다. 정상적인 순간 몰림은 즉시 통과시키되 지속적 남용은 막는 절충

Leaky를 쓰는 상황은

뒷단(DB, 외부 API)이 일정 속도 이상 못 버틸 때 - 무조건 평탄하게 흘려보내야 안전
트래픽 shaping(대역폭 제어, 결제/외부 연동 호출량 조절 등).
반대로 사용자 대면 API에서 응답 지연이 싫으면 Token Bucket(또는 nodelay)이 나음.

요약 비교표

알고리즘	정확도	메모리	버스트	구현 난이도
Fixed Window	낮음(경계문제)	적음	경계서 2배 샘	매우 쉬움
Sliding Log	최고	많음	없음	중간
Sliding Counter	높음	적음	거의 없음	중간
Token Bucket	높음	적음	허용	쉬움
Leaky Bucket	높음	적음	평탄화	중간

어디서 셀까

카운팅 로직을 어느 위치에 둘거냐를 말해볼 수 있습니다. 다음은 예시 입니다.

클라이언트 → [CDN/WAF] → [NGINX/게이트웨이] → [애플리케이션] → [DB]
              (엣지)        (네트워크, IP)       (유저/비즈니스)

엣지(CDN/WAF): 대규모 DDoS 흡수. Cloudflare 등.
게이트웨이/NGINX: IP 단위 거친 제한. 요청이 앱에 닿기 전 차단 → 제일 쌈.
애플리케이션: 유저, API키, 등급별 정밀 제한. 비즈니스 규칙 반영.

"앞단에서 거를수록 싸다"라고 말할 수 있습니다. 뒤로 갈수록 이미 자원을 쓴 뒤라 비싸게 됩니다. 즉, 위치에 따라 비용과 정밀도가 트레이드오프가 됩니다.

분산 환경의 어려움 (Redis)

인스턴스가 여러 개면 카운터를 공유해야 함 여기서 2가지 함정이 있습니다.

1. 원자성(atomicity) / race condition

동시에 두 요청이:
  read 카운터=4  →  둘 다 "4<5니까 OK"  →  둘 다 +1  →  실제 6 (한도 초과!)

read-modify-write가 쪼개지면 초과 통과하게 됩니다. Redis Lua 스크립트나 INCR(원자적 연산)로 "읽고-검사-증가"를 한 번에 처리해야 함. bucket4j-redis 같은 라이브러리가 이걸 해주게 됩니다.

2. 네트워크 비용

매 요청마다 Redis 왕복 → 지연 추가. 그래서 로컬 캐시 + 주기적 동기화 같은 최적화도 있습니다.

실무 (HTTP 규약)

초과 시 429 Too Many Requests 반환.
헤더로 상태 알려주기

RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 30          (초 후 리셋)
Retry-After: 30              (재시도까지 대기 초)

key 전략: IP / 유저ID / API키 / (IP+엔드포인트) 조합. 로그인 API는 IP+계정 조합으로 brute-force 방어.
Fail-open vs fail-closed: rate limiter(Redis)가 죽으면? 요청을 통과시킬지(open, 가용성 우선) 막을지(closed, 보안 우선) 미리 정해두기.

Docker 및 Docker Compose 도입 - 7/1

재윤 — Thu, 2 Jul 2026 11:36:41 +0900

들어가며

저희 서비스의 운영 서버는 2GB인 한 대로 운영하고 있습니다. 하지만 성능을 업그레이드를 하면서 스펙이 점점 올라가기 시작했습니다. NGINX, Spring Boot, PostgreSQL, 그리고 관측성을 위한 Grafana Alloy까지 올라갔습니다

여기에 검색 성능을 위한 Redis 고려와 CI/CD 파이프라인까지 붙이려는 시점이 되게 되었습니다.

서비스가 이 정도로 늘어나니 서버에 그때그때 손으로 설치하고 실행하는 방식이 한계에 부딪혔습니다. 이 글은 그 한계를 어떻게 느꼈고 왜 Docker와 Docker Compose를 선택했으며 2GB라는 제약 안에서 어떤 선택을 했는지 에 대한 기록입니다.

1. 왜 Docker인가

1.1 서비스가 늘어나면 수동 관리가 무너진다

서버에 현재 다음을 전부 설치한다고 생각해보았을 때

NGINX 설치 · 설정
JDK 설치 + Spring 실행 스크립트
PostgreSQL 설치 · 버전 관리
Grafana Alloy 바이너리
(예정) Redis

버전이 충돌하고 설정 파일이 서버 곳곳에 흩어지고 이 서버에 뭐가 깔려 있더라를 기억에 의존하게 됩니다.

서비스가 1~2개면 그냥 설치해도 되지만 6개쯤 되면 격리와 조합이 필요한 임계점이 오게 됩니다.

Docker는 각 서비스를 컨테이너로 격리하고 그 실행 환경을 이미지 하나에 담는다. 이 서버에 뭐가 깔려 있는가가 기억이 아니라 코드(docker-compose.yml)로 남게 됩니다.

1.2 CI/CD의 배포 단위가 필요했다

사실 Docker 도입의 가장 정직한 방아쇠는 CI/CD였습니다. CI/CD를 제대로 하려면 "빌드 산출물"을 서버로 옮겨 실행해야 하는데 그 산출물이 JAR 파일이면 여전히 "서버에 JDK 버전 맞고, 환경변수 맞고…"를 신경 써야 합니다. 반면 Docker 이미지는 실행 환경까지 통째로 담은 배포 단위입니다.

CI에서 docker build → 레지스트리에 push
서버에서 docker pull → docker compose up -d

CI에선 됐는데 서버에선 안 됨이 구조적으로 사라집니다. 롤백도 이전 이미지 태그로 다시 up 하면 끝나게 됩니다.

1.3 로컬 = 운영 환경 일치

새로 Redis를 구축하기 전에 이 이점이 특히 와닿았습니다. Compose 파일에 몇 줄 추가하는 것만으로 로컬에도 운영과 같은 버전의 Redis가 뜨게 됩니다. "내 로컬에 Redis 깔고 버전 맞추고…" 하는 온보딩 비용이 사라집니다.

2. 왜 Docker Compose인가

Docker(컨테이너화)를 왜? → 환경을 코드로 고정하고 어디서든 똑같이 뜨게 만들 수 있습니다.
Compose를 왜? → 그 컨테이너가 여러 개(NGINX + Spring + PG + Redis + Alloy)니까 한 파일로 묶어 한 번에 관리할 수 있습니다.

Compose는 다중 서비스 스택을 하나의 선언적 파일로 정의하고 docker compose 명령 하나로 전체를 재현할 수 있습니다.

서비스 간 통신도 서비스명으로 해결되고(db:5432, redis:6379),
기동 순서(depends_on), 전용 네트워크, 볼륨, 리소스 상한까지 전부 코드로 남는다. 특히 저희 서비스는 리소스 상한이 되게 중요하기 때문에 이것이 가장 도움이 될 것이라고 생각했습니다.

3. 2GB와의 싸움

서비스를 컨테이너로 나누는 것과 별개로 총 메모리는 여전히 2GB입니다. 현실적인 예산을 짜보게 되었습니다.

컴포넌트	대략 RAM
OS + Docker 데몬	200~400MB
Spring Boot (JVM)	400~700MB
PostgreSQL	200~400MB
NGINX	20~50MB
Grafana Alloy	100~200MB
Redis (캐시)	50~150MB

총합은 대략 1.2~1.8GB 나오게 됩니다. 2GB에서 돌아가긴 하지만 여유가 거의 없습니다. 트래픽이 튀거나 JVM GC가 돌 때 OOM으로 컨테이너가 죽을 수 있게 됩니다.

그래서 다음 세 가지를 안전장치로 걸게 되었습니다.

1. 스왑(swap)

2GB에선 스왑이 사실상 필수다. 순간 스파이크에 프로세스가 즉사하는 걸 막는다.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# /etc/fstab 에 등록해 재부팅 후에도 유지

2. JVM 힙 명시적 제한 & 서비스별 메모리 상한

한 프로세스가 폭주하는 걸 막을 수가 있습니다.
컨테이너 안의 JVM은 호스트 전체 메모리를 보고 힙을 크게 잡으려다 터지게됩니다. 그래서 힙을 명시하였습니다

spring:
  environment:
    - JAVA_OPTS=-Xms256m -Xmx512m -XX:MaxMetaspaceSize=128m
  mem_limit: 700m
postgres:
  mem_limit: 400m
redis:
  mem_limit: 150m
  command: redis-server --maxmemory 120mb --maxmemory-policy allkeys-lru

마치며

돌아보면 모든 결정이 "2GB 단일 서버"라는 하나의 제약에서 나오게 되었습니다.

서비스가 늘어 수동 관리가 한계 → Docker
6개 서비스를 한 파일로, 리소스 상한까지 → Compose
메모리가 빠듯해서 → JVM 힙 제한, mem_limit, swap

제약이 오히려 선택을 명확하게 만들어주게 되었습니다.

통합검색 성능 개선기

재윤 — Thu, 2 Jul 2026 11:35:20 +0900

1. 배경, 목표, 그리고 개선 방향

1.1 배경 및 목표

저희 서비스에는 통합검색 기능이 있습니다. 검색어 하나를 넣으면 보관함, 일정, 링크, 텍스트, 파일 5종을 한 번에 찾아줍니다. 그런데 이 API는 한 번 호출될 때마다 5개 테이블을 전부 검색하게 되었습니다.

사용자가 자료를 수천 개씩 쌓고 여러 명이 동시에 검색하면 과연 버틸 수 있을까? 이 막연한 불안에서 이 개선을 시작하게되었습니다.

1. SLO

SLI = 700ms 이내에 성공한 검색 요청 수 / 전체 검색 요청 수
SLO = SLI ≥ 95%

검색의 기준선이 필요했습니다. 사용자 응답성 연구와 SRE의 latency SLO 설계 방식을 참고해 700ms를 초기 기준으로 잡았습니다. (제일 참고 부분에 첨부하였습니다.)

2. 동시 접속자의 한계

부하가 걸렸을 때도 700ms를 지키는 가에 대한 한계를 숫자로 정확하게 알아야했습니다. DAU 1,000명을 가정하더라도 1,000명이 동시에 들어오는 것이 아니라 하루에 흩어져 들어와 잠깐씩 쓴다는 가정이 필요했습니다. 그래서 DAU를 동시 접속자로 환상해야했고 Little’s Law로 접근했습니다.

평균 동시 인원(L) = 도착률(λ) × 체류시간(W)
≈ (하루 사용자 수 ÷ 하루 이용 시간대) × 1인 세션 시간 = (1,000명 ÷ 12시간) × 8분 ≈ 11명

가정은 이렇게 넣었습니다.

1인 세션 = 8분 활동
하루 이용 시간대 = 12시간 - 한 사람의 이용 시간이 아니라 사용자들이 하루 중 들어오는 시간 폭. 새벽엔 거의 안 쓰니 깨어 있는 12시간 동안 흩어져 들어온다고 봤습니다.

평균 동시 사용자는 약 11명. 다만 트래픽은 몰리는 시간대가 있으니 피크를 그 4~5배로 보고 동시 약 50명을 목표로 잡았습니다.

3. 목표

DAU 1,000 규모(피크 동시 약 50명)에서, 통합검색을 p95 700ms 이내로 SLI 95% 이상 유지

2. 기존 구조와 문제점

2.1 기존 구조

통합검색은 5개 테이블을 다음과 같이 조회합니다.

WHERE users_id = ? AND status = 'ACTIVE'
  AND lower(컬럼) LIKE lower('%검색어%')

2.2 부하 테스트 설계

서버가 동시 몇 명까지 버티나(용량)부터 재기로 했고 그러려면 두 가지의 준비가 필요했습니다.

1. 더미 데이터

데이터	일반 유저 1명	헤비 유저 1명	상한
보관함	100	100	유저당 100개 (앱 제한)
일정	1,000	10,000	없음
링크	1,000	10,000	없음
텍스트	1,000	10,000	없음
파일	1,000	5,000	총 5GB (평균 1MB → 5,000개)
합계	약 4,100행	약 35,100행

일반 유저 29명 + 데이터를 많이 쌓아둔 헤비 유저 1명으로 구성했습니다.

2. 동시 사용자를 흉내 낼 방법

k6로 동시 사용자(VU)를 천천히 올리며, SLI(700ms 이내 비율) 패널로 관찰했습니다.

2.3 부하 테스트로 드러난 문제

우선, 극단을 봤습니다. 똑같은 단어로 검색하면 유저의 모든 데이터가 한 응답에 담기게 했습니다. 동시 사용자를 10 → 50 → 100 → 150 → 200명으로 올렸습니다.

지표	값
SLI(700ms)	0%
p95	35초
실패율	66% (500 에러)
전송량	910MB

가장 빠른 요청조차 2.9초였습니다. 500는 Broken pipe이었습니다. 거대한 JSON을 직렬화하는 도중 클라이언트가 60초 타임아웃으로 먼저 끊어버려 서버가 닫힌 소켓에 쓰다 실패한 것이었습니다.

그런데 이 결과로는 "동시 몇 명까지 버티나"를 알 수 없었습니다. 여기서 무너진 건 검색 처리 능력이 아니라 응답 크기였기 때문입니다. 그래서 변수를 하나로 좁혔습니다. 데이터 일부에만 단어를 심어 검색 결과가 유저당 50건만 나오게 맞추고 동시 접속자를 10 ~ 30명으로 줄였습니다.

동시	사용자 SLI(700ms 이내)
10명	100%
15명	100%
20명	~99%
25명	~85%
30명	~60%

단일 요청은 44ms로 빠른데도 동시 20명까지는 SLO를 지키다 25명부터 무너지기 시작해 30명에서 60%로 떨어졌습니다. 전체 p95 984ms, 처리량 36 req/s) 즉 개선 전 용량은 동시 약 20명. 목표(동시 50명)의 절반에도 못 미쳤습니다.

SLO를 지키지 못하는지 원인을 파악하기 위해 쿼리 실행 계획과 CPU 상태를 보았습니다.

Seq Scan on schedules
  Rows Removed by Filter: 39,005   ← 읽고 버린 행
  Buffers: shared hit=534          ← 전부 메모리(캐시)에서 읽음 (디스크 0)
  (actual ... rows=10)             ← 실제로 찾은 행

테이블엔 30명 전원의 39,015행이 섞여 있는데 전부를 한 줄씩 읽어 10건만 건지고 39,005행을 버립니다. 그리고 Buffers: shared hit이 말해주듯 이 읽기는 디스크가 아니라 메모리(캐시)에서 일어납니다. 디스크 대기가 아니라 순수 CPU로 3.9만 행을 훑고 문자열 비교(LIKE) 하는 작업이고 이게 5개 테이블에서 매 요청마다 반복됩니다.

CPU는 mpstat 명령어로 확인했습니다.

usr 97% idle 0% iowait 0%
- idle 0% → CPU 완전 포화
- iowait 0% → 디스크 대기 아님

즉 병목은 디스크도 메모리도 아닌 CPU였습니다. 인덱스 없는 풀스캔이 매 요청마다 5개 테이블에서 수만 행을 CPU로 훑고 있었고, 동시 사용자가 늘자 CPU가 가장 먼저 포화됐습니다.

3. 개선 1 - 인덱스 추가

풀스캔을 없애는 것이 첫 목표였습니다. 하지만 함정이 하나 있었습니다.

LIKE '%검색어%'는 인덱스를 못 탄다

가장 먼저 든 생각은 "검색하는 컬럼에 인덱스를 걸면 되지 않나?"였습니다. 하지만 PostgreSQL에서 LIKE '%검색어%'(앞 와일드카드)는 일반 btree 인덱스를 타지 못합니다. 인덱스는 앞에서부터 정렬된 자료구조라 '검색어%'처럼 앞이 고정돼야 쓸 수 있는데, '%검색어%'는 앞이 열려 있어 결국 전 행을 훑을 수밖에 없습니다. 검색어 컬럼에 인덱스를 걸어도 LIKE 자체는 빨라지지 않습니다. 방향을 바꿔야 했습니다.

검색은 항상 사용자 PK로 먼저 거르게 되었습니다. 테이블엔 30명 전원의 3.9만 행이 섞여 있지만 한 요청이 실제로 봐야 할 건 그 유저의 행뿐이라 LIKE가 훑는 대상이 전체 3.9만 행에서 그 유저의 약 1,000행으로 줄어듭니다.

CREATE INDEX idx_schedules_users_status ON schedules (users_id, status);
- 보관함 링크, 텍스트, 파일 4개 테이블도 동일하게
ANALYZE ...;

같은 쿼리의 실행 계획을 인덱스 전후로 떠봤습니다.

	인덱스 전	인덱스 후
실행 방식	Seq Scan (풀스캔)	Bitmap Index Scan
읽고 버린 행	39,005	990
읽은 페이지	534	22
쿼리 시간	5.1ms	0.68ms

읽고 버린 행이 39,005에서 990으로 줄었습니다. 읽은 페이지도 534 → 22로 떨어지며 단일 쿼리가 약 7.5배 빨라졌습니다.

개선 전과 똑같은 부하 테스트(동시 10→30명) 를 다시 돌렸습니다.

지표	개선 전	개선 후
p95 응답시간	984ms	464ms
처리량	36 req/s	85 req/s
SLI (동시 25명)	85%	~99.9%
SLI (동시 30명)	60%	~99.3%

전엔 25명부터 무너져 30명에서 SLI 60%였던 것 인덱스 후엔 30명까지 99% 이상으로 버텼습니다.

처리량은 약 2.4배(36→85 rps), p95는 절반 이하가 됐습니다. 용량으로 보면 동시 ~20명 → ~30명 으로 올라간 셈입니다.

하지만, 30명 구간에서 SLI가 딱 100%가 아니라 99.3%까지 미세하게 내려왔습니다. 부하 중 서버 CPU를 보니 여전히 ~92%로 높았습니다. 저는 CPU가 뭐 때문에 병목인지 궁금해졌습니다.

SQL은 EXPLAIN상 0.68ms로 빠른데 CPU가 높다는 건 비용이 SQL이 아니라 그 바깥 어딘가에 있다는 뜻이라고 생각했습니다. 그래서 부하 중 async-profiler로 CPU 플레임그래프를 떠서 직접 확인했습니다.

각 프레임이 자기 코드에서 직접 쓴 시간(self-time)을 패키지별로 묶어봤습니다

패키지(self-time)	비중
native / syscall / JIT	27.9%
JDK util (String, HashMap …)	24.6%
GC	13.8%
AWS/S3	12.4%
Hibernate/JPA	6.5%
Spring/AOP proxy	4.3%
기타	나머지

상위 개별 프레임을 봐도 HashMap, String같은 것들뿐이라, 원인은 보이지 않았습니다. native와 JDK util만 잔뜩 크고 정작 순수 Hibernate는 6.5%인데 그렇다고 ORM이 싸다고 결론 내리기엔 동시에 String 및 HashMap이 비정상적으로 컸습니다.

알고보니 self-time 패키지 별로 묶는 것은 그 순간 CPU가 물리적으로 어느 코드 줄에 있었나를 셉니다. 그런데 하나의 작업이 여러 패키지로 흩어지면 원인이 분해돼 버리는 것을 알게되었습니다. 메서드 단위인 inclusive로 다시 집계했습니다. 흩어졌던 비용이 원인 하나로 모이자 그림이 완전히 바뀌었습니다.

CPU 소비처	비중
S3 presigned URL 생성 (첨부 검색, 행마다)	42.6%
GC	15.6%
엔티티 하이드레이션 + DTO (4개 검색)	~18%
보관함 이름 조회	7.8%

통합검색 search() - 71.0%
- searchFiles(첨부) - 50.0%
  - S3 presigned URL 생성 - 42.6%
- searchLinks / Texts / Schedules / Folders ~18%
- FoldersService.findById - 7.8%
- GC -15.6%

병목은 검색 결과인 파일의 S3 presigned URL을 동기로 서명 및 생성하는 것이었습니다.

4. 개선 2 - 검색 결과의 S3 서명 제거

현재 통합검색 결과 화면은 이 URL을 즉시 쓰지 않으므로(상세 진입 시 발급해도 충분), 목록 응답에서는 서명을 생성하지 않도록 제거한 후, 부하 테스트(동시 10→30명)를 다시 돌렸습니다. 결과는 다음과 같습니다.

지표	인덱스 후	서명 제거 후
p95 응답시간	464.16ms	291.84ms (−37%)
p90	377.51ms	237.65ms
평균	224.23ms	157.13ms
최댓값	1.06s	759.65ms
처리량	84.6 req/s	120.5 req/s (+42%)
실패율	0.00%	0.00%
총 처리 요청	27,082	38,555
SLI(동시 30명)	~99.3%	~100%

요청을 1.1만 건 더 처리했고 p95는 절반 가까이, 처리량은 약 1.4배가 됐습니다.

부하 구간 내내 100% 라인에 붙어 있었지만, 정확히는 딱 100%가 아니었습니다. 21:35 한 지점에서 99.983%까지 미세하게 내려왔습니다.

약 0.017%의 요청만 700ms를 넘겼다는 뜻입니다.
38,555건 기준 대략 6~7건 수준이고, k6의 max=759.65ms가 바로 그 꼬리(tail)입니다.

드물게 700ms를 넘기는 꼬리가 아직 남아 있었습니다. 이 원인을 파악하기 위해 똑같이 플레임그래프를 측정해보았습니다.

CPU 소비처	제거 전	제거 후	계층
통합검색 search	71.0%	58.0%	최상위
GC	15.6%	5.1%	최상위
기타	나머지	나머지	최상위
JPA 쿼리 실행 및 매핑	-	~34%	통합 검색 search
findById	-	13.8%	통합 검색 search
기타 (AOP 프록시, DTO 생성 등)	-	~10%	통합 검색 search
쿼리 해석, 플랜, SQL 변환	-	22.2%	JPA 쿼리 실행 및 매핑
JDBC 드라이버	-	7.7%	JPA 쿼리 실행 및 매핑
JPQL 파싱	-	2.6%	JPA 쿼리 실행 및 매핑
하이드레이션(엔티티 생성)	-	1.2%	JPA 쿼리 실행 및 매핑

플레임그래프에서 FoldersService.findById가 13.8% 를 차지한다는 점이었습니다. 이 프레임은 그래프에 세 번(링크, 텍스트, 파일 안) 따로 잡혀 있었고 코드를 열어보니 원인을 알게 되었습니다.

for (AttachMents a : files) {                                  // 결과 행 N개
    String foldersName = foldersService.findById(a.getStorageId()).getName(); // 행마다 +1 쿼리
}

이 코드에서 검색 쿼리가 조건에 맞는 파일들을 한 번에 가져온 후 결과가 N개 행이라고 하면 그다음 루프가 그 행들을 돌면서 행마다 foldersService.findById(...)로 보관함 이름을 다시 조회합니다. 실제로 DB에 나가는 SQL을 세어보면

SELECT ... FROM attachments WHERE ... ;   -- 검색: 1번
SELECT ... FROM folders WHERE folders_id=?;  -- 1번째 행
SELECT ... FROM folders WHERE folders_id=?;  -- 2번째 행
...                                          -- N번째 행

즉 검색 1번 + 보관함 조회 N번 = 총 1 + N번의 쿼리가 나가고 있었습니다. 검색 결과가 100건이면 화면 하나에 쿼리가 101번 날아가는 셈입니다. 이것이 바로 N+1 문제라는 것을 알게 되었습니다

findById가 13.8%(links 7.2% + texts 3.3% + files 3.3%)까지 올라온 것도 이 세 곳의 반복 조회가 합쳐진 결과였습니다.

5. 개선 3 - N+1 제거 : DTO 프로젝션 + JOIN

N+1 해법은 보통 세 가지인데, 이 코드의 구조가 선택지를 좁혔습니다.

fetch join은 적용이 불가능했습니다. 보관함이 @ManyToOne이 아니라 경로식을 못 사용했습니다.
EntityGraph 같은 경우도 fetch join과 같은 방향이었습니다.
DTO 프로젝션은 연관관계 없이 조인이 가능하였습니다.

파일, 링크, 텍스트는 보관함을 연관관계가 아니라 FK로 들고 있어서 fetch join 및 entity graph는 쓸 수가 없었습니다. 게다가 이 둘은 N+1만 없앨 뿐 엔티티를 그대로 부풀려 로딩합니다. 반면 DTO 프로젝션은 N+1과 하이드레이션을 동시에 없앱니다. 그래서 DTO 프로젝션을 선택했습니다.

레포지토리 - DTO를 직접 select 및 Folders를 ON절로 JOIN

@Query("""
    select new com.toit.items.attachments.dto.response.AttachMentsFilesGetInFoldersResponse(
        a.attachmentsId, a.storageId, a.attachmentsType, a.objectKey,
        a.attachmentsExtension, a.attachmentsSize, a.fileName, a.createdAt,
        f.name, a.textContent)
    from AttachMents a
    join Folders f on f.foldersId = a.storageId
    where a.users.usersId = :usersId
      and a.status = :status
      and a.attachmentsType = :type
      and lower(coalesce(a.fileName, '')) like lower(concat('%', :keyword, '%'))
    order by a.createdAt desc
""")
List<AttachMentsFilesGetInFoldersResponse> searchFilesWithFolder(...);

→ 엔티티 하이드레이션도 생략. 링크 및 텍스트도 동일 패턴으로 적용했습니다.

CPU 소비처 및 지표	서명 제거 후	N+1 제거 후
findById	13.8%	0%
통합검색 search() 전체	58.0%	35.0%
p95	291.84ms	296.41ms
처리량	120.5 rps	112.5 rps
실패율	0%	0%

검색 전체 CPU가 58%에서 35%로 내려갔습니다.

6. 마무리

애플리케이션 병목을 걷어낸 뒤, 이 서버가 동시 몇 명까지 버티는지 한계를 다시 재보았습니다. k6로 VU(동시 사용자)를 1분 간격으로 30 → 50 → 70 → 90 → 110명까지 단계적으로 올렸고 동시에 서버의 CPU 및 메모리를 함께 기록했습니다.

부하 단계별 SLI (700ms 내 응답 비율)

동시 VU	SLI	상태
30	~100%	여유
50	~99.5%	양호
70	~97%	저하 시작
90	~86%	저하
110	~57%	붕괴

p95 1.02s, 처리량 127 rps, 실패율 0%. 동시 ~50명까지는 SLI 99%로 버티지만 70명부터 무너지기 시작하고 110명에선 절반 이상의 요청이 700ms를 넘겼습니다.

서버 CPU를 뜯어보니 부하 최고 구간의 시스템 전체과 자바 프로세스을 같이 봤습니다.

시스템 전체 (2 vCPU): usr ~93%, iowait 0%, idle 0%
자바 프로세스: %CPU ~50~63% (200% 중) → 약 0.5 코어만 사용

여기서 두 가지를 읽을 수 있었습니다.

usr가 93% : CPU가 커널 처리나 대기가 아니라 순수 유저 공간의 계산으로 포화됐다.
자바는 0.5 코어뿐 : 나머지 ~1.4 코어는 앱이 아닌 다른 프로세스 즉 DB(PostgreSQL) 가 쓰고 있었다.

LIKE 스캔은 Buffers: shared hit(디스크 읽기 0, 전부 메모리 캐시)로 돌고 있었습니다. 즉 DB는 디스크를 기다리는 게 아니라 캐시에 올라온 행을 CPU로 훑으며 문자열을 비교(LIKE) 하고 있었던 것입니다. 인덱스를 못 타는 LIKE '%keyword%'가 DB의 CPU를 태우고 있었습니다.

6.1 한 줄 요약

통합검색을 EXPLAIN, async-profiler, k6로 측정하며 병목을 하나씩 걷어냈습니다. 인덱스로 풀스캔을, 프로파일링으로 S3 서명(CPU 42.6%)을, JOIN으로 N+1을 제거해 p95 984ms → 292ms, 처리량 36 → 120 rps, 용량 동시 20명 → 50명으로 끌어올렸습니다. 그리고 마지막 한계 테스트에서 다음 병목(DB CPU)의 위치까지 확인했습니다.

레퍼런스

Jakob Nielsen, Response Time Limits (Nielsen Norman Group)
Google Search Central / web.dev, Core Web Vitals - INP (200ms good, 500ms poor)
Google, SRE Workbook - Implementing SLOs (percentile 기반 latency SLI)

Spring의 요청 처리 순서

재윤 — Thu, 2 Jul 2026 11:35:06 +0900

Spring에서 요청이 왔을 때 어떻게 되는지 하나하나 보려고 합니다. 하기 전에 알아야할 부분이 있습니다.

1. OSIV가 항상 인터셉터인 것은 아님.

Spring boot MVC에서는 보통 OpenEntityManagerInViewInterceptor 형태로 동작한다고 보면 되고 직접 OpenEntityManagerInViewFilter를 등록할 수도 있습니다.

그래서 흐름은 2가지로 나누게 됩니다.

OSIV Interceptor 방식: [필터들] → [DispatcherServlet] → [OSIV Interceptor] → [Controller]
OSIV Filter 방식: [OSIV Filter] → [다른 필터들] → [DispatcherServlet] → [Controller]

2. Repository 호출마다 미니 트랜잭션이 생기는지는 상황에 따라 다르다.

서비스 메서드에서 @Transactional이 없으면, Spring Data JPA Repository의 기본 메서드나 @Transactional(readOnly=true)가 붙은 조회 메서드는 자체적으로 짧은 트랜잭션을 열 수 있습니다.
하지만 서비스에 큰 @Transactional이 있으면 Repository들은 전부 그 하나의 트랜잭션에 참여합니다.
서비스에 @Transactional 없음: Repository 조회마다 짧은 트랜잭션 가능
서비스에 @Transactional 있음: 서비스 시작 시 트랜잭션 1개 시작, 그 안에서 Repository 여러 개 호출, 서비스 종료 시 한 번에 commit

0단계: 애플리케이션이 떠 있는 상태

사용자 요청이 오기전에 Spring boot 애플리케이션은 이미 실행되어있습니다.

main()
SpringApplication.run()
ApplicationContext 생성
내장 Tomcat 기동
Spring MVC / Security / JPA / DataSource 준비

대략 다음과 같은 것들이 만들어집니다.

[웹 계층]

내장 Tomcat
DispatcherServlet
HandlerMapping
HandlerAdapter
MessageConverter, 예: Jackson
Servlet Filter들
Spring Security FilterChain
HandlerInterceptor들

[스프링 빈]

Controller
Service
UseCase
Repository 프록시
TransactionManager
DataSource
EntityManagerFactory

[JPA/DB]

EntityManagerFactory
JpaTransactionManager
HikariCP 커넥션 풀
Hibernate 설정
엔티티 메타데이터

[보안]

SecurityFilterChain
JWT 필터
AuthenticationProvider 등

여기서 중요한 객체가 2개가 있습니다.

EntityManagerFactory = EntityManager를 만드는 공장
EntityManager = 실제 요청 중 엔티티를 관리하는 영속성 컨텍스트 역할

1단계 : 톰캣이 요청을 받음

클라언트가 요청을 다음과 같이 보냈다고 가정해보겠습니다.

GET /page/search?keyword=회의
Authorization: Bearer xxx.yyy.zzz

그러면 OS 소켓을 통해 톰캣으로 들어옵니다.

Client → (TCP) → OS Socket → Tomcat 8080 Listen

톰캣은 요청을 처리할 워커 스레드를 하나 배정합니다.

요청 1개 → Tomcat Worker Thread 1개 배정

이 스레드가 요청 처리의 중심이 되됩니다.

Tomcat Worker Thread → Filter → DispatcherSErvlet → Controller → Service → Repository → JSON 직렬화 → 응답 완료

그래서 우리가 말하는 스레드에 바인딩 된다는 말은 이 톰캣 워커 스레드에 묶인다는 뜻입니다.

대표적으로 이런 것들이 스레드에 묶입니다.

SecurityContext = 현재 인증 사용자 정보
EntityManager = 현재 요청의 영속성 컨텍스트
Transaction 정보 = 현재 트랜잭션 상태
DB Connection = 현재 트랜잭션에 연결된 커넥션

2단계 : 톰캣이 HTTP 요청을 Servlet 요청 객체로 만듦

톰캣은 HTTP 텍스트를 파싱합니다.

GET /page/search?keyword=회의 HTTP/1.1
Host: example.com
Authorization: Bearer xxx.yyy.zzz

그리고 Servlet API 객체를 만듭니다.

HttpServletRequest
HttpServletResponse

이제 자바 코드에서는 HTTP 요청을 문자열로 직접 파싱하지 않고 request 객체로 다루게 됩니다.

그 다음 톰캣은 이 요청을 DispatcherServlet으로 보낼 준비를 합니다. 하지만 그 전에!!

Servlet Filter Chain을 먼저 탑니다.

3단계 : Servlet Filter Chain 실행

필터는 DispatcerServlet 보다 앞에 있습니다.

순서는 = HttpServletRequest → CharacterEncdoingFilter → CorsFilter → Spring Security FilterChain → Custom Filter → DispatcherServlet

CharacterEncodingFilter → 요청/응답 인코딩을 맞춥니다 ex) UTF-8 설정
CORS Filter → 프론트엔드 도메인이 다른 경우 CORS 정책을 검사합니다 ex) Origin 검사, Access-Control-Allow-Origin 설정, preflight OPTIONS 처리
Spring Security FilterChain → 보안 필터들이 실행됩니다.
- 대략 == SecurityContextHolderFilter → JwtAuthenticationFilter → AUthorizationFilter
- JWT 인증 = Authorization 헤더 읽기 → Barer 토큰 추출 → JWT 서명 검증 → 만료 시간 검증 → userId, role 추출 → Authentication 객체 생성 → SecurityContextHolder에 저장

이후 컨트롤러에서는 다음과 같은 형식으로 사용자 정보를 꺼낼 수 있습니다.

SecurityContextHolder.getContext().getAuthentication();

Long usersId = SecurityUtil.getCurrentUserId();

이 시점의 상태로 봤을 때 OSIV가 인터셉터 방식이면 아직 영속성 컨텍스트는 없습니다.

현재 상태:

Tomcat Worker Thread 있음
HttpServletRequest 있음
SecurityContext 있음
EntityManager 없음
트랜잭션 없음
DB Connection 없음

즉, 일반적인 OSIV Interceptor 기준으로 필터 단계에서 JPA Lazy Loading을 하면 위험합니다.

Filter에서 Lazy Loading 시도 → EntityManager 없음 → LazyInitializationException 가능

단 OSIV를 Filter로 직접 등록하고 보안 필터보다 앞에 두면 필터에서도 EntityManager가 있을 수 있다. 하지만 일반적으으로는 필터 단계에는 아직 JPA 영속성 컨텍스트가 없다고 보는 게 안전합니다.

4단계 : DispatcherServlet 진입

필터를 다 통과하면 DispatcherServlet이 요청을 받습니다.

DispatcherServlet.doDispatch()

이 서블릿은 Spring MVC의 중앙 관제탑입니다. 하는 일은 다음과 같습니다.

4.1 HandlerMapping으로 컨트롤러 찾기
4.2 Interceptor preHandle 실행
4.3 HandlerAdapter로 컨트롤러 호출
4.4 컨트롤러 반환값 처리
4.5 JSON 변환 또는 View 렌더링
4.6 Interceptor afterCompletion 실행

HandlerMapping에서 요청 URL과 HTTP Method를 보고 어떤 컨트롤러 메서들르 호출할지 찾습니다.

GET /page/search
   ↓
PageSearchViewController.search()

이때 @GetMapping, @PostMapping, @RequestMapping 정보가 사용됩니다.

5단계 : OSIV Interceptor preHandle

HandlerMapping으로 컨트롤러를 찾은 뒤 인터셉터의 preHandle()이 실행됩니다.

OSIV가 켜져 있으면 여기서 EntityManager를 만듭니다.

OpenEntityManagerInViewInterceptor.preHandle()
   ↓
EntityManager 생성
   ↓
영속성 컨텍스트 생성
   ↓
현재 톰캣 워커 스레드에 바인딩

정확히는 Spring의 TransactionSynchronizationManager에 바인딩됩니다.

현재 Thread → TransactionSynchronizationManager → EntityManagerHolder → EntityManager

이 요청 스레드에서 JPA를 사용하면 이 EntityManger를 재사용합니다.

이 시점에서 열리는 것이

열림: EntityManager, 영속성 컨텍스트

아직 안 열림: DB 트랜잭션, DB 커넥션

OSIV가 연 것은 상자라고 봐야합니다.

영속성 컨텍스트 == 엔티티 담는 상자

하지만 아직 DB 작업 단위인 트랜잭션은 시작하지 않았습니다.

6단계 : 컨트롤러 호출 준비

컨트롤러 메서드를 호출하기 전에 Spring MVC가 파라미터를 준비합니다.

예를 들어 컨트롤러가 다음과 같다고 해보겠습니다.

@GetMapping("/page/search")
public ResponseEntity<PageSearchResponse> search(
        @RequestParam("keyword") String keyword
) {
    Long usersId = SecurityUtil.getCurrentUserId();
    return ResponseEntity.ok(pageSearchUseCase.search(usersId, keyword));
}

Spring MVC는 이런 일을 합니다.

6.1 @RequestParam("keyword") 읽기
6.2 request parameter에서 keyword 값 꺼내기
6.3 String 타입으로 변환
6.4 컨트롤러 메서드 인자로 넣기

만약 @RequestBody가 있으면 Jackson이 먼저 JSON을 객체로 바꾸게 됩니다.

HTTP Body JSON
   ↓
Jackson
   ↓
Request DTO

7단계 : 컨트롤러 실행

이제 컨트롤러가 실행됩니다.

public ResponseEntity<PageSearchResponse> search(String keyword) {
    Long usersId = SecurityUtil.getCurrentUserId();
    PageSearchResponse response = pageSearchUseCase.search(usersId, keyword);
    return ResponseEntity.ok(response);
}

흐름은 이렇게 됩니다.

7.1 SecurityContext에서 userId 꺼냄
7.2 UseCase 또는 Service 호출
7.3 응답 객체를 ResponseEntity로 감쌈

현재 상태는 다음과 같습니다.

Tomcat Worker Thread 있음
SecurityContext 있음
EntityManager 있음
트랜잭션은 아직 없을 수 있음
DB Connection도 아직 없을 수 있음

이제 핵심인 서비스로 간다.

8단계 : Service/ UseCase 진입

여기서 2가지 경로로 봐야하는데

A. UseCase에 @Transactional이 있음
B. UseCase에 @Transactional이 없음

우선 A로 진행하고 마지막에 B경로를 보겠습니다.

예를 들어 이렇게 되어 있다고 하자.

@Transactional(readOnly = true)
public PageSearchResponse search(Long usersId, String keyword) {
    Users user = usersService.findById(usersId);
    List<FolderDto> folders = foldersService.searchFolders(user, keyword);
    List<ScheduleDto> schedules = schedulesService.searchSchedules(user, keyword);
    List<LinkDto> links = linksService.searchLinks(user, keyword);
    List<TextDto> texts = textsService.searchTexts(user, keyword);
    List<FileDto> files = attachMentsService.searchFiles(user, keyword);

    return new PageSearchResponse(folders, schedules, links, texts, files);
}

이 경우 컨트롤러가 실제 객체를 바로 호출하지 않습니다.

Controller → UseCase Proxy → TransactionInterceptor → 실제 UseCase 객체

이제 @Transactional AOP가 동작합니다.

9단계 : @Transactional AOP가 실제로 하는일

이 부분을 세부 단계로 나눠서 봐야 합니다.

9.1 프록시가 호출을 가로챔

컨트롤러는 pageSearchUseCase.search()를 호출한다고 생각하지만, 실제로는 프록시가 먼저 받게 됩니다.

Controller → PageSearchUseCase Proxy → TransactionInterceptor

프록시는 @Transactional이 붙이 있는지 확인한다.

9.2 트랜잭션 설정 읽음

@Transactional에는 여러 설정이 있습니다.

@Transactional(readOnly=true)

프록시는 이런 정보들을 읽습니다.

readOnly = true
propagation = REQUIRED // 이미 트랜잭션이 있으면 참여 없으면 새로 시작
isolation = DEFAULT
rollbackFor = RuntimeException/Error 기본

현재 컨트롤러에서 서비스로 처음 들어가는 상황이면 보통 트랜잭션이 없습니다. 그래서 새로 시작합니다.

9.3 현재 스레드에서 EntityManager 확인

OSIV가 켜져 있다면 5단계에서 이미 EntityManager가 만들어져 있습니다.

현재 스레드 → TransactionSynchronizationManager → EntityManagerHolder 있음

그래서 @Transactional은 새 EntityManager를 만들지 않고 OSIV가 만들어 둔 EntityManager를 사용합니다. == OSIV가 만든 EntityManager → @Transactional이 트랜잭션을 붙임

만약 OSIV가 꺼져있다면 이 시점에 EntityManager를 새로 만든다.

OSIV OFF → @Transactional 시작 → EntityManager 생성 → 트랜잭션 종료 시 EntityManager close

9.4 트랜잭션 시작

JpaTransactionManager가 트랜잭션을 시작합니다.

JpaTransactionManager → EntityManager에 트랜잭션 시작 요청 → DB Connection 준비

이제부터 이 서비스 메서드 안에서는 DB 변경을 하나의 작업 단위로 묶을 수 있습니다.

Service 시작 → 여러 Repository 호출 → 모두 성공하면 commit, 중간에 실패하면 rollback

9.5 DB Connection 획득

트랜잭션이 시작되면서 또는 실제 SQL이 필요한 시점에 HikariCP에서 커넥션을 가져옵니다.

EntityManger/Hibernate → DataSource → HikariCP → DB Connection 획득

이 커넥션은 트랜잭션 동안 유지됩니다. 트랜잭션 시작 → Conntection 획득 → SELECT 여러 번 → 트랜잭션 종료 → Connection 반납

@Transactional이 UseCase 전체에 붙어 있으면, 내부 Repository 호출 5개가 같은 트랜잭션과 같은 커넥션 흐름 안에서 실행될 수 있습니다.

트랜잭션 1개
Connection 1개
   ├─ users 조회
   ├─ folders 조회
   ├─ schedules 조회
   ├─ links 조회
   ├─ texts 조회
   └─ files 조회

정확히는 커넥션 획득 시점은 설정과 실제 DB 접근 시점에 따라 약간 달라질 수 있지만 핵심은 트랜잭션 범위 동안 커넥션이 묶인다는 것입니다.

9.6 실제 서비스 메서드 실행

이제 프록시가 실제 서비스 메서드를 호출합니다.

TransactionInterceptor
   ↓
실제 PageSearchUseCaseImpl.search()

서비스 코드가 실행됩니다.

Users user = usersService.findById(usersId);
List<FolderDto> folders = foldersService.searchFolders(user, keyword);
List<ScheduleDto> schedules = schedulesService.searchSchedules(user, keyword);
List<LinkDto> links = linksService.searchLinks(user, keyword);
List<TextDto> texts = textsService.searchTexts(user, keyword);
List<FileDto> files = attachMentsService.searchFiles(user, keyword);

이 서비스 내부에서 Repository 호출이 발생합니다.

9.7 Repository/JPA 호출

Repository는 인터페이스처럼 보이지만 실제로는 스프링 데이터 JPA 프록시입니다.

textsRepository.searchByTextContent(...)
   ↓
Repository Proxy
   ↓
SimpleJpaRepository 또는 Query 실행 로직
   ↓
EntityManager

Repository는 EntityManager를 사용한다.

Repository
   ↓
EntityManager
   ↓
Hibernate Session
   ↓
JDBC Connection
   ↓
DB

JPQL or Query Method 해석은

List<Texts>findByContentContaining(String keyword);

Spring Data JPA는 메서드 이름을 보고 쿼리를 만듭니다.

findByContentContaining
   ↓
content like '%keyword%'

JPQL을 직접 썼다면 Hibernate가 JPQL을 SQL로 바꿉니다.

select t
from Texts t
where t.content like concat('%', :keyword, '%')

SQL은 대략 이렇게 됩니다.

select t.id, t.content, t.users_id
from texts t
where t.contentlike ?

PreparedStatement 생성은 Hibernate는 JDBC를 통해 SQL을 실행합니다.

SQL 생성
   ↓
PreparedStatement 생성
   ↓
파라미터 바인딩

예를 들어:

? = "%회의%"

DB로 SQL 전송

JDBC Connection
   ↓
DB에 SQL 전송

DB가 ResultSet 반환 → DB가 결과 row를 반환합니다.

ResultSet
   ├─ row 1
   ├─ row 2
   └─ row 3

Hibernate가 엔티티로 변환 → Hibernate는 ResultSet을 엔티티 객체로 바꾸게 됩니다.

ResultSet row
   ↓
Texts 엔티티 객체 생성
   ↓
필드 값 채움

이 과정을 하이드레이션이라고 보면 됩니다.

DB row
→ Java Entity

영속성 컨텍스트에 등록 → 엔티티는 영속성 컨텍스트에 등록됩니다.

영속성 컨텍스트
   ├─ EntityKey(Texts, 1) → Texts 객체
   ├─ EntityKey(Texts, 2) → Texts 객체
   └─ EntityKey(Texts, 3) → Texts 객체

그리고 변경 감지를 위해 스냅샷도 저장합니다.

현재 엔티티 값
Texts(id=1, content="회의 자료")

스냅샷
Texts(id=1, content="회의 자료")

나중에 flush 때 이 둘을 비교합니다.

현재 값 != 스냅샷
   ↓
UPDATE SQL 생성

LAZY 연관관계는 프록시로 둠 → 엔티티에 지연 로딩 관계가 있으면 실제 객체를 바로 가져오지 않고 프록시를 넣습니다.

@ManyToOne(fetch=FetchType.LAZY)
privateUsersusers;

조회 후 객체 상태는 이런 형태입니다.

Texts
   ├─ id = 1
   ├─ content = "회의 자료"
   └─ users = Users 프록시

나중에 text.getUsers().getName()을 호출하면 프록시 초기화가 일어납니다.

text.getUsers().getName()
   ↓
Users 프록시 초기화
   ↓
SELECT users ...

이때 영속성 컨텍스트가 살아 있어야 합니다. OSIV가 켜져 있으면 서비스 밖에서도 가능합니다.

9.8 DTO 반환

Repository가 엔티티를 반환하면 서비스에서 DTO로 꾸게 됩니다.

List<TextResponse> result = texts.stream()
    .map(TextResponse::from)
    .toList();

여기서 조심할 점이 있습니다. DTO 변환 중 LAZY 필드를 건드리면 추가 SQL이 나가게 됩니다.

public static TextResponse from(Texts text) {
    return new TextResponse(
        text.getId(),
        text.getContent(),
        text.getUsers().getName()
    );
}

text.getUsers().getName() 때문에 Users 조회가 추가로 나갈 수 있습니다.

Texts 100개 조회
   ↓
각 Text마다 users.getName()
   ↓
Users SELECT 100번
   ↓
N+1

그래서 성능이 중요한 조회는 fetch join이나 DTO 직접 조회를 써야합니다.

select new TextResponse(t.id, t.content, u.name)
from Texts t
join t.users u
where t.content like :keyword

9.9 실제 서비스 메서드 종료

서비스 메서드가 응답 DTO를 만들고 정상 종료합니다.

return new PageSearchResponse(folders, schedules, links, texts, files);

그러면 다시 TransactionInterceptor로 제어가 돌아가게 됩니다.

실제 Service 메서드 종료
   ↓
TransactionInterceptor로 복귀

이제 트랜잭션을 끝낼 차례입니다.

9.10 정상 종료 시 flush

트랜잭션을 commit하기 전에 flush가 일어날 수 있습니다.

flush = 영속성 컨텍스트 변경 내용을 SQL로 DB에 보내는 것

flush 때 Hibernate는 변경 감지를 합니다.

영속성 컨텍스트 안의 엔티티
   ↓
현재 값과 스냅샷 비교
   ↓
다르면 UPDATE SQL 생성
   ↓
INSERT/UPDATE/DELETE SQL 실행

조회 전용이면 보통 변경이 없으므로 UPDATE는 없습니다. @Transactional(readOnly = true)면 Hibernate가 flush를 줄이거나 변경 감지 부담을 줄이는 최적화를 할 수 있ㅅ브니다

readOnly = true
   ↓
조회 전용으로 취급
   ↓
flush 최적화 가능

9.11 commit

flush 후 문제가 없으면 commit 진행합니다.

commit = 트랜잭션 안에서 실행된 SQL 결과를 DB에 최종 확정

flush
   ↓
SQL 실행
   ↓
commit
   ↓
DB 반영 확정

flush와 commit 차이는 다시 정리

flush
= SQL을 DB에 보냄
= 아직 최종 확정 아님

commit
= 트랜잭션 결과를 최종 확정
= rollback 불가 상태가 됨

9.12 예외 발생 시 rollback

서비스 실행 중 RuntimeException이 발생하면 rollback합니다.

@Transactional
public void logic() {
    member.setName("재윤");
    throw new RuntimeException();
}

예외 발생
   ↓
TransactionInterceptor가 예외 감지
   ↓
rollback 판단
   ↓
rollback
   ↓
DB 변경 취소

기본적으로 Spring은 RuntimeException, Error에 대해 rollback합니다. Checked Exception은 기본적으로 rollback하지 않는다.

9.13 Connection 반납

트랜잭션이 끝나면 DB 커넥션을 HikariCP에 반납하게 됩니다.

commit 또는 rollback
   ↓
Connection 정리
   ↓
HikariCP에 반납

OSIV가 켜져 있어도 커넥션은 계속 잡고 있지 않는 것이 일반적입니다.

트랜잭션 종료
   ↓
Connection 반납
   ↓
EntityManager는 OSIV 때문에 계속 살아 있음

즉, 서비스 트랜잭션이 끝난 뒤 상태는 이렇게 됩니다.

EntityManager 있음
영속성 컨텍스트 있음
트랜잭션 없음
DB Connection 반납됨

10단계 : 컨트롤러로 복귀

서비스가 응답 객체를 반환하면 컨트롤러로 돌아오게 됩니다.

PageSearchResponse response = pageSearchUseCase.search(usersId, keyword);
return ResponseEntity.ok(response);

이 시점 상태는 다음과 같습니다,

Controller로 복귀
   ↓
ResponseEntity 생성
   ↓
트랜잭션은 끝남
   ↓
Connection 반납됨
   ↓
EntityManager는 아직 살아 있음

OSIV 때문에 영속성 컨텍스트는 아직 살아 있다.

11단계 : 컨트롤러 반환값 처리

DispatcherServlet이 컨트롤러 반환값을 받게 됩니다.

ResponseEntity<PageSearchResponse>
   ↓
HandlerMethodReturnValueHandler

ResponseEntity니까 HTTP 상태 코드와 Body를 준비합니다.

status = 200 OK
body = PageSearchResponse

그리고 HttpMessageConverter를 찾습니다. REST API라면 보통 Jackson이 선택된다.

MappingJackson2HttpMessageConverter

12단계 : JSON 직렬화

Jackson이 응답 객체를 JSON으로 바꾸게 됩니다.

PageSearchResponse
   ↓
Jackson
   ↓
JSON 문자열

DTO만 들어 있다면 보통 추가 쿼리가 없습니다,

DTO
   ↓
getter 호출
   ↓
단순 값 반환
   ↓
SQL 없음

하지만 DTO 안에 엔티티가 들어 있거나 엔티티를 직접 반환하면 위험합니다.

return order;

Jackson이 getter를 호출하면서 lazy loading이 발생할 수 있습니다.

Jackson
   ↓
order.getMember()
   ↓
Member 프록시 초기화
   ↓
EntityManager 살아 있음
   ↓
SELECT member ...

OSIV가 켜져 있기 때문에 JSON 직렬화 중에도 지연 로딩이 가능하다.

이게 OSIV의 장점이자 단점입니다.

장점:
LazyInitializationException이 덜 남

단점:
JSON 직렬화 중 예상치 못한 SQL 발생
N+1 문제를 숨김
성능 추적이 어려움

만약 OSIV가 꺼져 있다면 이 시점에 EntityManager가 없으므로 lazy loading은 터지게 됩니다.

OSIV OFF
   ↓
Jackson에서 lazy getter 호출
   ↓
EntityManager 없음
   ↓
LazyInitializationException

13단계 : OSIV afterCompletion

JSON 직렬화까지 끝나면 DispatcherServlet의 마무리 과정에서 인터셉터 afterCompletion()이 실행됩니다.

OpenEntityManagerInViewInterceptor.afterCompletion()
   ↓
현재 스레드에서 EntityManager unbind
   ↓
EntityManager.close()
   ↓
영속성 컨텍스트 종료

이제 요청 동안 살아 있던 “상자”가 닫히게 됩니다.

영속성 컨텍스트 close
   ↓
엔티티 관리 종료
   ↓
엔티티들은 준영속 상태
   ↓
참조 없으면 GC 대상

여기서 중요한 점:

OSIV afterCompletion에서 commit하는 게 아님.
commit은 이미 서비스 @Transactional 종료 시점에 끝났음.
OSIV는 EntityManager를 닫는 역할.

즉:

@Transactional
= 트랜잭션 commit/rollback 담당

OSIV
= 요청 끝에 EntityManager close 담당

14단계 : 필터 체인으로 복귀

DispatcherServlet이 끝나면 다시 필터 체인을 역순으로 빠져나가게 됩니다.

DispatcherServlet 종료
   ↓
Security Filter 복귀
   ↓
CORS Filter 복귀
   ↓
CharacterEncodingFilter 복귀

Spring Security는 마지막에 SecurityContext를 정리합니다.

SecurityContextHolder.clearContext()

왜 정리하냐면 톰캣 워커 스레드는 재사용되기 때문입니다.

요청 A: userId=1
   ↓
스레드 반납
   ↓
요청 B가 같은 스레드 사용 가능

만약 SecurityContext를 안 지우면 요청 B에서 요청 A의 사용자 정보가 남을 수 있다. 그래서 요청 끝에 반드시 정리한다.

15단계 : 톰캣 응답 전송

마지막으로 톰캣이 HTTP 응답을 클라이언트에게 보내게 됩니다.

HttpServletResponse
   ↓
HTTP Response
   ↓
TCP Socket
   ↓
Client

응답 예시는 이런 식입니다.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "folders": [],
  "schedules": [],
  "links": [],
  "texts": [],
  "files": []
}

응답 전송이 끝나면 톰캣 워커 스레드는 풀에 반납됩니다.

요청 처리 완료
   ↓
ThreadLocal 정리 완료
   ↓
워커 스레드 반납
   ↓
다음 요청 대기

전체 순서 요약

요청 도착

Tomcat
1. 소켓에서 HTTP 요청 수신
2. HttpServletRequest/Response 생성
3. Worker Thread 배정
Servlet Filter Chain
1. 인코딩 처리
2. CORS 처리
3. Spring Security
  1. JWT 검증
  2. SecurityContext 저장
DispatcherServlet
1. HandlerMapping
2. 컨트롤러 메서드 찾기
OSIV preHandle
1. EntityManager 생성
2. 영속성 컨텍스트 생성
3. 현재 스레드에 바인딩
Controller
1. request parameter 바인딩
2. SecurityContext에서 userId 조회
3. Service/UseCase 호출
1. @Transactional AOP
2. 6.1 프록시가 호출 가로챔
3. 6.2 트랜잭션 설정 확인
4. 6.3 EntityManager 확인
5. 6.4 트랜잭션 시작
6. 6.5 Connection 획득
7. 6.6 실제 서비스 메서드 실행
8. 6.7 Repository/JPA 실행
9. 6.8 flush
10. 6.9 commit 또는 rollback
11. 6.10 Connection 반납
Repository / JPA
1. Repository Proxy
2. EntityManager 사용
3. JPQL/Query Method → SQL
4. SQL 실행
5. ResultSet 수신
6. 엔티티 생성
7. 영속성 컨텍스트 등록
8. 스냅샷 저장
9. LAZY 프록시 생성
Service
1. 엔티티 → DTO 변환
2. 응답 객체 생성
Controller 반환
1. ResponseEntity 반환
JSON 직렬화
1. Jackson
2. DTO → JSON
3. 엔티티 lazy 접근 시 추가 SQL 가능
OSIV afterCompletion]
1. EntityManager unbind
2. EntityManager close
Filter 정리
1. SecurityContext clear
Tomcat
1. HTTP 응답 전송
2. Worker Thread 반납

UseCase에 @Transactional이 없으면 어떻게 바뀌나

public PageSearchResponse search(Long usersId, String keyword) {
    usersService.findById(usersId);
    foldersService.searchFolders(...);
    schedulesService.searchSchedules(...);
    linksService.searchLinks(...);
    textsService.searchTexts(...);
    attachMentsService.searchFiles(...);
}

이 경우 큰 트랜잭션 하나가 없습니다. 대신 Repository나 하위 Service 메서드에 붙은 트랜잭션이 각각 동작할 수 있습니다.

UseCase @Transactional 없음
 │
 ├─ usersRepository.findById()
 │    ├─ 짧은 readOnly 트랜잭션 시작
 │    ├─ SELECT
 │    ├─ commit
 │    └─ Connection 반납
 │
 ├─ foldersRepository.search()
 │    ├─ 짧은 readOnly 트랜잭션 시작
 │    ├─ SELECT
 │    ├─ commit
 │    └─ Connection 반납
 │
 ├─ schedulesRepository.search()
 │    └─ 같은 패턴
 │
 ├─ linksRepository.search()
 │    └─ 같은 패턴
 │
 ├─ textsRepository.search()
 │    └─ 같은 패턴
 │
 └─ filesRepository.search()
      └─ 같은 패턴

하지만 OSIV가 켜져 있으면 EntityManager는 요청 전체 동안 하나일 수 있습니다.

EntityManager 1개
   ├─ 짧은 트랜잭션 1
   ├─ 짧은 트랜잭션 2
   ├─ 짧은 트랜잭션 3
   ├─ 짧은 트랜잭션 4
   └─ 짧은 트랜잭션 5

즉, 차이는

@Transactional 있음: UseCase 전체를 하나의 트랜잭션으로 묶음

@Transactional 없음: Repository/하위 Service 단위로 트랜잭션이 여러 번 생길 수 있음

제일 중요한 결론

스프링 요청 흐름에서 헷갈리면 이 네 개를 분리해서 보면 됩니다.

1. 톰캣 스레드
   = 요청을 실행하는 주체

2. SecurityContext
   = 현재 로그인 사용자 정보

3. EntityManager / 영속성 컨텍스트
   = 엔티티를 담고 관리하는 상자
   = OSIV ON이면 요청 끝까지 살아 있음

4. @Transactional / 트랜잭션
   = DB 변경을 flush, commit, rollback하는 작업 단위
   = 보통 서비스 메서드 범위

5. DB Connection
   = 실제 DB와 통신하는 통로
   = 트랜잭션 중 실제 SQL 실행 시 잡고 끝나면 반납

한 문장으로 정리하면:

요청이 오면 톰캣 스레드가 필터와 DispatcherServlet을 거쳐 컨트롤러를 호출하고, OSIV가 EntityManager를 요청 동안 열어두며, 서비스의 @Transactional 프록시가 그 EntityManager에 트랜잭션과 DB 커넥션을 붙여 Repository/JPA 작업을 실행하고, 서비스 종료 시 flush/commit 후 커넥션을 반납하고, JSON 직렬화까지 끝난 뒤 OSIV가 EntityManager를 닫는다.

OSIV

재윤 — Thu, 2 Jul 2026 11:31:30 +0900

1. 트랜잭션 범위의 영속성 컨텍스트

트랜잭션이 시작될 때 영속성 컨텍스트가 시작되고 트랜잭션이 끝날 때 영속성 컨텍스트도 끝난다.
스프링에서는 보통 서비스 메서드에 @Transactional을 붙인다.

@Transactional
public Order findOrder(Long id) {
    return orderRepository.findOrder(id);
}

그러면 흐름은 다음과 같다.

서비스 안에서는 엔티티가 영속상태 였는데, 서비스가 끝나고 트랜잭션이 종료되면 컨트롤러에 반환된 엔티티는 준영속 상태가 된다.

2. 문제점

위 흐름에서 지연로딩 시에 문제가 생김

예를 들어 Order 엔티티가 있다고 가정해보자

@Entity
public class Order {

    @ManyToOne(fetch = FetchType.LAZY)
    private Member member;
}

LAZY는 처음 Order를 조회할 때 Member를 바로 조회하지 않는 전략이다. 대신 order.getMember()를 하면 실제 Member가 아니라 프록시 객체를 넣어둔다.

Order 조회
   │
   ├─ Order 실제 데이터 조회
   └─ Member는 실제 데이터가 아니라 프록시로 둠

프록시는 쉽게 말하면 이런 느낌이다.

“진짜 Member는 아직 안 가져왔고, 나중에 member.getName() 같은 실제 값이 필요하면 DB에서 조회할게.”

문제는 프록시가 DB에서 실제 데이터를 가져오려면 영속성 컨텍스트가 필요하다.

프록시 초기화 필요 → 영속성 컨텍스트 필요 → DB 조회

그런데 컨트롤러나 뷰 계층에서는 트랜잭션이 이미 끝났고 영속성 컨텍스트도 닫혔다…

그래서 프록시가 초기화 되지 못한다.

Controller/View → order.getMember().getName() → 프록시 초기화 시도 → 영속성 컨텍스트 없음 → LazyInitializationException

3. 해결하기 위한 방법

3.1 글로벌 FetchType.EAGER

LAZY를 EAGER로 바꾸는 것

@ManyToOne(fetch = FetchType.EAGER)
private Member member;

위와 같이 했을 때 Order를 조회할 때 Member도 같이 조회한다.

Order 조회
   │
   └─ Member도 즉시 조회

그러면 컨트롤러에서 order.getMember().getName()을 호출해도 이미 Member가 로딩되어있기 때문에 LazyInitializationException은 안난다.

하지만 이 방법은 추천하지 않는다. 이유는 두 가지 있다.

1. 사용하지 않는 엔티티까지 로딩한다.

화면 A는 Order만 필요하다고 해보자

화면 A : Order만 필요
화면 B : Order + Member 필요

그런데 Order.member를 글로벌로 EAGER로 설정하면 화면 A에서도 Member를 항상 같이 조회함. 안 쓰는 데이터를 매번 가져옴

2. JPQL에서 N + 1 문제가 발생할 수 있다.

em.find(Order.class, 1L)처럼 단건 조회할 때는 즉시 로딩이면 조인해서 가져올 수 있다.

select o.*, m.*
from orders o
left join member m on o.member_id = m.member_id
where o.id = 1

여기까지는 괜찮아 보이지만 그런데 JPQL을 쓰면 문제가 생긴다.

List<Order> orders =
    em.createQuery("select o from Order o", Order.class)
      .getResultList();

JQPL은 기본적으로 JPQL 자체를 먼저 SQL로 번역한다.

select * from orders

그 다음 Order.member가 EAGER니까 JPA는 각 Order의 Member를 추가로 조회해야한다.

select * from member where id = ?
select * from member where id = ?
select * from member where id = ?
select * from member where id = ?
...

만약 Order가 10개면,

Order 목록 조회 SQL 1번
각 Order의 Member 조회 SQL 10번
총 11번

그래서 N + 1 문제라고 한다.

이게 치명적인 이유는 데이터가 많아질 수록 SQL이 폭증하기 때문이다.

Order 10개  → SQL 11번
Order 100개 → SQL 101번
Order 1000개 → SQL 1001번

3.2 JPQL Fetch Join

현실적인 대안이 fetch join이다.

기존 JPQL은 다음과 같다.

select o
from Order o

이건 Order 만 조회한다.

하지만 fetch join을 쓰면 다음과 같이 진행된다.

select o
from Order o
join fetch o.member

뜻은 → Order를 조회할 때 연관된 Member도 SQL Join으로 같이 가져와라

실행 SQL은 다음과 같다.

select o.*, m.*
from orders o
join member m on o.member_id = m.member_id

그러면 Order와 Member를 한 번에 가져온다

Order 목록 조회 → SQL Join 한번 → Order + Member 모두 로딩

그래서 컨트롤러나 뷰에서 order.getMember().getName()을 호출해도 이미 Member가 로딩 되어있다. 그리고 N + 1도 줄일 수 있다.

기존:
Order 1번 조회 + Member N번 조회

fetch join:
Order와 Member를 JOIN으로 1번 조회

하지만 단점도 존재한다.

예를 들어 화면 마다 필요한 데이터가 다르다고 해보자

화면 A: order만 필요
화면 B: order + member 필요
화면 C: order + orderItems 필요
화면 D: order + member + orderItems 필요

그러면 Repository에 이런 메서드가 늘어날 수 있다.

findOrder()
findOrderWithMember()
findOrderWithOrderItems()
findOrderWithMemberAndOrderItems()

즉 화면 요구사항에 맞춘 조회 메서드가 계속 증가한다. → 프레젠테이션 계층이 알게 모르게 데이터 접근 계층을 침범하는 것

쉽게 말하면 화면에서 필요한 데이터 모양 때문에 Repository 메서드가 화면 별로 계속 생김

그래도 이게 어느 정도는 필요하다고 볼 수 있다. 왜냐하면 성능 최적화는 결국 화면 별로 필요한 데이터가 다르기 떄문.

화면 A는 order만 필요
화면 B는 member까지 필요

둘을 무조건 하나로 합치면 한쪽은 불필요한 데이터를 가져오고 너무 쪼개면 메서드가 많아진다. → 무조건 일반화하지말고 적절한 선에서 타협점을 찾아야함

3.3 강제로 초기화 및 Facade 계층

@Transactional
public Order findOrder(Long id) {
    Order order = orderRepository.findOrder(id);

    order.getMember().getName(); // 강제로 프록시 초기화

    return order;
}

여기서 중요한 건 order.getMember()만 호출하면 안될 수도 있다는 점이다. order.getMember()는 프록시 객체만 반환할수도 있다.

진짜 초기화는 실제 값을 사용할 때 일어남 이렇게 해야 Member 프록시가 초기화된다. 흐름은 다음과 같다.

Service 트랜잭션 안 → Order 조회 → order.getMember().getName() → Member 프록시 초기화 → 트랜잭션 종료 → Controller로 반환 → 이미 Member가 로딩되어 있으므로 사용 가능

but 단점도 있다. 서비스 계층이 프레젠테이션 계층을 의식하는 것임 즉, 서비스가 원래는 비즈니스 로직에 집중해야하는데 “뷰에서 member.name을 쓸 테니까 미리 초기화해야지” 이런 생각이 든다.

그래서 서비스 로직이 화면 요구사항에 오염될 수도 있다. == 좋지 않다.

그래서 나온 게 Facade 계층

Facade는 컨트롤러와 서비스 사이에 하나의 계층을 더 두는 방식이다. 원래 구조는 다음과 같다.

Controller → Service → Repository

Facade를 넣으면 다음과 같다.

Controller → Facade → Service → Repository

Facade의 역할은 다음과 같다.

프레젠테이션 계층과 서비스 계층 사이의 논리적 의존성 분리
프레젠테이션 계층에서 필요한 엔티티 초기화
서비스 계층 호출
레포지토리 호출 조합

예를 들어보면 다음과 같다.

class OrderFacade {

    @Autowired
    OrderService orderService;

    public Order findOrder(Long id) {
        Order order = orderService.findOrder(id);

        // 프레젠테이션 계층이 필요한 프록시 객체를 강제로 초기화
        order.getMember().getName();

        return order;
    }
}

그러면 서비스는 비즈니스 로직에 집중

class OrderService {

    public Order findOrder(Long id) {
        return orderRepository.findOrder(id);
    }
}

즉 강제 초기화 코드를 서비스에서 빼고 Facade로 옮긴 것

장점

Controller는 Service를 직접 알 필요가 줄어든다.
Service는 화면용 초기화 로직을 몰라도 된다.
화면에 필요한 데이터 준비는 Facade가 담당한다.
비즈니스 로직과 프레젠테이션용 로직을 분리할 수 있다.

흐름을 보면 다음과 같다.

Controller
OrderFacade
- 트랜잭션 시작
- Service 호출
- 필요한 프록시 초기화
- 엔티티 반환
Controller/View

주의할 점은 Facade에서 프록시를 초기화하려면 Facade도 트랜잭션 범위 안에 있어야 한다.

@Transactional
public Order findOrder(Long id) {
    Order order = orderService.findOrder(id);
    order.getMember().getName();
    return order;
}

왜냐하면 프록시 초기화는 영속성 컨텍스트가 살아 있을 때만 가능하기 때문

단점 → 계층 하나가 더 생긴다는 것 자체가 단점임 == 그래서 코드가 더 늘어남.

4. 준영속 상태와 지연 로딩 문제의 본질

3번에서 해결책을 보긴 했지만 문제의 본질은 엔티티가 프레젠테이션 계층에서 준영속 상태이기 때문에 발생하는 것

즉 컨트롤러나 뷰에서 엔티티를 사용할 때 영속성 컨텍스트가 이미 닫혀 있기 때문에 문제가 생기는 것

그래서 근본적으로 보았을 때 → 그러면 영속성 컨텍스트를 뷰까지 열어두면 되지 않을까? 이게 바로 OSIV이다.

5. OSIV란?

Open Session in View이며 Hibernate 용어로는 Session 이고 JPA에서는 EntityManager니까 정확히는 Open EntityManager in View라고 함.

뜻은 영속성 컨텍스트를 뷰까지 열어두는 것

즉, 서비스 계층이 끝났다고 바로 영속성 컨텍스트를 닫지 않고, 요청이 끝날 때까지 살려둔다.

6. 과거 OSIV : 요청 당 트랜잭션

과거 방식의 OSIV를 보자

이 방식은 요청이 들어오자마자 트랜잭션을 시작하고, 요청이 끝날 때 트랜잭션을 커밋한다.

이 방식의 장점은 다음과 같다.

요청 전체에서 영속성 컨텍스트가 살아 있음
뷰에서도 지연 로딩 가능
엔티티는 요청 끝까지 영속 상태

그래서 다음과 같은 것들이 가능하다.

Member member = memberService.getMember(id);
model.addAttribute("member", member);

뷰에서 member.orders 같은 지연 로딩 컬렉션을 접근해도 가능함.

하지만 치명적인 문제가 있었다.

문제는 요청 전체가 트랜잭션이라는 점

컨트롤러에서 단순히 화면 표시용으로 이름을 바꾼다고 가정

Member member = memberService.getMember(id);
member.setName("XXX"); // 화면에만 XXX로 보여주고 싶음
model.addAttribute("member", member);

개발자의 의도는 DB를 바꾸려는 게 아니라 화면에만 이름을 XXX로 보여주고 싶다라는 것

그런데 요청 끝에서 트랜잭션이 커밋됨 커밋 전에 Flush가 일어나고 변경 감지가 동작함.

member.setName("XXX")
영속 상태 엔티티 변경됨
요청 끝
flush
dirty checking
update member set name='XXX'

결과 적으로 DB이름까지 XXX로 바뀔 수 있음 그래서 과거 OSIV의 가장 큰 문제는

→ 프레젠테이션 계층에서 엔티티를 수정했는데 그 수정이 DB에 반영될 수 있다.

프러젠테이션 계층에서 엔티티 수정을 막기 위해 여라가지 방법들이 생겼다.

6.1 읽기 전용 인터페이스 제공

interface MemberView {
    String getName();
}

@Entity
class Member implements MemberView {
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

컨트롤러에는 Member가 아니라 MemberView 타입으로 넘긴다.

public MemberView getMember(Long id) {
    return memberRepository.findById(id);
}

그러면 프레젠테이션 계층에서는 getName()만 보이고 setName()은 못 쓴다.

Member 타입이면: getName() 가능, setName() 가능
MemberView 타입이면: getName() 가능, setName() 불가능

장점은 엔티티를 직접 수정하지 못하게 막을 수 있다.

단점은 인터페이스를 따로 설계해야해서 완전히 깔끔한 해결은 아니다.

6.2 엔티티 래핑

엔티티를 직접 넘기지 않고 읽기 메서드만 가진 래퍼 객체로 감싼다.

class MemberWrapper {

    private Member member;

    public MemberWrapper(Member member) {
        this.member = member;
    }

    public String getName() {
        return member.getName();
    }
}

컨트롤러에는 MemberWrapper를 넘긴다.

그러면 외부에서는 getName()만 호출할 수 있고, setName()은 호출할 수 없다.

MemberWrapper
- 내부에는 member를 가지고 있음 하지만 읽기 메서드만 외부에 제공

장점은 엔티티 직접 수정을 막을 수 있다.

단점은 래퍼 클래스를 계속 만들어야해서 번거롭다.

6.3 DTO만 반환

가장 전통적이고 실무에서 많이 쓰는 방식

class MemberWrapper {

    private Member member;

    public MemberWrapper(Member member) {
        this.member = member;
    }

    public String getName() {
        return member.getName();
    }
}

서비스나 컨트롤러에서 엔티티를 DTO로 변환해서 변환한다.

Member member = memberService.getMember(id);

MemberDTO dto = new MemberDTO(member.getName());

return dto;

DTO는 엔티티가 아니기 때문에 영속성 컨텍스트가 관리하지 않는다.

그래서 DTO 값을 바꿔도 DB 변경 감지가 일어나지 않는다.

Entity 수정 → 영속성 컨텍스트가 관리 중이면 DB 반영 가능
DTO 수정 → 그냥 일반 객체 수정, DB와 무관

단점은 코드량이 늘어난다는 것

MemberDTO
OrderDTO
OrderDetailDTO
OrderWithItemsDTO
...

그래서 API 서버에서는 보통 이 방식이 가장 안전함.

7. 스프링 OSIV: 비즈니스 계층 트랜잭션

과거 OSIV는 요청 전체가 트랜잭션이라 위험했음 그래서 스프링이 제공하는 OSIV는 조금 다르게 동작한다.

→ 영속성 컨텍스트는 요청 끝까지 유지하지만, 트랜잭션은 비즈니스 계층에서만 사용한다.

즉 서비스 계층에서 @Transactional이 붙은 메서드가 실행될 때만 트랜잭션을 시작한다.

흐름은 다음과 같다.

그림으로 보면 다음과 같음

그러면 영속성 컨텍스트는 요청 시작 부터 끝까지 살아있는 거고 트랜잭션이 Service 시작 후와 Service 종료까지만 살아있는데 트랜잭션 역할을 좀 더 봐보자 영속성 컨텍스트와 트랜잭션의 역할을 나누어보자

영속성 컨텍스트 = JPA가 엔티티를 관리하는 메모리 공간
트랜잭션 = DB에 변경 내용을 안전하게 반영하거나 취소하는 작업 단위

영속성 컨텍스트의 역할

JPA의 작업장이라고 말할 수 있으며
- 조회한 엔티티, 1차 캐시, 변경 감지용 스냅샷, 프록시 객체, 지연 로딩에 필요한 연결 정보

트른잭션의 역할

DB에 실제로 반영할지 말지를 결정하는 경계

예를 들어 서비스를

@Transactional
public void changeName(Long id) {
    Member member = memberRepository.findById(id);
    member.setName("재윤");
}

코드에서 save()가 없어도 DB에 반영이 가능함 이유는 트랜잭션 커밋 시점에 다음과 같은 일이 일어남

@Transactional 시작
DB 조회
엔티티 영속 상태
member.setName(”재윤”)
@Transactional 종료
flush
변경 감지
UPDATE SQL 실행
commit

여기서 트랜잭션의 역할은 이것임.

1. 이 작업 단위를 시작한다.
2. 변경 내용을 DB에 반영할 수 있는 상태로 만든다.
3. 커밋 시점에 flush를 통해 SQL을 실행한다.
4. 성공하면 commit한다.
5. 예외가 나면 rollback한다.

즉 영속성 컨텍스트는 트랜잭션 밖에서도 엔티티를 들고 있을 수 있지만, DB에 변경을 반영하는 flush/commit은 트랜잭션 안에서만 정상적으로 동작하도록 설계되어 있다.

스프링 OSVI의 핵심 특징을 보자

클라이언트 요청이 들어올 때 영속성 컨텍스트를 생성한다.
요청이 끝날 때까지 같은 영속성 컨텍스트를 유지한다.
한 번 조회한 엔티티는 요청이 끝날 때까지 영속 상태를 유지한다.
엔티티 수정은 트랜잭션이 있는 계층에서만 동작한다.
트랜잭션이 없는 프레젠테이션 계층은 지연 로딩을 포함한 조회만 가능하다.

중요한 문장 → 엔티티 수정은 트랜잭션이 있는 계층에서만 동작한다. 트랜잭션이 없는 프레젠테이션 계층은 징녀 로딩을 포함해서 조회만 할 수 있다.

즉, 컨트롤러에서 지연 로딩은 가능함.

Stringname=order.getMember().getName();

하지만 컨트롤러에서 수정해도 바로 DB에 반영되지는 않음

member.setName("XXX");

왜냐하면 컨트롤러에는 트랜잭션이 없기 때문

그러면 스프링 OSIV에서 트랜잭션 없이 읽기를 보자

영속성 컨텍스트를 통한 모든 변경은 트랜잭션 안에서 이루어져야한다. 그런데 단순 조회는 트랜잭션 없이도 가능함. 이것을 Nontransactional reads 즉, 트랜잭션 없이 읽기라고 함

트랜잭션 있음: 조회 가능, 수정 가능, flush 가능, commit 가능

트랜잭션 없음: 조회 가능, 지연 로딩 가능, 수정은 DB 반영 불가

스프링 OSIV에서는 컨트롤러/뷰 계층에 트랜잭션은 없지만 영속성 컨텍스트는 살아있다. 그래서 지연로딩이 가능함.

8. 스프링 OSIV 주의 사항 : 수정 후 트랜잭션 서비스 호출

정말 중요한 부분

스프링 OSIV는 프레젠테이션 계층에서 수정해도 DB에 반영되지 않는다.

Member member = memberService.getMember(id);
member.setName("XXX");
return "view";

이것만 있으면 DB에 반영되지 않는다 왜냐하면 컨트롤러에는 트랜잭션이 없고 요청 끝에서 OSIV는 flush()를 호출하지 않고 em.close()만 하기 때문

그런데 문제가 되는 경우가 있다.

Member member = memberService.getMember(id);
member.setName("XXX");

memberService.biz(); // @Transactional

이 흐름을 보면

요청 시작 → 영속성 컨텍스트 생성
memberService.getMember(id)
1. 트랜잭션 안에서 Member 조회
2. 트랜잭션 종료
3. 영속성 컨텍스트는 살아 있음
4. Member는 계속 영속 상태
컨트롤러에서 member.setName("XXX") → 트랜잭션은 없지만 영속 상태 엔티티 값이 바뀜
memberService.biz() 호출 → @Transactional 때문에 트랜잭션 시작 → 기존 영속성 컨텍스트에 트랜잭션이 붙음
biz() 종료 → 트랜잭션 커밋, flush 발생, 변경 감지 동작, 컨트롤러에서 바꾼 XXX도 DB에 반영됨

문제는 → OSIV에서는 같은 요청 안에서 하나의 영속성 컨텍스트를 여러 트랜잭션이 공유할 수 있다.

그래서 컨트롤러에서 바꿔둔 엔티틱밧이 나중에 실행된 트랜잭션에서 flush 될 수 있다.

이 해결 방법은 트랜잭션이 있는 비즈니스 로직을 모두 먼저 호출하고 그 다음에 엔티티를 변경해야한다.

9. OSIV에서 Repository 직접 호출

기존에는 계층을 엄격하게 나누면 Controller는 Service만 호출하고 Repository는 직접 호출하지 않는 게 일반적이다.

그런데 OSIV를 쓰면 영속성 컨텍스트가 컨트롤러까지 살아있다.

그래서 단순 조회하면 컨트롤러에서 Repository를 직접 호출해도 기술적으로 문제가 없다고 한다.

class OrderController {

    @Autowired
    OrderService orderService;

    @Autowired
    OrderRepository orderRepository;

    public String order(Order order, Model model) {
        Long id = orderService.order(order); // 상품 구매 비즈니스 로직

        Order orderResult = orderRepository.findOne(id); // 단순 조회
        model.addAttribute("order", orderResult);

        return "view";
    }
}

OSIV 사용 전 : 프레젠테이션 계층에서 사용할 지연 로딩 엔티티를 미리 초기화해야했다. 초기화는 서비스나 Facade가 담당했다.
OSIV 사용 후 : 영속성 컨텍스트가 프레젠테이션 계층까지 살아 있으므로 단순 엔티티 조회는 컨트롤러에서 Repository를 직접 호출해도 동작한다.

하지만 조심해야할 부분은 계층형 아키텍처 관점에서는 Controller가 Repository를 직접 아는 게 별로 좋지 않을 수 있다.

→ 너무 엄격하게 Controller는 무조건 Service만 호출해야한다라고 하면 오히려 단순 조회 코드도 불필요하게 복잡해질 수 있다.

즉, 비즈니스 로직은 Service에서 처리하고 단순 조회는 유연하게 볼 수 있다는 관점

10. Spring OSIV의 단점

크게 3가지가 있다.

10.1 같은 영속성 컨텍스트를 여러 트랜잭션이 공유할 수 있다.

요청 하나
- 영속성 컨텍스트 하나
- 트랜잭션 A
- 컨트롤러에서 엔티티 수정
- 트랜잭션 B

같은 영속성 컨텍스트 안에서 엔티티 상태가 유지 되기 때문에 나중 트랜잭션에서 예상치 못한 변경이 flush 될 수 있음

10.2 프레젠테이션 계층에서 수정 후 비즈니스 로직 호출하면 수정될 수 있다.

이건 예제로 본 내용

member.setName("XXX");
memberService.biz();// @Transactional

이 순서가 위험하다. 안전한 순서는 보통 다음과 같이

memberService.biz();// 먼저 트랜잭션 비즈니스 로직

member.setName("XXX");// 마지막 화면용 변경

하지만 제일 좋은 것은

컨트롤러에서 엔티티를 수정하지 않는다.
DTO로 변환해서 화면/API에 넘긴다.

10.3 프레젠테이션 계층에서 지연 로딩 SQL이 실행된다.

OSIV가 켜져 있으면 컨트롤러나 뷰에서도 지연 로딩이 가능함

그런데 이 말은 반대로 컨트롤러나 JSON 직렬화 중에도 SQL이 나갈 수 있다.는 뜻이다.

예를 들어:

return order;

Jackson이 JSON으로 변환하면서 getter를 호출

getMember()
getOrderItems()
getDelivery()

이때 지연 로딩이 터질 수 있어.

JSON 직렬화 -> getMember() -> SQL 실행

문제는 개발자가 Repository나 Service에서 쿼리를 명확히 호출한 게 아니라, 응답을 만드는 과정에서 쿼리가 나간다는 점

그래서 성능 추적이 어려워짐

"왜 이 API가 느리지?" -> Service 쿼리는 1개인데, JSON 직렬화 중 Lazy Loading으로 쿼리 수십 개 발생

이런 일이 생길 수 있음.

11. OSIV vs Facade vs DTO

OSIV를 쓰지 않는 대안으로 Facade나 DTO를 말한다.

11.1 OSIV 사용

장점:
뷰/컨트롤러에서 지연 로딩 가능
엔티티 그래프 탐색이 편함
코드가 줄어듦

단점:
쿼리 발생 위치가 불명확
프레젠테이션 계층에서 엔티티 수정 위험
성능 튜닝 지점이 흐려짐
원격 클라이언트에는 적용 불가

11.2 Facade 사용

장점:
서비스와 프레젠테이션 계층 분리
필요한 엔티티를 트랜잭션 안에서 초기화 가능

단점:
계층 하나 추가
위임 코드 증가
화면별 초기화 코드 증가

11.3 DTO 사용

장점:
API 응답 구조 명확
엔티티 노출 방지
프레젠테이션 계층에서 수정해도 DB와 무관
성능 최적화 쿼리와 응답 모델을 분리 가능

단점:
DTO 클래스와 변환 코드 증가

어떤 방법을 쓰든 OSIV를 사용하는 것과 비교해서 지루한 코드를 많이 작성해야 한다.

즉, OSIV는 편하다. 하지만 편한 만큼 조심해야 한다.

12. OSIV를 사용하는 방법이 항상 좋은 건 아니다

복잡한 화면에서는 OSIV가 오히려 효과적이지 않을 수 있다라는 것 예를 들어 관리자 통계 화면처럼 여러 테이블을 조인하고 집계해야 하는 경우

회원 수
주문 수
매출 합계
카테고리별 판매량
일자별 통계

이걸 엔티티 그래프 탐색으로 만들면 비효율적일 수 있다.

List<Order>orders=orderRepository.findAll();

for (Orderorder :orders) {
		order.getMember().getName();
		order.getOrderItems().size();
		order.getDelivery().getAddress();
}

이러면 지연 로딩이 계속 발생하고 N+1 문제가 생길 수 있음. 이런 경우에는 처음부터 필요한 데이터를 JPQL로 조회해서 DTO로 받는 게 낫다.

select new OrderStatsDto(
    o.id,
    m.name,
    sum(oi.price)
)
from Order o
join o.member m
join o.orderItems oi
group by o.id, m.name

즉, 복잡한 조회 화면은 이게 낫다.

엔티티 조회 후 그래프 탐색 보다 처음부터 DTO 조회

13. Spring Boot 기준으로 이해

Spring Boot + JPA에서는 보통 OSIV가 기본으로 켜져 있는 경우가 많음

spring.jpa.open-in-view=true

이 상태에서는 이런 일이 가능

@GetMapping("/orders/{id}")
publicOrderResponsegetOrder(@PathVariable Long id) {
	Order order=orderService.findOrder(id);
	
	// 서비스 트랜잭션은 끝났지만 OSIV 때문에 지연 로딩 가능
	String memberName=order.getMember().getName();
	
	return new OrderResponse(order.getId(),memberName);
}

하지만 API 서버에서는 보통 이렇게 하는 게 더 안전

spring.jpa.open-in-view=false

그리고 필요한 데이터를 서비스/리포지토리에서 명확히 가져온다.

@Transactional(readOnly=true)
public OrderResponsegetOrder(Long id) {
	Order order=orderRepository.findOrderWithMember(id);
	
	return new OrderResponse(
			order.getId(),
			order.getMember().getName()
	   );
}

또는 아예 DTO로 조회한다.

public OrderResponse findOrderDto(Long id) {
    return em.createQuery(
        "select new com.example.OrderResponse(o.id, m.name) " +
        "from Order o join o.member m " +
        "where o.id = :id",
        OrderResponse.class
    ).setParameter("id", id)
     .getSingleResult();
}

14. 결론

OSIV는 영속성 컨텍스트를 요청 끝까지 열어두어 컨트롤러/뷰에서도 지연 로딩을 가능하게 하지만 그만큼 쿼리 발생 위치와 엔티티 수정 위험을 조심해야 하는 전략이다.

톰캣

재윤 — Thu, 2 Jul 2026 11:24:09 +0900

톰캣은 한 마디로 설명 → 자바 웹 애플리케이션을 실행시켜주는 서블릿 컨테이너이자 WAS

Spring boot로 API 서버를 만들면 보통 우리가 직접 톰캣을 설치하지 않아도 된다. 내부적으로 내장 톰캣이 떠서 HTTP 요청을 받고 그 요청을 Spring MVC로 넘겨주게 된다.

1. 톰캣이 무엇인가?

톰캣, 정확히는 Apache Tomcat은 자바 기반 웹 애플리케이션을 실행하기 위한 서버이다.

역할을 나누어 보면 다음과 같다.

클라이언트
   ↓ HTTP 요청
Tomcat
   ↓
Servlet / Spring MVC
   ↓
Service
   ↓
Repository / DB

즉, 사용자가 브라우저나 앱에서 요청을 보내면 톰캣이 먼저 요청을 받는다.

예를 들어 사용자가 다음과 같은 요청을 보냈다고 해보자

GET /api/members/1 HTTP/1.1
Host: example.com

이 요청을 가장 먼저 받는 게 톰캣이다. 톰캣은 이 요청을 분석해서 Spring MVC 쪽으로 넘겨준다.

2. 톰캣은 웹 서버인가? WAS인가?

톰캣에 대해 알기 전에 우선 서블릿과 서블릿 컨테이너부터 공부해보자

2.1 서블릿을 우선 공부해보자

서브릿은 HTTP 요청을 자바 코드로 처리하기 위한 표준 객체

이 서블릿이 왜 필요했냐?

브라우저 요청은 원래 다음과 같은 문자열입니다. 브라우저가 /hello로 요청하면 실제로는 대충 다음과 같은 HTTP 메시지가 날아옴

GET /hello HTTP/1.1
Host: localhost:8080
User-Agent: Chrome
Accept: text/html

이건 그냥 네트워크를 타고 온 문자열 데이터라. 자바 입장에서는 원래 다음과 같은 걸 직접해야함.

1. 소켓 열기
2. 포트에서 요청 기다리기
3. HTTP 문자열 읽기
4. GET인지 POST인지 파싱하기
5. URL이 /hello인지 확인하기
6. 헤더 읽기
7. 바디 읽기
8. 응답 형식 맞춰서 직접 작성하기
9. 클라이언트에게 다시 보내기

만약 서블릿이 없으면 개발자가 이런 코드를 직접 짜야함

서블릿은 이 복잡한 HTTP 처리를 자바 객체 방식으로 바꿔주게 된다. 즉, 이 서블릿을 쓰면 개발자는 HTTP 문자열을 직접 파싱하지 않아도 된다.

protected void doGet(HttpServletRequest request,
                     HttpServletResponse response) throws IOException {
    response.getWriter().write("hello");
}

여기서 중요한 것은 다음과 같다.

HttpServletRequest = HTTP 요청을 자바 객체로 표현한 것
HttpServletResponse = HTTP 응답을 자바 객체로 표현한 것

즉 서블릿은 HTTP 세계와 자바 코드 사이의 표준 연결 규칙이다.

HTTP 요청 문자열
Tomcat이 파싱
HttpServletRequest 객체
Servlet의 doGet(), doPost() 호출
HttpServletResponse에 응답 작성
HTTP 응답으로 변환

왜 표준 객체이어야함은 서블릿이 표준이라는 것이 중요한데 만약 이 표준이 없으면 서버마다 요청 처리 방식이 다를 수 있다. 예를 들어

Tomcat에서는 handleRequest()
Jetty에서는 process()
Undertow에서는 execute()

이런 식이면 서버를 바꿀 때 마다 코드를 바꿔야함. 그런데 서블릿 표준이 있으니 개발자는 위와 같이 만들기만 하면 된다. 그래서 Tomcat이든 Jetty든 Undertow든 서블릿 규칙을 아는 서버는 위 코드를 실행할 수 있다.

즉 Servlet = Java 웹 서버와 java 웹 애플리케이션 사이의 공통 약속

예전에는 다음과 같이 컨트롤러 대신 직접 만들었다.

public class HelloServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest request,
                         HttpServletResponse response) throws IOException {
        response.getWriter().write("hello");
    }
}

사용자가 /hello로 요청하면 이 doGet()이 실행되는데 문제는 이 서블릿을 누가 실행하냐 라는 것

사용자 요청 → HelloServlet의 doGet() 실행

이 사이에서 요청을 받고, 서블릿을 찾아서, 메서드를 호출해주는 존재가 필요했습니다. 그것이 서블릿 컨테이너

2.2 서블릿 컨테이너가 하는 일

서브릿 컨테이너는 다음과 같은 일을 한다.

HTTP 요청을 받음
HttpServletRequest, HttpServletResponse 객체를 만듦
어떤 서블릿이 처리할 요청인지 찾음
해당 서블릿의 service(), doGet(), doPost() 등을 호출함
응답을 클라이언트에게 돌려줌
서블릿의 생성, 초기화, 종료까지 관리함

즉, 개발자가 직접 해야할 귀찮은 서버 작업을 대신 해준다.

흐름을 보면 브라우저에서 다음과 같이 요청했다고 해보자

GET /hello

그러면 흐름은 이렇다.

브라우저 → Tomcat → HelloServlet → 응답

조금 더 자세히 보면

브라우저가 GET /hello 요청
Tomcat이 요청을 받음
Tomcat이 HttpServletRequest 객체 생성
Tomcat이 HttpServletResponse 객체 생성
/hello를 처리할 서블릿을 찾음
HelloServlet의 doGet() 호출
response에 "hello" 작성
Tomcat이 HTTP 응답으로 변환해서 브라우저에 전달

2.3 Spring에서는 어떻게 연결되냐?

Spring MVC에서는 우리가 직접 HelloServelt 같은 걸 만들지 않는다. 대신 Controller를 만든다.

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }
}

그런데 이것도 내부적으로는 서블릿 컨테이너 위에서 동작한다. Spring MVC에서는 핵심 서블릿이 하나 있다.

DispatcherServlet

톰캣은 모든 요청을 이 DispatcherServlet에게 넘긴다.

브라우저 → Tomcat, 서블릿 컨테이너 → DispatcherServlet → Controller → Service → Repository

즉, Spring에서 서블릿 컨테이너는 DispatcherServelet을 실행시켜주는 역할을 한다.

2.4 웹 서버

웹 서버는 주로 정적 리소스를 처리한다.

예를 들어 HTML, CSS, JavaScript, 이미지, 동영상

대표적인 웹 서버는 Nginx, Apache HTTP Server가 있다.

2.5 WAS

WAS는 동적인 요청을 처리한다.

예를 들어 로그인, 회원가입, 게시글 작성, 주문 처리, 결제 처리, DB 조회

이런 요청은 파일을 내려주는 게 아니라, 서버 내부 로직을 실행해야 한다. 대표적인 WAS는 Tomcat, Jetty, Undertow, Wildfly, WebLogic, WebSphere가 있다.

여기서 의문점 → 웹 서버 없이도 WAS만으로도 서비스는 가능한가?

가능하다. Spring boot 내장 Tomcat만 띄워도 다음과 같이 동작할 수 있다.

Client → Spring boot 내장 Tomcat → Controller → Service → DB

실제로 로컬 개발할 때 우리가 localhost:8080을 쓰는데 이때 앞에 Nginx 같은 웹 서버 없이도 잘 동작함. 왜냐하면 Tomcat도 HTTP 요청을 받을 수 있기 때문임.

그러면 굳이 왜 웹 서버를 앞에 둘까?

WAS만으로도 가능하지만, 운영 화경에서는 WAS가 비즈니스 로직에 집중하도록 앞에 웹 서버를 두는 경우가 많다.

정적 파일 처리는 웹 서버가 훨씬 잘한다는 것 HTML, CSS, JS, 이미지, 동영상, 폰트 같은 것들 Tomcat도 이런 파일을 내려줄 수 있지만 Nginx 같은 웹 서버가 정적 파일 처리에 더 특화되어있다.

예를 들어 사용자가 이미지 파일을 요청했다고 한다면

GET /images/logo.png

이걸 Tomcat이 처리하면 Tomcat의 스레드, 메모리, 네트워크 자원을 사용한다. 그런데 Tomcat은 원래 이런걸 위해 존재하는 것이 아니라 보통 다음과 같은 요청을 처리하려고 있는 것

로그인, 회원가입, 게시글 작성, DB 조회, 결제, 검색

그래서 정적 파일은 Nginx가 처리하고 동적 요청만 Tomcat으로 넘기는 구조를 많이 쓴다.

또한, 리버스 프록시 역할을 한다. 운영에서는 Nginx가 앞에서 요청을 받고 WAS로 넘겨주는 구조인데 이 구조에서 Nginx는 일종의 문지기 역할을 한다.

외부 요청 받기, 내부 WAS 전달, 요청 경로 분기, 헤더 추가, 접근 제한

예를 들어

/api/*       → Spring Boot 서버
/admin/*     → 관리자 서버
/images/*    → 정적 파일 서버

또한, HTTP 처리를 앞단에서 하기 편하다. WAS만 써도 HTTPS 설정 가능하다. 하지만 운영에서는 보통 Nginx나 로드밸런서에서 HTTPS를 처리하고, 내부에서는 HTTP로 WAS에 전달한다.

이렇게 하였을 때 인증서 관리, TLS 설정, 갱신을 한 곳어세 처리하기 편하다.

또한, 로드밸런싱이 쉽다. WAS 서버가 여러 대일 때를 생각해보자.

Spring boot 서버 1, Spring boot 서버 2, Spring boot 서버 3

NGINX나 로드밸런서를 앞에 두면 요청을 여러 WAS로 나눠줄 수 이다.

client
- NGINX
  - Tomcat1
  - tomcat2
  - tomcat3

WAS만 직접 노출하면 이런 분산 처리를 직접 구성하기가 더 번거롭다.

또한, WAS를 보호한다. Tomcat은 비즈니스 로직을 실행하는 핵심 서버이다 그래서 가능하면 외부에 직접 노출하지 않고 앞에 NGINX나 로드밸런서를 두는 경우가 많다.

인터넷 → NGINX or Load Balancer → 내부망 Tomcat

이렇게 하면 Tomcat은 내부에서만 접근 가능하게 만들 수 있다. 또 NGINX에서 요청 크기 제한, 특정 IP 차단, Rate Limit, 잘못된 요청 필터링, 정적 파일 캐싱, 압축

또한, 장애 대응과 배포에도 유리하다. WAS를 재배포를 해야한다고 할 때 NGINX 앞단에서 트래픽을 조절하면 특정 WAS를 잠시 뺴고 배포할 수 있다.

Nginx
  ├── Tomcat 1  ← 배포 중이라 잠시 제외
  └── Tomcat 2  ← 계속 요청 처리

이런식으로 무중단 배포나 헬스 체크 구성도 쉬워진다. → 물론 요즘은 AWS ALB, Kubernetes Service/Ingress 같은 게 이 역할을 한다.

2.6 웹 서버랑 WAS를 분리한 이유

역사적 배경을 한 번 보자

처음에는 웹 서버가 정적 파일만 잘 내려주면 됐는데, 점점 로그인 및 게시판, 주문 같은 동적 기능이 필요해지면서 WAS가 등장함

처음 웹은 거의 정적 파일이었다.

초기 웹은 대부분 다음과 같은 요청이 많았다.

GET /index.html
GET /style.css
GET /logo.png

서버는 그냥 파일 찾아서 내려주면 됐다.

브라우저
  ↓
웹 서버
  ↓
HTML 파일 응답

이때 웹 서버의 역할은 단순했다.

요청받기
파일 찾기
파일 내려주기

대표적으로 Apache HTTP Server 같은 웹 서버가 이 역할을 잘했다.

그런데 동적인 기능이 필요해졌다. 시간이 지나면서 웹이 단순 문서가 아니라 서비스가 되기 시작했다.

로그인, 회원가입, 게시판 글쓰기, 댓글 작성 등등

이런 것들은 단순히 HTML 파일을 내려주는 걸로는 불가능하다. 로그인 같은 기능들은 DB를 봐야하기 때문

사용자가 아이디/비번 입력
  ↓
DB에서 회원 조회
  ↓
비밀번호 검증
  ↓
로그인 성공/실패 응답

즉, 웹 서버 혼자 파일만 내려주는 방식으로는 부족해진 것

그래서 CGI 같은 방식이 나왔다. → 초기에는 웹 서버가 직접 프로그램을 실행하는 방식이 있었다.

예를 들어 요청이 오면

Apache
  ↓
외부 프로그램 실행
  ↓
프로그램이 DB 조회
  ↓
결과 HTML 생성
  ↓
Apache가 응답

이런 방식이 CGI이다. 문제는 요청이 올 때마다 프로그램을 새로 실행하는 식이라서 비효율적이었다.

요청 1개 → 프로세스 1개 실행
요청 100개 → 프로세스 100개 실행

비용이 크고, 느리고, 많은 요청을 처리하기 어려웠다.

그래서 Java 는 Servelet이라는 표준이 나왔다.

요청마다 프로그램을 새로 실행하지 말고 자바 객체를 메모리에 올려두고 재사용하자. → Servlet 방식 == 서블릿 객체를 미리 만들어두고 요청 마다 메서드 호출

protected void doGet(HttpServletRequest request,
                     HttpServletResponse response) {
    // 요청 처리
}

요청이 올때마다 자바 프로그램을 새로 실행시키는 게 아니라 이미 떠 있는 JVM 안에서 메서드만 호출하는 방식 → 이걸 관리하는 게 서블릿 컨테이너 이고 대표가 Tomcat 이다.

그래서 웹 서버 옆에 WAS가 붙었다.

처음에는

Client
  ↓
Web Server
  ↓
HTML/CSS/JS/이미지 응답

그런데 동적 처리가 필요해지니까

Client
  ↓
Web Server
  ↓
CGI / 외부 프로그램
  ↓
DB

이후 java 웹 에서는

Client
  ↓
Web Server
  ↓
Servlet Container / WAS
  ↓
DB

예전 Java 웹 운영에서는 이런 구조가 흔했다

Client
  ↓
Apache HTTP Server
  ↓ mod_jk / AJP
Tomcat
  ↓
Servlet / JSP
  ↓
DB

Apache는 정적 파일과 앞단 요청 처리를 맡고, Tomcat은 Java Servlet/JSP 실행을 맡았다. 그때 관점에서는 Tomcat을 “웹 서버 뒤에 붙는 Java 실행 서버”처럼 많이 썼다

2.7 톰캣(Web Application Server)은 정확히 무엇인가?

톰캣은 원래 서블릿 컨테이너이다. 하지만 HTTP 요청을 직접 받을 수 있고, 동적 요청도 처리할 수 있기 떄문에 일반적으로 WAS라고도 부른다.

정리하면 다음과 같다.

Tomcat = Servlet Container + 간단한 Web Server 기능

다만 Nginx처럼 정적 파일 처리, 리버스 프록시, 로드밸런싱, TLS 종료 같은 기능에 특화된 서버는 아니다.

Spring MVC에서 모든 요청의 시작점은 사실상 DispatcherServlet이며 그 DispatcherServlet을 실행시켜주는 게 톰캣이다.

Tomcat, 서블릿 컨테이너 → 어떤 Servlet을 호출할지까지만 안다.

DispatcherServlet, Spring MVC의 Servlet → 어떤 Controller를 호출할지 안다.

Tomcat이 하는 일

Tomcat은 서블릿 컨테이너니까 이런 일을 한다.

HTTP 요청 받기
↓
HttpServletRequest / HttpServletResponse 생성
↓
이 요청을 처리할 Servlet 찾기
↓
DispatcherServlet 호출

예를 들어 요청이 이렇게 오면:

GET /members/1

Tomcat 입장에서는 이렇게 보는 것이다.

/members/1 요청이 왔네?
이 요청은 DispatcherServlet한테 보내야겠다.

Tomcat은 여기까지만 안다. Tomcat은 이런 건 모른다.

MemberController가 있는지
getMember() 메서드가 있는지
@PathVariable Long id를 어떻게 넣는지
JSON으로 응답해야 하는지

DispatcherServlet이 하는 일

DispatcherServlet은 Spring MVC의 핵심 서블릿이며, Tomcat이 DispatcherServlet을 호출하면 그때부터 Spring MVC 내부 로직이 시작된다.

DispatcherServlet
↓
HandlerMapping에게 물어봄
"이 요청을 처리할 Controller가 누구야?"
↓
HandlerAdapter가 Controller 메서드 실행
↓
ArgumentResolver가 파라미터 넣어줌
↓
HttpMessageConverter가 JSON 변환
↓
응답 반환

즉

이 요청을 처리할 Controller가 누구지?
어떤 메서드를 실행해야 하지?
파라미터는 어떻게 넣어야 하지?
반환값은 JSON으로 바꿔야 하나?

이건 Tomcat 자체가 하는 게 아니라, Tomcat 안에서 실행되는 DispatcherServlet이 Spring MVC 기능을 사용해서 하는 일이다.

3. 요청 흐름 자세히 보기

예를 들어 다음과 같은 요청이 있다.

GET /members/1

Spring Boot + Tomcat에서는 대략 이렇게 처리된다.

클라이언트가 HTTP 요청을 보냄
Tomcat의 Connector가 요청을 받음
Tomcat이 HttpServletRequest, HttpServletResponse 객체를 생성
해당 요청을 처리할 Servlet을 찾음
Spring MVC에서는 DispatcherServlet이 요청을 받음
DispatcherServlet이 HandlerMapping에게 물어봄
"GET /members/1 처리할 Controller가 누구야?"
HandlerMapping이 MemberController의 getMember()를 찾음
HandlerAdapter가 Controller 메서드를 실행
Service, Repository, DB 로직 수행
반환값을 JSON으로 변환
HttpServletResponse에 응답 작성
Tomcat이 클라이언트에게 HTTP 응답 반환

4. 톰캣의 주요 구성 요소

톰캣 내부 구조를 보면 대표적으로 이런 요소들이 있다.

Server
 └── Service
      ├── Connector
      └── Engine
           └── Host
                └── Context
                     └── Servlet

Sever → 톰캣 전체를 의미한다. == 톰캣 프로세스 하나라고 생각하면 된다.

Service → Connector와 Engine을 묶는 단위이다. == 요청을 받는 쪽과 요청을 처리하는 쪽을 연결한다.

Connector → Connector는 클라이언트의 요청을 받는 부분이다. 예를 들어 HTTP 요청은 보통 8080 포트로 들어온다.

<http://localhost:8080>

이 8080 포트에서 요청을 기다리는 게 Connector이다.

Spring boot 에서 다음과 같은 설정을 하면

server.port=8080

톰캣 Connector가 8080 포트에서 요청을 받게 된다. Connector는 HTTP 요청을 파싱해서 내부 객체로 바뀐다.

HTTP 요청 문자열
   ↓
HttpServletRequest
HttpServletResponse

Engine → Connector가 받은 요청을 실제 처리할 곳으로 넘긴다. 예를 들어 여러 도메인이나 여러 애플리케이션이 있을 때 적절한 Host, Context를 찾는다.

Host → 가상 호스트를 의미한다. 예를 들어 api.example.com, admin.example.com 같은 도메인 단위

Context → 하나의 웹 애플리케이션이다. 예를 들어 톰캣에 여러 애플리케이션을 올릴 수 있다. /app, /app2 각각 Context가 될 수 있다. Spring boot 애플리케이션 하나도 하나의 Context라고 볼 수 있다. 보통 Spring boot에서는 context-path를 설정할 수 있다.

server.servlet.context-path=/api

그러면 모든 요청 앞에 /api가 붙는다.

Servelet → 실제 요청을 처리하는 자바 객체이다. Spring MVC에서는 대표적으로 DispatcherServlet이 있다.

5. 톰캣의 스레드 모델

톰캣은 요청이 들어올 때마다 스레드를 사용해서 요청을 처리한다. 흐름은 다음과 같다.

요청 1 → Thread-1
요청 2 → Thread-2
요청 3 → Thread-3

Spring boot의 기본 MVC 방식은 일반적으로 요청 하나당 스레드 하나가 할당되는 구조이다. 예를 들어 동시에 100명이 요청하면 톰캣의 워커 스레드들이 각각 요청을 맡는다.

5.1 중요한 설정 - max-threads

톰캣은 무한정 스레드를 만드는 것이 아니다. 설정된 최대 스레드 수가 있다.
Spring boot 에서는 보통 이런식으로 설정할 수 있다.

server.tomcat.threads.max=200 // 최대 200개의 요청 처리 스레드를 사용할 수 있다.
server.tomcat.threads.min-spare=10 // 최소로 대기시켜둘 스레드의 수

5.2 만약 요청이 너무 많이 들어오면?

톰캣 최대 스레드 200개라고 가정해보았을 때

동시 요청 300개 → 200개 처리, 나머지 100개는 대기

대기열까지 꽉 차면 요청이 거절 될 수 있다. 관련 설정으로는 다음과 같은 것들이 있다.

server.tomcat.threads.max=200
server.tomcat.accept-count=100
server.tomcat.max-connections=8192

대략 의미는

max-connections = 동시에 연결 가능한 최대 커넥션 수
threads.max = 실제 요청을 처리하는 최대 스레드 수
accept-count = 스레드가 부족할 때 대기 가능한 요청 수

6. 톰캣과 DB 커넥션 풀의 관계

톰캣 스레드 수와 DB 커넥션 풀 크기는 서로 영향을 준다. 예를 들어

server.tomcat.threads.max=200
spring.datasource.hikari.maximum-pool-size=10

이렇게 설정되어있다고 가정해보자 그러면 톰캣은 동시에 200개의 요청을 처리하려고 할 수 있다. 그런데 DB 커넥션은 10개 밖에 없다. 그러면 DB를 사용한느 요청은 10개만 실제로 DB에 접근할 수 있고 나머지는 커넥션을 기다린다.

Tomcat Thread 200개
DB Connection 10개

→ DB 작업이 필요한 요청 200개가 들어오면
→ 10개만 DB 사용
→ 190개는 커넥션 대기
→ 응답 지연 증가
→ 타임아웃 가능

그래서 성능 튜닝할 때는 톰캣 스레드만 늘리면 안 된다. 같이 봐야하는 것들은 다음과 같다.

Tomcat threads
HikariCP maximum-pool-size
DB max_connections
API 응답 시간
CPU 사용률
메모리 사용률
외부 API 호출 시간

7. 톰캣과 Spring boot 내장 톰캣

예전에는 보통 다음과 같이 진행했다.

톰캣 서버 설치
WAR 파일 빌드
톰캣 webapps 폴더에 배포
톰캣 실행

즉, 톰캣이 먼저 있고 그 위에 애플리케이션을 올렸다.

External Tomcat
  └── my-app.war

하지만 Spring boot에서 이걸 업그레이드를 했다. 애플리케이션 안에 톰캣이 포함된다.

my-app.jar
  └── embedded Tomcat

그래서 다음과 같이 실행한다.

java -jar app.jar

그러면 Spring boot가 실행되면서 내부에서 톰캣도 같이 실행된다.

즉,

Spring Boot 실행
  ↓
내장 Tomcat 실행
  ↓
DispatcherServlet 등록
  ↓
8080 포트에서 요청 대기

8. 톰캣이 없으면 Spring MVC가 동작할까?

일반적인 Spring MVC 웹 애플리케이션은 서블릿 기반이다. 그래서 요청을 받아서 DispatcherServlet을 실행시켜 줄 서블릿 컨테이너가 필요하다 그 역할을 톰캣이한다. 다만 반드시 톰캣이어야하는 것은 아니다. Spring boot에서는 다른 서버도 사용할 수 있다.

Tomcat, Jetty, Undertow

9. 톰캣 vs NGINX

구분	Tomcat	Nginx
주요 역할	자바 웹 애플리케이션 실행	웹 서버, 리버스 프록시
동적 요청 처리	가능	직접 비즈니스 로직 처리 X
정적 파일 처리	가능하지만 전문은 아님	매우 강함
Java Servlet 실행	가능	불가능
Spring Boot 실행	가능	불가능
로드밸런싱	가능은 하지만 보통 Nginx 사용	강함
TLS/HTTPS 처리	가능	보통 Nginx에서 처리

10. 톰캣과 서블릿 생명주기

톰캣은 서블릿 객체를 직접 관리한다. 서블릿 생명주기는 보통 다음과 같다.

서블릿 클래스 로딩
서블릿 인스턴스 생성
init() 호출
요청마다 service() 호출
종료 시 destroy() 호출

코드로 보면

public class MyServlet extends HttpServlet {

    @Override
    public void init() {
        System.out.println("서블릿 초기화");
    }

    @Override
    protected void service(HttpServletRequest req, HttpServletResponse resp) {
        System.out.println("요청 처리");
    }

    @Override
    public void destroy() {
        System.out.println("서블릿 종료");
    }
}

요청 마다 서블릿 객체를 새로 만드는 것이 아니라 보통 서블릿 객체는 하나 만들어두고 여러 요청을 여러 스레드가 동시에 처리한다. 그래서 서블릿이나 Controller에서 공유 상태를 조심해야한다. 예를 들어 다음고 ㅏ같은 코드는 위험하다

@RestController
public class MemberController {

    private String name;

    @GetMapping("/members")
    public String getMember(@RequestParam String name) {
        this.name = name;
        return this.name;
    }
}

Controller는 싱글톤 빈이기 때문에 여러 요청이 동시에 들어오면 this.name 값이 서로 덮어써질 수 있다.

그래서 요청마다 달라지는 값은 지역 변수로 둬야 한다.

@GetMapping("/members")
public String getMember(@RequestParam String name) {
    return name;
}

11. 톰캣 요청 처리와 HTTP 메서드

톰캣은 HTTP 메서드에 따라 서블릿 메서드를 호출한다.

GET     → doGet()
POST    → doPost()
PUT     → doPut()
DELETE  → doDelete()
PATCH   → service() 내부에서 처리

Spring MVC에서는 우리가 직접 doGet()을 구현하지 않고 다음과 같이 쓴다.

@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
@PatchMapping

내부적으로는 톰캣이 요청을 받고, DispatcherServlet을 거쳐서 알맞은 Controller 메서드가 실행된다.

이미지 조회 시 S3 원본 직접 전송 구조를 Lambda 리사이즈 및 CloudFront 캐싱 구조로 전환

재윤 — Fri, 12 Jun 2026 16:47:45 +0900

저희 서비스는 사용자가 저장한 이미지를 본인만 조회할 수 있도록 S3 Presigned URL 방식을 사용하고 있었습니다. 인증된 사용자에게만 만료 기한이 있는 URL을 발급해 보안을 유지하는 구조였습니다. 그런데 코드를 살펴보니 이미지 조회 과정에서 비효율이 있었습니다. 사용자가 이미지를 조회할 때마다 보유한 이미지 수만큼 서버에서 Presigned URL을 생성하고 있었고, 동일한 이미지를 다시 조회해도 매번 새로운 URL을 발급하고 있었습니다.

이번 글에서는 이 문제를 해결하기 위해 기존 S3 기반 이미지 조회 구조를 CloudFront Signed Cookie, Lambda 리사이징, CloudFront 캐싱 구조로 개선한 과정을 정리합니다. S3로만 이미지를 조회하다가 CloudFront와 Lambda를 도입하려는 분들에게, 구조 변경의 이유와 적용 과정, 그리고 개선 결과를 함께 공유하고자 합니다.

1. 기존 구조 및 문제점

1.1 기존 구조 및 문제점

이미지 조회 기존 구조는 다음과 같았습니다.

클라이언트 조회 요청
- 서버: DB 조회 + presigned URL 생성 (이미지 N장 × N회)
- 클라이언트: presigned URL로 S3에서 이미지 직접 다운로드

여기서 두 가지 문제가 있었습니다.

1. 문제 1 - 조회마다 presigned URL 재생성

기존 구조에서는 이미지를 조회할 때마다 서버에서 S3 Presigned URL을 새로 발급했습니다. 이미지 접근 권한을 제한하기 위해 만료 시간이 있는 URL을 사용하는 방식이었지만 같은 이미지를 다시 조회해도 매번 서버 호출과 서명 연산이 반복되는 문제가 있었습니다.

특히 그리드 화면처럼 여러 이미지를 한 번에 조회하는 경우, 이미지 개수만큼 Presigned URL을 생성해야 하므로 서버 부담이 커질 수 있었습니다.

2. 문제 2 - 그리드 조회 시 원본 크기 이미지 전체 다운로드

클라이언트는 Presigned URL로 S3 원본 이미지를 다운로드해 화면에 표시했습니다. 즉, 수 MB 크기의 원본 이미지가 그대로 전달되고 있었습니다. 이로 인해 이미지 크기가 클수록 로딩 시간이 길어졌고, 이미지마다 표시 시점이 달라져 사용자 경험이 일정하지 않은 문제가 발생했습니다.

1.2 문제 2번에 대한 측정

이미지 크기에 따른 S3 조회 속도를 정확히 확인하기 위해 Flutter에서 presigned URL로 이미지를 로드하는 시간을 직접 측정했습니다.

측정 결과

이미지 크기	p50	p95	p99
Small (1.0MB)	317ms	775ms	969ms
Medium (2.3MB)	745ms	1,738ms	1,842ms
Large (10.1MB)	677ms	2,185ms	2,875ms

p50 기준으로 이미지 크기가 클수록 다운로드 시간이 늘어났습니다. 더 주목할 점은 p95입니다. Small은 p50 317ms에서 p95 775ms로 2.4배 벌어지고, Large는 p50 677ms에서 p95 2,185ms로 3.2배 벌어집니다. 원본 크기가 클수록 응답 시간의 분산도 함께 커지는 구조를 정확하게 알 수 있었습니다.

2. 개선 1 - 조회할 때마다 서버를 거치지 않고 최적화된 이미지 제공

저는 이미지 조회 과정에서 발생하는 두 가지 비효율을 줄이고 싶었습니다. 첫 번째는 이미지 개수만큼 Presigned URL을 반복 발급해야 하는 서버 부담이고 두 번째는 화면에는 썸네일만 필요함에도 원본 이미지를 그대로 다운로드하는 클라이언트 측 부담이었습니다.

그래서 문제를 단순히 “이미지를 어떻게 가져올 것인가”가 아니라, “서버의 서명 연산을 줄이면서도 화면 크기에 맞는 이미지만 전달할 수 있는 구조”로 다시 생각해보았습니다.

이를 해결하기 위해 먼저 문제를 두 방향으로 나누어 접근했습니다.

이미지 접근 권한을 유지하면서도 서버 호출을 줄이는 것이었습니다. 기존처럼 이미지별로 URL을 매번 발급하는 방식이 아니라, 한 번 인증된 사용자가 일정 시간 동안 허용된 이미지 경로에 접근할 수 있는 구조가 필요하다고 판단했습니다. 다만, 이미지가 외부에 공개되어서는 안 되기 때문에 URL을 알고 있더라도 인증되지 않은 사용자는 접근할 수 없는 방식이어야 했습니다.
이미지 자체의 용량을 줄이고, 화면 크기에 맞는 이미지만 전달해 로딩 속도를 개선하는 것이었습니다. 기존에는 썸네일 화면에서도 원본 이미지를 그대로 다운로드했기 때문에, 실제 화면에 필요한 것보다 훨씬 큰 이미지가 전달되고 있었습니다. 이미지를 화면 크기에 맞게 리사이즈하고, 전송 용량도 줄여 더 빠르게 응답할 수 있는 구조가 필요했습니다.

먼저 기존 S3 Presigned URL 방식 안에서 해결할 수 있는 방법을 검토했습니다.

클라이언트에서 발급받은 Presigned URL을 일정 시간 캐싱해두는 방법도 생각했습니다. 하지만 Presigned URL은 만료 시간이 있고 다시 발급될 때마다 URL 값이 달라질 수 있습니다. 결국 클라이언트는 URL이 유효한지 확인하거나 만료된 경우 다시 서버에 요청해야 했습니다. 따라서 클라이언트 캐싱만으로는 이미지 조회 전에 서버를 거쳐야 하는 구조를 근본적으로 해결하기 어렵다고 판단했습니다.
또한 S3에 썸네일 이미지를 미리 생성해두는 방법도 생각했습니다. 이 방식은 원본 이미지 다운로드 문제를 줄일 수 있지만, 사용되지 않을 크기의 이미지까지 미리 생성해야 하고 저장 용량도 증가한다는 단점이 있었습니다.

결국 S3 Presigned URL 방식만으로는 서버 호출을 줄이면서도 필요한 크기의 이미지만 효율적으로 전달하기 어렵다고 판단했습니다.

그래서 이미지 조회의 진입점을 S3가 아니라 CDN으로 옮기는 방향을 생각했습니다.

CDN을 사용하여 반복적으로 조회되는 이미지를 사용자와 가까운 위치에서 빠르게 전달할 수 있습니다. 이를 통해 이미지 로딩 시간뿐만 아니라 사용자가 화면에서 느끼는 대기 시간도 줄일 수 있다고 판단했습니다.
또한 CDN은 단순히 이미지를 빠르게 전달하는 캐시 계층이 아니라, 사용자에게 이미지를 제공하는 새로운 진입점이 됩니다. 따라서 이미지 접근 제어도 S3가 아닌 CDN 계층에서 처리할 수 있다고 판단했습니다.

또한 이미지 용량을 줄이고 화면 크기에 맞게 변환하는 작업은 서버에서 직접 처리하기보다, 필요할 때만 실행되는 서버리스 방식으로 분리하는 것이 적합하다고 판단했습니다.

이미지 리사이즈는 모든 요청에서 항상 필요한 작업이 아니라, 캐시된 결과가 없을 때만 수행되면 된다고 생각을 하였습니다. 항상 실행 중인 서버에 리사이즈 부담을 주기보다는, 캐시 미스 시점에만 별도의 함수가 실행되어 이미지를 변환하는 구조가 더 효율적이라고 생각했습니다.

이러한 기준을 바탕으로 AWS에서 제공하는 CloudFront와 Lambda를 활용하는 방향을 검토했습니다.

CloudFront는 이미지 조회의 진입점 역할을 하면서 캐싱을 통해 반복 요청을 빠르게 처리할 수 있고, Lambda는 캐시 미스 시점에만 실행되어 원본 이미지를 필요한 크기로 변환할 수 있습니다.
또한 CloudFront에서 제공하는 Signed Cookie를 사용하면, 이미지 URL을 알고 있더라도 인증되지 않은 사용자는 접근할 수 없도록 제한할 수 있습니다. 이를 통해 등록된 사용자와 허용된 기기만 CloudFront를 통해 이미지를 조회할 수 있는 구조를 만들 수 있다고 판단했습니다.

→ 이 구조를 사용함으로써 운영 서버에 비효율적인 요청을 없앨 수 있고, 이미지 크기와 사용자의 기기 화면에 맞게 줄여 속도가 개선될 것이라고 생각했습니다.

아키텍처를 만들어보았습니다.

이미지 조회 시 서버를 거치지 않고 Secure Storage에 저장된 쿠키를 첨부해 CloudFront에 직접 요청합니다. 쿠키가 만료된 경우 서버에 재발급을 요청한 뒤 자동으로 재시도하며, 캐시 미스 시 Lambda가 S3 원본을 가져와 리사이즈한 결과를 CloudFront가 캐싱합니다.

2.2 AWS 보안

1. S3 직접 접근 차단

S3 버킷은 퍼블릭 액세스를 차단하고, CloudFront OAC(Origin Access Control)를 통해서만 접근할 수 있도록 구성했습니다. 따라서 사용자가 S3 객체 URL을 직접 알고 있더라도 S3로 직접 요청하면 AccessDenied가 반환됩니다.
또한 이미지 조회 요청은 CloudFront를 통해서만 처리되며, CloudFront에서는 Signed Cookie를 검증해 인증된 사용자만 이미지에 접근할 수 있도록 구성했습니다.

2. Lambda 직접 접근 차단

리사이즈를 수행하는 Lambda Function URL에는 AWS_IAM 인증을 적용했습니다. 여기에 CloudFront Lambda OAC를 연결해, CloudFront가 SigV4 서명 요청을 보낼 때만 Lambda를 호출할 수 있도록 했습니다.

3. CloudFront Signed Cookie 인증

CloudFront의 리사이즈 경로, 기본 접근 경로에 Viewer access restriction을 적용했습니다. 따라서 Signed Cookie가 없는 요청은 CloudFront 단계에서 차단됩니다. 사용되는 쿠키는 아래 3개입니다.

CloudFront-Policy → 어떤 경로에, 언제까지 접근 가능한지 적힌 정책
CloudFront-Signature → 위 Policy가 서버가 만든 진짜 정책인지 증명하는 서명값
CloudFront-Key-Pair-Id → 서명 검증에 사용할 공개키 ID

쿠키 운영 정책은 다음과 같이 잡았습니다.

TTL: 15분
저장 위치: Flutter Secure Storage
만료 처리: 이미지 요청 시 403이 발생하면 쿠키를 재발급한 뒤 한 번 재시도
로그아웃 처리: 저장된 Signed Cookie 삭제

2.3 이미지 다운로드의 문제

조회 구조를 CloudFront와 리사이즈 방식으로 바꾸고 나니, 이번에는 다운로드 쪽에서 문제가 생겼습니다. 기존에는 하나의 presigned URL로 조회와 다운로드를 모두 처리하고 있었습니다. 이미지를 화면에 보여줄 때도, 외부로 공유하거나 저장할 때도 같은 URL을 사용했습니다.

그런데 조회용 URL을 CloudFront 리사이즈 URL로 바꾸면서 이 URL로 다운로드를 시도하면 400px로 리사이즈된 WebP 파일이 내려왔습니다. 화면에 작게 표시할 때는 충분하지만 사용자가 이미지를 외부로 공유하거나 저장할 때는 원본 화질이 필요했습니다.

생각해보니 조회와 다운로드는 애초에 요구사항이 달랐습니다.

조회 → 화면 크기에 맞는 작은 이미지면 충분 (리사이즈)
다운로드 → 원본 화질 그대로 필요 (원본)

그래서 두 경로를 분리하기로 했습니다. 조회는 Lambda를 거치는 리사이즈 경로를 사용하고, 다운로드는 S3 원본을 그대로 가져오는 경로를 사용하도록 했습니다.

조회 → Lambda 리사이즈 → WebP
다운로드 → S3 원본 그대로

다운로드 경로 역시 CloudFront를 통하기 때문에 S3에 직접 접근하지 않고 조회와 동일하게 Signed Cookie로 인증하도록 했습니다.

3. 개선 후 재측정

개선 후에도 기존 측정과 동일하게 Small, Medium, Large 3개의 이미지를 기준으로 Flutter에서 이미지 로드 시간을 측정했습니다.

테스트 이미지는 다음과 같습니다.

Small: 1.0MB 원본 이미지
Medium: 2.3MB 원본 이미지
Large: 10.1MB 원본 이미지

CloudFront는 캐시 특성상 첫 요청과 이후 요청의 동작이 다르기 때문에, 두 상태를 구분해서 측정했습니다.

캐시 미스: CloudFront에 캐시가 없어 Lambda가 원본을 읽어 리사이즈하는 첫 요청
캐시 히트: 리사이즈 결과가 CloudFront에 캐싱된 이후의 요청

3. 측정 결과 및 개선 전 비교

구분	원본 크기	개선 후 전송 크기	S3 p50	CF 캐시 히트 p50	p50 기준 감소율
Small	1.0MB	13.4KB	317ms	45ms	85.8% 감소
Medium	2.3MB	22.3KB	745ms	40ms	94.6% 감소
Large	10.1MB	32.9KB	677ms	38ms	94.4% 감소

각 이미지별로 웜업 5회 후 100회 반복 측정한 결과입니다.S3 전체 누적 기준 p50 538ms에서 CloudFront 캐시 히트 p50 45ms로, p50 기준 약 12배 개선됐습니다. 전송 크기도 크게 줄었습니다. 기존에는 1.0~10.1MB 원본 이미지를 그대로 전송했지만, 개선 후에는 Lambda에서 400px 리사이즈 및 WebP 변환을 거쳐 13.4~32.9KB로 전송됩니다.

3.1 분석

가장 두드러진 변화는 응답 시간의 안정성입니다. S3는 이미지 크기가 클수록 p95가 폭발적으로 벌어집니다. Large 기준으로 p50 677ms인데 p95는 2,185ms로 3.2배 차이가 납니다. 반면 CloudFront 캐시 히트는 세 이미지 모두 p50 38~45ms, p95 62~64ms 수준으로 원본 크기와 무관하게 안정적입니다. S3에서는 원본 크기가 클수록 사용자가 체감하는 속도가 느려질 뿐 아니라 예측하기도 어려웠는데, CloudFront 캐시 히트 이후에는 그 분산 자체가 사라졌습니다.

캐시 미스 상태에서는 개선 전보다 오히려 느린 결과가 나왔습니다. CloudFront에 캐시가 없는 첫 요청에서는 Lambda가 S3 원본을 읽고 sharp로 리사이즈 및 WebP 변환을 수행해야 하기 때문입니다. 캐시 미스 측정은 각 이미지의 첫 요청 1회씩을 샘플로 기록했으며, Small 967ms, Medium 980ms, Large 2,320ms였습니다. Large의 캐시 미스가 가장 높은 건 원본 파일 크기(10.1MB)의 영향이고, Small과 Medium이 비슷한 수준으로 나온 건 Lambda가 이미 웜 상태였기 때문으로 보입니다. 즉, 이번 개선은 첫 요청 속도보다 반복 조회 성능을 개선하는 방향입니다. 한 번 리사이즈된 이미지가 CloudFront에 캐싱되면 이후 요청은 원본 크기와 무관하게 안정적인 속도로 제공됩니다. 실제 사용 환경에서는 같은 이미지를 반복 조회하는 경우가 많기 때문에 대부분의 요청이 캐시 히트로 처리됩니다.

3.2 한계점 및 보완 계획

캐시 히트 상태에서는 p50 기준 85~94% 개선 효과가 있었지만, 캐시 미스 상태에서는 Lambda 리사이즈 처리 시간이 추가되어 S3 직접 조회보다 느려지는 한계가 있습니다. 이를 보완하기 위해 Flutter 클라이언트 캐싱을 함께 적용할 계획입니다. CloudFront 캐시가 서버 측 캐시 역할을 한다면, Flutter 로컬 캐시는 사용자 기기에서 반복 조회되는 이미지를 즉시 재사용하는 역할을 합니다. 최종적으로는 다음과 같은 다층 캐시 구조를 목표로 합니다. 이를 통해 최초 요청에서 Lambda 리사이즈가 수행되더라도, 이후 동일 이미지 재조회나 화면 재진입 시에는 Flutter 로컬 캐시 또는 CloudFront 캐시를 통해 더 빠르게 이미지를 표시할 수 있습니다.

[외주] 배포 이후 - 달라진 요구사항 회의, 그리고 계속 쌓는 업데이트 로그 (6/5, 6/17, 7/1)

재윤 — Thu, 11 Jun 2026 20:28:29 +0900

최근 업데이트: 7/1

저번 포스팅에서 클라이언트와의 커뮤니케이션 문제를 겪고 계약 구조를 다시 잡았다고 이야기했습니다. 이번 글은 그 이후의 기록입니다.

다만 이 글은 한 번 쓰고 끝내는 글이 아닙니다. 유지보수 계약 기간 동안 요구사항 회의와 업데이트 내역을 날짜별로 계속 쌓아가는 로그이며, 새 회의가 있을 때마다 마지막 섹션에 내용이 추가됩니다.

1. 달라진 요구사항 회의 (6/5)

6월 5일, 사장님과 첫 정식 요구사항 회의를 가졌습니다. 확실히 달랐습니다. 예전처럼 "이것도 되면 좋겠는데"가 아니라, 하나하나 꼼꼼하게 정리해서 말씀해 주셨습니다. 계약 구조를 다시 잡은 효과를 회의 방식에서부터 체감할 수 있었습니다.

2. 고시원 관리 프로그램 2차 업데이트 계획표

요구사항을 정리하고 나서 가장 먼저 한 일은 우선순위를 나누는 것이었습니다. 모든 기능을 한꺼번에 처리하려고 하면 결국 아무것도 제대로 못 하는 상황이 생기기 때문입니다.

기준은 단순하게 잡았습니다. 현재 고시원 운영에 직접 영향을 주는 기능은 높음, 불편하지만 당장 급하지 않은 기능은 중간, 있으면 좋지만 여유가 생길 때 작업해도 되는 기능은 낮음으로 분류했습니다.

그 결과 미납 상태 처리, 계약 만료일 분리, 월세 납부일 자동 TodoList 표시처럼 실제 운영과 직결되는 기능들을 Phase 1로 묶어 가장 먼저 처리하기로 했습니다. 이후 Phase 2, 3에서 입실자 관리 개선과 반복 TodoList 같은 기능들을 순차적으로 진행하고, 주식 차트 스타일의 연간 캘린더는 학습 시간이 필요한 만큼 Phase 4로 따로 분리했습니다.

전체 일정은 약 한 달 반, 7월 20일 전후를 목표로 잡았습니다. 진행하면서 기간이 달라질 수 있지만, 변동이 생길 경우 미리 공유드릴 예정입니다.

3. 사장님 미팅 후기 및 미팅 끝나고 난 후

계획표를 완성한 후 사장님과 미팅을 진행하였습니다. 사장님께서는 계획표를 보시고 기한이 명확하게 정해져 있어서 좋다고 말씀해 주셨습니다. 또한 이 계획표는 총무님들께도 공유하여, 배포가 이루어질 때마다 함께 진행 상황을 체크하겠다고 하셨습니다.

유지보수 계약 부분도 순조롭게 마무리되었습니다. 월 15만원씩, 1년간의 유지보수 계약에 사장님께서 흔쾌히 동의해 주셨고, 계약서도 함께 작성하였습니다. 저번 포스팅에서 이야기했던 계약 구조가 이렇게 실제로 자리를 잡게 되었고, 저 역시 앞으로의 작업에 더 집중할 수 있겠다는 안도감이 들었습니다.

4. 날짜별 요구사항 & 업데이트 로그

이 섹션은 요구사항 회의가 있을 때마다 최신 날짜가 위에 오도록 계속 추가됩니다.

5. 날짜별 요구사항 업데이트

6/5

todoList
- 각 입실자의 월세 납부일마다 todoList에 해당자가 뜨게
- 퇴실일 기준 한 달 전에 todoList에 뜨게
- 반복 일정 등록 기능 → 생성·수정·삭제 가능, 요일/날짜 지정 모두 지원
  - 날짜 지정 시 말일 처리: 1월 30일 등록 건은 2월엔 28일에 표시 (28일 이후 날짜는 전부 28일로)
  - 기간은 등록일 기준 5년 뒤까지
대시보드
- 도면 사진 위에 이름·방타입 표시 + 오른쪽에 층별 이름·방타입 목록
  - 오른쪽 목록도 도면처럼 클릭 시 상세 보기

입실자 관리
- 입실자 목록이 세로로 너무 길다 → 층별(섹션) 보기 / 행 높이 줄이기 2가지 방식 중 선택 가능하게
- 상태 컬럼 제거
- 방 관리 컬럼
  - 가격에 천원 단위가 안 들어가는 문제
  - 방관리 키워드(부동산식 입력) 추가·수정·삭제
  - 방 관리 데이터 기입 시 todoList에 자동 반영
- 상세 관리 → 기존 퇴실일을 계약 만료일로 변경하고, 확정 퇴실일 컬럼 별도 추가
- 월세 납부일 컬럼
  - 5일 전·4일 전 표시 불필요, 당일만 표시
  - 하나라도 미납이면 계속 미납 상태 유지 (예: 6월에 4·5월 냈어도 3월 미납이면 미납 표시)
- 이력에서 수정 가능하게 → 단, 보증금만
- 상세 페이지에 메모장
- 상세 이력 및 신규 입실자 등록에 계약금 항목

연간 캘린더
- 막대 그래프 축소 시 잘 안 보임 → 토스 주식 차트 형태로 (단위: 일·주·월·년 선택)
https://www.tossinvest.com/stocks/A039490/order
통계
- 없음

6/17

todoList
- 방에 대한 유지보수 내역 추가하면 달력에 다 뜨게 하며 할일, 월세납부, 계약 만료 버튼 처럼 추가하기
- todoList에서 우선순위를 지정할 수 있으면 좋겠다. 그래서 할일을 중간에 넣을 수 있도록
입실자 관리
- 현금 승계 부분에서 계좌 내역을 2개만 선택할 수 있게. == 사장님, 원장님
- 입실일에 대한 개월 수 데이터 필요
출력이라는 큰 타이틀이 필요 && 1년 단위, 달 단위 필요
- 방 유지보수 내역 출력 → PDF 필요
- 현금 승계 프린트 한 번에 되게 → 한장에 다 모아서 하루치를 다 보고 싶다. 1인당 종이 하나씩 써야해서 불편하다.
데이터 백업 → 추후 많이 만들어졌을 때 진행
- 사장님 입장 → 병원에서 일을 하셨는데 이게 데이터 보관이 정말 중요했다. 그래서 나도 관리 잘해주셨으면 한다. 나한테 맡기는 것이 분명 리스크가 있을 수 있다.

7/1

todoList
- 각 월세에 대한 분들 그 달의 납부가 되었는지 안 되었는지
  - 표시가 어려우면 ‘-’, ‘+’ 같은 방향으로
  - 체크는 할 수 있게끔
- todoList에서 뜨는 게 월세 납우 일자가 만약 3월 31일이면 2월은 28일날 뜨게 나와야하고 7월 31일이면 6월은 30일 뜨도록 진행
입실자 관리
- 이력 부분에서 보증금 차감 이력이 안 보인다.
  - 이게 없으면 이 사람이 왜 차감 되었는지 볼 수가 없다.
- 이력 부분에서 다른 모든 데이터들이 수정이 가능할 수 있도록
  - 월세 납부 이력, 기본정보, 계약 정보 모두
  - 이게 필요한 이유는 현재 이력에서 수정이 안되니 이 사람을 입실을 다시 하고 해야하는데 만약 이 사람이 원래 있던 방에 다른 사람이 이미 입실해있으면 반영이 안 된다.
  - 원래는 이력 데이터라 수정이 되면 안 좋을 것 같다고 생각했지만,, 어차피 많이 건드릴 필요가 없을 것 같다.
- 입실자 현황 인쇄 → 사장님께서 브라우저를 통해 인쇄 버튼을 눌렸는데 이상하게 나옴. 확대 축소는 다른 곳에서 잘 되는데 내가 만든 프로그램에서는 안 됨.
  - 입실자 현황을 PDF로 할 수 있는 것이 필요
대시보드 & 입실자 관리 & 통계
- 현재 방 밖에 없는데 공용 공간이 하나 있으면 좋겠다.
  - 고시원에서 주방, 세탁기 같은 것들 AS 받으면 기록할 방법이 없다.
  - 수기로 넣을 수 있게 해주면 좋겠다.
- 공용 공간도 통계에서 방 관리 유지 통계에서 보이도록
- 공용 공간이 todoList에서 기입할 수 있도록 하면 좋겠다.
통계
- 각 유지보수 금액들 월별 예상 수입 추이 처럼 통계가 나오면 좋겠다.

다음 요구사항 회의가 진행되면 이 글에 이어서 기록하겠습니다.

[외주] 고시원 관리 프로그램 2차 업데이트 요구사항 정리 및 계획표 (6/5, 6/17, 7/1 통합)

재윤 — Thu, 11 Jun 2026 20:26:31 +0900

6/5 미팅에서 말씀해 주신 요구사항에 더해, 6/17과 7/1 미팅에서 추가로 말씀해 주신 요구사항까지 통합하여 정리하고 작업 계획표를 다시 작성했습니다. 검토 후 수정이 필요한 부분이 있으시면 말씀해 주세요.

각 항목 뒤의 괄호는 요구사항이 나온 미팅 날짜입니다. 표시가 없는 항목은 6/5 미팅 기준입니다.

1. 요구사항 전체 정리

1.1 todoList

1.1.1 각 입실자들의 월세 납부일이 있다. todoList에 하루마다 월세 내는 날 해당자가 뜨는 것

1.1.2 각 입실자들의 퇴실일 기준으로 한 달 전에 todoList에 뜨는 것

1.1.3 반복적인 todoList에 들어갈 것을 넣을 수 있으며 수정, 생성, 삭제가 가능함. 또한, 반복적인 일에 대해서 설정할 때 요일로 물어볼 수도 있으며 날짜로도 지정 가능하다.

날짜로 지정할 때 2월 같은 경우는 1월 30일 → 2월 28일 같은 것에 뜨게 (28일 이후로는 전부 28일 날짜에 넣어주면 됨)
기간 설정으로는 넣은 날짜에 맞추어 5년 뒤까지

1.1.4 방에 대한 유지보수 내역을 추가하면 달력에 표시되며, 할일·월세납부·계약만료 버튼처럼 추가 가능하게(6/17)

1.1.5 todoList 우선순위 지정 기능 - 할일을 중간에 끼워 넣을 수 있도록 (6/17)

1.1.6 각 입실자의 월세가 그 달에 납부되었는지 표시 - 표시가 어렵다면 '-', '+' 방식으로, 체크는 가능하게 (7/1)

1.1.7 월세 납부일 말일 처리 - 납부일이 3월 31일이면 2월엔 28일에, 7월 31일이면 6월엔 30일에 뜨도록 (7/1)

1.2 대시보드

1.2.1 도면 사진 위에 이름과 방타입이 뜨는 것과 오른쪽에 각 층마다 이름 & 방타입이 뜨는 것

오른쪽에 뜨는 이름 & 방타입의 경우 도면과 같이 누르면 상세도 보인다.

1.3 입실자 관리

1.3.1 현재 입실자 목록이 세로로 너무 길어서 세로 길이를 줄이고 싶다.

해결 방법 → 각 층별(섹션)로 볼 수 있는 방법, 위아래 줄이는 방법 2가지로 선택해서 볼 수 있게 진행

1.3.2 상태 컬럼은 필요 없다.

1.3.3 방 관리 컬럼

가격 천원이 안 들어감
방관리 키워드(부동산처럼 입력하자) - 수정, 삭제, 추가
방 관리에 대한 데이터 기입 시에 todoList에서도 자동으로 보이게

1.3.4 상세 관리

입실일에 대한 개월 수 데이터 필요
계약서 상의: 계약 만료일 컬럼 추가, 추가적인 컬럼 실질적인 (퇴실일 필요) 2가지가 있음. 그래서 현재 퇴실일이 있는데 이것을 계약 만료일로 진행하고, 퇴실일을 따로 만들어서 확정 퇴실일이 필요하다.

1.3.5 월세 납부일 컬럼

5일전, 4일전 보이는 형태는 필요없다. 그 날만 있으면 된다.
하나라도 안 내면 미납 처리 - 미납 상태이면 계속 미납이 뜨도록 (예: 6월인데 5월, 4월은 냈어도 3월이 미납이면 계속 미납 표시)

1.3.6 이력에서 수정할 수 있도록 (퇴실 처리 갔을 때 데이터 수정, 단 보증금만)

1.3.7 입실자 관리 상세 페이지에서 메모장

1.3.8 상세 이력 및 신규 입실자 등록에서 계약금 필요

1.3.9 현금 승계에서 계좌 내역을 2개만 선택 가능하게 - 사장님, 원장님 (6/17)

1.3.10 이력에서 보증금 차감 이력 표시 - 차감 사유를 확인할 수 있도록 (7/1)

1.3.11 이력 데이터 전체 수정 가능하게 - 월세 납부 이력, 기본 정보, 계약 정보 모두 (7/1)

기존 1.3.6(보증금만 수정)의 확장. 현재는 이력 수정이 안 되어 재입실 처리를 해야 하는데, 원래 방에 다른 입실자가 있으면 반영이 안 되는 문제

1.4 연간 캘린더

1.4.1 막대 그래프 축소 시 잘 보이지 않음 → 토스 주식 차트 스타일로 구현

1.4.2 단위는 일 / 주 / 월 / 년 선택

1.5 출력 (6/17 신규)

1.5.1 '출력' 큰 메뉴 신설 - 1년 단위, 달 단위 지원 (6/17)

1.5.2 방 유지보수 내역 PDF 출력 (6/17)

1.5.3 현금 승계 출력을 하루치 한 장에 모아서 - 현재 1인당 종이 한 장씩 필요해 불편 (6/17)

1.5.4 입실자 현황 PDF 출력 - 브라우저 인쇄 시 화면이 깨지는 문제 해결 (7/1)

1.6 공용 공간 (7/1 신규)

1.6.1 공용 공간 등록 - 주방, 세탁기 등 AS 내역을 수기로 기록 가능하게 (7/1)

1.6.2 공용 공간도 방 유지보수 통계에 포함 (7/1)

1.6.3 공용 공간을 todoList에서 기입 가능하게 (7/1)

1.7 통계 (7/1 신규)

1.7.1 유지보수 금액을 월별 예상 수입 추이처럼 통계로 표시 (7/1)

1.8 데이터 백업 (6/17)

1.8.1 데이터 백업 - 데이터가 충분히 쌓인 뒤 진행하기로 협의. 세부 방안은 「데이터 관리 방안 보고서(6/17)」 참고

2. 작업 계획표

우선순위 분류 기준

높음 - 현재 운영에 직접 영향을 주는 기능
중간 - 불편하지만 당장 급하지 않은 기능
낮음 - 개선 사항, 여유 있을 때 작업

Phase 1 - 긴급 수정 (6/10 ~ 6/20, 약 1.5주) - 완료

번호	우선순위	기능 예상	소요
1.3.5		미납 상태 누적 처리 (하나라도 미납 시 계속 표시)	1~2일
1.3.4		계약 만료일 / 퇴실일 컬럼 분리	1일
1.3.5		월세 납부일 당일만 표시로 변경	0.5일
1.1.1		월세 납부일 기준 당일 자동 TodoList 표시	1~2일
1.1.2		퇴실일 1개월 전 자동 TodoList 표시	1일
1.3.8		상세 이력 및 신규 입실자 등록에서 계약금 필요	1 ~ 2일

Phase 2 - 중간 우선순위 개선 (6/21 ~ 7/1, 약 1.5주) - 완료

번호	우선순위	기능 예상	예상 소요
1.3.1		입실자 목록 세로 길이 축소 (층별 섹션 / 접기 2가지 방식)	1~2일
1.3.2		상태 컬럼 제거	0.5일
1.3.3		방 관리 가격 천원 단위 수정	0.5일
1.3.3		방 관리 키워드 부동산 스타일 입력 (수정 / 삭제 / 추가)	1일
1.3.6		퇴실 이력에서 보증금 수정 가능하도록	1일
1.2.1		도면 위 이름 & 방타입 표시 + 오른쪽 목록 연동 클릭 시 상세 보기	1~2일
1.1.3		반복 TodoList 생성 / 수정 / 삭제 (요일 or 날짜 지정)	1~2일

Phase 3 - 낮은 우선순위 개선 (7/2 ~ 7/11, 약 1.5주) - 완료

번호	우선순위	기능	예상 소요
1.1.3		반복 기간 설정 (최대 5년)	0.5일
1.3.3		방 관리 데이터 입력 시 TodoList 자동 반영	0.5일
1.3.7		입실자 상세 페이지 메모장 추가	0.5일
1.3.4		입실일 기준 개월 수 표시	0.5일

Phase 4 - 6/17 추가 요구사항: 출력 & TodoList 확장 (7/12 ~ 7/24, 약 2주)

번호	우선순위	기능	예상 소요
1.5.1		'출력' 메뉴 신설 (1년 / 달 단위)	1~2일
1.5.3		현금 승계 하루치 한 장 출력(어려움)	1~2일
1.5.2		방 유지보수 내역 PDF 출력	1~2일
1.3.9		현금 승계 계좌 2개 제한 (사장님 / 원장님)	0.5일
1.1.4		방 유지보수 내역 달력 표시 + 버튼 추가	1~2일
1.1.5		TodoList 우선순위 지정 (중간 삽입)	1~2일

Phase 5 - 7/1 추가 요구사항: 이력, 공용 공간, 통계 (7/25 ~ 8/8, 약 2주)

번호	우선순위	기능	예상 소요
1.5.4		입실자 현황 PDF 출력 (인쇄 깨짐 해결)	1~2일
1.3.10		보증금 차감 이력 표시	0.5~1일
1.3.11		이력 데이터 전체 수정 (월세 납부 / 기본 정보 / 계약 정보)	2~3일
1.1.6		월세 납부 여부 표시 및 체크	1일
1.1.7		월세 납부일 말일 처리	0.5~1일
1.6.1~3		공용 공간 등록 + 통계 포함 + TodoList 연동	2~3일
1.7.1		유지보수 금액 월별 추이 통계	1~2일

Phase 6 - 연간 캘린더 (8/9 ~ 8/23, 약 2주)

번호	우선순위	기능	예상 소요
1.4.1		연간 캘린더 주식 차트 스타일 학습 및 구현	1~1.5주
1.4.2		캘린더 단위 선택 (일 / 주 / 월 / 년)	1일

별도 진행

번호	기능	비고
1.8.1	데이터 백업	데이터가 충분히 쌓인 뒤 진행 (시기 별도 협의, 6/17 보고서 참고)

전체 예상 일정 요약

Phase	내용	기간 상태
Phase 1	긴급 수정	6/10 ~ 6/20
Phase 2	중간 우선순위 개선	6/21 ~ 7/1
Phase 3	낮은 우선순위 개선	7/2 ~ 7/11
Phase 4	6/17 추가 요구사항 (출력 & TodoList 확장)	7/12 ~ 7/24
Phase 5	7/1 추가 요구사항 (이력 · 공용 공간 · 통계)	7/25 ~ 8/8
Phase 6	연간 캘린더	8/9 ~ 8/23
완료 목표		8월 23일 전후