고민보단 실천을

이미지 업로드 파이프라인 최적화: 리사이징, 썸네일, WebP/AVIF 변환을 어디서 처리할까

Just-Do-It — Fri, 10 Apr 2026 20:59:22 +0900

이미지 업로드 파이프라인 최적화: 리사이징, 썸네일, WebP/AVIF 변환을 어디서 처리할까

이미지 업로드는 저장만 되는 순간 끝나는 기능이 아니다. 원본 보관, 파생 이미지 생성, 포맷 변환, 캐시 전략까지 연결돼야 비용과 성능이 안정된다.

중급 설계에서는 클라이언트, 엣지, 서버, 비동기 워커 중 어디에서 어떤 처리를 할지 역할을 나눠야 한다.

왜 지금 이 주제가 중요한가

원본을 그대로 서비스하면 대역폭과 LCP가 모두 악화된다.
모든 변환을 동기 요청에서 처리하면 업로드 성공률과 응답 시간이 떨어진다.
포맷 변환은 성능 개선 도구이지만 브라우저 호환성과 저장 비용을 함께 고려해야 한다.

핵심 설계 포인트

업로드 경로는 원본 저장과 메타데이터 기록을 우선 완료하고, 변환은 비동기 워커로 넘긴다.
썸네일, 리스트용, 상세용처럼 실제 사용 크기 기준으로 파생 이미지를 정의한다.
WebP/AVIF는 클라이언트 지원 범위와 CDN 협상을 고려해 선택한다.
원본과 파생 이미지 키 규칙을 맞춰 purge와 재생성을 쉽게 만든다.

예시 구성

client upload -> object storage(original)
original stored -> queue publish(image_id)
worker -> resize 320/768/1280 + WebP/AVIF variants
CDN -> Accept header 기반 서빙 또는 명시적 파일 경로 사용

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

실제 화면에서 필요한 이미지 크기와 포맷을 먼저 목록화한다.
업로드 성공 경로와 변환 파이프라인을 분리해 요청 시간을 줄인다.
비동기 워커에 재시도, 실패 보상, 중복 실행 방지 키를 넣는다.
CDN 캐시 키와 format negotiation 전략을 설계한다.
실제 네트워크 환경에서 LCP와 전송량 개선을 측정한다.

운영 체크포인트

변환 실패 이미지를 재처리할 수 있는 운영 툴이 필요하다.
클라이언트 업로드 직후에는 placeholder 또는 original fallback 전략을 둔다.
이미지 품질 설정은 감으로 정하지 말고 실제 파일 크기와 시각 품질을 비교한다.

운영 지표/알람 추천

업로드 성공률과 처리 파이프라인 지연
리사이즈/변환 큐 적체와 실패 비율
원본/파생 이미지 저장 비용과 CDN hit ratio
모바일/저대역폭 환경에서의 LCP 변화

빠른 점검 명령/쿼리

# 업로드 원본 크기/형식 상위 10개 확인
# 변환 worker 처리 시간과 실패율 비교
# CDN hit/miss와 이미지 포맷 협상 결과 점검

구조화 로그 필드 추천

traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

핵심 경로 에러율: 0.1% 이하
핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
중복 실행 또는 데이터 유실: 0건
장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

모든 포맷 변환을 동기 업로드 요청에서 처리한다: 성공률이 떨어진다.
화면 요구와 무관한 크기를 많이 만든다: 저장 비용과 캐시 효율이 나빠진다.
브라우저 호환성 검증 없이 AVIF만 밀어붙인다: 특정 환경에서 깨진다.

바로 적용 템플릿

이미지 파이프라인 템플릿:
original 저장 -> async transform
variant size 목록(thumb/list/detail/hero)
format policy(WebP/AVIF/JPEG fallback)
재처리 및 purge 절차

검증 방법

저대역폭 모바일 환경에서 이미지 최적화 전후 LCP와 전송량을 비교한다.
변환 워커 장애 후 재처리 절차로 누락된 파생 이미지가 복구되는지 확인한다.

장애 대응 Runbook(초안)

현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
롤백 또는 비상 스위치가 준비돼 있다.
최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "이미지 업로드 파이프라인 최적화: 리사이징, 썸네일, WebP/AVIF 변환을 어디서 처리할까"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

Q. 팀 합의가 자꾸 흔들립니다. 무엇을 문서로 남겨야 하나요?
A. 상태 전이, 기본값, 예외 처리, 롤백 기준 네 가지는 반드시 남겨야 한다. 이 네 가지가 없으면 장애 때 판단이 흔들린다.

참고/출처

GraphQL 성능 튜닝: N+1 문제, DataLoader, Persisted Query로 병목 줄이기

Just-Do-It — Fri, 10 Apr 2026 19:59:53 +0900

GraphQL 성능 튜닝: N+1 문제, DataLoader, Persisted Query로 병목 줄이기

GraphQL은 필요한 데이터를 정확히 요청할 수 있게 해 주지만, 서버가 자동으로 효율적인 쿼리를 만들어 주는 것은 아니다.

중급 운영에서는 스키마 설계, resolver 호출 패턴, 캐싱, persisted query를 함께 다뤄야 실제 성능이 좋아진다.

왜 지금 이 주제가 중요한가

N+1 문제는 작은 데이터셋에서는 안 보이다가 실서비스에서 폭발한다.
복잡한 쿼리는 DB 병목뿐 아니라 네트워크 payload와 캐시 무효화 비용도 키운다.
쿼리 자유도가 높을수록 서버는 guardrail을 명확히 둬야 한다.

핵심 설계 포인트

resolver는 각각 독립적으로 DB를 때리지 않도록 DataLoader 또는 batch layer를 둔다.
persisted query를 사용해 쿼리 길이와 캐시 키를 안정화한다.
depth/complexity 제한을 두어 과도한 쿼리를 차단한다.
필드별 비용이 큰 경우 캐시 가능한 읽기 모델을 분리한다.

예시 구성

const userLoader = new DataLoader(async (ids) => {
  const rows = await db.users.findByIds(ids);
  return ids.map((id) => rows.find((row) => row.id === id));
});

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

상위 10개 GraphQL query와 resolver 호출 패턴을 먼저 측정한다.
N+1이 심한 경로에 DataLoader를 적용하고, 배치 키를 설계한다.
persisted query를 도입해 캐시와 보안 정책을 단순화한다.
complexity limit를 붙이고 운영 알람 기준을 정한다.
쿼리 변경 시 DB 플랜과 payload 크기를 같이 검토한다.

운영 체크포인트

GraphQL query 이름(operationName)을 로그에 남겨야 병목 분석이 가능하다.
persisted query 캐시 미스율이 높으면 배포/빌드 파이프라인을 점검한다.
schema 변경 시 클라이언트 쿼리 수집 데이터를 함께 본다.

운영 지표/알람 추천

버전별 트래픽 비율과 미지원 버전 접근 수
deprecation/sunset 헤더 적용률
클라이언트 오류율(4xx)과 호환성 이슈 건수
변경 후 고객사별 migration 진행률

빠른 점검 명령/쿼리

curl -I https://example.com/api/resource
curl -H 'Accept: application/vnd.example.v2+json' https://example.com/api/resource
rg 'Sunset|Deprecation|api-version' ./logs -n

구조화 로그 필드 추천

traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

핵심 경로 에러율: 0.1% 이하
핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
중복 실행 또는 데이터 유실: 0건
장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

DataLoader를 전역 싱글턴으로 둔다: 요청 간 캐시 오염이 생길 수 있다.
복잡도 제한 없이 외부 공개 GraphQL을 연다: 비용 예측이 어려워진다.
persisted query를 도입하면서 버전 관리가 없다: 배포 직후 미스가 늘어난다.

바로 적용 템플릿

GraphQL 성능 템플릿:
operationName 로깅
요청 스코프 DataLoader
persisted query + hash registry
depth/complexity limit

검증 방법

같은 쿼리에서 resolver 호출 횟수가 DataLoader 전후로 줄었는지 확인한다.
persisted query 강제 후 미등록 쿼리가 적절히 차단되는지 검증한다.

장애 대응 Runbook(초안)

현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
롤백 또는 비상 스위치가 준비돼 있다.
최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "GraphQL 성능 튜닝: N+1 문제, DataLoader, Persisted Query로 병목 줄이기"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

참고/출처

Feature Flag 운영 가이드: 점진 배포, A/B 테스트, Kill Switch를 안전하게 설계하는 방법

Just-Do-It — Fri, 10 Apr 2026 15:59:43 +0900

Feature Flag 운영 가이드: 점진 배포, A/B 테스트, Kill Switch를 안전하게 설계하는 방법

Feature Flag는 배포를 기능 공개와 분리해 주지만, 규칙 없이 늘리면 두 번째 설정 시스템이 된다.

중급 팀에서 중요한 것은 '플래그를 만드는 법'보다 '언제 제거하고, 누가 소유하며, 장애 때 어떻게 끄는가'를 정의하는 것이다.

왜 지금 이 주제가 중요한가

배포와 공개를 분리하면 리스크를 줄일 수 있지만, 오래된 플래그는 코드 복잡도를 폭발시킨다.
점진 배포와 실험은 목적이 다르다. 하나의 플래그에 두 목적을 섞으면 해석이 꼬인다.
kill switch가 없다면 플래그는 비상 장치가 아니라 장식에 가깝다.

핵심 설계 포인트

release flag, experiment flag, ops flag를 타입별로 구분한다.
타깃 규칙은 사용자 속성, 지역, 앱 버전처럼 안정적인 차원을 우선 사용한다.
기본값과 fallback을 코드에 남기고, 원격 설정 실패 시 동작을 명확히 한다.
플래그 만료일과 제거 owner를 생성 시점에 같이 기록한다.

예시 구성

flag: checkout_redesign
type: release
default: false
targeting: internal-users -> 5% cohort -> country=KR 25%
kill-switch: true면 즉시 기존 checkout으로 fallback

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

기능 위험도에 따라 플래그 타입과 소유 팀을 정한다.
0% -> 내부 사용자 -> 5% -> 25% -> 100%처럼 단계별 rollout 계획을 만든다.
각 단계에서 보는 성공 지표와 rollback 기준을 미리 적는다.
릴리스 후 만료된 플래그를 정리하는 정기 리뷰를 캘린더에 넣는다.
실험용 플래그는 분석 이벤트와 함께 설계해 해석 충돌을 막는다.

운영 체크포인트

플래그 목록에 owner, 생성일, 만료일, 대체 코드 위치를 포함한다.
모든 플래그 변경은 감사 로그와 알림 채널에 남긴다.
운영 플래그는 UI 클릭만 믿지 말고 API/CLI로도 비상 전환 가능해야 한다.

운영 지표/알람 추천

flag 평가 실패율과 fallback 사용 비율
점진 배포 단계별 에러율/전환율 변화
kill switch 발동 횟수와 복구 시간
환경별 설정 drift 여부

빠른 점검 명령/쿼리

# 환경별 flag 기본값과 targeting rule diff 확인
# kill switch가 없는 flag 목록이 있는지 점검
# rollout 대상 세그먼트와 실제 트래픽이 일치하는지 확인

구조화 로그 필드 추천

traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

핵심 경로 에러율: 0.1% 이하
핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
중복 실행 또는 데이터 유실: 0건
장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

실험과 장애 대응 플래그를 하나로 만든다: 롤백 기준이 충돌한다.
플래그를 제거하지 않는다: 코드 경로가 두 배가 된다.
원격 설정 실패 시 기본값이 정의되지 않았다: 장애 때 더 큰 장애가 난다.

바로 적용 템플릿

Feature Flag 템플릿:
name / type / owner / createdAt / expiresAt
defaultValue / fallbackBehavior
rolloutPlan(단계별 대상, 지표, rollback 기준)
cleanupTicket(제거 일정)

검증 방법

원격 설정 서버가 응답하지 않을 때 fallback이 의도대로 동작하는지 확인한다.
kill switch를 켠 뒤 1~2분 내 트래픽과 에러율이 안정화되는지 리허설한다.

장애 대응 Runbook(초안)

현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
롤백 또는 비상 스위치가 준비돼 있다.
최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "Feature Flag 운영 가이드: 점진 배포, A/B 테스트, Kill Switch를 안전하게 설계하는 방법"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

참고/출처

Elasticsearch 샤드 설계 실전: shard/replica 개수와 검색 성능을 같이 보는 기준

Just-Do-It — Fri, 10 Apr 2026 14:59:23 +0900

Elasticsearch 샤드 설계 실전: shard/replica 개수와 검색 성능을 같이 보는 기준

Elasticsearch는 샤드를 많이 쪼갠다고 빨라지지 않는다. 작은 샤드가 많아질수록 메타데이터, merge, relocation 비용이 눈에 띄게 커진다.

중급 운영에서는 인덱스 설계를 데이터 크기와 검색 패턴이 아니라, 장애 복구 시간과 운영 인력까지 포함해 봐야 한다.

왜 지금 이 주제가 중요한가

샤드 수는 성능뿐 아니라 장애 복구 시간과 노드 증설 전략에 직접 영향을 준다.
replica는 가용성 도구이면서 검색 처리량 레버이기도 하다.
hot shard를 방치하면 특정 노드만 포화되고 클러스터 전체 성능이 흔들린다.

핵심 설계 포인트

인덱스당 샤드 수는 예상 총 데이터와 일 단위 증가량, 보관 정책으로 산정한다.
샤드 크기는 너무 작지도, 너무 크지도 않게 유지해야 merge와 relocation이 감당 가능하다.
시간 기반 데이터는 rollover와 ILM으로 관리하고, 고정 도메인 데이터는 검색 패턴 중심으로 나눈다.
replica는 읽기 분산과 장애 복구 목표를 기준으로 결정한다.

예시 구성

{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "index.lifecycle.name": "logs-hot-warm"
  }
}

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

현재 인덱스별 데이터 크기와 일일 증가량을 측정한다.
읽기/쓰기 비율과 장애 시 복구 목표 시간을 기준으로 샤드 목표 크기를 정한다.
rollover, index template, ILM 정책을 함께 설계한다.
hot shard 여부를 대시보드로 추적하고 재인덱싱 기준을 문서화한다.
운영 중 샤드 증감은 비용이 크므로 초반에 작은 PoC로 검증한다.

운영 체크포인트

샤드 재배치가 잦은 시간대에는 롤오버와 대규모 배포를 겹치지 않는다.
template 변경 전후로 새 인덱스에만 반영되는지 확인한다.
검색 latency와 인덱싱 throughput을 분리해서 본다. 둘은 자주 충돌한다.

운영 지표/알람 추천

검색 지연(p95/p99)과 timeout 비율
shard size, segment merge, relocation 횟수
refresh/replication 지연과 인덱싱 처리량
hot shard 여부와 노드별 디스크 사용률

빠른 점검 명령/쿼리

curl -s http://localhost:9200/_cat/shards?v
curl -s http://localhost:9200/_cluster/health?pretty
curl -s http://localhost:9200/index/_stats?pretty

구조화 로그 필드 추천

traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

핵심 경로 에러율: 0.1% 이하
핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
중복 실행 또는 데이터 유실: 0건
장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

작게 쪼개면 무조건 빠를 거라 믿는다: 오히려 관리 비용이 급증한다.
replica를 0으로 두고 운영한다: 노드 장애가 곧 서비스 장애가 된다.
hot shard를 애플리케이션 키 설계 탓으로만 본다: 실제로는 인덱스 전략이 원인인 경우가 많다.

바로 적용 템플릿

샤드 설계 체크리스트:
총 데이터 크기 / 일 증가량 / 보관 기간
목표 샤드 크기 / replica 수 / rollover 기준
장애 복구 시간 목표(RTO)와 재인덱싱 허용 여부

검증 방법

샤드 재배치 또는 노드 장애를 가정해 클러스터가 목표 시간 안에 회복되는지 확인한다.
실제 검색 쿼리 상위 10개로 p95 지연이 목표 범위인지 측정한다.

장애 대응 Runbook(초안)

현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
롤백 또는 비상 스위치가 준비돼 있다.
최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "Elasticsearch 샤드 설계 실전: shard/replica 개수와 검색 성능을 같이 보는 기준"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

참고/출처

분산 스케줄링 설계: Cron, Quartz, ShedLock 중 어떤 방식이 운영에 유리한가

Just-Do-It — Thu, 9 Apr 2026 20:59:55 +0900

분산 스케줄링 설계: Cron, Quartz, ShedLock 중 어떤 방식이 운영에 유리한가

스케줄러는 단순해 보이지만, 인스턴스가 두 대만 넘어가도 '누가 실행할 것인가'가 운영 이슈가 된다.

중급 설계에서는 스케줄 실행 정확도보다 중복 실행 방지, 실패 재시도, 관측 가능성을 먼저 다뤄야 한다.

왜 지금 이 주제가 중요한가

단일 인스턴스 cron은 간단하지만 장애 조치가 취약하다.
Quartz는 강력하지만 운영 복잡도와 상태 저장 비용이 따른다.
ShedLock은 간단한 분산 락 기반이지만 정밀한 스케줄 엔진을 대체하진 못한다.

핵심 설계 포인트

단순 반복 작업이면 플랫폼 수준 cron(Kubernetes CronJob 포함)부터 검토한다.
정확한 일정, misfire 처리, 달력 기반 스케줄이 필요하면 Quartz가 유리하다.
기존 애플리케이션 내부 작업을 최소 변경으로 분산 환경에 올리려면 ShedLock이 현실적이다.
어떤 방식을 택하든 실행 이력과 중복 실행 감지를 남겨야 한다.

예시 구성

Cron: 플랫폼이 주기적으로 컨테이너 실행
Quartz: trigger + job store + misfire policy
ShedLock: @Scheduled + distributed lock + max lock duration

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

작업 종류를 단순 반복, 시간 정밀, 장시간 실행, 고가용성으로 분류한다.
중복 실행 허용 여부와 최대 실행 시간, 재시도 정책을 정한다.
락 저장소(DB/Redis) 또는 scheduler 저장소의 가용성을 확인한다.
실행 성공률, misfire, 지연을 모니터링하는 대시보드를 만든다.
수동 재실행 절차와 비상 중지 절차를 문서화한다.

운영 체크포인트

NTP와 timezone이 어긋나면 스케줄러 디버깅이 매우 어려워진다.
장시간 실행 작업은 락 만료와 heartbeat 전략을 같이 설계한다.
실패한 작업을 수동으로 다시 돌릴 수 있는 운영 도구가 필요하다.

운영 지표/알람 추천

실행 성공률과 misfire 횟수
중복 실행 감지 건수와 락 획득 실패율
스케줄 지연 시간과 backlog 증가량
실행 노드별 편중 여부

빠른 점검 명령/쿼리

# 최근 24시간 misfire/중복 실행 로그 확인
# 락 키별 획득 실패 건수와 재시도 간격 점검
# 노드 시계 오차(NTP)와 timezone 설정 확인

구조화 로그 필드 추천

traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "job processed",
  "traceId": "8d3f...",
  "eventId": "evt_123",
  "queue": "outbox-relay",
  "status": "DONE",
  "latencyMs": 184,
  "retryAttempt": 0
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

핵심 경로 에러율: 0.1% 이하
핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
중복 실행 또는 데이터 유실: 0건
장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

분산 환경에서 단순 `@Scheduled`만 쓴다: 인스턴스 수만큼 중복 실행된다.
락 만료 시간을 너무 짧게 잡는다: 작업 중복 실행 가능성이 커진다.
실행 이력을 저장하지 않는다: 실패 재현과 감사가 불가능하다.

바로 적용 템플릿

스케줄링 선택 템플릿:
중복 실행 허용 여부
최대 실행 시간 / 재시도 정책 / 수동 재실행 절차
락 또는 job store 종류
모니터링 지표(misfire, success, duration)

검증 방법

인스턴스를 2대로 늘린 뒤 같은 시각에 작업이 한 번만 실행되는지 검증한다.
작업 도중 프로세스 종료 시 락 만료와 재실행이 의도대로 동작하는지 확인한다.

장애 대응 Runbook(초안)

현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
롤백 또는 비상 스위치가 준비돼 있다.
최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "분산 스케줄링 설계: Cron, Quartz, ShedLock 중 어떤 방식이 운영에 유리한가"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

참고/출처

DB 커넥션 풀 튜닝 실전: HikariCP maximumPoolSize를 감으로 정하면 안 되는 이유

Just-Do-It — Thu, 9 Apr 2026 19:59:31 +0900

DB 커넥션 풀 튜닝 실전: HikariCP maximumPoolSize를 감으로 정하면 안 되는 이유

커넥션 풀은 많을수록 좋지 않다. DB가 동시에 처리할 수 있는 양보다 커넥션이 더 많아지면 대기열만 늘어난다.

중급 운영에서는 애플리케이션 스레드 수와 DB 동시 실행 능력, 쿼리 특성을 함께 보고 풀 크기를 정해야 한다.

왜 지금 이 주제가 중요한가

커넥션 부족은 바로 느껴지지만, 과도한 풀 크기는 조용히 DB를 포화시킨다.
풀 대기 시간은 애플리케이션 병목인지 DB 병목인지 구분하는 핵심 지표다.
thread pool, HTTP timeout, transaction 길이와 연결하지 않으면 숫자만 바꾸는 튜닝이 된다.

핵심 설계 포인트

pool size는 DB CPU 코어 수와 평균 쿼리 시간, 동시성 모델을 기준으로 계산한다.
connection timeout은 사용자 요청 timeout보다 짧아야 한다.
읽기/쓰기 풀 분리나 bulk job 전용 풀을 통해 서로 다른 워크로드를 격리한다.
긴 트랜잭션과 N+1 쿼리를 먼저 줄이지 않으면 풀 확장은 임시 처치에 그친다.

예시 구성

spring:
  datasource:
    hikari:
      maximum-pool-size: 24
      minimum-idle: 8
      connection-timeout: 2000

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

현재 Hikari 지표(active, idle, pending, acquire time)를 수집한다.
DB slow query와 app thread dump를 같이 확인해 병목 위치를 구분한다.
커넥션 풀 크기를 소폭 조정하며 p95 acquire time 변화를 비교한다.
배치 잡과 온라인 요청이 같은 풀을 쓰는지 점검하고 필요하면 분리한다.
최종 값은 문서와 코드 설정에 같이 남긴다.

운영 체크포인트

풀 크기를 올리기 전에 쿼리 최적화와 transaction length를 먼저 본다.
DB max_connections와 애플리케이션 인스턴스 수를 같이 계산한다.
장애 시 pending thread가 폭증하는지 대시보드에 노출한다.

운영 지표/알람 추천

event loop lag 또는 GC pause time
CPU 사용률, 스레드/핸들러 대기 시간
메모리 사용량과 heap pressure
timeout/retry 비율과 다운스트림 오류 상관관계

빠른 점검 명령/쿼리

# event loop lag 또는 GC pause 로그를 먼저 본다
# CPU 100% 구간과 외부 호출 timeout 구간을 같이 본다
# 병목 함수/핫스팟이 요청 경로와 직접 연결되는지 확인

구조화 로그 필드 추천

traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

핵심 경로 에러율: 0.1% 이하
핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
중복 실행 또는 데이터 유실: 0건
장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

응답이 느리니 pool size부터 늘린다: DB 포화를 더 빠르게 만든다.
connection timeout이 너무 길다: 사용자 요청이 불필요하게 오래 매달린다.
batch job과 API 트래픽이 같은 풀을 쓴다: 서로의 tail latency를 망친다.

바로 적용 템플릿

풀 튜닝 템플릿:
DB max_connections / 앱 인스턴스 수 / 목표 pool size
connection timeout < request timeout
active/pending/acquire time 대시보드
긴 쿼리 상위 N개 점검

검증 방법

부하 테스트에서 acquire time p95가 줄었는지, 동시에 DB CPU가 포화되지 않는지 확인한다.
일부 인스턴스 재시작 상황에서도 DB max_connections를 넘지 않는지 검증한다.

장애 대응 Runbook(초안)

현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
롤백 또는 비상 스위치가 준비돼 있다.
최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "DB 커넥션 풀 튜닝 실전: HikariCP maximumPoolSize를 감으로 정하면 안 되는 이유"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

참고/출처

Cache-Control 고급 활용: stale-while-revalidate, stale-if-error로 체감 성능 높이기

Just-Do-It — Thu, 9 Apr 2026 14:59:47 +0900

Cache-Control 고급 활용: stale-while-revalidate, stale-if-error로 체감 성능 높이기

응답을 즉시 보여주면서도 완전히 오래된 데이터만 내보내지 않는 절충안이 필요할 때 `stale-while-revalidate`가 빛난다.

중급 팀에서는 캐시 시간을 늘리는 것이 아니라, '신선도와 가용성을 분리해서 다루는 방식'으로 Cache-Control을 설계해야 한다.

왜 지금 이 주제가 중요한가

캐시를 너무 짧게 두면 원본 서버 부하가 커지고, 너무 길게 두면 신선도 문제가 생긴다.
`stale-if-error`는 장애 시 사용자 체감 품질을 지키는 강력한 수단이다.
브라우저, CDN, 프록시가 각각 캐시 헤더를 다르게 소비하기 때문에 의도를 명확히 해야 한다.

핵심 설계 포인트

`max-age`는 일반 정상 상태의 신선도, `stale-while-revalidate`는 백그라운드 재검증 허용 범위다.
`stale-if-error`는 원본 장애 시 얼마나 오래 이전 응답을 보여줄지 정의한다.
ETag/Last-Modified와 함께 쓰면 네트워크 비용과 정합성 균형이 좋아진다.
로그인 사용자, 개인화 응답은 공용 캐시와 명확히 분리한다.

예시 구성

Cache-Control: public, max-age=60, stale-while-revalidate=300, stale-if-error=600
ETag: "post-list-v42"
Vary: Accept-Encoding

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

정적/준정적/개인화 응답을 먼저 분류한다.
각 응답에 허용 가능한 stale window와 오류 시 fallback 시간을 정한다.
브라우저와 CDN 정책을 별도 테스트 환경에서 검증한다.
배포 후 hit ratio와 origin offload 비율을 관측하며 값을 조정한다.
중요 페이지는 stale 응답이 비즈니스에 미치는 영향을 제품 팀과 합의한다.

운영 체크포인트

개인화 응답에 `public` 캐시를 붙이지 않도록 라우트별 검증을 둔다.
CDN이 `stale-while-revalidate`를 어떻게 해석하는지 문서와 실제 동작을 함께 확인한다.
원본 서버 장애 시 stale 응답 제공 여부를 대시보드에서 확인할 수 있어야 한다.

운영 지표/알람 추천

캐시 hit ratio와 stale 응답 비율
원본 저장소 QPS/지연과 캐시 도입 전후 비교
stampede 방지 키의 lock contention
메모리 사용량과 eviction 비율

빠른 점검 명령/쿼리

redis-cli INFO stats | rg 'keyspace_hits|keyspace_misses'
redis-cli TTL cache:user:123
redis-cli --latency-history

구조화 로그 필드 추천

traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

핵심 경로 에러율: 0.1% 이하
핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
중복 실행 또는 데이터 유실: 0건
장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

max-age만 키우고 끝낸다: 신선도와 장애 대응이 분리되지 않는다.
캐시 가능한 응답과 아닌 응답을 라우트 수준에서 분리하지 않는다.
ETag 재검증 없이 stale 응답만 늘린다: 잘못된 값이 오래 남을 수 있다.

바로 적용 템플릿

Cache-Control 템플릿:
public/private
max-age=초
stale-while-revalidate=초
stale-if-error=초
ETag 또는 Last-Modified 병행

검증 방법

원본 서버를 의도적으로 오류 상태로 만들어 stale-if-error가 실제로 동작하는지 확인한다.
재검증 시 304 비율과 origin 응답시간 감소 효과를 비교한다.

장애 대응 Runbook(초안)

현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
롤백 또는 비상 스위치가 준비돼 있다.
최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "Cache-Control 고급 활용: stale-while-revalidate, stale-if-error로 체감 성능 높이기"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

참고/출처

API 버저닝 전략 실전: URI vs Header vs Media Type, 언제 갈아타야 하는가

Just-Do-It — Thu, 9 Apr 2026 13:59:21 +0900

API 버저닝 전략 실전: URI vs Header vs Media Type, 언제 갈아타야 하는가

API 버저닝은 URL 취향 싸움이 아니라, 호환성 비용을 어떤 계층에서 감당할지 정하는 선택이다.

중급 팀에서는 신규 버전을 만드는 기준, 이전 버전 폐기 절차, 고객사 마이그레이션 가시성까지 포함해 설계해야 한다.

왜 지금 이 주제가 중요한가

버전 전략이 없으면 하위 호환성 부담이 코드 전체로 퍼진다.
버전이 많아질수록 운영/문서/모니터링 비용이 함께 증가한다.
중요한 것은 어디에 버전을 넣느냐보다 언제 breaking change로 판단하느냐이다.

핵심 설계 포인트

URI 버저닝은 명시적이고 디버깅이 쉽지만 경로 중복이 커질 수 있다.
Header 또는 media type 버저닝은 자원 식별을 유지하지만 클라이언트와 게이트웨이 지원을 점검해야 한다.
breaking change 기준과 sunset timeline을 문서/헤더/공지 채널로 함께 관리한다.
버전별 트래픽을 관측할 수 있어야 실제 폐기가 가능하다.

예시 구성

GET /v2/orders/123
Accept: application/vnd.example.orders.v2+json
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Deprecation: true

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

지금까지 발생한 breaking change 사례를 모아 버전 정책 문장으로 정리한다.
신규 버전 노출 방식(URI, header, media type)을 API 게이트웨이 제약과 함께 검토한다.
Deprecation/Sunset 헤더, 문서, 고객 공지 템플릿을 만든다.
버전별 사용량 대시보드를 만들고, 지원 종료 기준을 운영 정책으로 박는다.
핵심 SDK 또는 샘플 코드도 버전 전환 흐름에 맞춰 같이 업데이트한다.

운영 체크포인트

지원 종료 전 고객사별 버전 사용량을 확인할 수 있어야 한다.
새 버전 배포 전 SDK/문서/예제 코드가 함께 준비돼야 한다.
버전별 알람과 에러율을 분리해 회귀를 빠르게 잡는다.

운영 지표/알람 추천

버전별 트래픽 비율과 미지원 버전 접근 수
deprecation/sunset 헤더 적용률
클라이언트 오류율(4xx)과 호환성 이슈 건수
변경 후 고객사별 migration 진행률

빠른 점검 명령/쿼리

curl -I https://example.com/api/resource
curl -H 'Accept: application/vnd.example.v2+json' https://example.com/api/resource
rg 'Sunset|Deprecation|api-version' ./logs -n

구조화 로그 필드 추천

traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

핵심 경로 에러율: 0.1% 이하
핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
중복 실행 또는 데이터 유실: 0건
장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

버전은 URL에만 있고 정책이 없다: 결국 아무 버전도 지우지 못한다.
사소한 변경까지 버전을 올린다: 문서와 운영 비용만 커진다.
Sunset 공지 없이 구버전을 끊는다: 고객 장애가 곧 신뢰 하락으로 이어진다.

바로 적용 템플릿

버전 정책 템플릿:
breaking change 정의
노출 방식(URI/header/media type)
Deprecation / Sunset 공지 절차
버전별 트래픽 모니터링

검증 방법

구버전과 신버전 클라이언트가 같은 배포에서 동시에 동작하는지 통합 테스트한다.
지원 종료 헤더와 문서 링크가 실제 응답에 포함되는지 확인한다.

장애 대응 Runbook(초안)

현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
롤백 또는 비상 스위치가 준비돼 있다.
최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "API 버저닝 전략 실전: URI vs Header vs Media Type, 언제 갈아타야 하는가"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

참고/출처

무중단 스키마 변경(Expand-Contract) 실전: 컬럼 추가/이동/삭제를 안전하게

Just-Do-It — Tue, 7 Apr 2026 20:59:54 +0900

무중단 스키마 변경(Expand-Contract) 실전: 컬럼 추가/이동/삭제를 안전하게

스키마 변경은 코드 배포보다 무섭다. 데이터가 바뀌면 롤백이 어려워서 '안전한 절차'가 필요하다.

Expand-Contract 한 장 요약

Expand: 새 구조 추가(컬럼/테이블/인덱스).
Backfill: 기존 데이터 채우기(청크/멱등).
Dual-write: 일정 기간 구/신 구조 동시 기록.
Switch-read: 읽기를 신 구조로 전환(Feature Flag).
Contract: 구 구조 제거(삭제는 마지막).

예시 SQL(Expand + Backfill)

ALTER TABLE users ADD COLUMN first_name TEXT;
ALTER TABLE users ADD COLUMN last_name TEXT;
UPDATE users
SET first_name = split_part(name, ' ', 1),
    last_name  = split_part(name, ' ', 2)
WHERE first_name IS NULL;

Backfill을 청크로 나누는 이유

대용량 UPDATE는 락과 IO를 길게 잡아 서비스 지연을 만들 수 있다.
청크 처리로 락 시간을 줄이고, 중간 실패 시 재시작을 쉽게 한다.
진행률 지표(처리 row 수/속도)를 남기면 운영이 쉬워진다.

-- 예: id 범위로 청크 처리(개념)
UPDATE users
SET first_name = ..., last_name = ...
WHERE id BETWEEN :from AND :to AND first_name IS NULL;

적용 순서(실무 플로우)

긴 글을 한 번에 다 적용하기보다, 아래 순서대로 '작게' 넣고 관측하면서 키우는 게 실무에서 성공률이 높다.

현재 상태를 수치로 확인한다(지표/로그/샘플 트래픽).
팀 규칙(키/상태/응답 포맷/설정)을 문서로 고정한다.
핵심 경로 1개(가장 중요한 엔드포인트/잡/토픽)부터 적용한다.
부하/동시성/실패를 재현하는 테스트를 만든다(운영과 비슷하게).
관측(대시보드/알람)을 붙인다: 실패가 '조용히' 넘어가지 않게.
점진적으로 확장한다(적용 범위를 넓히기 전에 효과를 확인).
배포/롤백 계획을 문서화한다(누가, 언제, 어떤 조건에서 되돌릴지).
1~2주 운영 데이터를 보고 규칙/기본값을 재조정한다(처음 값은 대개 틀린다).

운영 체크포인트

Contract(삭제) 전에 구 컬럼 참조가 정말 없는지 로그/메트릭으로 확인한다.
Backfill은 멱등하게 만든다(재실행 가능).
대용량 UPDATE는 청크로 나누고 락/IO를 관측한다.

운영 지표/알람 추천

에러율(4xx/5xx)과 실패 원인 top N
지연(p95/p99)과 타임아웃 비율
재시도 횟수/비율(있다면)
핵심 비즈니스 지표(성공률 등)와 상관관계

빠른 점검 명령/쿼리

장애가 났을 때 '어디부터 볼지'가 정해져 있으면 대응 속도가 빨라진다. 아래는 팀에서 그대로 템플릿으로 쓰기 좋은 최소 목록이다.

# 지표: 에러율/지연(p95/p99)/타임아웃/재시도 비율 확인
# 로그: correlation id로 요청 1건을 end-to-end 추적
# 설정: 기본값(타임아웃/리밋/락/인덱스)을 문서에서 재확인

구조화 로그 필드 추천

traceId/requestId/eventId 중 하나는 반드시 포함
endpoint/method/status/latencyMs 같은 기본 필드
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)
민감정보 마스킹(토큰/비밀번호/개인정보)

{
  "level": "INFO",
  "message": "request completed",
  "requestId": "...",
  "method": "POST",
  "path": "/api/orders",
  "status": 201,
  "latencyMs": 123,
  "userId": 1004,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대 응답/상태 전이가 맞는지
2) 실패: 입력 오류/다운스트림 오류가 '예상한 에러 포맷'으로 떨어지는지
3) 동시성/재시도: 같은 요청이 2~3번 들어와도 데이터가 깨지지 않는지(멱등성)

추가(가능하면):
- 지연/타임아웃: 느린 상황에서 서킷/타임아웃이 상한을 지키는지
- 재시도 폭주: retry가 장애를 키우지 않는지

트레이드오프/대안

기본값은 팀/서비스에 따라 달라진다: 숫자는 '정답'이 아니라 '출발점'이다.
가용성 vs 보호(fail-open vs fail-closed) 결정을 미루면 장애 때 더 큰 혼란이 온다.
관측 없이 최적화하면: 좋아졌는지 나빠졌는지 판단이 안 된다.
단순한 구현이 항상 좋은 건 아니다: 운영/디버깅 비용까지 합쳐서 판단해야 한다.

성공 기준(SLO) 예시

에러율: 5xx 0.1% 이하(서비스 특성에 맞게)
지연: p95 300ms 이하(핵심 API 기준)
타임아웃: 전체 요청의 0.01% 이하
중복 실행(멱등): 0건(또는 '부작용 0건')

자주 터지는 실수/트러블슈팅

Expand 없이 바로 삭제한다: 구버전이 즉시 터진다.
Backfill 중 서비스 트래픽과 경합한다: 락 대기로 장애가 커진다.

바로 적용 템플릿

팀 문서/코드 리뷰에서 바로 복붙할 수 있게 최소 규격을 템플릿으로 남겨두는 게 반복 작업을 줄인다.

Expand-Contract 템플릿:
1) Expand -> 2) Backfill -> 3) Dual-write -> 4) Switch-read -> 5) Contract
삭제는 마지막, 최소 1회 배포 주기 뒤

검증 방법

구버전/신버전 동시 운영 중 읽기/쓰기 호환이 깨지지 않는지 검증한다.

장애 대응 Runbook(초안)

현상: 무엇이 깨졌나(에러/지연/중복/누락) 한 문장으로 적기
범위: 언제부터/어느 사용자/어느 엔드포인트/어느 파티션인지
증거: 로그 3줄 + 지표 1개로 재현 가능한 단서 만들기
임시 조치: 제한(레이트리밋), 차단(서킷), 롤백/스위치 등
근본 원인: 키/정렬/락/타임아웃/재시도 등 어떤 규칙이 깨졌는지
재발 방지: 테스트 추가 + 대시보드/알람 + 문서 업데이트
후속 조치: 고객 공지/내부 공유(영향 범위, 원인, 재발 방지) 템플릿으로 남기기

리뷰 체크리스트

성공/실패 기준이 수치로 정의돼 있다(지표, 임계값).
입력 검증/에러 처리가 400/409/429 등으로 명확하다(500 남발 금지).
동시성/재시도 상황에서도 데이터가 깨지지 않는다(멱등성/락/유니크).
타임아웃이 상한으로 존재한다(무한 대기 금지).
부하 증가 시 동작이 예측 가능하다(인덱스/큐/풀 고갈 대비).
로그에 상관관계 키(traceId/requestId/eventId)가 있다.
설정 기본값이 문서로 남아 있다(왜 이 값인지).
롤백/비상 조치(runbook)가 준비돼 있다.
테스트에 최소 1개 이상의 실패 케이스가 있다(운영 재현 목적).
참고/출처(공식 문서)로 팀이 더 깊게 확인할 경로가 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 무엇을 해결하나(한 문장)
2) 범위: 적용 대상(엔드포인트/잡/토픽/테넌트)
3) 규칙: 키/정렬/상태/응답 포맷/기본값
4) 예외: 허용하지 않는 케이스(차단/에러 코드)
5) 운영: 지표/알람/대시보드 링크
6) 장애 대응: 임시 조치 + 롤백 절차
7) 변경 이력: 언제/누가/무엇을 바꿨나

FAQ(자주 묻는 질문)

Q. 이걸 도입하면 성능이 무조건 좋아지나요?
A. 항상 그렇진 않다. 목표는 보통 '장애 반경 축소'와 '예측 가능성'이다. 성능은 인덱스/타임아웃/풀/캐시처럼 병목을 같이 잡아야 체감이 나온다.

Q. "무중단 스키마 변경(Expand-Contract) 실전: 컬럼 추가/이동/삭제를 안전하게"를 적용했는데도 문제가 남아요. 어디부터 봐야 하나요?
A. 먼저 로그/지표로 실패 지점을 좁히고, 설정/키/인덱스 같은 고정 요소부터 점검한다. 재현 가능한 체크리스트를 먼저 만든다.

Q. 운영에서 가장 흔한 실수는요?
A. 규칙을 문서화하지 않고 팀마다 다르게 구현하는 것이다. 같은 이름의 기능이라도 데이터 모델/키/상태 정의가 다르면 장애가 난다.

Q. 최소 도입으로 효과를 보려면?
A. 체크리스트 1~2개만이라도 먼저 적용해 효과가 보이는 변화를 만든 뒤 범위를 넓히는 게 안전하다.

Q. 테스트를 어디까지 해야 하나요?
A. 최소로는 (1) 정상 케이스, (2) 실패 케이스, (3) 동시성/재시도 케이스 3가지는 자동화하는 게 좋다. 운영 이슈의 대부분이 3번에서 나온다.

참고/출처

TypeScript 런타임 검증 실전: Zod로 API 스키마 드리프트 막기

Just-Do-It — Tue, 7 Apr 2026 19:59:16 +0900

TypeScript 런타임 검증 실전: Zod로 API 스키마 드리프트 막기

TypeScript는 컴파일 타임에만 안전하다. 런타임에는 API가 바뀌면 그대로 터진다. Zod로 '명확히 실패'하게 만들어 조기 발견을 돕는다.

스키마 정의

import { z } from 'zod';
export const UserSchema = z.object({
  id: z.number().int().positive(),
  email: z.string().email(),
  name: z.string().min(1),
  createdAt: z.string().datetime(),
});

응답 파싱

const res = await fetch('/api/users/1');
const json = await res.json();
const user = UserSchema.parse(json);

safeParse를 쓰는 이유

parse는 예외를 던진다. 화면에서 우아하게 실패하고 싶거나, 에러 리포트를 풍부하게 남기고 싶으면 safeParse가 운영에 유리하다.

const parsed = UserSchema.safeParse(json);
if (!parsed.success) {
  captureException(parsed.error);
  throw new Error('Invalid API response schema');
}
return parsed.data;

적용 순서(실무 플로우)

긴 글을 한 번에 다 적용하기보다, 아래 순서대로 '작게' 넣고 관측하면서 키우는 게 실무에서 성공률이 높다.

현재 상태를 수치로 확인한다(지표/로그/샘플 트래픽).
팀 규칙(키/상태/응답 포맷/설정)을 문서로 고정한다.
핵심 경로 1개(가장 중요한 엔드포인트/잡/토픽)부터 적용한다.
부하/동시성/실패를 재현하는 테스트를 만든다(운영과 비슷하게).
관측(대시보드/알람)을 붙인다: 실패가 '조용히' 넘어가지 않게.
점진적으로 확장한다(적용 범위를 넓히기 전에 효과를 확인).
배포/롤백 계획을 문서화한다(누가, 언제, 어떤 조건에서 되돌릴지).
1~2주 운영 데이터를 보고 규칙/기본값을 재조정한다(처음 값은 대개 틀린다).

운영 체크포인트

검증 실패를 Sentry 등에 보내 스키마 드리프트를 조기에 발견한다.
스키마는 가장 깨지기 쉬운 경계(외부 API, 핵심 엔드포인트)부터 적용한다.
parse 예외를 앱 전역 에러 처리 규칙으로 묶는다.

운영 지표/알람 추천

에러율(4xx/5xx)과 실패 원인 top N
지연(p95/p99)과 타임아웃 비율
재시도 횟수/비율(있다면)
핵심 비즈니스 지표(성공률 등)와 상관관계

빠른 점검 명령/쿼리

장애가 났을 때 '어디부터 볼지'가 정해져 있으면 대응 속도가 빨라진다. 아래는 팀에서 그대로 템플릿으로 쓰기 좋은 최소 목록이다.

# 지표: 에러율/지연(p95/p99)/타임아웃/재시도 비율 확인
# 로그: correlation id로 요청 1건을 end-to-end 추적
# 설정: 기본값(타임아웃/리밋/락/인덱스)을 문서에서 재확인

구조화 로그 필드 추천

traceId/requestId/eventId 중 하나는 반드시 포함
endpoint/method/status/latencyMs 같은 기본 필드
실패 이유(reasonCode)와 재시도 횟수(retryAttempt)
민감정보 마스킹(토큰/비밀번호/개인정보)

{
  "level": "INFO",
  "message": "request completed",
  "requestId": "...",
  "method": "POST",
  "path": "/api/orders",
  "status": 201,
  "latencyMs": 123,
  "userId": 1004,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대 응답/상태 전이가 맞는지
2) 실패: 입력 오류/다운스트림 오류가 '예상한 에러 포맷'으로 떨어지는지
3) 동시성/재시도: 같은 요청이 2~3번 들어와도 데이터가 깨지지 않는지(멱등성)

추가(가능하면):
- 지연/타임아웃: 느린 상황에서 서킷/타임아웃이 상한을 지키는지
- 재시도 폭주: retry가 장애를 키우지 않는지

트레이드오프/대안

기본값은 팀/서비스에 따라 달라진다: 숫자는 '정답'이 아니라 '출발점'이다.
가용성 vs 보호(fail-open vs fail-closed) 결정을 미루면 장애 때 더 큰 혼란이 온다.
관측 없이 최적화하면: 좋아졌는지 나빠졌는지 판단이 안 된다.
단순한 구현이 항상 좋은 건 아니다: 운영/디버깅 비용까지 합쳐서 판단해야 한다.

성공 기준(SLO) 예시

에러율: 5xx 0.1% 이하(서비스 특성에 맞게)
지연: p95 300ms 이하(핵심 API 기준)
타임아웃: 전체 요청의 0.01% 이하
중복 실행(멱등): 0건(또는 '부작용 0건')

자주 터지는 실수/트러블슈팅

as로 타입 단언 후 그대로 사용: 런타임 버그가 조용히 퍼진다.
모든 응답을 과도하게 검증: 성능/복잡도 증가(핵심부터).

바로 적용 템플릿

팀 문서/코드 리뷰에서 바로 복붙할 수 있게 최소 규격을 템플릿으로 남겨두는 게 반복 작업을 줄인다.

도입 순서:
1) 외부 API 응답 스키마부터 Zod 적용
2) safeParse + 에러 로깅
3) 테스트에서 mismatch 재현
4) 점진 확대

검증 방법

필드를 일부러 삭제한 모킹 응답으로도 앱이 '명확히 실패'하는지 확인한다.

장애 대응 Runbook(초안)

현상: 무엇이 깨졌나(에러/지연/중복/누락) 한 문장으로 적기
범위: 언제부터/어느 사용자/어느 엔드포인트/어느 파티션인지
증거: 로그 3줄 + 지표 1개로 재현 가능한 단서 만들기
임시 조치: 제한(레이트리밋), 차단(서킷), 롤백/스위치 등
근본 원인: 키/정렬/락/타임아웃/재시도 등 어떤 규칙이 깨졌는지
재발 방지: 테스트 추가 + 대시보드/알람 + 문서 업데이트
후속 조치: 고객 공지/내부 공유(영향 범위, 원인, 재발 방지) 템플릿으로 남기기

리뷰 체크리스트

성공/실패 기준이 수치로 정의돼 있다(지표, 임계값).
입력 검증/에러 처리가 400/409/429 등으로 명확하다(500 남발 금지).
동시성/재시도 상황에서도 데이터가 깨지지 않는다(멱등성/락/유니크).
타임아웃이 상한으로 존재한다(무한 대기 금지).
부하 증가 시 동작이 예측 가능하다(인덱스/큐/풀 고갈 대비).
로그에 상관관계 키(traceId/requestId/eventId)가 있다.
설정 기본값이 문서로 남아 있다(왜 이 값인지).
롤백/비상 조치(runbook)가 준비돼 있다.
테스트에 최소 1개 이상의 실패 케이스가 있다(운영 재현 목적).
참고/출처(공식 문서)로 팀이 더 깊게 확인할 경로가 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 무엇을 해결하나(한 문장)
2) 범위: 적용 대상(엔드포인트/잡/토픽/테넌트)
3) 규칙: 키/정렬/상태/응답 포맷/기본값
4) 예외: 허용하지 않는 케이스(차단/에러 코드)
5) 운영: 지표/알람/대시보드 링크
6) 장애 대응: 임시 조치 + 롤백 절차
7) 변경 이력: 언제/누가/무엇을 바꿨나

FAQ(자주 묻는 질문)

Q. "TypeScript 런타임 검증 실전: Zod로 API 스키마 드리프트 막기"를 적용했는데도 문제가 남아요. 어디부터 봐야 하나요?
A. 먼저 로그/지표로 실패 지점을 좁히고, 설정/키/인덱스 같은 고정 요소부터 점검한다. 재현 가능한 체크리스트를 먼저 만든다.

Q. 최소 도입으로 효과를 보려면?
A. 체크리스트 1~2개만이라도 먼저 적용해 효과가 보이는 변화를 만든 뒤 범위를 넓히는 게 안전하다.