개발.. 한놈만 팬다

[LOOp:pak vol.4] 스투시 반팔티를 10명이 동시에 주문하면 생기는 일

h7ung — Sun, 7 Jun 2026 15:58:45 +0900

`@Transactional`로 묶었다고 동시성이 해결되는 건 아니다. 그건 원자성(A) 얘기지 격리성(I) 얘기가 아니다. 재고 5개짜리 상품에 10명이 동시에 주문을 넣는 상황을 따라가며 비관적 락, 낙관적 락, 그리고 "사실 읽을 필요도 없는" 원자적 UPDATE까지 저울질한 기록.

시작은 단순한 착각이었다

주문 로직을 짜면서 처음엔 이렇게 생각했다.

"재고 차감이랑 주문 생성을 @Transacional 로 묶었으니, 동시에 주문이 들어와도 알아서 잘 처리하겠지

트랜잭션이 ACID 를 보장하니깐 동시성도 트랜잭션이 잘 막아줄 것이라고 막연히 믿었다.

혼자 주문할 땐 이 믿음이 안깨진다.

읽고 -> 확인하고 -> 줄이고 -> 커밋 읽기와 쓰기가 딱 붙어 있어서 문제가 생길 틈이 안보인다. 검증할 상황 자체가 안오니깐.

그런데 "10명이 동시에"를 그려보려고 손님을 한명 더 붙여봤다.

손님 A 가 재고를 읽고 아직 줄이기 전인 그 찰나에, 손님 B 도 같은 재고를 읽는다. 둘 다 "재고 있음"을 확인하고 통과한다.

그 순간 알았다. @Transactional 이 지켜주는 건 내 트랜잭션 안이지, 남이 끼어드는 것이 아니었다. 혼자일 땐 붙어 있는 것처럼 보이던 읽기와 쓰기 사이의 틈이, 두 명을 겹쳐 놓으니 그제야 드러났다.

이 글은 그 착각이 깨지고, 대안을 하나씩 저울질해간 과정을 따라간 기록이다.

트랜잭션이 보장하는 것과 보장하지 않는 것

먼저 주문 하나를 쪼개봤다. 한 줄처럼 보이는 주문도 사실 여러 작업이다.

BEGIN;
SELECT stock FROM product WHERE id = 1;      -- (1) 재고 읽기
-- 애플리케이션에서 if (stock > 0) 체크         -- (2) 확인
UPDATE product SET stock = stock - 1 ...;     -- (3) 차감
INSERT INTO orders ...;                        -- (4) 주문 생성
COMMIT;

트랜잭션은 이 1~4번을 하나로 묶어, 중간에 실패하면 통째로 되돌린다.

3번까지 했는데 4번에서 서버가 죽어도, 재고만 깍이고 주문은 없는 유령 상태가 안생긴다.

여기 까지는 트랜잭션이 확실하게 해준다.

ACID 를 다시 보면 이렇다.

- A (원자성): 다 되거나 다 안되거나

- C (일관성): 트랜잭션 전후로 DB 규칙이 안깨짐

- I (격리성): 동시에 도는 트랜잭션들이 서로 간섭하지 않은 것처럼 보이게 함

- D (지속성): 커밋된 건 서버가 죽어도 살아남음

내가 기대한 "동시 주문이 알아서 처리되는 것"은 원자성이 아니라 격리성의 영역이였다.

격리성은 트랜잭션을 그냥 묶는다고 강하게 보장되는 게 아니다. 이게 첫번째 깨달음이었다.

실제로 뭐가 터지는지 그려봤다

재고 5개, 동시 주문 10명.

각자 위의 1~4번을 자기 트랜잭션으로 돌리다고 하고, 두명만 떼어내 타임라인을 그려봤다.

문제는 t2와 t4이다. A와 B 둘다 "남이 차감하기 전의 재고 5"를 읽었다.

둘다 5-1=4 를 계산했고, B 의 UPDATE 가 A 의 결과를 덮어썼다.

A 가 깎은 1개가 증발한 것이다.

10명으로 늘리면, 운 나쁘면 10명 전무 stock = 5 를 읽고 전부 통과해서 재고 5개짜리를 10명에게 팔아버린다.

Lost Update (갱신 손실) — "읽고 → 계산하고 → 쓰는(read-modify-write)" 패턴에서, 읽은 값이 쓰는 시점엔 이미 낡아버려 한쪽의
갱신이 통째로 사라지는 현상.

여기서 처음 착각이 완전히 깨졌다. 위 두 트랜잭션은 각각 멀쩡히 @Transactional로 묶여 있었다. 원자성도 지속성도 완벽했다. 그런데도 깨진 건 격리성이 약해서 서로의 중간 작업을 못 막았기 때문이다. 트랜잭션은 죄가 없다. 동시성은 별개의 문제다.

격리 수준을 올리면 되지 않을까 (두 번째 착각)

"격리 수준이라는 게 있다던데, 그걸 높이면 막히는 거 아니야?"

격리 수준은 트랜잭션들이 서로 얼마나 격리되는지 정한 표이다.

격리수준	막아주는 것	샐 수 있는 이상현상
READ UNCOMMITTED	(거의 없음)	Dirty Read까지 다 샘
READ COMMITTED	Dirty Read	Non-repeatable Read, Phantom
REPEATABLE READ	+ Non-repeatable Read	Phantom (표준상)
SERIALIZABLE	전부	전부

표만 보면 "격리 수준을 더 높은 단계(REPEATABLE READ나 SERIALIZABLE)로 올리면 lost update도 막히겠네"가 합리적인 추론이다. 그런데 막상 들여다보니 아니었다. 그 이유를 매장 상황으로 바꿔보면 분명해진다.

스투시 매장에 재고 현황판이 하나 걸려 있고, 직원 A와 B가 각자 손님을 받는다고 하자.

주문을 처리하는 직원이 하는 일은 두 가지다. 현황판을 본다(재고 확인), 그리고 새 숫자를 적는다(재고 차감).

거의 동시에 손님을 받으면 이렇게 흘러간다.

여기서 핵심은, A도 B도 잘못 본 게 아니라는 점이다. 둘 다 봤을 때 진짜로 5였다. 읽기는 완벽하게 정확했다.

문제는 적기(쓰기)가 서로 덮어쓴 데 있다. B가 적을 때 A가 이미 적어둔 4를 그냥 지워버린 것이다.

그런데 격리 수준이라는 다이얼이 조절하는 건 오직 "본다(읽기)"뿐이다.

표에 있는 이상현상 세 개의 이름을 보면 전부 Dirty Read, Non-repeatable Read, Phantom Read — 죄다 "읽기"다.

즉 격리 수준은 "현황판을 볼 때 뭐가 보이게 할 거냐"를 정하는 규칙이지, "적기끼리 부딪히는 것"과는 다른 영역이다. 문제는 쓰기에 있는데 다이얼은 읽기만 만지니, 아무리 돌려도 안 풀린다.

그럼 "REPEATABLE READ면 내가 본 값을 지켜준다던데?"라는 의문이 남는다.

실제로 MySQL InnoDB의 기본값이 REPEATABLE READ인데도 위 상황은 그대로 일어난다.

함정은 이 "지켜준다"의 뜻에 있다.

REPEATABLE READ가 약속하는 건 "A 눈에 보이는 화면을 끝까지 5로 유지해준다"이지, "현황판의 진짜 내용을 지켜준다"가 아니다.

B가 현황판을 진짜로 4로 바꿔놔도, A 눈에는 친절하게 계속 5를 보여준다. A를 "5라고 적힌 옛날 화면"에 가둬두는 셈이다.

그래서 오히려 A는 "내 화면은 5니까 5겠지" 하고 4를 적어버린다. 읽기 일관성을 지켜주는 것과 쓰기 충돌을 막아주는 것은 전혀 다른 얘기다.

SERIALIZABLE까지 올리면 막히긴 한다.

이 수준에선 직원이 현황판을 보는 순간부터 아예 판을 잡아버려서, 다른 직원이 동시에 보지 못하게 하기 때문이다.

하지만 이건 매장의 모든 조회를 다 줄 세우는 것과 같다. 동시성이 바닥으로 떨어지고 데드락도 잦아진다. 주문 한 줄 막자고 시스템 전체를 직렬화하는 건 과하다.

그래서 두 번째 결론에 도달했다.

격리 수준을 올리는 건 lost update의 정답이 아니다. 격리 수준은 "읽기의 일관성"을 다루는 다이얼이고, 내 문제는 "특정 쓰기가 덮어써지는 것"이다. 연장이 애초에 안 맞았다. 내가 풀어야 할 건 "이 한 행을 갱신하는 동안 끼어들지 못하게 하는 것"이고, 그건 그 행을 콕 집어 제어하는 락 전략의 영역이다.

락 전략 1 — 비관적 락: 일단 잠그고 본다

비관적 락의 전제는 이렇다. "충돌은 자주 난다고 비관적으로 가정한다. 그러니 건드리기 전에 미리 잠가 남이 못 들어오게 한다."
읽을 때부터 락을 거는 방식이다. 평범한 SELECT가 아니라 SELECT ... FOR UPDATE를 쓴다.

BEGIN;
SELECT stock FROM product WHERE id = 1 FOR UPDATE;  -- 이 행에 배타 락
-- if (stock > 0)
UPDATE product SET stock = stock - 1 WHERE id = 1;
INSERT INTO orders ...;
COMMIT;   -- 여기서 락 해제

FOR UPDATE가 붙으면 그 행에 배타 락이 걸리고, 락이 걸린 동안 다른 트랜잭션이 같은 행을 FOR UPDATE로 읽으려 하면 앞 트랜잭션이 COMMIT할 때까지 멈춰서 기다린다. 타임라인이 이렇게 바뀐다.

핵심은 t4다. B는 A가 끝날 때까지 아예 못 읽는다.

그래서 B가 읽는 시점엔 이미 A가 깎은 최신값(4)을 보고, lost update가 원천 차단된다. 줄을 세운 것이다.

다만 대가가 있다. 한 행에 주문이 몰리면 모두 한 줄로 서서 처리량이 떨어진다.

여러 행을 서로 다른 순서로 잠그면 데드락이 생길 수 있어 "락은 항상 같은 순서로 잡는다"는 규칙이 따라온다.

그리고 락 보유 시간은 곧 트랜잭션 길이라서, FOR UPDATE를 잡은 채 느린 작업(외부 API 호출 등)을 하면 줄 선 사람 전부가 그만큼 기다린다. 트랜잭션은 짧게 가져가야 한다.

락 전략 2 — 낙관적 락: 일단 진행하고, 충돌나면 그때 처리

낙관적 락의 전제는 정반대다.

"충돌은 드물다고 낙관적으로 가정한다. 미리 잠그지 말고 진행하되, 마지막에 '내가 읽은 뒤 누가 건드렸나'만 확인한다."

여기서 짚고 넘어갈 게 있다. 낙관적 락은 사실 DB의 락이 아니다.

진짜 락을 거는 게 아니라 version 컬럼으로 충돌을 감지하는 애플리케이션 레벨 기법이다.

이름에 '락'이 붙어 헷갈리기 쉬운 부분이다.

BEGIN;
SELECT stock, version FROM product WHERE id = 1;   -- 락 없이 읽음. stock=5, version=1
-- if (stock > 0)
UPDATE product
SET stock = stock - 1, version = version + 1
WHERE id = 1 AND version = 1;     -- 내가 읽었던 version 조건
COMMIT;

핵심은 WHERE ... AND version = 1과, 이 UPDATE가 실제로 몇 행을 바꿨는지(affected rows) 확인하는 데 있다.

1이면 그 사이 아무도 안 건드린 것이다. => 성공.
0이면 누군가 먼저 version을 올린 것이다. 내가 읽은 값은 이미 낡았다. => 충돌, 실패.

비관적 락과 결정적으로 다른 점은 B를 막지 않았다는 것이다.

B는 자유롭게 진행했고, 마지막 UPDATE 순간에 "내가 읽은 게 낡았다"를 스스로 발견했다.

그래서 B는 이제 다시 읽고 다시 시도하거나, 사용자에게 "다시 시도해달라"고 알려야 한다.

이 충돌 후 재시도 로직이 낙관적 락의 핵심이자 부담이다.

// 충돌 시 최대 3번까지 재시도
async function placeOrder(productId: number) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const { stock, version } = await readProduct(productId);
    if (stock <= 0) throw new Error("품절");

    const affected = await db.query(
      `UPDATE product SET stock = stock - 1, version = version + 1
       WHERE id = ? AND version = ?`,
      [productId, version]
    );

    if (affected.rowCount === 1) return; // 성공
    await sleep(randomBackoff());        // 충돌 → 잠깐 쉬고 재시도
  }
  throw new Error("주문 실패, 잠시 후 다시 시도해주세요");
}

락을 안 잡으니 대기가 없고, 충돌이 드문 상황에선 비관적 락보다 처리량이 높다. 데드락 걱정도 없다.

하지만 충돌이 잦으면 이야기가 달라진다.

다들 같은 version을 읽고 한 명만 성공, 나머지는 전부 실패 후 재시도, 재시도해도 또 충돌... 이런 재시도 폭풍이 일면 오히려 비관적 락보다 느려질 수 있다.

둘 중 뭘 고를까

	비관적 락	낙관적 락
가정	충돌이 자주 난다	충돌이 드물다
방식	미리 잠굼 (for update)	나중에 감지 (version)
충돌시	애초에 막아서 대기	실패 후 재시도
진짜 DB 락인가	o (배타 락)	x (앱 레벨 기법)
유리한 상황	총돌 잦음 / 짧은 트랜잭션 / 꼭 성공해야 함	충돌 드묾 / 읽기 위주 / 대기 비용큼
주의점	대기, 데드락, 처리량 저하	재시도 폭풍, 재시도 로직 부담

판단 기준을 두 개로 좁히면 이렇다.

- 이 상품에 동시 주문이 진짜 몰리는가? 몰리면 비관적 락(낙관적으로 가면 재시도 지옥). 아니면 낙관적 락.
- 충돌했을 때 "다시 시도하세요"가 자연스러운가? 게시글 동시 수정 같은 건 자연스럽다(낙관적에 적합). 결제나 재고처럼 조용히 정확하게 처리돼야 하는 건 대기를 감수하더라도 비관적이 안전한 경우가 많다.

그런데 한정판이라면

여기서 한 가지 의문이 들었다. "스투시 한정판처럼 수천 명이 5개 재고에 몰리면, 비관적 락은 이들을 한 줄로 세워버리는데 — 뒤쪽 사람은 끝없이 기다리는 거 아닌가?"
맞다. 그리고 사용자 경험 관점에서 최악은 "실패"가 아니라 "언제 끝날지 모르는 대기"다.

이런 폭발적 트래픽에서는 DB 락에 도달하기 전에 경쟁 자체를 줄이는 접근(인메모리 저장소에서 재고를 먼저 차감해 걸러내거나, 요청을 큐에 넣어 순서대로 처리하는 식)을 쓴다.

핵심은 "될 사람은 빨리 되게, 안 될 사람은 빨리 알게"다. 다만 이는 트랜잭션·락의 범위를 넘는 주제라 여기서는 방향만 짚고 넘어간다.

마지막 의문 — 재고 차감은 꼭 읽어야 할까

비관적/낙관적을 비교하다 보니 더 근본적인 의문이 들었다.

"그런데 재고 차감은 애초에 읽을 필요가 있나?"

Lost update의 원인은 "읽고 → 계산하고 → 쓰는" 패턴이라고 했다.

읽기와 쓰기 사이에 틈이 생기고, 그 틈에 남이 끼어드는 게 문제였다.

그렇다면 그 틈 자체를 없애면 된다.

재고 차감은 읽지 않고 DB가 원자적으로 계산하게 시킬 수 있다.

UPDATE product
SET stock = stock - 1
WHERE id = 1 AND stock >= 1;   -- 재고가 1 이상일 때만 차감

UPDATE 한 방으로 끝난다.

WHERE stock >= 1 덕분에 재고가 0이면 0행이 바뀌고(품절), UPDATE는 그 행에 자동으로 락을 잡고 원자적으로 실행되니 lost update가 구조적으로 불가능하다.

읽고-쓰기 사이의 틈이 없으니 끼어들 자리도 없다. affected rows가 0이면 품절로 처리하면 된다.

단순 카운터형 재고에는 이게 가장 깔끔하다.

다만 차감 전에 복잡한 비즈니스 검증이 필요하거나, 재고 외 다른 필드도 함께 조건 검사해야 한다면 락 전략으로 돌아가야 한다.

그래서 마지막 판단은 이 질문으로 귀결된다. 내 상황은 단순 카운터인가, 복잡한 검증이 필요한가.

정리하며

이번 공부에서 가장 크게 바뀐 생각은 "트랜잭션으로 묶으면 동시성이 해결된다"는 믿음이 깨진 것이다.

트랜잭션은 한 작업의 원자성·지속성을 보장하지만, 여러 작업이 동시에 부딪힐 때의 조율(격리성)은 격리 수준과 락이라는 별도의 도구로 풀어야 했다.

그리고 락을 비교하다가 "애초에 읽지 않으면 충돌도 없다"는 데까지 와보니, 결국 정답은 하나로 고정되어 있지 않았다.

충돌 빈도, 트랜잭션 길이, 검증 복잡도, 트래픽 규모에 따라 비관적 락이 맞을 때도, 낙관적 락이 맞을 때도, 락 없이 원자적 UPDATE 한 줄로 끝낼 때도 있다.

이 글을 쓰는 지금도 "내 케이스엔 뭐가 맞나"는 결국 상황을 보고 판단할 문제라고 생각한다.

9.5초 → 0.27초: 측정으로 시작한 API 성능 개선기

h7ung — Fri, 5 Jun 2026 18:59:54 +0900

강의 목록 API 하나를 "추측 대신 측정"으로 파고들어
캐싱 → 구조 개선 → 메모리까지 잡은 기록.
Stack: Node.js · TypeScript · TypeORM(MySQL) · Redis · Vitest

한눈에 보기

지표	Before	After	변화
응답 시간(대형 케이스)	9.5 s	0.27 s	−97%
외부 인기도 API	7,000 ms	20 ms (캐시 히트)	−99.7%
요청당 객체 메모리	3,560 KB	53 KB	−98.5%
조립 객체 수	1,652개	20개	−98.8%

응답 20건을 주는 API가 매번 1,652건을 다 만들고 있었다. → 20건만 만들도록 바꾼 이야기.

개선 여정 (요약)

1. 측정부터 — 구간별 타이밍

const mark = (label) => { marks[label] = now() - last; last = now(); };
// 각 await 뒤에 mark('단계')  →  로그로 한 줄 출력

상위 몇 구간이 대부분을 차지했다. 가장 무거워 보이는 곳부터 더 쪼개 봤다.

2. 삽질 ① — "인덱스 없나?" → ❌

엔티티에 product_id 인덱스 선언이 안 보여 풀스캔을 의심했다. 그런데 마이그레이션엔 이미:

UNIQUE KEY product_course_unique (product_id, course_id)  -- prefix로 product_id 커버

EXPLAIN ANALYZE로 확인:

Index lookup on product_course (product_id=...)  actual time=..4.64  rows=1939

의심	실제
인덱스 없는 풀스캔?	❌ 인덱스 정상, SQL ~12ms
느린 진짜 이유	✅ 1,939행을 객체로 만드는 비용 (전송+ORM 하이드레이션)

느린 게 SQL인지 행→객체 변환인지는 전혀 다른 문제. EXPLAIN 한 줄로 갈린다.

3. 반전 — 진범은 외부 인기도 API

상품에 연결된 전체 강의(1,652건) 의 인기도를 외부 API에서 가져오는데, 이 호출 하나가 응답 건수에 비례해 폭증했다

처리 건수: 1,652

인기도 API      ████████████████████████████████████  7,238 ms    83%
상품강의맵         ███  569 ms
강의 상세 조회      ██  462 ms
카테고리 조회        ▏  150 ms
점수/부착          ▏   90 ms
────────────────────────────────────────────────────
총합            ~8.7 s

응답 건수에 비례(건수 ↑ → 시간 ↑). 다른 모든 구간을 합쳐도 외부 API 하나의 1/8. 나머지 최적화는 일단 곁가지였다.

가장 큰 레버부터. 7초짜리 외부 호출 앞에선 수십 ms 최적화는 의미가 작다.

4. 개선 ① — 외부 호출 Redis 캐싱

외부 API는 못 고치니 결과를 캐싱. 기존 캐시 서비스(같은 데이터 모양)를 재사용.

const cached = await popularityCache.get(key);
const courses = cached ?? (await popularityClient.fetch(...)).data;
if (!cached) popularityCache.set(key, courses).catch(...);   // fire-and-forget

호출	외부 API	전체
1회차 (캐시 미스)	~7,000 ms	~9.5 s
2회차 (캐시 히트)	37 ms	0.58 s

⚠️ 첫 요청은 여전히 느림(캐싱의 숙명) · 무효화·TTL은 기존 로직 재사용.

5. 개선 ② — 페이지네이션 앞당기기 ⭐

캐시 히트 0.58초의 남은 절반은 "1,652건 전부 조립 후 20건만 slice" 구조였다.

핵심 통찰: 정렬에 필요한 값은 id · popularity · 입장시각 셋뿐 → 무거운 조립 없이 정렬 가능.

// Phase A — 전체를 가볍게 (정렬·total)
const tuples = ids.filter(visible).map(id => ({ id, popularity, enteredAt }));
tuples.sort(compare);
const pageIds = tuples.slice(offset, offset + limit).map(t => t.id);

// Phase B — 페이지 20건만 무겁게
const [courses, categories] = await Promise.all([fetchFull(pageIds), fetchCategories(pageIds)]);

구간	Before	After
전체 1,652건 처리	349 ms	58 ms
전체(캐시 히트)	0.58 s	0.27 s

❓ 두 번 조회 = 중복? → 아니다. A는 1,652건×2컬럼(정렬용), B는 20건×풀컬럼(조립용). 페이지는 A 정렬 후에야 정해져 합칠 수 없다. 겹치는 건 20행 재조회뿐.

6. 메모리 — GC 노이즈를 피해 측정

heapUsed 델타는 GC 탓에 −81 ~ +28MB로 요동 → 결정적 지표(조립 배열의 JSON 바이트)로 측정.

const builtKB = JSON.stringify(builtArray).length / 1024;

Before  ████████████████████████████████████████  3,560 KB  (1,652개)
After   ▌                                              53 KB  (   20개)
                                                      ≈ 67× ↓

GC 런타임에서 "요청당 메모리"는 heapUsed 델타보다 데이터 볼륨 프록시가 정직하다.

7. 테스트 우선 (+ 캐시 함정)

리팩터링 전에 "응답 동일성"(정렬·total·페이지) 테스트를 통과시켜 두고 시작.

⚠️ 캐싱 도입 후 기존 테스트가 흔들림 — 캐시 히트로 미소비된 mockResolvedValueOnce가 누수되어 다음 테스트를 오염.

beforeEach(async () => {
  vi.restoreAllMocks();                 // 누수 spy 제거
  vi.spyOn(client, 'fetch').mockResolvedValue({ data: [...] });
  await cache.flush('popularity:cache:*');
});

최종 스코어보드

응답시간   9.5s ████████████████████  →  0.27s ▌        (−97%)
외부API    7.0s ███████████████       →  0.02s ▏        (−99.7%)
메모리     3.5MB ██████████████        →  53KB ▏        (−98.5%)

코드를 더 똑똑하게 짠 게 아니라, 꼭 필요한 만큼만 하도록 바꿨다.
1,652건을 다 만들어 20건만 쓰던 걸 — 20건만 만들도록.

[LOOp:pak vol.4] 이 규칙은 도메인일까, 유스케이스일까 — Service / Facade 의 진짜 분기 기준

h7ung — Fri, 29 May 2026 12:52:40 +0900

멈춘 코드

브랜드 도메인을 만들고 있었다. 요구사항은 단순했다

"어드민이 브랜드를 등록할 때, 동일한 이름의 soft-deleted 행이 있으면 새 INSERT 대신 그 행을 복구(restore)하라."

설계 문서는 이 로직을 BrandAdminFacade.create 에 두라고 했다. 그대로 옮기다가 손이 멈췄다.

// BrandAdminFacade.create()
fun create(name: String): BrandInfo {
    val existing = brandRepository.findByName(name)        // ← 왜 Facade 가 이걸 알지?
    return when {
        existing == null -> save(BrandModel(name))
        existing.deletedAt != null -> existing.restore()   // ← 이게 진짜 "어드민 흐름" 인가?
        else -> throw CONFLICT
    }
}

처음엔 그냥 컨벤션이 어긋난 느낌 정도라고 넘기려 했다. 설계 문서를 따랐으니 일단 진행하면 되겠지, 라고.

그런데 손은 계속 멈춰 있었다. 어색함의 정체가 단순한 스타일 문제가 아닌 것 같았다. 책임 위치 자체가 어긋났다는 직감에 가까웠다. 그래서 한 단계 깊이 들어가 봤다.

Service 에 둘까, Facade 에 둘까. 답을 찾으려면 한 단계 위의 질문을 먼저 풀어야 했다.

이건 도메인 규칙인가, 유스케이스인가?

두 단어의 경계

그런데 실제 케이스에 대보면 한 가지 룰을 두고 둘 다 말이 되어 보일 때가 있다. auto-restore 가 정확히 그런 경우였다.

도메인이라 보면: "Brand 의 이름은 영구 식별자다" 는 Brand 개념의 본질.
유스케이스라 보면: "어드민이 POST 로 등록 요청 시, 충돌하면 restore 한다" 는 어드민의 행동 양식.

둘 다 말이 됐다. 표 옆에 두 옵션을 놓고 한참을 갈팡질팡했다. 표가 답을 줄 거라 기대했는데, 표는 정의일 뿐 판별 기준은 아니었다.

다른 기준들도 거쳐봤다

"진입점 불변성"이라는 기준에 도달하기 전에 몇 가지 다른 잣대를 시도했었다.

"상태가 있는가?" — auto-restore 는 상태 없는 연산이고, Service 도 Facade 도 stateless 라 변별이 안 됐다.
"테스트하기 쉬운가?" — 양쪽 모두 단위/통합으로 테스트 가능. 차이가 거의 없었다.
"재사용성이 높은가?" — 다른 도메인이 부를 일이 적었다. 약한 신호.

그러다 "다른 진입점이 들어와도 같은 정책이어야 하나?" 라는 질문을 던졌더니 답이 또렷해졌다.

진입점 불변성이라는 한 줄 테스트

"이 규칙은 진입점이 바뀌어도 같아야 하나?"

여기서 진입점이란 코드를 부르는 시작점 — REST API, 배치 잡, 시드 스크립트, CLI, 혹은 미래에 생길지 모를 어떤 호출자.

같은 정책을 다른 진입점에서 호출했을 때 일관성이 유지되어야 하는지 묻는 거다.

만약 정책이 진입점마다 달라야 한다면 — 예를 들어 어드민 화면에선 auto-restore, 배치는 무조건 CONFLICT — 이 규칙은 유스케이스의 일부다.

반대로, 진입점이 늘어도 정책이 같아야 한다면 그 규칙은 진입점 위쪽 어딘가에 살아야 한다. 거기가 도메인이다.

이 기준이 실용적인 이유는, 미래에 진입점이 추가될 때 일관성이 자동으로 보장되기 때문이다. 반대 상황을 그려보면 차이가 분명해진다.

유스케이스 레이어에 도메인 규칙을 두면, 진입점이 늘 때마다 룰이 분산된다. 누군가는 복붙하고, 누군가는 빠뜨린다. 시간이 지나면 어느 쪽이 정답인지도 모호해진다.

auto-restore 에 대입하기

Q. "Brand 의 auto-restore 가 진입점 무관해야 하나?"
A. YES — 누가 등록하든 "같은 이름 = 같은 브랜드" 라는 정책은 유지돼야 한다.

// BrandService.register() — 도메인 계층
@Transactional
fun register(name: String): BrandModel {
    val existing = brandRepository.findByNameIncludingDeleted(name)
    return when {
        existing == null -> brandRepository.save(BrandModel(name))
        existing.deletedAt != null -> existing.also { it.restore() }
        else -> throw CoreException(ErrorType.CONFLICT, "이미 사용 중인 이름입니다.")
    }
}

// BrandAdminFacade.create() — 응용 계층
fun create(name: String): BrandInfo =
    BrandInfo.from(brandService.register(name))

이걸 보고 솔직히 한 번 더 의심이 들었다. "Facade 가 한 줄 위임밖에 안 하면, 발제에서 까는 *Impl 안티패턴이랑 본질적으로 같은 거 아닌가?"

그래서 한 번 더 자문했다 — "이 Facade 가 미래에도 비어 있을 게 확실한가?" 답은 아니었다. 어드민 흐름엔 슬랙 알림이나 변경 이력 같은 부수효과가 들어올 자리가 필요하다. 도메인은 진입점 무관, Facade 는 진입점 종속. 지금 비어 있어도 그 자리는 의미가 있다.

비어있는 자리도 책임의 표현이라는 것. 결정 이후에 얻은 작은 깨달음이었다.

결정 이후에도 흔들리는 것들

여기까지가 글의 답이고, 여기서부터는 정직한 자기 점검이다. 결정한 다음에도 머릿속에 남는 의심들이 있다.

1. YAGNI 위반일 수 있다.
"미래에 다른 진입점이 추가될 가능성" 자체가 가설이고, 그 가설을 근거로 추상화 비용을 지금 지불한 거다. 진입점이 영영 REST 하나뿐이라면 이 결정은 과한 결정이 된다. 다만 그 추상화 비용이 한 줄짜리 위임 메서드 한 개라 부담이 작다고 봤다.

2. 반대 결정도 충분히 옳을 수 있다.
"지금은 어드민만 등록한다. 다른 진입점이 생길 때 옮겨도 늦지 않다. 그때까지 Facade 안에 명시적으로 두는 게 가독성이 좋다" 라는 논리도 일리가 있다. 내 결정이 맞다 가 아니라 내 기준에서 정합적이다 가 더 정확한 표현일 거다.

마지막으로...

이 기준이 만능은 아니다. 위에 적은 흔들림들이 그 증거다.

그럼에도 "진입점이 늘어날 때 규칙이 따라가야 하는가" 라는 질문은 "복잡도를 어디서 흡수할 것인가" 라는 더 큰 질문의 작은 버전이라고 생각한다. 도메인 위쪽에 둔 규칙은 진입점이 늘면 자동으로 적용되고, 유스케이스 쪽에 둔 규칙은 진입점이 늘면 복제된다. 시간이 갈수록 이 차이가 코드의 결을 결정한다.

다음에 같은 결정 앞에 서면, 나는 다시 같은 자문을 할 것 같다. 그리고 또 잠깐은 흔들릴 것 같다.

"이 규칙은, 진입점이 바뀌어도 같은가?"

MongoDB 쿼리에서 대시보드로: AI와 함께 만든 시청 데이터 관측 도구

h7ung — Fri, 22 May 2026 17:15:29 +0900

언젠가 만들고 싶다고 생각만 하던 도구가 있었다.

회사에서 반복적으로 마주치는 불편함을 해결할 화면이 있으면 좋겠다고 자주 생각했지만, 막상 시작하려고 하면 데이터, 기준, 화면 구성이 한꺼번에 떠올라 쉽게 손이 가지 않았다.

이번에는 달랐다.

AI가 있어서 시작할 수 있었다.

문제의식과 업무 맥락을 설명하면 AI가 기능을 나누고 구현 순서를 잡는 데 도움을 줬다.

그렇게 머릿속에만 있던 내부 도구를 움직이는 웹앱으로 만들 수 있었다.

그 결과물이 Observatory다.

반복 쿼리에서 업무 대시보드로 바뀐 흐름

아래 앱 화면 캡처는 외부 공개를 위해 실제 수치, 개인 식별 정보, 랭킹/테이블 데이터 영역을 블러 처리했다.

왜 만들었나

우리 회사는 교육 콘텐츠를 다루고 있고, 수강생의 시청 기록은 여러 시스템에 쌓인다.

운영성 데이터는 RDB에, 날짜별·콘텐츠별 세부 기록은 MongoDB에 저장되어 있다.

문제는 내가 자주 확인해야 하는 데이터가 대부분 MongoDB 쪽에 있었다는 점이다.

MongoDB Atlas에서 직접 쿼리하면 볼 수는 있었다.

하지만 특정 기간, 그룹, 강의, 상품, 콘텐츠 기준으로 질문이 바뀔 때마다 쿼리 문법을 다시 찾아야 했다.

내가 원한 것은 쿼리 결과가 아니라, 업무 질문에 바로 답할 수 있는 화면이었다.

이전 방식	Observatory로 바꾼 뒤
MongoDB Atlas에서 직접 쿼리 작성	기간, 그룹, 강의, 상품, 멤버 기준으로 필터 조회
결과 표를 보고 직접 흐름 해석	일별 추이 그래프와 랭킹으로 흐름 확인
다음 질문이 생기면 다시 쿼리 작성	랭킹 항목 클릭으로 바로 필터 적용
커리큘럼과 시청 기록을 수동 비교	미시청 콘텐츠와 남은 시간을 한 화면에서 확인

어떤 화면을 만들었나

Observatory는 대시보드에서 출발했다.

최근 7일, 14일, 30일 기준으로 총 시청시간, 활성 멤버 수, 일별 추이, 멤버그룹 Top 10을 볼 수 있다.

그룹 막대를 클릭하면 해당 그룹 안의 멤버와 강의 Top 5도 이어서 확인할 수 있다.

화면확인할 수 있는 것업무에서 좋은 점

대시보드	총 시청시간, 활성 멤버, 일별 추이, 그룹 Top 10	전체 흐름을 빠르게 파악
Members	멤버별 시청 기록과 많이 시청한 멤버	특정 수강생의 이용량 확인
MemberGroups	그룹별 시청 기록과 랭킹	고객사·조직 단위 흐름 확인
Courses	강의별 랭킹, 멤버별 랭킹	인기 강의와 많이 수강한 사람 확인
Products	상품별 랭킹, 상품 안의 강의 랭킹	패키지나 상품 단위 성과 확인
Contents	콘텐츠별 기록, 미시청 콘텐츠	남은 구간과 세부 콘텐츠 확인

랭킹 기능은 특히 중요했다.

콘텐츠 회사에서 “무엇이 많이 소비되고 있는가”는 자연스럽게 궁금해지는 질문이다.

그래서 멤버, 멤버그룹, 강의, 상품 화면에 총 재생 시간 기준 Top 5, Top 10, Top 20 랭킹을 넣었다.

랭킹은 순위를 보여주는 것으로 끝나지 않는다.

항목을 클릭하면 해당 멤버, 그룹, 강의, 상품으로 필터가 적용된다.

숫자를 보고 궁금해진 지점을 다시 쿼리로 옮겨 적지 않아도 된다.

Courses 랭킹 화면

가장 업무적인 기능: 미시청 콘텐츠

B2B 교육 서비스에서 수강 데이터는 민감하다.

단순히 누가 무엇을 봤는지의 문제가 아니라, 고객사의 교육 성과나 이수 판단과 연결될 수 있기 때문이다.

특히 “어느 구간을 보지 않았는가”는 자주 확인해야 하는 정보다.

예전에는 특정 멤버, 강의, 상품 기준의 시청 기록을 조회한 뒤 커리큘럼 전체 목록과 비교해야 했다.

필요한 값을 잘못 넣으면 결과가 달라지고, 데이터 구조를 다시 확인해야 할 때도 있었다.

Contents 시청기록 화면

그래서 콘텐츠 화면에 미시청 컨텐츠 영역을 만들었다.

멤버 ID, 강의 ID, 상품 ID를 입력하면 백오피스의 강의 커리큘럼과 MongoDB의 시청 기록을 비교해, 아직 보지 않은 콘텐츠와 남은 시간을 보여준다.

이 기능은 단순 편의 기능이라기보다 반복 확인을 줄이고 실수를 줄이기 위한 장치에 가깝다.

민감한 데이터를 다룰수록 “빠르게 본다”만큼 “정확하게 본다”가 중요하기 때문이다.

구현하면서 정리한 것

Next.js 기반 내부 어드민	로그인, 페이지 라우팅, 화면 구성
MongoDB aggregation	시청시간 합계, 일별 추이, 랭킹 계산
백오피스 API 연결	ID만 있는 데이터에 그룹명, 강의명, 상품명, 멤버 정보 보강
환경 선택	DEV / QA / STAGING에 따라 API와 DB 전환
CSV 다운로드	필터링한 결과를 추가 분석으로 연결

기술적으로 아주 새로운 것을 만든 것은 아닐 수 있다.

하지만 나에게는 의미가 컸다.

이 프로젝트는 거창한 서비스라기보다, 내가 매일 느끼던 병목을 줄이기 위해 만든 작은 제품에 가깝다.

무엇보다 AI 덕분에 “이런 게 있으면 좋겠다”에서 멈추지 않을 수 있었다.

AI가 모든 것을 대신 만들어줬다기보다는, 내가 이미 알고 있던 불편함을 실제 도구로 바꾸는 속도를 만들어줬다.

Observatory를 만들면서 느낀 것은 업무 개선이 꼭 거창할 필요는 없다는 점이다.

반복해서 검색하는 쿼리 하나, 매번 비교해야 하는 표 하나, 확인할 때마다 조심스러운 데이터 하나가 좋은 출발점이 될 수 있다.

이번 프로젝트는 그걸 확인한 경험이었다.

내가 필요해서 만들었고, 그래서 더 현실적인 도구가 됐다.

다음에도 비슷한 불편함을 만나면 예전보다 조금 더 빨리 생각할 것 같다.

“이거, 화면으로 만들 수 있지 않을까?”

[LOOp:pak vol.4] 좋아요, 그 단순해 보이는 기능에서 결정해야 했던 것들

h7ung — Fri, 22 May 2026 13:49:38 +0900

좋아요 등록·취소는 단순한 INSERT/DELETE 같지만, 멱등성을 제대로 보장하려면 다섯 개의 결정을 거친다. DB unique 제약과 hard delete 같은 결정들이 한 트랜잭션 안에서 도메인 정합성을 어떻게 만드는지 정리한다.

1. POST /products/{id}/likes 한 줄에서 시작

좋아요는 처음 봤을 때 단순한 기능이었다. 명세상 엔드포인트는 세 개뿐이다.

(user_id, product_id) 한 행을 INSERT 하거나 DELETE 하는 일이다.

그런데도 설계 문서를 쓰는 동안 결정해야 했던 것이 다섯이었다.

멱등성, 좋아요 수의 위치, soft delete 와 unique 의 충돌, BaseEntity 상속 여부, 그리고 그 모두를 묶는 hard delete 결단.

이 글은 그 다섯을 거치며 본 트레이드오프를 정리한다. 정답을 안다고 말하기보다는, 그 시점에 어떤 옵션이 있었고 왜 그것을 골랐는지에 가깝다.

2. 멱등성 — 같은 요청을 N 번 보내도 결과가 같으려면

좋아요는 사용자 입장에서 "한 번 누르면 끝" 인 행위지만, 네트워크 위에서는 그 한 번이 두세 번 도착할 수 있다. 같은 POST 가 두 번 와도 좋아요는 1개여야 하고, 같은 DELETE 가 두 번 와도 결과는 "없음" 으로 같아야 한다.

처음에는 단순하게 봤다. 애플리케이션 단에서 exists 한 번 체크하면 끝날 거라고. 문제는 동시 요청이다. 두 트랜잭션이 동시에 exists 를 false 로 받고 둘 다 INSERT 를 시도하면 같은 (user_id, product_id) 행이 두 개 들어가는 race condition 이 생긴다.

이걸 막는 가장 단순한 방어선은 DB 의 UNIQUE 제약이다.

CREATE UNIQUE INDEX uk_likes_user_product ON likes (user_id, product_id);

이 제약이 있으면 두 번째 INSERT 는 무결성 예외로 떨어지고, 애플리케이션은 그 예외를 잡아 "이미 좋아요가 있다" 로 해석하면 그만이다. 두 단계 방어선이 만들어진다.

1차 — 애플리케이션 exists 사전 체크: 흔한 재요청을 SELECT 한 번으로 흡수
2차 — DB unique 제약: 1차에서 못 잡은 race condition 을 막는다

흔한 경우는 빠르게, 드문 경우는 안전하게. 흐름으로 그리면 이렇다.

DELETE 쪽은 더 단순하다. 영향 행 수가 0 이면 "원래 없었음" 으로 흡수한다.

3. 좋아요 수, 어디에 두어야 하나

좋아요 수는 두 곳에서 쓰인다 — 상품 상세 페이지의 표시와 상품 목록의 정렬 옵션 (sort=likes_desc). 정렬은 데이터 모델의 선택을 강하게 좁힌다.

처음에는 ③ (매번 COUNT) 이 가장 깔끔하다고 봤다. 정규화의 교과서적 형태다.

그런데 sort=likes_desc 가 결정을 좁혔다. 모든 상품의 좋아요 수를 알아야 하는데, COUNT 를 매 상품마다 돌리면 인덱스 활용이 거의 불가능하고 좋아요가 늘어날수록 ORDER BY 가 풀스캔에 가까워진다. ② 도 비슷한 사정이지만, 우리가 보관하는 통계가 like_count 하나뿐인데 테이블을 하나 더 두는 건 과해 보였다.

남은 건 ① — Product.like_count 컬럼. 정렬 인덱스가 본문에 그대로 걸리고, 상품 목록 조회가 단일 쿼리로 끝난다.

CREATE INDEX ix_products_like_count ON products (like_count);

대신 트레이드오프가 분명하다. 인기 상품의 like_count 가 hot row 가 되고, likes 와의 정합성 책임이 애플리케이션으로 옮겨온다. hot row 는 UPDATE products SET like_count = like_count + 1 같은 원자적 증감으로 안전해지고, 정합성은 같은 @Transactional 안에 묶는 것으로 보장된다.

4. 취소된 좋아요가 다시 좋아요가 되는 순간 — soft delete × unique 충돌

여기까지는 자연스러웠다. 그런데 다른 도메인의 정책이 한 가지 걸렸다. 이 프로젝트의 BaseEntity 는 deleted_at 컬럼으로 soft delete 를 한다 — Brand, Product, Order 모두 이 정책을 따른다.

좋아요도 같은 방식으로 가면 이런 상황이 만들어진다.

[지난 주]  user=1, product=10, deleted_at=2026-05-15 09:00   ← 취소된 행
[오늘]     user=1, product=10                                  ← 같은 사용자가 다시 좋아요

새 INSERT 가 (user_id, product_id) unique 제약과 충돌한다. 좋아요는 잠깐 누르고 떼는 행위라 이 시나리오가 드물지 않다.

A 와 B 는 DB 차원의 영리한 트릭이지만 각자 비용이 있었다. C 는 표준적이지만 짧은 액션에 무거웠다. 남은 건 D — Like 만 hard delete 로 가는 결단이었다.

좋아요는 다른 도메인과 달리 취소가 자주 일어나고, 이력 보존의 가치가 크지 않다. 누군가 좋아요 했다가 취소했다는 사실을 시스템이 굳이 기억할 이유가 없다.

5. Like 만 hard delete — 그리고 BaseEntity 한 줄을 안 썼다

BaseEntity 는 id, createdAt, updatedAt, deletedAt 컬럼을 자동 관리한다. 상속하는 순간 그 엔티티는 자동으로 soft delete 의 인프라를 갖는다. 그런데 Like 는 hard delete 다. deleted_at 도, updated_at 도 필요 없다. 두 옵션이 있었다.

결국 b 를 골랐다. 컬럼은 거짓말을 하지 않아야 한다. deleted_at 이 있다는 건 "이 엔티티는 soft delete 됩니다" 라는 약속이다. 그 약속을 지키지 않는 컬럼을 남겨두는 게 더 큰 비용이라고 봤다.

Brand 와 Like — 같은 시스템에서 다른 정책

흥미로운 건, Brand 는 정반대 길을 골랐다는 점이다. 브랜드도 이름 unique 제약 때문에 같은 충돌을 겪는데, Brand 는 자동 restore (4 의 옵션 C) 로 풀었다.

처음에는 두 도메인이 같은 정책을 가져가는 게 "일관성" 이라고 봤다. 그런데 일관성에는 두 종류가 있었다 — 표면 일관성 (모두 같은 패턴) 과 본질 일관성 (각자의 특성에 맞는 패턴). 다른 정책을 가져가도 "왜 그렇게 선택했나" 의 사고가 일관되면 그것이 본질 일관성이다.

6. 정리 — 단순한 기능에 숨어 있던 결정들

이번에 배운 것

요구사항 한 줄 — sort=likes_desc — 이 데이터 모델의 큰 결정을 좌우할 수 있다. API 명세는 단순한 출입구 같지만, 그 안쪽 데이터의 형태를 결정한다.
모든 도메인이 같은 패턴을 가져가는 게 자동으로 옳은 건 아니다. 깰 때는 이유를 명시하고 받아들일 비용을 솔직히 적어두는 것이 더 중요하다.

다음 단계에서 확인할 것

설계는 거기까지였고, 실제 구현은 다음 주의 과제다. 그때 검증할 가설이 몇 개 있다.

Product.like_count 의 hot row 경합 — 원자적 UPDATE 로 충분한가, 비관/낙관 락이 필요한가
existsBy + DB unique 의 두 방어선이 동시 요청에서 어떻게 작동하는지
트래픽이 커진 가상의 미래에 like_count 를 비동기 집계로 분리하는 게 정말 필요한지

이 글이 만든 답들이 다음 주에 깨질 수도 있다. 그게 깨졌을 때 또 한 번 정리하는 것이 다음 글의 자리다.

[LOOp:pak vol.4] 회원 도메인을 TDD로 만들며 — 1주차 회고

h7ung — Fri, 15 May 2026 13:51:04 +0900

루프팩 첫 주, 회원 도메인 세 가지를 TDD로 구현했다.
잘한 것보다 어색했던 게 더 많아서, 일단 기록부터 남긴다. TDD를 막 시작한 사람, 도메인 검증을 어디 둘지 고민하는 사람에게 참고가 될지도.
(Red 실패하는 테스트 Green 최소 구현 Refactor 코드 정리 다음 사이클)

이번 주에 한 일

3개의 유스케이스를 TDD 사이클 한 바퀴씩 돌렸다.

회원가입 POST /api/v1/users
내 정보 조회 GET /api/v1/users/me (이름 마지막 글자 * 마스킹)
비밀번호 수정 PATCH /api/v1/users/me/password

각 기능은 test → feat → refactor 세 커밋으로 끊어서, 한 사이클이 어디서 끝나는지 git 그래프만 봐도 보이도록 했다.

가장 곱씹었던 결정 — 검증 책임의 위치

회원가입 한 줄 짜는 데 검증이 다섯 종류가 나왔다.

loginId가 영문/숫자만인가?
이름이 비어있지 않은가?
이메일 형식이 맞는가?
비밀번호가 정책(8~16자, 허용 문자, 생년월일 미포함)을 만족하는가?
이미 가입된 loginId인가?

처음엔 UserService 한 곳에 다 넣었다가, 이 다섯 개는 같은 곳에 있으면 안 될 것 같다는 느낌이 들었다. 그래서 다음과 같이 나눴다.

UserModel.init 형식 검증 loginId · 이름 · 이메일 "도메인 불변식" 이게 깨진 객체는 존재해선 안 됨

UserService 정책 + 컨텍스트 검증 비밀번호 규칙 · 중복 · 인증 "정책은 변한다"

DB/외부 의존이 필요한 검증도 여기에 Controller 입출력 매핑만 검증 책임 X "얇게 유지" DTO ↔ 도메인 변환만 담당

도메인 모델 — 형식 검증

init {
    if (!loginId.matches(LOGIN_ID_REGEX)) throw CoreException(BAD_REQUEST, "...")
    if (name.isBlank()) throw CoreException(BAD_REQUEST, "...")
    if (!email.matches(EMAIL_REGEX)) throw CoreException(BAD_REQUEST, "...")
}

UserModel의 init 블록에 둔 이유는 단순하다. 이 규칙이 깨진 UserModel 인스턴스는 시스템 어디에도 존재해선 안 되기 때문이다. 도메인 객체의 불변식이라면, 그 객체의 생성 시점에 강제하는 게 가장 안전하다.

도메인 서비스 — 정책/컨텍스트 검증

@Transactional
fun signUp(loginId: String, rawPassword: String, ...): UserModel {
    if (userRepository.findByLoginId(loginId) != null) {
        throw CoreException(CONFLICT, "이미 사용 중인 로그인 ID입니다.")
    }
    validatePassword(rawPassword, birthDate)
    val user = UserModel(...)
    return userRepository.save(user)
}

비밀번호 규칙은 언제든 바뀔 수 있는 정책이고, 중복 체크는 Repository가 필요한 컨텍스트 검증이다. 둘 다 도메인 모델 안에 넣을 수 없는 이유가 분명하다.

TYPE 1 형식 검증 위치 · Model.init 깨지면 객체 자체가 성립하지 않음

TYPE 2 정책 검증 위치 · Service 정책은 변하지만 모델은 변하지 않음

TYPE 3 컨텍스트 검증 위치 · Service DB/외부 의존이 필요한 검증

한 번 막혔던 곳 — 검증 순서

처음 작성한 signUp 흐름은 이랬다.

// before
validatePassword(rawPassword, birthDate)        // 1. 비밀번호 정책 검증
if (userRepository.findByLoginId(loginId) != null) { ... }  // 2. 중복 체크
val user = UserModel(...)                       // 3. 객체 생성

테스트를 돌리다 보니, 이미 가입된 사용자가 잘못된 비밀번호로 다시 시도할 때 응답 메시지가 "비밀번호 형식 오류" 로 뜨는 게 어색했다. 사용자 입장에서 진짜 원인은 "이미 가입된 ID" 인데, 그게 가려졌다.

순서를 뒤집고 나니 두 가지가 좋아졌다.

// after — Refactor 커밋 0dd5742
if (userRepository.findByLoginId(loginId) != null) { ... }  // 1. 중복 먼저
validatePassword(rawPassword, birthDate)        // 2. 정책 검증
val user = UserModel(...)                       // 3. 객체 생성

응답이 정직해졌다 — 진짜 원인이 먼저 보임.
불필요한 정규식·BCrypt 비용이 줄었다 — 어차피 실패할 요청이면 가장 싼 검증부터.

fail-fast 라는 단어를 책에서만 봤는데, 직접 순서 바꾸고 테스트 돌렸을 때 "아 이게 그거구나" 싶었다. 5줄 순서가 전부였다.

순서 하나 바꿨을 뿐인데 응답이 정직해지고, 불필요한 BCrypt 비용도 같이 사라졌다.

작은 추상화의 큰 효과 — `PasswordEncoder`

처음엔 이렇게 썼다.

class UserService(
    private val passwordEncoder: BCryptPasswordEncoder,  // 구현체에 직접 의존
)

Refactor 단계에서 인터페이스로 바꿨다.

class UserService(
    private val passwordEncoder: PasswordEncoder,  // 인터페이스에 의존
)

@Configuration
class PasswordConfig {
    @Bean
    fun passwordEncoder(): PasswordEncoder = BCryptPasswordEncoder()
}

한 줄 변화처럼 보이지만 테스트 코드가 달라진다. mockk<PasswordEncoder>() 로 인코딩 결과를 통제할 수 있게 되어, 단위 테스트에서 BCrypt 연산 비용도 사라지고 "이 입력에 이 결과를 반환한다"고 명시적으로 지정할 수 있게 됐다. Refactor 커밋 짜면서 이 변화를 넣을 때 솔직히 처음엔 그냥 인터페이스로 바꾸는 게 뭐가 다른가 싶었는데, 테스트가 훨씬 가벼워지는 걸 보고서야 이해가 됐다.

"추상화는 다형성을 위해서가 아니라, 통제 가능성을 위해서 한다"는 말이 이번에 와닿았다.

KPT

Keep — 페이즈 단위 커밋 분리
PR 리뷰 단위가 명확해지고, "왜 이 코드가 추가되었는지"가 커밋 그래프로 그대로 설명됐다. Refactor 커밋만 따로 보면 "이 주에 뭘 정리했는가"가 한눈에 보여서, 이건 앞으로도 계속 유지하고 싶다.

Problem — Red 단계 한 커밋이 너무 컸다
회원가입 Red 커밋이 +563줄. stub 프로덕션 코드를 한 번에 다 넣다 보니 "테스트 1개 추가"의 단위가 무너졌다. 진짜 TDD스럽게 한다면 더 잘게 쪼개야 했다.

Try — 다음 사이클부턴 "검증 케이스 1~2개 = Red 1커밋"
엔드포인트 단위가 아니라 검증 케이스 단위로 끊어보고 싶다. 그리고 Refactor 단계에서 발견한 인터페이스 추상화는 별도 PR로 분리해도 될지 시도해볼 예정.

마무리

1주차 끝났는데 아직 모르겠는 게 더 많다. 그래도 이번 주 테스트 하나하나 돌리면서 건진 게 있다.

검증 코드 한 줄을 어디 둘지 정하는 건, 결국 "이 테스트가 무엇을 검증해야 하는가"를 먼저 정하는 일이었다. 테스트가 흔들리면 설계가 흔들리고, 설계가 잡히면 테스트도 같이 잡혔다.

[항해 복귀 스터디] 2주차 설계 + 아키텍처 패턴

h7ung — Mon, 2 Feb 2026 22:23:14 +0900

Mock API를 우선 제공해야 하는 필요성에 대한 이해

Mock API는 데이터베이스 연결이나 백엔드 처리 없이 정적 응답만 제공합니다. 테스트 및 개발용: 실제 API가 준비되지 않았거나 불완전하거나 불안정한 경우 사용

https://velog.io/@khy226/msw로-모의-서버-만들기

MSW(Mock Service Worker)로 더욱 생산적인 FE 개발하기

MSW(Mock Service Worker)는 Service Worker를 이용해 서버를 향한 실제 네트워크 요청을 가로채서(intercept) 모의 응답 (Mocked response)를 보내주는 API Mocking 라이브러리이다.

velog.io

https://techblog.woowahan.com/20154/

API 모킹으로 테스트를 더 편리하게, Mock Service GUI 소개 | 우아한형제들 기술블로그

여러분은 프론트엔드의 API 모킹 환경을 어떤 방식으로 구축하고, 사용하고 계신가요? 이 글에서는 API 모킹 환경을 개발자 친화적으로 개선해 나가는 과정을 다루며, 2023 우아한테크콘퍼런스에

techblog.woowahan.com

RESTful한 API 설계

REST API는 REST 아키텍처 스타일을 따르는 API를 말하고, RESTful API는 그 REST 원칙을 충실히 지켜 설계된 이상적인 API를 의미합니다. 모든 RESTful API는 REST API지만, 그 반대는 아닙니다.

RESTful의 주요 특징

자원(Resource) 중심 : 모든 것을 자원으로 보고, URI(Uniform Resource Identifier)로 명확하게 식별합니다 (예: /users, /products/123).
표준 HTTP 메서드 활용 : 데이터 생성/조회/수정/삭제(CRUD)를 HTTP 메서드에 매핑합니다 (GET: 조회, POST: 생성, PUT/PATCH: 수정, DELETE: 삭제).
상태 비저장(Stateless) : 서버는 클라이언트의 이전 요청 상태를 기억하지 않으며, 각 요청은 독립적입니다.
표현(Representation) : 클라이언트와 서버는 자원의 상태를 JSON, XML 등의 형식으로 주고받습니다 (Representation of State Transfer)
클라이언트-서버 구조 : 클라이언트와 서버가 분리되어 독립적으로 개발 및 발전할 수 있습니다.

다양한 아키텍처 패턴에 대한 이해

레이어드 아키텍처

각 레이어는 자기 책임만 갖고, 아래 레이어에만 의존한다

1️⃣ Controller Layer (Presentation Layer)

HTTP 요청/응답 처리
입력값 검증
인증/인가 처리
DTO 변환
비즈니스 로직 ❌
DB 접근 ❌

2️⃣ Service Layer (Business Layer)

핵심 비즈니스 로직
트랜잭션 관리
여러 Repository 조합

3️⃣ Repository Layer (Persistence Layer)

DB 접근
CRUD 처리
ORM / Query Builder 사용

4️⃣ Domain / Model Layer (선택적)

엔티티 정의
도메인 규칙

장점	단점
유지 보수성 한 레이어 수정 → 다른 레이어 영향 최소화	과도한 보일러플레이트 → 작은 프로젝트엔 오히려 복잡
		테스트 용이성 service 단위 테스트 쉬우며 repository mock 가능	Service 비대화 → 도메인 단위로 service 분리 필요

헥사고날 아키텍처

비즈니스 로직은 중심에 두고, DB·웹·메시지·외부 API 같은 것은 전부 갈아 끼울 수 있게 만든 구조

https://mangkyu.tistory.com/396

[Architecture] 헥사고날 아키텍처를 통한 의미 수준과 구현 수준에 대한 이해(semantic and implementation l

1. 헥사고날 아키텍처에 대하여[ 헥사고날 아키텍처의 도메인 엔티티(Domain Entity) ]우리는 소프트웨어를 개발할 때 어떠한 의미를 갖는 이론적 토대를 바탕으로 개발을 하게 된다. 예를 들어 우리

mangkyu.tistory.com

https://ivory-room.tistory.com/91

[Architecture] 헥사고날 아키텍처(Hexagonal Architecture) (ft. 계층형 아키텍처, 클린 아키텍처, DDD)

헥사고날 아키텍처를 설명하기전에 계층형 아키텍처와 클린 아키텍처, 그리고 도메인 주도 설계(DDD)관련하여 가볍게 짚고 넘어가야한다. 헥사고날 아키텍처는 전통 방식인 계층형 아키텍처의

ivory-room.tistory.com

클린 아키텍처

https://daryeou.tistory.com/280#google_vignette

클린 아키텍처(Clean Architecture) 개념 및 원칙

개발이란 마치 여러 개의 기반이 되는 블록을 만들어 설계 원칙에 따라 조립하여 완성해 나아가는 과정이라고 생각합니다. 여기서 설계 원칙은 수 많은 디자인 패턴들을 의미하며, 이번 주는 아

daryeou.tistory.com

핵사고날 아키텍처는 공부하면 공부할수록 너무 어려운 개념인것 같다는 생각이 들었다.

어렵고 크게 와닿지 않는 개념이라고 생각했는데 https://tech.kakaopay.com/post/home-hexagonal-architecture/ 이런글을 공유를 받았는데 공감이 되면서 슬픈 사실인것 같다는 생각을 했다.

[항해 복귀 스터디] 1주차 TDD

h7ung — Mon, 2 Feb 2026 22:15:57 +0900

10주간 항해를 마치고 부족한 부분을 다시 공부하고자 항해 그 후 스터디에 참여를 하여 스터디를 진행을 하였습니다.

스터디를 진행을 하면서 개인적으로 공부를 했던것을 기록하려고 합니다.

해당 내용은 항해에서 배웠던 10주간 챕터들 중에서 항해하면서 부족하고 추가로 공부할 필요가 있는 것을 키워드 별로 공부를 진행 했습니다.

런던파와 고전파에 대한 이해와 본인의 견해 수립

런턴파와 고전파의 가장 큰 차이는 테스트에서의 격리(isolation)를 어떻게 정의하고 구현하느냐이다.

런던파

런던파는 테스트 대상 코드가 다른 객체/클래스에 의존할 경우, 이 의존성을 모두 테스트 대역(test double) 으로 대체해야 한다고 본다.

테스트 대역은 실제 객체 대신 사용하는 ‘단순화된 대체’ 객체로, 복잡성을 줄이고 테스트를 격리한다.

특징

테스트 대상 코드(Class)를 협력자(Collaborator)로부터 완전히 분리
실제 객체 대신 mock(모의 객체) 을 적극적으로 사용
테스트 실패 시 문제가 반드시 테스트 대상 코드에 있음이 확인됨
객체 간 상호작용(interaction) 를 검증하는 방식 중심
하나의 클래스만 독립적으로 테스트 하는 구조를 지향

public class PaymentService {
    private final PaymentGateway paymentGateway;
    private final OrderRepository orderRepository;

    public PaymentService(PaymentGateway paymentGateway,
                          OrderRepository orderRepository) {
        this.paymentGateway = paymentGateway;
        this.orderRepository = orderRepository;
    }

    public void pay(long orderId) {
        Order order = orderRepository.find(orderId);
        paymentGateway.charge(order.getAmount());
        orderRepository.markPaid(orderId);
    }
}

@ExtendWith(MockitoExtension.class)
class PaymentServiceLondonTest {

    @Mock
    PaymentGateway paymentGateway;

    @Mock
    OrderRepository orderRepository;

    @InjectMocks
    PaymentService paymentService;

    @Test
    void 결제하면_PG와_Repository가_정확히_호출된다() {
        Order order = new Order(1L, 100);
        when(orderRepository.find(1L)).thenReturn(order);

        paymentService.pay(1L);

        verify(orderRepository).find(1L);
        verify(paymentGateway).charge(100);
        verify(orderRepository).markPaid(1L);
    }
}

⇒ 객체 간 협력 구조가 테스트 대상

고전파

고전파는 단위 테스트에서 모든 의존성을 대역으로 바꾸는 것을 지양한다.

특징

공유 상태(shared state) 를 유발할 수 있는 외부 의존성(예: DB, 파일 시스템)만 테스트 대역을 쓴다
나머지 협력 객체는 실제 객체(real instance) 를 사용해 테스트한다
테스트는 서로 독립적으로 실행되도록 만들고 격리하지만, 의존성 자체는 교체하지 않는다

class FakePaymentGateway implements PaymentGateway {
    @Override
    public void charge(int amount) {
        // 아무것도 안 함 (항상 성공)
    }
}

class InMemoryOrderRepository implements OrderRepository {
    private final Map<Long, Order> store = new HashMap<>();

    public InMemoryOrderRepository() {
        store.put(1L, new Order(1L, 100, "CREATED"));
    }

    @Override
    public Order find(long id) {
        return store.get(id);
    }

    @Override
    public void markPaid(long id) {
        store.get(id).setStatus("PAID");
    }
}

class PaymentServiceClassicalTest {

    @Test
    void 결제하면_주문상태가_PAID가_된다() {
        OrderRepository repo = new InMemoryOrderRepository();
        PaymentGateway gateway = new FakePaymentGateway();

        PaymentService service = new PaymentService(gateway, repo);

        service.pay(1L);

        Order order = repo.find(1L);
        assertEquals("PAID", order.getStatus());
    }
}

런던파 vs 고전파

구분 런던파 고전파

관심사	객체 간 호출 관계	최종 상태 / 결과
Mock	매우 많이 씀	최소한만
테스트 실패 이유	“A가 B를 안 불렀음”	“결과가 틀림”
리팩토링	깨지기 쉬움	비교적 안정
속도	빠름	느릴 수 있음

두 분파 차이의 핵심은 “격리”해석에 있다.
런던파는 의존성을 강제로 대역으로 바꿔 테스트를 더 격리시킨다.
고전파는 실제 의존 객체를 활용하여 테스트의 현실성을 유지한다.
어느 쪽이 옳다기보다 목적에 따라 선택해 사용하는 것이 중요하다.

참고

테스트 대역(Test Double)에 대한 이해

테스트에서 진짜 객체 대신 쓰는 가짜 객체들을 통칭하는 말

(DB, 외부 API, 결제 모듈 같은 “의존성”을 진짜로 쓰면 테스트가 느리고 불안정해지니까 대신 넣는 것)

“진짜 대신 써서 테스트를 안정적으로 만들기 위한 모든 가짜들” = 테스트 대역

1. Dummy

아무 역할도 없는 채우기용 객체

Dummy 객체는 테스트 대상 코드가 정상적으로 실행되도록 타입과 의존성만 충족시키는 용도의 객체이다.

Dummy는 어떤 행동도 수행하지 않으며, 호출되더라도 의미 있는 결과를 만들지 않는다. 또한 테스트의 검증 대상이 아니며, 결과값이나 호출 여부를 확인하는 데 사용되지 않는다.

(예시)

주문을 취소하는 서비스가 있고, 이 서비스는 EmailService와 OrderRepository를 의존한다.

여기서 cancelOrder()가 delete를 호출하는지만 테스트를 하고 싶은 상황

public class OrderService {

    private final OrderRepository orderRepository;
    private final EmailService emailService;

    public OrderService(OrderRepository orderRepository,
                        EmailService emailService) {
        this.orderRepository = orderRepository;
        this.emailService = emailService;
    }

    public void cancelOrder(long orderId) {
        orderRepository.delete(orderId);
        // emailService는 여기서 안 쓰임
    }
}

Dummy 구현

public class DummyEmailService implements EmailService {
    @Override
    public void sendCancelEmail(long orderId) {
        // 아무것도 하지 않음
    }
}

⇒ 이 객체는 컴파일을 위해 필요하지만, 실행 결과에는 아무런 영향도 주지 않는다.

test code

@Test
void cancelOrder_calls_delete() {
    OrderRepository fakeRepo = new FakeOrderRepository();
    EmailService dummyEmailService = new DummyEmailService();

    OrderService service = new OrderService(fakeRepo, dummyEmailService);

    service.cancelOrder(10L);

    assertTrue(fakeRepo.isDeleted(10L));
}

여기서 dummyEmailService는 호출되든 말든 중요하지 않고, 테스트의 검증 대상이 아니다.

2. Stub

“정해진 값”만 돌려주는 객체 Dummy 가 아무것도 하지 않는 객체라면, Stub 은 필요한 값만 돌려주는 객체이다.

Stub은 테스트 대상이 외부 의존성(DB, API, 시간, 환경 등)에 의존하지 않도록 하기 위해 사용된다.

즉,테스트 대상 로직이 특정 상황에 있다고 믿게 만들기 위해 사용하는 객체이다.

특징

호출되면 미리 정해진 값을 반환한다.
내부 로직은 없다.
호출 횟수나 인자는 검증하지 않는다.
테스트는 Stub 이 만든 결과값을 기반으로 판단한다.

(예시)

public class DiscountService {

    private final UserRepository userRepository;

    public DiscountService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public int getDiscount(long userId) {
        User user = userRepository.findById(userId);

        if (user.isVip()) {
            return 30;
        }
        return 10;
    }
}

Stub 구현

public class VipUserRepositoryStub implements UserRepository {

    @Override
    public User findById(long userId) {
        return new User(userId, true); // 항상 VIP 유저 반환
    }
}

⇒ DB 를 조회하지 않고 항상 vip 유저를 반환하여 테스트 환경을 강제로 vip 상태로 만든다.

test code

@Test
void vipUser_gets_30_percent_discount() {
    UserRepository stub = new VipUserRepositoryStub();
    DiscountService service = new DiscountService(stub);

    int discount = service.getDiscount(1L);

    assertEquals(30, discount);
}

⇒ findById()가 호출됐는지 관심 없으며, 오직 반환된 discount 값만 검증한다.

3. Spy

호출 여부를 기록하는 객체 Stub 이 값을 통제했다면, Spy 는 무슨 일이 일어났는지 기록 한다.

메서드의 실제 동작은 그대로 수행하면서 이 메서드가 호출되었는가 / 몇번 호출되었는가 / 어떤 인자로 호출되었는가를 확인하고 싶을때 사용된다.

특징

실제 구현을 감싸거나 위임한다.
호출 기록을 저장한다.
결과값은 실제 로직에 따른다.
테스트는 호출여부 + 결과 둘 다 볼 수 있다.

(예시)

public class EmailServiceSpy implements EmailService {

    private int sendCount = 0;

    @Override
    public void sendCancelEmail(long orderId) {
        sendCount++;
        System.out.println("메일 발송됨"); // 실제 동작
    }

    public int getSendCount() {
        return sendCount;
    }
}

test code

@Test
void cancelOrder_sends_email() {
    EmailServiceSpy spy = new EmailServiceSpy();
    OrderRepository dummyRepo = new DummyOrderRepository();

    OrderService service = new OrderService(dummyRepo, spy);

    service.cancelOrder(1L);

    assertEquals(1, spy.getSendCount());
}

⇒ 실제 내부 로직이 실행이 되고, 몇번 호출됐는지도 검증한다.

4. Mock

행위까지 검증하는 객체 Stub 은 값을 검증하고, Mock 은 행동을 검증한다.

특징

실제 동작 없다.
호출 규칙을 미리 정의한다.
테스트가 끝나면 자동으로 검증을 한다.
행위기반(Behavior-based) 테스트

(예시)

EmailService emailMock = mock(EmailService.class);

OrderService service =
    new OrderService(dummyRepo, emailMock);

service.cancelOrder(1L);

verify(emailMock).sendCancelEmail(1L);

⇒ 메일이 실제로 보내졌는지가 아니라 오직 sendCancelEmail 이 호출됐는지만 검증을 한다.

5. Fake

진짜처럼 동작하지만 단순한 구현

실제 구현(DB, Redis, 외부 API)이 너무 무겁거나 느릴 때, 테스트에서 “진짜처럼” 여러 로직을 실행해야 할 때 Fake 가 사용된다.

특징

실제와 유사한 로직을 가진다.
상태를 저장한다.
여러 메서드가 서로 영향을 준다.
Mock 처럼 호출 규칙을 검증하지 않는다.
Stub 보다 훨씬 많은 로직을 가진다.

(예시)

public interface UserRepository {
    void save(User user);
    User findById(long id);
}

Fake

public class FakeUserRepository implements UserRepository {

    private Map<Long, User> store = new HashMap<>();

    @Override
    public void save(User user) {
        store.put(user.getId(), user);
    }

    @Override
    public User findById(long id) {
        return store.get(id);
    }
}

⇒ 실제 DB 가 없고 메모리 Map 을 사용하며 동작은 진짜 Repository 와 동일하다.

test code

@Test
void user_can_be_saved_and_loaded() {
    UserRepository fakeRepo = new FakeUserRepository();
    UserService service = new UserService(fakeRepo);

    User user = new User(1L, "user");
    service.register(user);

    User loaded = service.find(1L);

    assertEquals("user", loaded.getName());
}

참고

단위 테스트와 통합 테스트의 차이와 장단점에 대한 이해

단위테스트(Unit Test)

클래스 하나를 고립시켜서 로직만 검증한다.

구분 내용 실무 의미

장점	실행 속도가 매우 빠름	수백~수천 개도 CI에서 몇 초
	실패 원인이 명확함	어떤 클래스/메서드가 문제인지 바로 앎
	리팩토링 안전망	내부 구조 바꿔도 기능 깨졌는지 바로 확인
	Spring 없이 실행 가능	IDE에서 바로 실행 가능
	TDD에 적합	설계가 자연스럽게 좋아짐
단점	DB, JPA, 트랜잭션 검증 불가	쿼리, 매핑 오류는 잡지 못함
	실제 Bean 구성과 다를 수 있음	@Autowired, @Qualifier 오류 못 잡음
	Mock이 많아질수록 테스트가 복잡	유지보수 비용 증가
	“실제 서비스 동작” 보장은 못함	통과했는데 API는 깨질 수 있음

서비스코드

public class OrderService {
    private final DiscountPolicy discountPolicy;

    public OrderService(DiscountPolicy discountPolicy) {
        this.discountPolicy = discountPolicy;
    }

    public int calculatePrice(int price) {
        return price - discountPolicy.discount(price);
    }
}

test code

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {

    @Mock
    DiscountPolicy discountPolicy;

    @InjectMocks
    OrderService orderService;

    @Test
    void 할인정책이_적용된_가격을_계산한다() {
        when(discountPolicy.discount(10000)).thenReturn(1000);

        int result = orderService.calculatePrice(10000);

        assertThat(result).isEqualTo(9000);
    }
}

통합테스트(Integration Test)

Spring Boot 전체를 띄우고 실제 빈, 실제 DB와 함께 테스트

구분 내용 실무 의미

장점	실제 Spring Bean 조합 검증	설정 오류, DI 오류를 잡아줌
	JPA, 쿼리, 매핑 검증	실무 장애의 대부분을 미리 차단
	트랜잭션 동작 확인	commit/rollback 문제 검증
	API 단위 검증 가능	프론트와의 계약 테스트
단점	실행 속도가 느림	Spring + DB 기동
	실패 원인 추적이 어려움	어느 계층이 문제인지 불명확
	테스트 데이터 관리 필요	초기화, 롤백, 시드 필요
	CI 비용 큼	Testcontainer, Docker 필요할 수 있음

@SpringBootTest
@Transactional
class OrderServiceIntegrationTest {

    @Autowired
    OrderService orderService;

    @Autowired
    OrderRepository orderRepository;

    @Test
    void 주문이_DB에_저장된다() {
        Order order = new Order(10000);

        orderService.placeOrder(order);

        Order saved = orderRepository.findById(order.getId()).get();
        assertThat(saved.getPrice()).isEqualTo(10000);
    }
}

좋은 테스트 코드에 대한 이해

https://toss.tech/article/test-strategy-server

좋은 테스트

Fast: 테스트는 빠르게 동작하여 자주 돌릴 수 있어야 함
Independent: 각각의 테스트는 독립적이며 서로 의존해서는 안 됨
Repeatable: 어느 환경에서도 반복 가능해야 함
Self-Validating: 테스트는 성공 또는 실패로 bool 값으로 결과를 내어 자체적으로 검증되어야 함
Timely: 테스트는 적시에 즉, 테스트하려는 실제 코드를 구현하기 직전에 구현해야 함

https://tech.inflab.com/20230404-test-code/#테스트-코드를-왜-작성하는-것인가

https://jojoldu.tistory.com/674

pub/sub 로직 개선하기

h7ung — Wed, 25 Jun 2025 21:44:32 +0900

pub/sub 로직 개선했던 서비스에서 간단하게 배경 설명을 한다면,,

수강신청이라는 서비스가 있다.

b2e 화면에서 수강생들이 수강신청을 진행을 하면 backoffice 에서 관리자가 해당 상품에 대해서 수강신청 확정 버튼을 클릭해 수강생들이 신청한 강의들을 확정처리하여 강의를 들을 수 있게 하는 서비스가 있다.

이 서비스는 처음에 batch 로 작업이 진행이 되었다.

batch 로 1시간에 한번씩 작업이 진행이 되었다.

하지만 이 서비스의 확정 처리 기능은 빈번하게 발생하는 작업이 아니였고 비정기적으로 진행이 되는 작업이였다.

비정기적으로 작업이 되는 서비스에 batch 는 과한 스펙이 되었다.

그래서 이 확정처리 기능은 batch 에서 pub/sub 으로 변경이 되었다.

pub/sub 은 이렇게 구현을 하였다.

pub/sub 을 통해서 수강신청 확정 버튼을 클릭할때마다 확정 처리 기능이 진행이 되었다.

근데 여기에도 비효율적인 로직이 있었다.

pub/sub 에서 Run 으로 message 로 확정 처리 대상이 되는 id 값을 던지지만 run 에서 run job 을 호출할때 해당 메시지를 전달하지 않고 있다라는 점이다.

run job 에서는 전체 수강신청 상품 대상으로 조회한뒤 해당 되는 상품을 찾아 확정 처리 작업을 진행하고 있었다.

run 에서 run job 을 호출할때 pub/sub 에서 받은 id 를 그대로 전달해주면 되지 않을까??? 라는 의문이 들었다.

그래서 run 의 소스 코드를 한번 확인을 해보았다.

        # Pub/Sub 메시지 추출
        envelope = request.get_json()
        if not envelope or 'message' not in envelope:
            return "Invalid message", 200

        message = envelope['message']
        data = ''
        if 'data' in message:
            data = base64.b64decode(message['data']).decode('utf-8')

        print(f"Received Pub/Sub message: {data}")

        # Cloud Run Job 실행
        client = run_v2.JobsClient()
        job_path = client.job_path(project=project_id, location=location, job=job_name)
        run_request = run_v2.RunJobRequest(name=job_path)

        print(f"Triggering Cloud Run Job: {job_path}")
        operation = client.run_job(request=run_request)

message 만 추출하고 바로 run-job 을 호출하는 로직이였다.

여기서 message 를 추출한 다음 run-job 호출할때 해당 값을 넣어 주면 되지 않을까? 라는 생각이 들었다.

어떤 방법이 있는지 GPT 에게 물어봤다. GPT 는 환경변수 방식, 커맨드 인자 방식 두가지 방법을 알려주었다.

기준	환경변수 사용	커맨드 인자 사용
간단한 설정값 전달	✅ 권장	가능하지만 과함
보안 정보 (e.g. API 키)	❌ 비추천 (Secret Manager 권장)	❌ 비추천
실행 시간마다 바뀌는 값 (동적 파라미터)	✅ 좋음	✅ 좋음
스크립트나 CLI 스타일에 익숙함	❌ 적합하지 않음	✅ 적합
가독성 / 로깅이 중요한 경우	덜 직관적 (env)	✅ 명확하게 로그로 노출
컨테이너 재사용 가능성	✅ 환경에 따라 분기 쉬움	✅ 인자에 따라 다양화 가능

권장 방식 -> 일반적으로는 환경변수 방식이 더 유연하고 안전

Cloud Run Job의 실행 오버헤드가 적고 설정이 간단합니다
Dockerfile이나 ENTRYPOINT 수정 없이도 작동 가능
컨테이너 내부에서 표준 환경변수 접근 (process.env, os.environ) 방식으로 활용 가능
Cloud Console이나 gcloud UI에서도 시각적으로 관리하기 쉬움

이렇게 두가지 방식에 대해 특징과 권장방식에 대해서 확인을 해보고 실 사용하는 서비스를 각각의 특징에 대입해서 봤을때 환경변수 사용하는 것이 더 적합한 방식이라고 판단이 되어 환경변수 사용하는 방식을 선택한 뒤 run 의 소스 코드를 수정하였다.

        # 3. 메시지에서 필요한 값 추출
        try:
            payload = json.loads(data)
        except json.JSONDecodeError:
            logger.warning("Message is not valid JSON")
            payload = {}

        registration_product_id = str(payload.get("registrationProductId", '')).strip() or None
        product_id = str(payload.get("productId", '')).strip() or None

        # 4. Cloud Run Job 실행을 위한 클라이언트 및 job path
        client = run_v2.JobsClient()
        job_path = client.job_path(project=project_id, location=location, job=job_name)

        # 5. 환경변수 오버라이드 설정
        env_vars = []
        if registration_product_id: # message 로 받은 key 값
            env_vars.append(run_v2.EnvVar(name="REGISTRATION_PRODUCT_ID", value=registration_product_id))
        if product_id: # message 로 받은 key 값
            env_vars.append(run_v2.EnvVar(name="PRODUCT_ID", value=product_id))

        overrides = None
        if env_vars:
            container_override = run_v2.RunJobRequest.Overrides.ContainerOverride(env=env_vars)
            overrides = run_v2.RunJobRequest.Overrides(container_overrides=[container_override])

        # 6. Job 실행 요청 생성
        run_request = run_v2.RunJobRequest(
            name=job_path,
            overrides=overrides
        )

message 에서 필요한 값을 추출한 뒤 해당 값을 환경변수 오버라이드로 설정을 하여 job 실행시에 해당 환경변수를 넣어 주었다.

이렇게 run 소스 코드를 수정하고 run-job 을 실행하여 환경 변수가 잘 들어오는지 테스트를 해보았다.

run 에서는 로그가 잘 나오고 있어 run-job 에서 확인해보았다.

input 을 넣어 로그를 확인해보니 잘 노출 되고 있어 환경 변수가 run-job 에도 잘 전달 되고 있는 것을 확인했다.

이렇게 환경변수를 활용하여 run 에서 run-job 을 호출할때 해당 값을 전달 할 수 있었다!!

api 속도 개선 해보기

h7ung — Sun, 16 Mar 2025 13:50:17 +0900

사내 서비스를 이용하던 중 전체 강의 화면에서 화면 로딩이 2~3초가 걸려서 원인이 궁금했다.

화면 로딩이 2~3 초면 사용자가 이용하기에 화면 로딩이 너무 느리다고 체감이 되고, 서비스 사용하기에 불편함을 느낄것 같았다.

그래서 이것을 개선해보기로 했다!

전체 강의 보기 화면에서 호출되는 api 를 파악하고 제일 응답 속도가 느린 api 를 확인해보았다.

제일 응답 속도가 느린 api 는 filters 였고 이 api 응답값을 통해서 프론트에서 화면을 뿌려주고 있었다.

filters API 구조를 확인을 해보자!

server to server 통신을 하고 있고, 내부에서 많은 연산이 진행이 되고 있었다.

여기서 연산이 가장 오래 걸리는 것을 파악하기 위해서 console.time(), console.timeEnd() 두개를 이용했다.

속도를 확인해보고 싶은 부분 시작점에 console.time 을 추가했고 끝점에 console.timeEnd 를 넣어 연산 속도를 확인할 수있었다.

this.server.addHook('onRequest', (request, reply, done) => {
  (request.raw as any).startTime = Date.now();
  done();
});
this.server.addHook('onResponse', (request, reply, done) => {
  const startTime = (request.raw as any).startTime;
  if (startTime) {
    console.log(`Request took ${Date.now() - startTime} ms`);
  }
  done();
});

또한 전체 api 응답 시간을 확인 하기 위해서 preHandler 쪽에 코드를 추가하여 확인 할 수 있었다.

속도가 오래 걸리는 부분은 두가지가 있었다.

첫번째는 server to server 통신을 하고 있던 부분, course ids 를 통한 course 조회하는 부분이였다.

각각 대략 1s 정도가 걸렸다.

server to server 통신하는 부분 속도 개선하기!

server to server 통신하는 부분의 기능을 확인해보니 모든 사용자마다 다른 응답값을 주는 것이 아니라 동일한 값을 응답하고 있었다.

요청하는 query 에 따라서 다르게 응답하겠지만 client 에서 요청하는 값을 확인해보니 sortType 만 영향이 있었다.

sortType 도 newest/popularity 두가지 뿐이였다.

매번 사용자마다 해당 api 를 호출하는 것은 비효율적인 것으로 판단이 되어 cache 사용하는 방안으로 개선을 해보았다.

let filteredCourses;
if (cache) {
	filteredCourses = cache;
} else {
    filteredCourses = (
      (await this.classFinderClient.getClassFinderApi(`url`, {
        site: Site.LXP,
        price,
        totalPlayTime,
        state,
        sortType,
      })) as {
        data: FtsResponseDto;
      }
    ).data as unknown as { courseId: number; popularity?: number }[];
    this.curationCacheService
      .setCache({ ...query, site: Site.LXP }, filteredCourses)
      .catch((err) => console.error('curation cache setting error:', err));
}

cache 를 조회하여 있다면 redis 에서 값을 가져와서 사용하였고, 없다면 api 호출을 하는 방안으로 진행하였다.

redis 에 set 할때는 비동기로 처리하였다. redis 에 set 을 하고 그 외의 다른 작업이 없었고, 그 후에 다른 연산 과정이 많기 때문에 동기로 처리할 이유가 없었다.

redis key 로 api 호출할때 사용하는 query 를 사용하였다. 윗 부분에 해당 api 호출할때 sortType 만 다르다고 하여 sortType 만 사용해도 될 것 같다고 생각이 들텐데 추후 api 호출할때 다른 값도 사용할 수도 있으니 확장성을 고려하여 query 전체를 사용했다.

export class CurationCacheService {
  private cacheService: FastCache;
  readonly ttlInSec: number; //1day

  constructor({ cacheService = defaultCache, ttl = CURATION_CACHE_TTL } = {}) {
    this.cacheService = cacheService;
    this.ttlInSec = ttl;
  }
  static get CURATION_CACHE_KEY() {
    return 'cache';
  }

  async getCache(query: CourseFilterQuery & { site: string }): Promise<filteredCourses[] | null> {
    const session = await this.cacheService.get(`${CurationCacheService.CURATION_CACHE_KEY}:${JSON.stringify(query)}`);
    return session ? (ObjectUtil.deserialize(session) as filteredCourses[]) : null;
  }

  async setCache(query: CourseFilterQuery & { site: string }, value: filteredCourses[]) {
    const key = `${CurationCacheService.CURATION_CACHE_KEY}:${JSON.stringify(query)}`;
    await this.cacheService.set(key, ObjectUtil.serialize(value) as string, this.ttlInSec);
    this.logger.debug(`grant curation cache ok, cacheKey=${key}`);
  }
}

윗 부분의 코드는 redis set / get 하는 class 이다.

ttl 은 1 day 로 설정했다. 1 day 를 설정한 이유는 해당 api 호출 값이 빈번하게 바뀔일이 없어서 1 day 로 설정했다.

해당 부분으로 변경 후 속도가 줄어든 것을 확인 할수 있었다.

많은 ids 로 db 조회 시 응답 속도 개선하기!

db 조회하는 부분은 위에 표시한 부분이다.

//courseService
async findCoursesByIds(ids: number[]) {
  return this.courseDao.selectByIds(ids);
}

//courseDao
async selectByIds(ids: number[]) {
  return this.repository.findBy({ id: In(ids) });
}

이 부분의 코드를 타고 들어가보면 이렇게 typeorm 을 사용하고 있었다.

id 에 index 가 걸려있어서 index 를 타서 검색을 할텐데 왜 오래 걸리는지 의문이 들었다.

explain 를 사용해서 실제 쿼리가 index 를 타는지 확인을 해보았는데 full scan 을 하고 있었다.

알고 보니 검색하려는 id 갯수가 많아서 index 를 타지 않는다는 것이였다.

this.courseService.searchSelectionIds({
  ids: courseIds,
  select: COURSE_SELECTION_IDS,
}),

//courseService
async searchSelectionIds(query: RequestSelectionQuery) {
  return this.courseDao.searchSelectionIds(query);
}

//courseDao
async searchSelectionIds(query: RequestSelectionQuery) {
  return this.repository
    .createQueryBuilder(this.tableName)
    .select(this.buildSelectQuery(this.tableName, query.select))
    .where((qb) => {
      qb.andWhere(`${this.tableName}.id IN (:ids)`, { ids: query.ids });
    })
    .getRawMany();
}

db 조회할때 필요한 값만 select 하는 방안으로 개선을 했더니 속도가 개선 되는 것을 확인했다.

before / after 을 확인해보았을때 확실히 속도가 개선된 것을 확인 할 수 있었다!!

개발.. 한놈만 팬다

[LOOp:pak vol.4] 스투시 반팔티를 10명이 동시에 주문하면 생기는 일

시작은 단순한 착각이었다

트랜잭션이 보장하는 것과 보장하지 않는 것

실제로 뭐가 터지는지 그려봤다

격리 수준을 올리면 되지 않을까 (두 번째 착각)

락 전략 1 — 비관적 락: 일단 잠그고 본다

락 전략 2 — 낙관적 락: 일단 진행하고, 충돌나면 그때 처리

둘 중 뭘 고를까

그런데 한정판이라면

마지막 의문 — 재고 차감은 꼭 읽어야 할까

정리하며

9.5초 → 0.27초: 측정으로 시작한 API 성능 개선기

한눈에 보기

개선 여정 (요약)

1. 측정부터 — 구간별 타이밍

2. 삽질 ① — "인덱스 없나?" → ❌

3. 반전 — 진범은 외부 인기도 API

4. 개선 ① — 외부 호출 Redis 캐싱

5. 개선 ② — 페이지네이션 앞당기기 ⭐

6. 메모리 — GC 노이즈를 피해 측정

7. 테스트 우선 (+ 캐시 함정)

최종 스코어보드

[LOOp:pak vol.4] 이 규칙은 도메인일까, 유스케이스일까 — Service / Facade 의 진짜 분기 기준

멈춘 코드

두 단어의 경계

다른 기준들도 거쳐봤다

진입점 불변성이라는 한 줄 테스트

auto-restore 에 대입하기

결정 이후에도 흔들리는 것들

마지막으로...

MongoDB 쿼리에서 대시보드로: AI와 함께 만든 시청 데이터 관측 도구

왜 만들었나

어떤 화면을 만들었나

화면확인할 수 있는 것업무에서 좋은 점

가장 업무적인 기능: 미시청 콘텐츠

구현하면서 정리한 것

[LOOp:pak vol.4] 좋아요, 그 단순해 보이는 기능에서 결정해야 했던 것들

1. POST /products/{id}/likes 한 줄에서 시작

2. 멱등성 — 같은 요청을 N 번 보내도 결과가 같으려면

3. 좋아요 수, 어디에 두어야 하나

4. 취소된 좋아요가 다시 좋아요가 되는 순간 — soft delete × unique 충돌

5. Like 만 hard delete — 그리고 BaseEntity 한 줄을 안 썼다

Brand 와 Like — 같은 시스템에서 다른 정책

6. 정리 — 단순한 기능에 숨어 있던 결정들

이번에 배운 것

다음 단계에서 확인할 것

[LOOp:pak vol.4] 회원 도메인을 TDD로 만들며 — 1주차 회고

이번 주에 한 일

가장 곱씹었던 결정 — 검증 책임의 위치

도메인 모델 — 형식 검증

도메인 서비스 — 정책/컨텍스트 검증

한 번 막혔던 곳 — 검증 순서

작은 추상화의 큰 효과 — PasswordEncoder

KPT

마무리

[항해 복귀 스터디] 2주차 설계 + 아키텍처 패턴

Mock API를 우선 제공해야 하는 필요성에 대한 이해

RESTful한 API 설계

다양한 아키텍처 패턴에 대한 이해

레이어드 아키텍처

헥사고날 아키텍처

클린 아키텍처

[항해 복귀 스터디] 1주차 TDD

런던파와 고전파에 대한 이해와 본인의 견해 수립

런던파

고전파

런던파 vs 고전파

테스트 대역(Test Double)에 대한 이해

1. Dummy

2. Stub

3. Spy

4. Mock

5. Fake

단위 테스트와 통합 테스트의 차이와 장단점에 대한 이해

단위테스트(Unit Test)

통합테스트(Integration Test)

좋은 테스트 코드에 대한 이해

pub/sub 로직 개선하기

api 속도 개선 해보기

작은 추상화의 큰 효과 — `PasswordEncoder`