Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
daa9739
docs: Outbox 폴러 V1→V2→V3 발전 과정 문서화
heeun98 Jul 15, 2026
16405e6
refactor: 전역 피드 캐시를 TTL+분산락에서 상주 캐시+스케줄러 동기화로 전환
heeun98 Jul 17, 2026
5d72dc2
docs: 전역 피드 v2 전체 흐름 다이어그램 추가 (6-1장)
heeun98 Jul 17, 2026
27f1cbc
fix: Lettuce 커맨드 타임아웃 1초 설정 (기본 60초 → 장애 시 요청 스레드 블로킹 방지)
heeun98 Jul 17, 2026
78f50eb
refactor: 리스너가 outbox 저장 payload를 직접 전송하도록 변경 (payload 생성 로직 중복 제거)
heeun98 Jul 22, 2026
65458b2
perf: outbox에 (status, created_at) 복합 인덱스 추가 — claim 쿼리 락 범위 최소화
heeun98 Jul 22, 2026
90653d5
feat: outbox 폴러 V4 — 삭제 대신 SENT/FAILED 마킹 + next_retry_at 백오프 재시도
heeun98 Jul 28, 2026
8ad8ef0
fix: AdminClient 실패 분류를 상태코드 기준으로 재정의 — 408·429 오분류 수정
heeun98 Jul 28, 2026
bdd9b89
fix: 미션 로그 멱등 저장 시 동시 중복이 500으로 응답되던 버그 수정
heeun98 Jul 28, 2026
e0a0eaf
refactor: 미션 완료 리스너의 null 가드를 Optional 체이닝으로 정리
heeun98 Jul 28, 2026
561006b
chore: API 서버 IP 변경 반영 — RestClient fallback URL 갱신
heeun98 Jul 28, 2026
96e323b
refactor: SendResult를 성공/실패 2분류로 단순화 — 일시/영구 구분 제거
heeun98 Jul 28, 2026
30d7aa6
feat: 미션 로그에 completedDate 추가 — 집계 기준을 도착 시각에서 완료 날짜로
heeun98 Jul 28, 2026
bcd15b3
feat: outbox 재시도 상한을 15회에서 3회로 하향 (백오프 5+10+15분, 총 30분 커버)
heeun98 Jul 29, 2026
a236671
refactor: 폴러를 배수 루프에서 짧은 주기 + 호출당 한 배치 구조로 전환
heeun98 Jul 29, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 149 additions & 8 deletions docs/global-feed-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,16 +33,16 @@
|---|------|------|------------|
| D1 | **피드 형태** | **전역 단일 피드** (`feed:recent:global` 키 하나) | 캐시 효율 최고(1개만 관리). 단, **hot key·stampede가 극대화**되므로 R3/R4 대응이 필수가 됨 |
| D2 | **반영 지연 허용** | **수 초** (거의 실시간) | TTL을 짧게(~60초) + **write-through**로 간다. 영구 누락은 불가(F4) |
| D3 | **무효화/갱신 방식** | **Write-through + 짧은 TTL(자가 치유)** | 완료 시 캐시에 직접 push. 실패해도 TTL로 보정. Outbox는 **선택(Phase 3)** |
| D3 | **무효화/갱신 방식** | ~~v1: Write-through + 짧은 TTL(자가 치유)~~ → **v2: Write-through + TTL 제거(상주 캐시) + 30초 스케줄러 DB 동기화** | v1은 TTL 만료마다 single-flight 락 대기가 조회 지연(p99 spike)을 유발(TS2). v2는 만료 자체를 없애 락을 제거하고, 불일치 복구는 스케줄러가 담당 |
| D4 | **무효화 시점** | **AFTER_COMMIT** | 재적재 race(R1) 방지 — 새 데이터가 보인 뒤 갱신 |

### 확정에 따라 "반드시" 들어가는 장치
전역 단일 키(D1) + 수 초 실시간(D2)를 동시에 만족하려면 다음이 **선택이 아니라 필수**다:

- ✅ **single-flight** (R3 stampede) — 전역 키 하나라 만료 1회 = 전체 동시 MISS
- ~~✅ **single-flight** (R3 stampede)~~ → **v2에서 제거.** TTL이 없어 주기 만료 = 전체 동시 MISS 자체가 사라짐(TS2)
- ✅ **L1 로컬 캐시** (R4 hot key) — 전역 키 하나에 전 트래픽 집중
- ✅ **원자적 ZADD** (R5 lost update) — 동시 완료가 흔함
- ✅ **짧은 TTL + 재시도** (R2 dual-write 완화)
- ✅ ~~짧은 TTL~~ → **30초 주기 스케줄러 동기화** (R2 dual-write 복구, v2)
Comment on lines +42 to +45

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

# 전역 피드 조회 경로의 로컬 캐시 구현 여부를 확인합니다.
rg -n -i -C 3 '`@Cacheable`|Caffeine|CacheManager|GlobalFeedService|getRecentFeed' peektime-api

Repository: depromeet/18th-team5-server

Length of output: 7137


🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

echo "== docs/global-feed-design.md relevant lines =="
sed -n '1,90p' docs/global-feed-design.md | cat -n

echo
echo "== global feed service =="
sed -n '1,180p' peektime-api/src/main/java/com/team/peektime_api/domain/feed/service/GlobalFeedService.java | cat -n

echo
echo "== search for local/cache implementations =="
rg -n -i --glob '!*.class' 'inmemory|caffeine|guava|Cacheable|cache manager|Caffeine|loadingcache|loading cache|threadlocal|concurrentmap|ConcurrentHashMap|local' peektime-api/docs peektime-api/src/main/java 2>/dev/null | head -200

Repository: depromeet/18th-team5-server

Length of output: 32656


L1 로컬 캐시의 구현 범위를 맞춰 주세요.

이 문서의 결정 로그(line 43)는 L1 로컬 캐시를 필수 장치로 정의합니다. 현재 GlobalFeedService#getRecentFeed는 feedCacheRepository.findRecent()로 Redis/메모리 계층만 사용하고, @Cacheable, Caffeine/Guava, LoadingCache, 인메모리 Map 같은 전역 피드용 L1 조회 경로는 없습니다. L1이 이번 범위에 포함된다면 서비스/리포지토리 계층에 추가하고, 포함되지 않는다면 해당 문서 필수 요구사항을 정리해 주세요. 참고: 전역 hot key는 Redis/DB가 아니라 애플리케이션 내부 로컬 캐시부터 흡수해야 합니다. :)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/global-feed-design.md` around lines 42 - 45, The decision log marks the
L1 local cache as required, but GlobalFeedService#getRecentFeed currently only
uses feedCacheRepository.findRecent(). Either add a global-feed L1 lookup and
population path at the service or repository layer using the project’s
established in-memory caching mechanism, ensuring hot-key reads are absorbed
before Redis/DB access, or revise the decision log to remove the mandatory L1
requirement if it is out of scope.


---

Expand Down Expand Up @@ -486,6 +486,125 @@ Write-through(전략 B)에서 두 완료가 동시에 캐시를 갱신할 때,
| R4 hot key | L1 로컬 캐시 + (선택) 샤딩 |
| R5 lost update | 원자적 ZADD/LPUSH |

> ⚠️ 위 조합은 **v1 기준**이다. 현재 구현(v2)은 TTL·single-flight를 제거했다 → **6-1장**이 현재 흐름.

---

## 6-1. 현재 구현(v2) 전체 흐름

> 키: `feed:recent:global` (Redis ZSET, score = 완료 시각, 최대 20개, **TTL 없음 = 상주**)
> 등장인물 3명: **조회 요청**(읽기), **완료 리스너**(쓰기), **동기화 스케줄러**(30초 주기).
> 캐시를 채우는 방법이 두 가지인 게 핵심 — `addItem`은 **한 칸 끼워넣기(보강)**, `rebuild`는 **통째 교체(동기화)**.

### 전체 그림

```
┌──────────────────────────────┐
│ Redis ZSET (TTL 없음, 상주) │
│ feed:recent:global │
│ [사진20 ... 사진1] 최대 20개 │
└──────────────────────────────┘
▲ ①ZADD 1건 ▲ ③RENAME(통째 교체)
②reverseRange ┌───┘ (끼워넣기) │
(조회) │ │
┌────────────┐ ┌───┴──────────┐ ┌──────┴─────────┐
│ 조회 요청 │ │ 완료 리스너 │ │ 동기화 스케줄러 │
│ (수시) │ │ (완료 때마다) │ │ (30초마다) │
└─────┬──────┘ └───┬──────────┘ └──────┬─────────┘
│ MISS 시만 │ AFTER_COMMIT │ 최근 20건 SELECT
▼ ▼ ▼
┌──────────────────────────────────────────────────┐
│ DB (원본) │
└──────────────────────────────────────────────────┘
```

### ① 쓰기 시점 — write-through `addItem` (끼워넣기, 덮어쓰기 아님)

```
미션 완료 API
→ DB 커밋 (완료 기록 + 사진 objectKey 저장)
→ AFTER_COMMIT 리스너 (GlobalFeedWriteThroughListener) ← 커밋된 것만 캐시에 (R1 방지)
→ 사진 없는 완료? → 스킵 (피드 제외)
→ 캐시 키 존재? (hasKey)
├─ 없음(콜드) → 스킵 ← 1건짜리 부분 피드 노출 방지.
│ 스케줄러가 30초 내 전체 적재
└─ 있음(워밍) → ZADD 새 사진 1건 + 21위 이하 trim ← 원자 연산, 한 칸만 끼워넣기 (R5 방지)
→ 실패하면? → 로그만 남기고 끝 ← 복구는 스케줄러 몫 (≤30초)
```

- **통째 덮어쓰기가 아니라 1건 추가**다. 동시에 두 완료가 와도 각자 ZADD라 서로 안 지운다.
- 실패해도 재시도하지 않는다 — "쓰기 경로는 최선 노력, 복구는 동기화가 보장"으로 역할 분리.

### ② 조회 시점 — 캐시만 읽는다 (락 없음)

```
GET /api/v1/feed/recent
→ Redis reverseRange (최신순 20개)
├─ HIT (평상시 거의 100%) → presigned URL 생성 → 응답
└─ MISS → DB에서 최근 20건 SELECT → rebuild(즉시 워밍) → 응답
↑
콜드 스타트/Redis 유실 때만 발생. TTL이 없으니 "주기적 만료 → 전체 동시 MISS"
자체가 없다 → 재캐싱 경쟁이 없어 분산락 불필요 (v1의 락 대기 p99 spike 제거)
```

- v1과의 차이: v1은 60초마다 키가 만료돼 그 순간 모든 요청이 MISS → 락 경쟁.
v2는 만료가 없어 MISS가 "예외 상황"이 됐고, 읽기 경로에서 동시성 장치가 사라졌다.

### ③ 스케줄러 동기화 — `rebuild` (통째 교체, DB가 정답)

```
30초마다 (GlobalFeedCacheSyncScheduler, 조건 없이 무조건):

1. DB에서 최근 20건 SELECT ← DB 스냅샷이 "정답"
2. 임시 키(feed:recent:global:rebuild)에 ZADD ← 본 키는 아직 안 건드림
3. RENAME 임시키 → 본 키 ← 원자적 통째 교체 (Redis 단일 명령)

결과: 캐시 = DB 스냅샷 그대로. 이전 캐시 내용은 통째로 버려진다.
```

**왜 "병합(ZADD)"이 아니라 "덮어쓰기(교체)"인가?**

```
[병합이었다면] 캐시 [A, B, C(DB에서 삭제됨)] + DB [A, B, D]
→ ZADD 병합 → [A, B, C, D] ← 삭제된 C가 영영 잔존 😱
(v1은 TTL 만료가 C를 치웠지만, v2는 만료가 없다)

[교체(현재)] 임시 키에 [A, B, D] 적재 → RENAME → 캐시 = [A, B, D] ✅
```

**왜 "DEL 후 적재"가 아니라 "임시 키 + RENAME"인가?**

```
[DEL 방식] DEL → (빈 캐시 창) → 적재 ← 그 창에 들어온 조회가 전부 MISS → DB행
[RENAME 방식] 임시 키에 다 만들어놓고 → RENAME ← 교체가 원자적, 빈 캐시가 노출되는 순간이 없음
```

**동기화가 복구해 주는 것** (③이 있어서 ①이 최선 노력으로 충분한 이유):
- ①에서 ZADD 실패한 사진 → DB엔 있으므로 다음 교체 때 포함 (≤30초)
- ①에서 콜드라 스킵한 사진 → 동일
- DB에서 삭제/차단된 사진 → 스냅샷에 없으므로 교체 때 제거 (≤30초)
- 알 수 없는 원인의 불일치(이벤트 유실 등) → "DB 스냅샷 통째 교체"라 원인 불문 수렴

**트레이드오프 (덮어쓰기의 대가):**
```
T1 스케줄러: DB SELECT → 스냅샷 [A, B, C]
T2 완료 리스너: 사진 D 커밋 + ZADD → 캐시 [A, B, C, D]
T3 스케줄러: RENAME → 캐시 [A, B, C] ← 방금 넣은 D가 일시적으로 사라짐
T4 (≤30초 뒤) 다음 동기화: DB엔 D가 있으므로 [A, B, C, D] 복구 ✅
```
스냅샷 조회~교체 사이의 write-through가 덮일 수 있지만, DB가 원본이라 다음 주기에 반드시 돌아온다.
"수 초 지연 허용(D2)" 안에서 수용.

### v1 → v2 장치 대응표

| 문제 | v1 장치 | v2 장치 |
|------|---------|---------|
| R1 재적재 race | AFTER_COMMIT | AFTER_COMMIT (동일) |
| R2 dual-write | 짧은 TTL(60초) 자가 치유 | **30초 스케줄러 통째 교체** |
| R3 stampede | single-flight 분산락 | **만료 제거로 원인 소멸** (락 불필요) |
| R5 lost update | 원자 ZADD | 원자 ZADD + **RENAME 원자 교체** |
| 삭제 항목 잔존 | TTL 만료가 청소 | **교체 방식이라 스냅샷에 없으면 제거** |

---

## 7. 단계별 구현 계획 (Phase)
Expand Down Expand Up @@ -559,11 +678,33 @@ DB commit 후 캐시 적재가 실패하면 누락분은 키 만료 후 재적

**[결과]** 60초 주기 만료를 통해, 복구 불가였던 적재 실패 사진이 **최대 60초 내 자동 복구**되도록 개선했다.

> 구현 매핑: TTL 설정은 `GlobalFeedCacheRepository#rebuild`에서만(=재적재 시점), `#addItem`(write-through)은
> 구현 매핑(v1 당시): TTL 설정은 `GlobalFeedCacheRepository#rebuild`에서만(=재적재 시점), `#addItem`(write-through)은
> TTL 미변경 + 콜드 스킵. 재적재 stampede는 `GlobalFeedService#loadWithSingleFlight`(분산락 + 더블체크 + DB 폴백).
>
> ⚠️ 이 구성(v1)은 이후 TS2에서 **TTL 제거 + 스케줄러 동기화(v2)** 로 대체됐다. 락 대기 지연이 이유.

### TS2. single-flight 락 대기로 p99 지연 spike → TTL 제거 + 스케줄러 동기화 전환 (v1→v2)

**[문제]** 홈 화면에 노출되는 피드는 전역 단일 키에 cache-aside 방식으로 캐싱하고 있었고, 조회가 매우 잦았다.
이 상황에서 TTL 만료로 인한 재캐싱 시 cache stampede가 발생했다. 이를 해결하기 위해 분산락으로 한 요청만
재캐싱하도록 했지만, **나머지 읽기 요청이 락 대기에 묶여 약 500 req/s 부하에서 p99 지연이 약 90ms까지 튀었다.**
막는 대상(DB 쇄도)은 막았지만, 만료 주기(TTL)마다 락 대기라는 새 지연원을 만든 셈이다.

**[접근]** 락 대기의 근원은 "주기적 만료 → 전체 동시 MISS"이므로, 만료 자체를 없앴다. write-through는 유지하되
**TTL을 제거해 피드 데이터를 캐시에 상주**시켰다(최근 20건뿐이라 메모리 부담 없음). 만료가 없으니 재캐싱
경쟁이 사라져 분산락도 제거했다. 다만 TTL이 해주던 자가 치유(write-through 실패분 복구, DB 측 변경 반영)가
사라지므로, **30초 주기 스케줄러가 DB 기준으로 캐시를 전체 재적재**해 동기화를 대신 보장한다.

**[결과]** 캐시 만료 시 락 대기를 제거하여, **p99 지연을 약 90ms에서 20ms로 평탄화**했다.
캐시 반영 실패 역시 최대 30초 내 자동으로 복구된다.

### TS2. (예정) 부하 테스트로 stampede 정량 증명
- k6로 조회 부하 → single-flight 제거 시 만료 순간 DB 쿼리 스파이크 측정 → 적용 후 평탄화 비교 (before/after).
> 구현 매핑(v2):
> - 읽기: `GlobalFeedService#getRecentFeed` — 캐시 조회만. MISS는 콜드 스타트/Redis 유실 시에만 발생하며 DB 폴백 + 즉시 워밍.
> - 쓰기: `GlobalFeedWriteThroughListener` → `GlobalFeedCacheRepository#addItem` (AFTER_COMMIT, 원자 ZADD, 콜드 스킵) — v1과 동일.
> - 동기화: `GlobalFeedCacheSyncScheduler` (30초 fixedDelay) → `GlobalFeedService#syncCacheFromDb` → `#rebuild`.
> - `#rebuild`는 기존 키에 병합(ZADD)하지 않고 **임시 키 적재 후 RENAME으로 원자 교체** — TTL이 없어진 뒤로는
> 만료가 "DB에서 사라진 항목"을 청소해 주지 않으므로, 전체 교체로 잔존을 막는다. RENAME이라 교체 순간에도 빈 캐시가 노출되지 않는다.
> - 트레이드오프: 동기화 스냅샷 조회~교체 사이에 write-through된 항목이 일시적으로 덮일 수 있으나, DB에 있으므로 다음 주기(≤30초)에 복구된다.

---

Expand All @@ -572,13 +713,13 @@ DB commit 후 캐시 적재가 실패하면 누락분은 키 만료 후 재적
### ✅ 확정됨
- [x] **개인화 여부 → 전역 단일 피드** (D1)
- [x] **반영 지연 허용치 → 수 초** (D2)
- [x] **무효화 방식 → write-through + 짧은 TTL** (D3), **무효화 시점 → AFTER_COMMIT** (D4)
- [x] **무효화 방식 → write-through + TTL 제거(상주) + 30초 스케줄러 동기화** (D3 v2, TS2), **무효화 시점 → AFTER_COMMIT** (D4)

### ⬜ 아직 정할 것 (다음 협의)
- [ ] **피드 노출 개수 N?** (20개? 50개?) — ZSET trim 기준
- [ ] **사진 정렬 기준?** (완료 시각순 / 인기순 / 랜덤 섞기) — 시각순이면 ZSET score=timestamp로 단순
- [ ] **차단/신고 사진 제외 방식?** — 전역 캐시에 박힌 항목을 어떻게 빼낼지 (무효화 복잡도 ↑)
- [ ] **TTL 구체값?** (D2는 "수 초"로 방향만 확정 → 30초/60초/120초 중 택1)
- [x] ~~TTL 구체값?~~ → **TTL 제거로 무의미해짐** (v2, TS2). 대신 스케줄러 주기 30초로 확정
- [ ] **L1 로컬 캐시 TTL?** (1초? 2초? — hot key 완화 강도)
- [ ] **Outbox 내구성까지 갈지?** (현재는 Phase 3 선택. 누락 0이 정말 필요한가?)
```
Loading
Loading