[아키텍처 설계 명세서] Spring Boot · React 풀스택 다계층 캐시 레이어 아키텍처 설계서 (SAD)

문서 제·개정 이력 (Revision History)

제1장. 설계 개요 및 아키텍처 원칙 (1. Architecture Overview & Principles)

[설계 핵심 정의 (Architecture Blueprint Summary)]: 본 설계서는 React 18 프론트엔드(L0 Browser Memory Cache) → CDN 및 HTTP 프로토콜(L1 Edge/ETag Cache) → Spring Boot 로컬 힙(L2 Caffeine In-Memory Cache) → 분산 메모리 그리드(L3 Redis 7.2 Cluster)로 이어지는 풀스택 4단계(End-to-End Multi-Tier) 캐시 레이어 참조 아키텍처와 실시간 정합성 무효화(Invalidation) 및 장애 격리 메커니즘을 명세함.

1.1 시스템 컨텍스트 및 풀스택 다계층 캐시 흡수 구조 (System Context View)

• 시스템 경계 및 단계별 트래픽 필터링 메커니즘:
  • 사용자 브라우저에서 발생하는 전체 조회 요청의 60~70%는 React TanStack Query 인메모리 캐시(L0)와 CDN/HTTP 304 Not Modified(L1) 계층에서 네트워크 비용 없이 즉시 흡수됨.
  • 백엔드 WAS로 진입한 요청의 90% 이상은 JVM 내부 Caffeine(L2, 응답 ≤ 0.5ms) 및 Redis Cluster(L3, 응답 ≤ 3ms)에서 처리되어, 최종 RDBMS까지는 전체 트래픽의 3~5% 미만만 도달하도록 데이터베이스 부하를 원천 차단함.

1.2 캐시 아키텍처 핵심 설계 원칙 명세 (Architecture Principles Specification)

1.3 비기능 품질 속성 및 목표 SLA/SLO 명세 (Quality Attribute Specification)

제2장. 논리 아키텍처 및 컴포넌트 설계 (2. Logical & Component View)

2.1 React · CDN · Spring Boot(L1/L2) 5계층 캐시 논리 아키텍처 구조도

• 구조 명세: 전체 캐시 아키텍처는 데이터가 위치하는 물리적 거리에 따라 Client & Edge Cache Zone (React/CDN/HTTP) → Spring Boot Tiered Cache Core (L1 Caffeine & SingleFlight) → Distributed Grid & Sync Bus (L2 Redis Cluster & Pub/Sub)의 3대 영역·8개 핵심 컴포넌트(COMP-01 ~ COMP-08)로 구성됨.

2.2 컴포넌트 카탈로그 및 책임 명세표 (Component Specification Catalog)

2.3 백엔드(Spring Boot) 및 프론트엔드(React) 캐시 모듈 표준 패키지 구조

[1] Spring Boot 백엔드 캐시 레이어 표준 패키지 구조
com.company.platform
├── common.cache
│   ├── config
│   │   ├── CacheSpec.java                 # [정책 정의] 캐시 이름별 L1/L2 TTL, MaxSize, Jitter 비율 Enum 명세
│   │   ├── TieredCacheConfig.java         # [COMP-04] Caffeine(L1) + Redis(L2) + CircuitBreaker 빈 조립
│   │   └── HttpCacheHeaderConfig.java     # [COMP-03] ShallowEtagHeaderFilter 및 Cache-Control 인터셉터
│   ├── core
│   │   ├── TieredCacheManager.java        # [COMP-04] Spring CacheManager 커스텀 구현체
│   │   ├── TieredCache.java               # [COMP-04] L1 조회 -> L2 조회(L1 역채움) -> SingleFlight DB 로드
│   │   └── JitterTtlGenerator.java        # [COMP-07] Base TTL ± 15% 랜덤 Jitter 계산기
│   ├── guard
│   │   ├── SingleFlightExecutor.java      # [COMP-06] 동일 키 동시 요청 병합 (Local Future + Distributed Lock)
│   │   └── BloomFilterGuard.java          # [COMP-06] 미존재 ID 캐시 관통(Penetration) 방어 필터
│   └── sync
│       ├── CacheEvictEvent.java           # [COMP-08] 도메인 상태 변경 시 발행되는 내부/PubSub 이벤트 레코드
│       ├── PostCommitCacheEvictor.java    # [COMP-08] @TransactionalEventListener(AFTER_COMMIT) 무효화 처리기
│       └── RedisCacheEvictSubscriber.java # [COMP-08] 전 WAS 파드 L1 Caffeine 동시 무효화 리스너
└── domain.product
    ├── application.dto
    │   └── ProductCacheDto.java           # [AP-01] 캐시 저장 전용 불변 Java Record (JPA @Entity 분리)
    └── application.service
        └── ProductQueryService.java       # @Cacheable(cacheNames = "product:detail", key = "#productId")

[2] React 프론트엔드 캐시 레이어 표준 디렉토리 구조 (TanStack Query v5)
src/
├── app/providers/
│   └── QueryProvider.tsx                  # [COMP-01] QueryClient 전역 설정 (staleTime, gcTime, BroadcastChannel)
├── shared/api/
│   ├── httpClient.ts                      # Axios/Fetch 인스턴스 (ETag / If-None-Match 조건부 요청 헤더 인터셉터)
│   └── sseCacheSync.ts                    # [COMP-08] 백엔드 SSE 캐시 무효화 이벤트 수신 -> queryClient.invalidateQueries
└── entities/product/api/
    ├── productKeys.ts                     # [Query Key Factory] 계층형 쿼리 키 중앙 관리 (오타 및 누락 방지)
    ├── useProductDetailQuery.ts           # 조회 훅 (staleTime: 60_000, placeholderData, prefetch)
    └── useUpdateProductMutation.ts        # 변경 훅 (onMutate 낙관적 업데이트 + onSuccess 캐시 무효화)

제3장. 프로세스 및 런타임 파이프라인 설계 (3. Process & Runtime Sequence View)

3.1 풀스택 캐시 조회(Read Look-aside) 및 쓰기 무효화(Write Invalidation) 8단계 시퀀스

• 동적 실행 흐름:
  • Phase 1 (Read Path: STEP 1 ~ STEP 5): React 컴포넌트가 데이터를 요청하면 L0(TanStack Query) → L1(CDN/HTTP 304) → L2(WAS Caffeine) → L3(Redis Cluster) 순서로 캐시를 확인하며, 전 계층 Miss 시에만 STEP 5(SingleFlight Lock)를 통해 단 1개의 스레드가 DB를 조회하여 상위 캐시를 역순으로 채움(Backfill).
  • Phase 2 (Write & Invalidation Path: STEP 6 ~ STEP 8): 상태 변경(POST/PUT/DELETE) 요청은 DB 트랜잭션이 물리적으로 커밋된 직후(AFTER_COMMIT)에만 L2 Redis 키를 삭제(UNLINK)하고 Redis Pub/Sub으로 전 WAS의 L1 캐시를 즉시 비우며, 클라이언트 측 TanStack Query 캐시를 동기화함.

3.2 단계별 런타임 캐시 처리 규격 및 타임아웃·예외 계약 명세표

제4장. 데이터 및 영속성 아키텍처 설계 (4. Data & Persistence View)

4.1 캐시 키 스키마·직렬화·TTL Jitter 설계 및 전 계층 정합성 동기화 구조도

• 캐시 데이터 뷰 명세: 다계층 캐시 환경에서 가장 치명적인 장애 원인인 배포 시 클래스 스키마 호환성 깨짐(Serialization Conflict), 동시 만료 폭주(Cache Avalanche), WAS 노드 간 로컬 캐시 불일치(Stale L1 Cache)를 해결하기 위한 표준 데이터 스키마 및 동기화 파이프라인을 명세함.

4.2 도메인별 다계층 캐시 정책 및 TTL·크기·무효화 규격 명세표 (Cache Policy Matrix)

제5장. 물리 배포 및 회복탄력성·관측성 설계 (5. Deployment, Resilience & Observability View)

5.1 풀스택 캐시 런타임 토폴로지 및 서킷브레이커·관측성 구조도

• 물리 배치 및 고가용성 명세: 프론트엔드 React SPA와 CloudFront CDN을 거쳐 진입한 트래픽은 Kubernetes/WAS 클러스터 내 Stateless Spring Boot 파드(L1 Caffeine 내장)에서 처리되며, 백엔드 분산 캐시는 3개 가용영역(Multi-AZ)에 걸친 Redis 7.2 Cluster(3 Master + 3 Replica)로 구성되어 단일 노드/AZ 장애 시 자동 Failover를 수행함.

5.2 캐시 스탬피드(Stampede) 방어, 서킷브레이커(Fail-Open) 및 관측성 상세 설계

• 캐시 회복탄력성·메모리 보호·관측성 엔지니어링 파라미터 명세표 (Cache Engineering Specification)

제6장. 표준 인터페이스 및 코드 템플릿 명세 (6. Standard Interface & Code Specification)

6.1 백엔드(Spring Boot) 및 프론트엔드(React) 캐시 레이어 표준 구현 코드 템플릿

• [Template 1] 도메인별 캐시 정책 레지스트리 및 Jitter TTL 계산기 (CacheSpec.java — COMP-04, COMP-07)
  JAVA

  package com.company.platform.common.cache.config;
  
  import java.time.Duration;
  import java.util.concurrent.ThreadLocalRandom;
  import lombok.Getter;
  import lombok.RequiredArgsConstructor;
  
  @Getter
  @RequiredArgsConstructor
  public enum CacheSpec {
      // 캐시명(버전 포함), L1 최대 개수, L1 TTL, L2 기본 TTL, Jitter 비율(0.15 = ±15%)
      COMMON_CODE("v1:common:code", 5_000, Duration.ofMinutes(10), Duration.ofHours(6), 0.15),
      PRODUCT_DETAIL("v1:product:detail", 10_000, Duration.ofSeconds(15), Duration.ofMinutes(30), 0.15),
      USER_PERMISSION("v1:user:perm", 20_000, Duration.ofSeconds(10), Duration.ofMinutes(15), 0.10),
      SEARCH_LIST("v1:search:list", 0, Duration.ZERO, Duration.ofMinutes(3), 0.15); // L1 미사용(0), L2 전용
  
      private final String cacheName;
      private final int l1MaxSize;
      private final Duration l1Ttl;
      private final Duration l2BaseTtl;
      private final double jitterRatio;
  
      public Duration computeL2JitterTtl() {
          long baseMillis = l2BaseTtl.toMillis();
          double factor = 1.0 + ThreadLocalRandom.current().nextDouble(-jitterRatio, jitterRatio);
          return Duration.ofMillis(Math.max(1000L, (long) (baseMillis * factor)));
      }
  }

• [Template 2] L1(Caffeine) + L2(Redis) + SingleFlight 통합 계층형 캐시 (TieredCache.java — COMP-04, COMP-05, COMP-06)
  JAVA

  package com.company.platform.common.cache.core;
  
  import com.github.benmanes.caffeine.cache.Cache;
  import java.util.concurrent.Callable;
  import java.util.concurrent.CompletableFuture;
  import java.util.concurrent.ConcurrentHashMap;
  import lombok.RequiredArgsConstructor;
  import lombok.extern.slf4j.Slf4j;
  import org.springframework.cache.support.AbstractValueAdaptingCache;
  import org.springframework.data.redis.core.RedisTemplate;
  
  @Slf4j
  @RequiredArgsConstructor
  public class TieredCache extends AbstractValueAdaptingCache {
  
      private final String name;
      private final CacheSpec spec;
      private final Cache<Object, Object> l1CaffeineCache; // null if L1 disabled
      private final RedisTemplate<String, Object> l2RedisTemplate;
      private final ConcurrentHashMap<String, CompletableFuture<Object>> inFlightLocks = new ConcurrentHashMap<>();
  
      @Override
      protected Object lookup(Object key) {
          String redisKey = buildRedisKey(key);
          // 1. L1 (Caffeine) 로컬 메모리 조회 (0ms)
          if (l1CaffeineCache != null) {
              Object l1Val = l1CaffeineCache.getIfPresent(key);
              if (l1Val != null) {
                  return l1Val;
              }
          }
          // 2. L2 (Redis Cluster) 분산 캐시 조회 + L1 역채움(Backfill)
          try {
              Object l2Val = l2RedisTemplate.opsForValue().get(redisKey);
              if (l2Val != null) {
                  if (l1CaffeineCache != null) {
                      l1CaffeineCache.put(key, l2Val);
                  }
                  return l2Val;
              }
          } catch (Exception ex) {
              // [AP-05 Fail-Open] Redis 장애 시 예외를 전파하지 않고 DB 조회로 Fallback
              log.warn("[TieredCache] L2 Redis lookup failed for key={}. Falling back to origin.", redisKey, ex);
          }
          return null;
      }
  
      @Override
      @SuppressWarnings("unchecked")
      public <T> T get(Object key, Callable<T> valueLoader) {
          ValueWrapper cached = get(key);
          if (cached != null) {
              return (T) cached.get();
          }
          // 3. [COMP-06 SingleFlight] 핫 키 동시 만료 시 단일 스레드만 DB ValueLoader 실행
          String lockKey = buildRedisKey(key);
          CompletableFuture<Object> future = inFlightLocks.computeIfAbsent(lockKey, k ->
              CompletableFuture.supplyAsync(() -> {
                  try {
                      T loaded = valueLoader.call();
                      put(key, loaded);
                      return toStoreValue(loaded);
                  } catch (Exception e) {
                      throw new ValueRetrievalException(key, valueLoader, e);
                  } finally {
                      inFlightLocks.remove(k);
                  }
              })
          );
          return (T) fromStoreValue(future.join());
      }
  
      @Override
      public void put(Object key, Object value) {
          Object storeVal = toStoreValue(value);
          if (l1CaffeineCache != null) {
              l1CaffeineCache.put(key, storeVal);
          }
          try {
              l2RedisTemplate.opsForValue().set(buildRedisKey(key), storeVal, spec.computeL2JitterTtl());
          } catch (Exception ex) {
              log.warn("[TieredCache] L2 Redis put failed for key={}", key, ex);
          }
      }
  
      public void evictLocalOnly(Object key) {
          if (l1CaffeineCache != null) {
              l1CaffeineCache.invalidate(key);
          }
      }
  
      private String buildRedisKey(Object key) {
          return "prod:commerce:" + name + ":" + key;
      }
  }

• [Template 3] 트랜잭션 커밋 이후(AFTER_COMMIT) L2 삭제 및 Pub/Sub 전 노드 L1 무효화 (PostCommitCacheEvictor.java — COMP-08)
  JAVA

  package com.company.platform.common.cache.sync;
  
  import com.company.platform.common.cache.core.TieredCache;
  import com.company.platform.common.cache.core.TieredCacheManager;
  import lombok.RequiredArgsConstructor;
  import lombok.extern.slf4j.Slf4j;
  import org.springframework.data.redis.core.StringRedisTemplate;
  import org.springframework.stereotype.Component;
  import org.springframework.transaction.event.TransactionPhase;
  import org.springframework.transaction.event.TransactionalEventListener;
  
  @Slf4j
  @Component
  @RequiredArgsConstructor
  public class PostCommitCacheEvictor {
  
      public static final String INVALIDATION_TOPIC = "cache:invalidation:topic";
      private final StringRedisTemplate stringRedisTemplate;
      private final TieredCacheManager tieredCacheManager;
  
      public record CacheEvictEvent(String cacheName, String key) {}
  
      // [AP-02] 반드시 물리 DB 트랜잭션이 성공적으로 커밋된 직후에만 캐시 무효화 수행
      @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
      public void onAfterCommitEvict(CacheEvictEvent event) {
          String redisKey = "prod:commerce:" + event.cacheName() + ":" + event.key();
          try {
              // 1. L2 Redis 비동기 논블로킹 삭제 (DEL 대신 UNLINK 사용)
              stringRedisTemplate.unlink(redisKey);
              // 2. 클러스터 내 모든 WAS 파드의 L1 Caffeine 캐시 동시 제거를 위해 Pub/Sub 브로드캐스트
              String payload = event.cacheName() + "::" + event.key();
              stringRedisTemplate.convertAndSend(INVALIDATION_TOPIC, payload);
          } catch (Exception ex) {
              log.error("[CacheEvictor] Failed to evict L2/PubSub for {}", redisKey, ex);
              // Redis 장애 시에도 현재 노드의 L1 캐시는 즉시 비움
              TieredCache cache = tieredCacheManager.getTieredCache(event.cacheName());
              if (cache != null) cache.evictLocalOnly(event.key());
          }
      }
  }

• [Template 4] React 프론트엔드 TanStack Query v5 계층형 키 팩토리 및 낙관적 업데이트·무효화 훅 (productQueries.ts — COMP-01)
  TYPESCRIPT

  // File: src/entities/product/api/productQueries.ts
  import { QueryClient, useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
  import { httpClient } from '@/shared/api/httpClient';
  
  // 1. [Query Key Factory] 계층적 쿼리 키 표준화 (부분 무효화 및 자동완성 보장)
  export const productKeys = {
    all: ['products'] as const,
    lists: () => [...productKeys.all, 'list'] as const,
    list: (filters: Record<string, unknown>) => [...productKeys.lists(), filters] as const,
    details: () => [...productKeys.all, 'detail'] as const,
    detail: (productId: string) => [...productKeys.details(), productId] as const,
  };
  
  // 2. [L0 Read Hook] staleTime(1분) 동안 네트워크 호출 0회 보장 + ETag 조건부 요청 연동
  export function useProductDetailQuery(productId: string) {
    return useQuery({
      queryKey: productKeys.detail(productId),
      queryFn: async ({ signal }) => {
        const { data } = await httpClient.get(`/api/v1/products/${productId}`, { signal });
        return data.data;
      },
      staleTime: 60 * 1000,       // 1분간 Fresh 상태 유지 (중복 API 호출 원천 차단)
      gcTime: 10 * 60 * 1000,     // 언마운트 후 10분간 가비지 컬렉션 보류
      retry: 1,
    });
  }
  
  // 3. [Write & Invalidation Hook] 낙관적 업데이트(Optimistic UI) 및 관련 캐시 즉시 무효화
  export function useUpdateProductMutation(productId: string) {
    const queryClient = useQueryClient();
  
    return useMutation({
      mutationFn: (payload: { name: string; price: number }) =>
        httpClient.put(`/api/v1/products/${productId}`, payload),
      onMutate: async (newProduct) => {
        await queryClient.cancelQueries({ queryKey: productKeys.detail(productId) });
        const previous = queryClient.getQueryData(productKeys.detail(productId));
        queryClient.setQueryData(productKeys.detail(productId), (old: any) => ({ ...old, ...newProduct }));
        return { previous };
      },
      onError: (_err, _newProduct, context) => {
        if (context?.previous) {
          queryClient.setQueryData(productKeys.detail(productId), context.previous);
        }
      },
      onSettled: () => {
        // 백엔드 AFTER_COMMIT 무효화와 동기화하여 상세 및 목록 캐시 재검증 트리거
        queryClient.invalidateQueries({ queryKey: productKeys.detail(productId) });
        queryClient.invalidateQueries({ queryKey: productKeys.lists() });
      },
    });
  }

제7장. 아키텍처 적합성 검증 및 기술 스택 명세 (7. Architecture Fitness & Tech Stack BOM)

7.1 ArchUnit & ESLint 기반 캐시 아키텍처 적합성 자동 검증 규칙 (Fitness Functions)

모든 백엔드(Spring Boot) 및 프론트엔드(React) 코드는 CI 빌드 단계에서 아래 5대 캐시 아키텍처 적합성 규칙(CACHE-RULE-01 ~ CACHE-RULE-05)을 자동 검증하며, 위반 시 PR 병합이 차단됨.

package com.company.platform.architecture;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.methods;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import jakarta.persistence.Entity;
import org.springframework.cache.annotation.CachePut;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.transaction.annotation.Transactional;

@AnalyzeClasses(packages = "com.company", importOptions = ImportOption.DoNotIncludeTests.class)
public class CacheArchitectureFitnessTest {

    // [CACHE-RULE-01] @Cacheable / @CachePut 메서드는 절대 JPA @Entity를 직접 반환할 수 없음 (불변 DTO/Record 강제)
    @ArchTest
    static final ArchRule CACHE_RULE_01_forbid_caching_jpa_entities_directly =
        methods().that().areAnnotatedWith(Cacheable.class).or().areAnnotatedWith(CachePut.class)
            .should().haveRawReturnType(
                com.tngtech.archunit.base.DescribedPredicate.not(
                    com.tngtech.archunit.core.domain.properties.CanBeAnnotated.Predicates.annotatedWith(Entity.class)
                )
            )
            .because("JPA @Entity 직접 캐싱은 LazyInitializationException 및 프록시 직렬화 오염을 유발하므로 불변 Record DTO만 캐싱해야 함");

    // [CACHE-RULE-02] @Transactional 서비스는 RedisTemplate을 직접 참조하여 동기 삭제/갱신할 수 없음 (AFTER_COMMIT 강제)
    @ArchTest
    static final ArchRule CACHE_RULE_02_transactional_services_must_not_call_redis_directly =
        noClasses().that().resideInAPackage("..application.service..")
            .and().areAnnotatedWith(Transactional.class)
            .should().dependOnClassesThat().haveFullyQualifiedName("org.springframework.data.redis.core.RedisTemplate")
            .because("트랜잭션 롤백 시 캐시 불일치를 막기 위해 캐시 무효화는 반드시 @TransactionalEventListener(AFTER_COMMIT)에서 수행해야 함");
}

7.2 전사 표준 풀스택 캐시 기술 스택 명세서 (Standard Cache Layer BOM)