[REDIS-01] FeatureFlag Redis 키·pub/sub 채널 계약
작업 내용 (설계 의도)
변경 사항
BE-03(캐시·pub/sub 구현)이 착수 전에 소비할 Redis 키/채널/TTL 계약을 private-redis-convention 형식으로 명문화한다(senior-pm 정합 #4 — 유령 참조 제거). 근거 TDD: ../TDD.md “방안 비교 — 변경 전파”·Observability. 키 설계·TTL·채널 계약 문서 산출까지가 이 티켓의 범위이며, RedisTemplate·Config 등 앱 코드는 BE-03(be-implementer)이 작성한다.
캐시 키 계약 (look-aside)
| 항목 | 값 |
|---|---|
| 키 패턴 | featureflag:flag:{flagKey} |
| 자료구조 | String (JSON 직렬화된 FeatureFlagSnapshot) — 단일 플래그 원자 read/write, Hash 불필요 |
| TTL | 600초(10분) — pub/sub가 1차 무효화 수단이고 TTL은 안전망(유실 대비 상한) |
| 무효화 트리거 | 플래그 생성/수정/아카이브 시 쓰기 인스턴스가 put(갱신) → 채널 broadcast. TTL은 보조 |
| 스캔 | KEYS 금지. 부트스트랩 전체 로드는 MySQL findAllActive 사용(캐시 인덱스 Set 불필요) |
| 예시 값 | {"key":"demo.feature.hello","type":"RELEASE","status":"ACTIVE","strategy":{"strategyType":"GLOBAL_TOGGLE","enabled":true},"description":"demo"} |
pub/sub 채널 계약
| 항목 | 값 |
|---|---|
| 채널 | featureflag:changes |
| 전달 보장 | 유실 허용(pub/sub) — 유실분은 각 인스턴스 @Scheduled(30초) 전체 리프레시가 수렴. 유실 불가 요건 아니므로 Stream 불필요 |
| 메시지 | 변경된 flagKey(String) + 변경 occurredAt(ISO-8601, 전파 지연 측정용). 최소 payload |
| 구독자 동작 | 수신 시 해당 key 재조회 후 로컬 덮어쓰기(멱등). occurredAt→수신 시각차를 전파 지연으로 기록 |
서버 설정 (docker compose)
- 캐시+pub/sub 혼용이나 세션/락과 키스페이스 공유 — eviction은 기존 compose 정책 유지(신규 요구 없으면 변경 없음). pub/sub는 메모리 상주 아님(전달 즉시 소멸).
- pub/sub 리스너는 인스턴스마다 전용 구독 커넥션 1개 추가 — 다중 인스턴스 스케일아웃 시 선형 증가(NFR·Observability BE-12 게이지로 모니터).
롤백
계약 문서 산출물(코드 아님)이라 롤백 대상 없음. 채널명/키 네임스페이스 변경은 파괴적 변경(마이그레이션 계획 필요) — 초기 확정으로 회피.
의존
- 없음 (인프라 선행 계약 — BE-03이 이 계약을 병행 선행으로 참조)
검증 케이스
- 로컬 Redis에
featureflag:flag:demo.feature.hello를 넣고TTL이 600초 이하로 설정됨을 redis-cli로 확인한다 SUBSCRIBE featureflag:changes상태에서PUBLISH featureflag:changes "demo.feature.hello"시 수신됨을 재현한다- 예시 snapshot JSON이 String 값으로 저장/조회 round-trip된다
KEYS없이 특정 key 조회(GET)만으로 평가 캐시가 동작함을 확인한다(스캔 미사용)