AI 뉴스 기반 주식 추천 서비스(StockAI)에서 조회 속도 저하 문제를 분석하고, BE(Spring Boot) + FE(Next.js) 전체 스택에 걸쳐 13개 최적화 항목을 도출. 순차적 병목 → 병렬화, 2왕복 → 1왕복, 중복 요청 → 캐시 재사용 등의 원칙으로 접근.

1. 국내 주식 배치 가격 조회: 순차 → 병렬

Before

StockPriceBatchService.processChunk()
├─ stockCode[0]: cache miss → KIS API → 125ms
├─ stockCode[1]: cache miss → KIS API → 125ms
├─ stockCode[2]: cache miss → KIS API → 125ms
├─ ... (50개 순차 대기)
└─ stockCode[49]: cache miss → KIS API → 125ms
총 소요: ~6.25초

• Semaphore(10), RateLimiter(8.0/sec)로 동시성 제어는 있으나 for문 안에서 순차 acquire() 후 동기 호출
• 해외 주식(OverseasStockPriceBatchService)은 이미 @Async + CompletableFuture 병렬 패턴인데 국내만 누락

After

StockPriceBatchService.processChunk()
├─ 1차: 캐시 조회 (cache hit 즉시 반환)
└─ 2차: cache miss 항목만 CompletableFuture.allOf() 병렬 dispatch
    ├─ Future[0]: @Async → KIS API
    ├─ Future[1]: @Async → KIS API
    ├─ ... (Semaphore=10, 최대 10개 동시)
    └─ Future[49]: @Async → KIS API
총 소요: ~6.25초 (50개 ÷ 8 TPS), 하지만 스레드는 블록하지 않음

핵심 인사이트

• 동시성 제어 도구(Semaphore, RateLimiter)와 호출 방식(동기/비동기)은 독립적 — 제어 도구가 있다고 병렬이 되는 건 아님. @Async + CompletableFuture로 스레드에 작업을 분산해야 Semaphore가 의미 있음
• RateLimiter 초당 8건 제약이 병목 → 50건 처리에 최소 50÷8 ≈ 6.25초 필요. Semaphore=10으로 10개 스레드가 동시에 acquire()해도 RateLimiter가 8 TPS로 직렬화하므로, 시간 단축은 RateLimiter 한도 완화 전제
• 병렬화의 진짜 이점은 스레드 블록 해제 — 순차 코드에서는 호출 스레드가 6.25초 내내 점유되지만, @Async에서는 Future를 반환 후 스레드가 즉시 해제됨

효과

2. OAuth WebClient: 매번 생성 → 싱글톤 재사용

Before

private WebClient getOAuthClient() {
    return WebClient.builder()
            .baseUrl(kisConfig.getOauthUrl())
            .build();  // 매 호출 시 새 인스턴스
}

• WebClient.builder().build()는 내부적으로 새 Reactor Netty ConnectionProvider 생성
• 커넥션 풀 생성 비용 + TCP handshake + SSL 협상이 매 토큰 갱신마다 발생
• KIS 토큰은 하루에도 수십 번 갱신 가능 (TTL 만료, 회수 등)

After

// WebClientConfig.java
@Bean("kisOAuthWebClient")
public WebClient kisOAuthWebClient(KisConfig kisConfig) {
    HttpClient httpClient = HttpClient.create()
            .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)
            .responseTimeout(Duration.ofSeconds(5));
    return WebClient.builder()
            .baseUrl(kisConfig.getOauthUrl())
            .clientConnector(new ReactorClientHttpConnector(httpClient))
            .build();
}

핵심 인사이트

• WebClient는 무상태(stateless)이지만 내부 ConnectionProvider는 상태ful — build()마다 새 커넥션 풀이 생성되고, 기존 풀의 커넥션은 close되지 않은 채 방치됨 (메모리 leak 가능)
• Spring에서 HTTP 클라이언트 Bean은 반드시 싱글톤으로 관리해야 커넥션 재사용이 가능
• 위 코드에서는 명시적 ConnectionProvider 없이 HttpClient.create()를 사용하므로 기본 풀(무제한 idle)이 적용됨 — Section 3의 커넥션 풀 설정을 OAuth용 WebClient에도 동일하게 적용해야 stale connection 문제가 발생하지 않음

효과

3. WebClient 커넥션 풀 설정

Before

Reactor Netty 기본 ConnectionProvider:
- maxConnections: 500 (ConnectionProvider.pool 생성 시)
- maxIdleTime: 무한 (idle 커넥션 정리 없음)
- maxLifeTime: 무한
- evictInBackground: 없음

• 500개 커넥션이 필요 없는 서비스인데 기본값 사용
• idle 커넥션이 영구 생존 → DB/대상 서버에서 timeout이 발생해도 클라이언트는 모름 → stale connection 에러

After

ConnectionProvider provider = ConnectionProvider.builder("kis-pool")
    .maxConnections(100)
    .pendingAcquireMaxCount(500)
    .pendingAcquireTimeout(Duration.ofSeconds(10))
    .maxIdleTime(Duration.ofSeconds(30))
    .maxLifeTime(Duration.ofSeconds(60))
    .evictInBackground(Duration.ofSeconds(30))
    .build();

핵심 인사이트

• maxIdleTime과 maxLifeTime의 차이 — idleTime은 마지막 사용 후 경과, lifeTime은 커넥션 생성 후 경과. 둘 다 설정해야 오래된 커넥션이 정리됨
• evictInBackground는 별도 스레드에서 주기적으로 정리. 없으면 커넥션이 다음 요청 시점에야 close됨
• KIS API는 1초당 8건 제한이므로 100개 커넥션으로 충분. 과도한 풀 크기는 리소스 낭비

효과

4. 카탈로그 + 가격 통합: 2왕복 → 1왕복

Before

FE (Server Component)
  ├─ 1st: GET /api/stocks?page=0 → 종목 목록 [{stockCode, name, sector...}]
  │         응답에 가격 없음 (또는 캐시에 없으면 withoutPrice)
  └─ 2nd: POST /api/stocks/prices → {005930: {price:...}, 000660: {price:...}}
            ↑ 1st 응답의 stockCode 목록이 필요 → 반드시 순차

왕복: 2회 (waterfall)

• BE에 이미 StockCatalogWithPriceResponse DTO와 enrichWithPrice() 메서드가 존재
• But 캐시에 없는 가격은 withoutPrice로 반환 → FE가 별도 batch 호출 필수

After

FE (Server Component)
  └─ 1st: GET /api/stocks?page=0 → {stockCode, name, sector, price, changeRate...}
           enrichWithPrice()에서 캐시 miss 시 StockPriceService로 실시간 조회
           (조회 결과는 @Cacheable에 의해 캐시에도 저장됨)

왕복: 1회

핵심 인사이트

• Backend-Driven Enrichment 원칙 — 클라이언트가 조합해야 할 데이터는 서버에서 미리 합쳐서 반환하는 것이 네트워크 왕복을 줄이는 근본적 해결책
• enrichWithPrice()에서 “캐시에 없으면 빈 값 반환”은 안전하지만 비효율적 — 실시간 조회로 채워도 @Cacheable에 의해 후속 요청은 캐시 hit가 됨
• 다수의 cache miss가 한꺼번에 발생할 수 있으므로 배치 병렬화 선행 필수

효과

5. HikariCP 커넥션 풀 튜닝

Before

Spring Boot 기본 HikariCP:
- maximumPoolSize: 10
- minimumIdle: 10
- connectionTimeout: 30000ms (30초)
- leakDetectionThreshold: 0 (비활성)

• 10개 풀로 고부하 시 커넥션 대기 발생 가능
• 30초 타임아웃은 너무 김 → 장애 시 장시간 응답 지연
• 커넥션 누수 감지 없음

After

spring.datasource.hikari:
  maximum-pool-size: 20
  minimum-idle: 5
  idle-timeout: 300000       # 5분
  max-lifetime: 600000       # 10분
  connection-timeout: 5000   # 5초
  leak-detection-threshold: 10000  # 10초

핵심 인사이트

• maximumPoolSize는 “동시 연결 수”가 아니라 “풀의 최대 크기” — 10개가 다 사용 중이면 11번째 요청은 대기. 서비스의 동시 DB 쿼리 수(동시 가격 조회 + 카탈로그 + 인증 등)를 기준으로 설정해야 함
• connection-timeout=5000은 “5초 내 커넥션 획득 실패 시 예외” → 30초 동안 스레드가 블록되는 것 방지
• leak-detection-threshold=10000은 커넥션을 10초 이상 반납하지 않으면 WARN 로그 → 버그 조기 발견
• max-lifetime=10분은 MySQL wait_timeout(기본 28800초=8시간)보다 짧게 설정하는 원칙에는 맞으나, 지나치게 공격적 — 풀 전체 커넥션이 10분마다 교체되어 불필요한 TCP 재연결 발생. 보통 5~30분 사이가 적절하며, MySQL의 wait_timeout과 interactive_timeout을 확인 후 그보다 2~3분 짧게 설정하는 것이 권장됨

효과

6. Balance/Summary 중복 호출 통합

Before

GET /api/account/balance       → kisApiClient.getBalance() → output1
GET /api/account/balance/summary → kisApiClient.getBalance() → output2
                                                          ↑ 같은 KIS API 2회 호출

• 클라이언트가 두 API를 연속 호출하면 동일한 KIS API 요청이 2번 발생
• KIS API는 초당 호출 제한이 있어 중복 호출이 제한 소모

After

getBalanceFull() → kisApiClient.getBalance() 1회 호출
  ├─ getBalance():      캐시된 응답에서 output1 추출
  └─ getBalanceSummary(): 캐시된 응답에서 output2 추출

핵심 인사이트

• 같은 외부 API를 여러 서비스 메서드에서 호출할 때 캐시 또는 통합이 필요 — 응답의 다른 부분(output1 vs output2)만 필요하더라도, 요청 자체는 동일하므로 1회만 호출
• KIS API의 getBalance()는 무거운 호출 (잔고 전체 조회). TTL 10초 캐시면 충분 (실시간성 요구 낮음)

효과

7. DB 인덱스: sector 단일 컬럼

Before

-- 복합 인덱스만 존재
CREATE INDEX idx_stocks_market_type_sector ON stocks (market_type, sector);

-- findBySector() 쿼리:
SELECT * FROM stocks WHERE sector = '반도체'
-- → 복합 인덱스의 선행 컬럼(market_type)이 조건에 없으므로 인덱스 미사용 → Seq Scan

After

CREATE INDEX idx_stocks_sector ON stocks (sector);

핵심 인사이트

• 복합 인덱스의 최 좌선 원칙(Leftmost Prefix Rule) — (A, B) 인덱스는 WHERE A=?와 WHERE A=? AND B=?에만 사용 가능. WHERE B=?는 인덱스를 타지 않음
• 단일 컬럼 인덱스 추가는 디스크 공간을 약간 차지하지만, 필터 전용 쿼리의 성능은 극적으로 개선

효과

8. Circuit Breaker Fallback: 장애 전파 → Graceful Degradation

Before

private StockPriceResponse getStockPriceFallback(Exception e) {
    throw new RuntimeException("Circuit open");  // 호출부로 예외 전파
}

• CB가 열리면 모든 가격 조회가 500 에러
• 프론트엔드는 에러 표시 또는 빈 값

After

private StockPriceResponse lastGoodResponse;  // 마지막 정상 응답 캐시

private StockPriceResponse getStockPriceFallback(Exception e) {
    StockPriceResponse response = new StockPriceResponse();
    if (lastGoodResponse != null) {
        response = lastGoodResponse;           // stale data라도 반환
        response.setError("CIRCUIT_OPEN_STALE");
    } else {
        response.setError("CIRCUIT_OPEN");
    }
    return response;
}

핵심 인사이트

• Circuit Breaker의 목적은 “장애 격리” — fallback에서 예외를 throw하면 격리가 아니라 형태만 바뀐 장애 전파
• 호출부가 이미 error 필드를 체크하는 구조(if (price.getError() == null))라면, fallback이 에러 DTO를 반환하는 것이 자연스러운 흐름
• 사용자는 “일시적 오류” 메시지를 보는 대신 “가격 정보 없음”으로 부드럽게 저하
• Stale Data 전략 — CB가 열리기 직전의 마지막 정상 응답을 반환하면, 사용자는 0이나 빈 값 대신 “마지막으로 확인된 가격”을 볼 수 있어 UX가 크게 개선됨. 단, 데이터가 오래될 수 있으므로 FE에서 error 필드로 표시 필요

효과

9. FE 카탈로그 Waterfall 제거

Before

Server Component:
  const catalog = await getStocks(...)      // ~200ms
  const prices = await getBatchPrices(codes) // ~6s (전체 cache miss 시)
  // 총: ~6.2초 (순차)

After

Server Component:
  const catalog = await getStocks(...)  // 이미 가격 포함 (~200ms + 실시간 조회)
  const prices = catalog에서 추출       // 0ms (추출만)
  // 총: ~200ms (캐시 hit) or ~1.5s (miss)

핵심 인사이트

• Server Component에서의 waterfall은 TTFB에 직접 영향 — CSR에서는 병렬 useSWR이 가능하지만, SSR에서는 await의 순차 실행이 불가피
• 해결책은 “FE에서 병렬화”가 아니라 “BE에서 합쳐서 보내기” — 근원적 해결
• 후속 페이지(infinite scroll)의 delta 조회는 유지: SSR은 첫 페이지만 담당

효과

10. TradePanel raw fetch → SWR 전환

Before

useEffect(() => {
  getHoldings().then(setUserHolding).catch(...);
}, [isAuthenticated, stockCode]);
// 페이지 이동 시마다 재요청, dedup 없음

After

const { data: holdings } = useSWR(
  isAuthenticated ? 'user-holdings' : null,
  getHoldings,
  { dedupingInterval: 5000 }
);
// 동일 key면 dedup, Dashboard와 캐시 공유

핵심 인사이트

• raw fetch + useEffect는 SWR의 dedup, 캐시, 재검증 이점을 모두 포기하는 것 — 동일한 API를 다른 컴포넌트에서 다른 전략으로 호출하면 중복 요청 발생
• SWR key를 통일하면 여러 컴포넌트가 같은 캐시를 공유 → 네트워크 요청 1회로 N개 컴포넌트 업데이트

효과

11. 렌더 중 dispatch → useEffect

Before

if (deltaPrices) {
  dispatch({ type: 'merge', prices: deltaPrices });
}
// 렌더 함수 본문 내에서 state 변경 → React가 두 번 렌더링함

• SWR이 deltaPrices를 갱신 → 리렌더 1회 + dispatch로 reducer 상태 변경 → 리렌더 1회 = 동일 데이터에 2회 렌더

After

useEffect(() => {
  if (deltaPrices) dispatch({ type: 'merge', prices: deltaPrices });
}, [deltaPrices]);

핵심 인사이트

• React에서 렌더 중 state 변경은 “바로 다시 렌더”를 트리거 — useEffect는 렌더 완료 후 실행되므로, SWR 갱신 → 리렌더(데이터 반영) → useEffect에서 dispatch → 리렌더(가격 반영)이 되지만, 첫 리렌더에서 이전 가격을 보여주므로 깜빡임이 줄어듦
• 더 근본적으로는 accumulatedPrices를 useMemo로 계산하면 dispatch 없이 합성 가능:

const accumulatedPrices = useMemo(() => {
  const merged = { ...initialPrices };
  if (deltaPrices) Object.assign(merged, deltaPrices);
  return merged;
}, [initialPrices, deltaPrices]);

이렇게 하면 reducer와 dispatch를 완전히 제거할 수 있으며, 리렌더도 SWR 갱신 시 1회만 발생함

효과

12. Price Badge retry 범위 축소

Before

mutate(
  (key) => Array.isArray(key) && key[0] === 'batch-prices',
  undefined,
  { revalidate: true }
);
// → batch-prices로 시작하는 모든 SWR key 재검증

• 1개 종목 에러 → 전체 배치 재요청

After

// 해당 종목 단건 API로 대체
const retryPrice = await getStockPrice(stockCode);

핵심 인사이트

• SWR mutate의 필터 매칭은 편리하지만 비용이 큼 — prefix 매칭으로 수십 개 key를 재검증하면, 정상 가격까지 불필요하게 다시 fetch
• 에러 발생 종목만 단건 API로 조회하는 것이 네트워크 비용 최소

효과

13. 캔들 데이터 SWR 전환

Before

const [state, dispatch] = useReducer(reducer, initialState);

const fetchCandleData = useCallback(() => {
  dispatch({ type: 'FETCH_START' });
  getDailyCandles({...}).then(d => dispatch({type:'FETCH_CANDLES_SUCCESS', payload: d}));
}, [...]);

useEffect(() => { fetchCandleData(); }, [fetchCandleData]);

After

const { data: candles, isLoading: candlesLoading } = useSWR(
  stockCode ? ['daily-candles', stockCode, period, startDate, endDate] : null,
  () => getDailyCandles({stockCode, period, startDate, endDate}),
  { revalidateOnFocus: false }
);

const { data: minuteCandles } = useSWR(
  viewMode === 'minute' && stockCode ? ['minute-candles', stockCode] : null,
  () => getMinuteCandles(stockCode),
  { revalidateOnFocus: false }
);

핵심 인사이트

• 로딩/에러/데이터 상태 관리는 SWR이 이미 제공 — useReducer로 직접 관리하면 코드 중복 + 버그 가능성 증가
• SWR key에 파라미터를 포함하면 파라미터 변경 시 자동 재요청 → useCallback 의존성 관리 불필요
• viewMode === 'minute' 조건부 key(null이면 fetch 안 함)로 불필요한 API 호출 방지

효과

종합 효과 요약

핵심 교훈 3가지

1. 서버에서 합쳐서 보내면 클라이언트 waterfall은 사라진다 — FE 최적화보다 BE 응답 구조 개선이 근본적
2. 동시성 제어 ≠ 병렬 처리 — Semaphore와 RateLimiter는 제한일 뿐, @Async가 있어야 스레드가 분산됨
3. 캐시 전략은 “miss 시 어떻게 채울 것인가”까지 설계해야 한다 — hit만 최적화하면 miss 경로가 새 병목이 됨

추가 고려 항목

14. Cache Stampede 방지

다수의 cache miss가 동시에 발생하면, 여러 스레드가 동일 키에 대해 외부 API를 중복 호출함.

// @Cacheable만 사용 시: 10개 스레드가 동시에 getStockPrice("005930") 호출 → KIS API 10회
// 해결: @Cacheable + CacheLoader 또는 stampede guard
@Cacheable(value = "stockPrice", key = "#stockCode", sync = true)
public StockPriceResponse getStockPrice(String stockCode) { ... }

• Spring의 sync = true는 같은 키에 대해 1개 스레드만 로드하고 나머지는 대기 → 중복 API 호출 방지
• 대규모 트래픽에서는 분산 락(Redis) 또는 Caffeine의 RefreshAfterWrite도 고려

15. FE Error Boundary 적용

CB fallback이 정상 응답을 반환하더라도, FE 렌더링 중 예외(예: stale data의 null 필드 접근)가 발생하면 전체 페이지가 깨질 수 있음.

<ErrorBoundary fallback={<StockCardSkeleton />}>
  <StockCard stock={stock} />
</ErrorBoundary>

• 개별 종목 카드 단위로 Error Boundary를 감싸면, 한 종목의 렌더 에러가 전체 목록에 영향을 주지 않음
• SSR에서는 Next.js의 error.tsx로 페이지 레벨 대응

이 글에서 반복해서 등장하는 세 가지 개념을 먼저 정리한다.

• SSR (Server-Side Rendering): 서버에서 HTML을 완성해 브라우저에 보내는 방식. 클라이언트가 빈 화면을 보지 않고 곧바로 콘텐츠를 볼 수 있다. 단, 서버가 데이터를 가져와야 하므로 응답 자체가 느려질 수 있다.
• ISR (Incremental Static Regeneration): 정적 페이지를 빌드한 뒤 일정 시간(revalidate)이 지나면 백그라운드에서 다시 생성하는 방식. 매 요청마다 서버가 일할 필요 없으므로 응답이 빠르고, 캐시 만료 시에만 갱신된다.
• Delta 조회: 이미 가지고 있는 데이터는 다시 요청하지 않고, 새로 필요한 데이터만(DELTA) 조회하는 방식. 전체 재조회를 피해 API 호출 횟수를 크게 줄일 수 있다.

문제 상황

주식 전체조회 페이지(/stocks, /overseas-stocks) 접속 시 체감 속도가 느렸다. 페이지 구성에 3개의 API가 호출되는데, 이 호출들이 직렬 워터폴로 동작하고 있었고, 스크롤로 추가 페이지를 로드할 때마다 이미 받은 데이터까지 전부 재조회하는 구조적 문제가 있었다.

원인 분석

1. SSR → Client Hydration 직렬 워터폴

SSR: getStocks(page=0)         ──→ HTML 전송 ──→ Hydration ──→ useEffect ──→ getBatchPrices()
     [200~500ms]                                    [100~300ms]              [200~500ms]

SSR에서 종목 목록만 가져오고, 시세는 클라이언트 마운트 후에야 요청된다. 시세 요청은 SSR 완료 → HTML 전송 → Hydration → useEffect 실행 이후에야 시작되므로 최소 1왕복 시간이 낭비된다.

2. 스크롤 시 전체 재조회 (O(N²) 폭발)

기존에는 SWR 키를 전체 종목코드를 join한 문자열로 생성했다:

const stableKey = stockCodes.slice().sort().join(',');
useSWR(['batch-prices', stableKey], () => getBatchPrices(stockCodes));

페이지가 추가될 때마다 stableKey가 변경 → SWR이 새 요청으로 인식 → 이미 받은 종목까지 전부 재조회:

5페이지까지 로드하면 15번 chunk 요청이 발생하지만, 실제로는 5번이면 충분하다. accumulatedPrices 상태가 있었지만 batchPrices ?? accumulatedPrices에서 batchPrices가 우선하여 재조회를 막지 못했다.

3. BATCH_CHUNK_SIZE = 20이 너무 작음

100개 종목이면 5번의 POST 요청이 동시 발생. 백엔드 부하 시 429 에러 → 지수 백오프 재시도(최대 10.5초)가 연쇄 발생.

4. force-dynamic으로 매 요청마다 백엔드 히트

export const dynamic = 'force-dynamic'으로 ISR 캐시 없이 매번 백엔드 호출.

5. fetcher 재시도 3회 + 403 포함

재시도 상태코드에 403이 포함되어 있었고, 최대 3회 재시도로 10.5초까지 대기 가능.

적용한 개선

P0: Delta 시세 조회

핵심 변경: 이미 가진 시세는 재조회하지 않고, 신규 종목만 API 호출.

// Before: 전체 종목을 매번 조회
useSWR(['batch-prices', stableKey], () => getBatchPrices(stockCodes));

// After: accumulatedPrices에 없는 종목만 delta 조회
const newCodes = stockCodes.filter((code) => !accumulatedPrices[code]);
useSWR(['batch-prices-delta', deltaKey], () => getBatchPrices(newCodes));

상태 관리는 useReducer로 변경하여 filter 변경 시 reset, delta 데이터 도착 시 merge:

type PriceAction =
  | { type: 'reset'; prices: Record<string, MappedStockPrice> }
  | { type: 'merge'; prices: Record<string, MappedStockPrice> };

function priceReducer(state, action) {
  switch (action.type) {
    case 'reset': return action.prices;
    case 'merge':  return { ...state, ...action.prices };
  }
}

효과: 스크롤 시 API 호출이 페이지당 1회로 고정. 5페이지 기준 15회 → 5회 (67% 감소).

P0: SSR에서 시세 함께 프리페치

// Before: SSR에서 카탈로그만 fetch
initialData = await getStocks({ page: 0, size: 20, ... });

// After: 카탈로그 + 시세를 SSR에서 연속 fetch 후 prop 전달
initialData = await getStocks({ page: 0, size: 20, ... });
if (initialData.content.length > 0) {
  const codes = initialData.content.map((item) => item.stockCode);
  initialPrices = await getBatchPrices(codes);
}

initialPrices prop을 클라이언트 컴포넌트에 전달하여, 첫 화면 로드 시 Hydration 대기 없이 시세 표시.

효과: 클라이언트 워터폴 1단계 제거, 첫 화면 시세 로딩 시간 약 500ms~1s 단축.

P1: BATCH_CHUNK_SIZE 20 → 50

// Before
const BATCH_CHUNK_SIZE = 20;
// After
const BATCH_CHUNK_SIZE = 50;

효과: 100개 종목 기준 5회 → 2회 POST 요청 (60% 감소).

P1: ISR 도입

// Before
export const dynamic = 'force-dynamic';
// After
export const revalidate = 30;

30초간 캐시된 페이지를 서브. 종목 목록은 자주 변하지 않으므로 30초면 충분.

효과: 대부분의 사용자가 캐시된 SSR 페이지를 받아 백엔드 호출 생략.

P2: fetcher 재시도 축소

// Before: retries = 3, retryable = [403, 429, 502, 503]
export async function fetcher<T>(url, init, retries = 3) { ... }
const retryable = [403, 429, 502, 503];

// After: retries = 1, retryable = [429, 502, 503]
export async function fetcher<T>(url, init, retries = 1) { ... }
const retryable = [429, 502, 503];

403은 권한 문제이므로 재시도 무의미. 최대 대기 10.5초 → 1.5초로 단축.

P2: Context 리렌더 최적화

BatchPriceProvider의 value와 hook 반환값에 useMemo 적용:

// Provider value 메모이제이션
const value = useMemo(
  () => ({ domestic, overseas, loadingCodes, errorCodes }),
  [domestic, overseas, loadingCodes, errorCodes]
);

// 개별 hook 반환값 메모이제이션
export function useBatchDomesticPrice(stockCode: string) {
  const ctx = useContext(BatchPriceContext);
  const data = ctx.domestic[stockCode];
  const isLoading = ctx.loadingCodes.has(stockCode);
  const error = ctx.errorCodes.get(stockCode);
  return useMemo(() => ({ data, isLoading, error }), [data, isLoading, error]);
}

효과: 다른 종목의 시세 업데이트 시 관련 없는 카드 컴포넌트의 불필요한 리렌더 방지.

Lint 트러블슈팅

초기에 useRef로 accumulated prices를 관리하려 했으나, React 19의 react-hooks/refs 린트 규칙에 의해 “Cannot access refs during render” 에러 발생. 렌더 중 ref 읽기/쓰기를 금지하는 규칙.

useState + useEffect 조합도 react-hooks/set-state-in-effect 규칙에 걸림.

최종적으로 useReducer 를 사용하여:

• filter 변경 시 → dispatch({ type: 'reset' })
• delta 데이터 도착 시 → dispatch({ type: 'merge' })

state 업데이트가 reducer에서 이루어지므로 린트 에러 없이 안전하게 동작.

BE 개선이 추가로 필요한 부분

FE 개선만으로 상당한 효과를 얻었지만, 근본적 해결을 위해서는 BE 개선도 필요:

핵심 교훈

1. SWR 키 설계가 성능을 결정한다: 전체 데이터를 join한 키는 추가 로드마다 전체 재조회를 유발. Delta 기반 키 설계가 필수.
2. SSR 프리페치는 체감 속도에 결정적: 클라이언트에서만 fetch하면 Hydration 대기시간이 반드시 발생.
3. useReducer가 렌더 중 상태 업데이트의 안전한 대안: useRef는 렌더 중 접근 불가, useState + useEffect는 린트 에러. useReducer의 dispatch는 안전.
4. ISR로 SSR 부하 감소: force-dynamic은 매 요청마다 백엔드 호출. 실시간성이 덜 중요한 목록 페이지는 revalidate로 충분.

오늘은 Harness, CLAUDE.md, AGENTS.md가 각각 어떤 역할을 하는지 정리해봤다.

처음 이름만 보면 셋 다 작업을 더 효율적으로 도와주는 무언가처럼 느껴진다. 하지만 실제로는 다루는 대상도 다르고, 사용되는 맥락도 분명히 다르다.

• Harness는 소프트웨어를 안전하게 배포하기 위한 운영 플랫폼이다.
• CLAUDE.md는 AI에게 프로젝트 규칙을 알려주는 문서다.
• AGENTS.md는 AI의 역할 분담과 작업 흐름을 정의하는 문서다.

즉, Harness는 실제 서비스 전달 과정을 다루는 도구이고, CLAUDE.md와 AGENTS.md는 AI가 프로젝트 안에서 더 정확하고 일관되게 작업하도록 돕는 가이드 문서라고 이해하면 된다.

Harness란

Harness는 빌드, 테스트, 배포, 검증, 롤백 같은 과정을 자동화하고 관리하는 플랫폼이다.

개발에서는 코드를 작성하는 것만으로 일이 끝나지 않는다. 작성한 코드가 실제 운영 환경까지 안전하게 전달되어야 하고, 그 과정에서 문제가 생기면 빠르게 감지하고 되돌릴 수 있어야 한다. 이때 필요한 것이 바로 배포 흐름의 자동화다.

예전에는 사람이 직접 서버에 접속해서 명령어를 실행하거나, 배포 순서를 기억해서 수동으로 진행하는 경우가 많았다. 하지만 서비스 규모가 커질수록 이런 방식은 실수 가능성이 높고, 같은 작업을 반복하더라도 품질을 일정하게 유지하기 어렵다. Harness는 이 과정을 파이프라인으로 정의해 누가 실행하더라도 같은 절차와 기준으로 배포가 이루어지게 돕는다.

왜 필요한가

서비스를 배포할 때는 보통 다음과 같은 흐름이 필요하다.

1. 빌드
2. 테스트
3. 배포
4. 배포 후 검증
5. 장애 발생 시 롤백

이 과정을 전부 사람이 수동으로 처리하면 몇 가지 문제가 생긴다.

• 실수가 발생하기 쉽다.
• 배포 속도가 느려진다.
• 팀원마다 방식이 달라 일관성이 깨질 수 있다.
• 문제가 발생했을 때 원인 추적과 복구가 어려워진다.

결국 배포는 단순히 애플리케이션을 서버에 올리는 작업이 아니라, 서비스 품질을 유지하기 위한 운영 절차의 일부라고 볼 수 있다. Harness는 바로 이 절차를 자동화하고 표준화하는 데 초점이 맞춰져 있다.

핵심 특징

1. 자동화
   • 코드 변경 이후 빌드, 테스트, 배포를 자동으로 실행할 수 있다.
2. 안정성
   • 배포 중 이상이 감지되면 중단하거나 이전 버전으로 롤백할 수 있다.
3. 표준화
   • 팀 전체가 동일한 배포 절차를 공유할 수 있다.
4. 가시성
   • 현재 배포가 어느 단계에 있는지, 어디서 실패했는지 확인하기 쉽다.

예시로 보면

예를 들어 쇼핑몰 서비스의 결제 기능을 수정했다고 가정해보자. 개발자가 코드를 main 브랜치에 머지하면 아래와 같은 흐름이 자동으로 실행될 수 있다.

1. 애플리케이션 빌드
2. 자동 테스트 실행
3. 스테이징 서버 배포
4. 정상 동작 여부 확인
5. 운영 서버 배포
6. 오류 발생 시 자동 롤백

이런 흐름이 없다면 배포 이후 문제가 생겼을 때 누가 어떤 순서로 무엇을 해야 하는지 혼란이 생기기 쉽다. 반면 Harness를 사용하면 배포 과정 자체를 하나의 관리 가능한 시스템으로 다룰 수 있다.

장점과 한계

Harness의 가장 큰 장점은 사람이 하던 반복 작업을 줄이고, 배포를 더 안정적으로 만들 수 있다는 점이다. 배포 이력을 추적하기 쉽고, 승인 단계나 검증 단계도 체계적으로 넣을 수 있다.

다만 자동화가 많아질수록 파이프라인 설계가 복잡해질 수 있다. 그래서 단순히 도구를 도입하는 것보다, 어떤 기준으로 배포를 운영할 것인지 먼저 정리하는 것이 중요하다.

CLAUDE.md란

CLAUDE.md는 AI가 프로젝트 안에서 작업할 때 참고하는 규칙 문서다.

이름만 보면 Claude 전용 문서처럼 느껴질 수 있지만, 실제로 담기는 내용은 특정 AI 하나에만 해당되는 경우가 많지 않다. 프로젝트 구조, 실행 방법, 코딩 규칙, 수정하면 안 되는 부분 같은 정보는 대부분의 AI 코딩 도구가 공통으로 필요로 하는 문맥이다.

사람이 새로운 프로젝트에 참여할 때도 먼저 프로젝트 구조, 실행 방법, 코딩 규칙, 수정하면 안 되는 부분 같은 내용을 전달받는다. AI도 마찬가지다. 이런 정보가 정리되어 있지 않으면 AI는 코드만 보고 맥락을 추측해야 하고, 그 과정에서 잘못된 가정을 할 가능성이 커진다.

CLAUDE.md는 이런 문제를 줄이기 위해 AI에게 프로젝트 문맥을 빠르게 전달하는 역할을 한다. 다만 중요한 것은 파일 이름 자체보다 그 안에 어떤 규칙과 기준이 정리되어 있는가이다.

보통 들어가는 내용

• 프로젝트 개요
• 실행 명령어
• 테스트 방법
• 코드 스타일 규칙
• 수정하면 안 되는 영역
• 작업 우선순위
• 커밋 또는 리뷰 원칙

왜 필요한가

AI는 프로젝트의 암묵적 규칙을 자동으로 완벽하게 이해하지 못한다. 예를 들어 어떤 디렉터리는 건드리면 안 된다거나, 특정 파일명 규칙을 따라야 한다거나, 테스트를 반드시 돌려야 한다는 기준은 문서로 명확히 주어져야 한다.

이런 규칙이 CLAUDE.md에 잘 정리되어 있으면 AI는 더 적은 시행착오로 원하는 방향의 결과를 낼 수 있다. 반대로 문서가 오래되어 실제 프로젝트와 맞지 않으면 오히려 잘못된 기준을 따르게 될 위험도 있다.

정리하면 CLAUDE.md는 이름상으로는 Claude 계열 도구를 떠올리게 하지만, 실제 내용은 다른 AI 코딩 도구에도 충분히 적용될 수 있는 프로젝트 작업 설명서에 가깝다.

AGENTS.md란

AGENTS.md는 AI의 역할 분담과 작업 흐름을 정의하는 문서다.

CLAUDE.md가 프로젝트 전체에서 공통으로 지켜야 할 규칙에 가깝다면, AGENTS.md는 그 안에서 어떤 역할이 무엇을 담당하는지 더 구체적으로 나누는 문서라고 볼 수 있다.

예를 들어 하나의 AI가 모든 작업을 한 번에 처리하는 대신, 초안 작성, 기술 검토, 최종 점검처럼 역할을 나눠서 작업한다면 AGENTS.md가 유용해진다.

예시 역할

• writer: 초안 작성
• reviewer: 기술 정확성과 문장 품질 검토
• publisher: 발행 전 형식 점검

왜 필요한가

역할이 나뉘면 책임도 명확해진다. 누가 초안을 작성하고, 누가 정확성을 검토하고, 누가 최종 형식을 확인하는지 정해져 있으면 작업 흐름이 훨씬 선명해진다.

특히 문서 작성, 코드 리뷰, 발행 점검처럼 단계가 분리되는 작업에서는 이런 역할 정의가 품질 관리에 도움이 된다. 다만 작은 프로젝트에서는 역할을 지나치게 세분화할 경우 오히려 관리 비용만 늘어날 수 있다.

결국 AGENTS.md는 AI 협업 워크플로우를 정리하는 문서라고 볼 수 있다.

세 가지의 차이

세 가지는 모두 작업 효율을 높이기 위한 수단이라는 공통점이 있지만, 집중하는 대상은 서로 다르다.

이 표를 보면 Harness는 실제 운영 자동화에 가까운 개념이고, CLAUDE.md와 AGENTS.md는 AI가 프로젝트 안에서 더 잘 일하기 위한 문서라는 차이가 분명해진다. 그중에서도 CLAUDE.md는 공통 규칙에, AGENTS.md는 역할 분담과 흐름에 더 초점이 맞춰져 있다.

마무리

이번에 정리하면서 느낀 점은, 셋 다 결국 일을 더 잘하기 위한 도구이지만 해결하려는 문제가 서로 다르다는 것이다.

• Harness는 코드가 운영 환경까지 안전하게 전달되도록 돕는다.
• CLAUDE.md는 AI가 프로젝트 규칙을 정확히 이해하도록 돕는다.
• AGENTS.md는 AI가 역할에 따라 체계적으로 협업하도록 돕는다.

즉, Harness는 개발과 운영을 연결하는 플랫폼이고, CLAUDE.md와 AGENTS.md는 AI와 프로젝트를 연결하는 문서라고 정리할 수 있다. 특히 CLAUDE.md는 특정 AI만을 위한 절대적인 규칙서라기보다, 여러 AI 도구에도 활용 가능한 공통 작업 가이드라는 관점으로 이해하는 것이 더 정확하다.

앞으로는 새로운 도구나 문서를 볼 때, 단순히 “무엇을 하는가”만 보는 것이 아니라 “어떤 문제를 해결하기 위해 존재하는가”까지 함께 생각해보면 더 이해가 잘 될 것 같다.

• Harness는 소프트웨어를 개발한 뒤 실제 운영 환경까지 안전하게 전달하기 위한 빌드, 테스트, 배포, 검증 과정을 자동화하고 관리하는 플랫폼이다.
• 단순히 코드를 작성하는 것에서 끝나는 것이 아니라, 그 코드가 어떤 흐름으로 배포되고 운영되는지까지 설계하는 개념에 가깝다.
• 즉, 개발과 운영 사이를 연결하는 DevOps 관점의 엔지니어링이라고 볼 수 있다.
• 예전에는 배포를 사람이 직접 서버에 접속해 명령어를 실행하거나, 순서를 기억해가며 수동으로 진행하는 경우가 많았다.
• 하지만 서비스 규모가 커질수록 이런 방식은 실수 가능성이 높고, 같은 작업을 반복할 때마다 품질이 달라질 수 있다.
• Harness는 이런 배포 과정을 파이프라인으로 정의해서, 누가 실행하더라도 같은 절차와 기준으로 배포가 이루어지도록 돕는다.

왜 필요한가

서비스 개발에서는 기능 구현 이후에도 여러 단계가 필요하다.

1. 빌드
2. 테스트
3. 배포
4. 배포 후 검증
5. 장애 발생 시 롤백

• 이 과정을 사람이 수동으로 처리하면 실수가 발생하기 쉽다.
• 배포 속도가 느려질 수 있다.
• 팀원마다 방식이 달라 일관성이 깨질 수 있다.
• 문제가 발생했을 때 원인을 추적하거나 이전 상태로 되돌리기 어려울 수 있다.
• 특히 실무에서는 배포 전에 어떤 테스트를 통과해야 하는지, 누가 승인해야 하는지, 배포 후 어떤 지표를 확인해야 하는지까지 함께 관리해야 한다.

• 결국 배포는 단순히 애플리케이션을 올리는 작업이 아니라, 서비스 품질을 유지하기 위한 운영 절차의 일부라고 볼 수 있다.

• Harness는 이런 문제를 줄이기 위해 배포 흐름을 자동화된 파이프라인으로 구성하도록 도와준다.

Harness의 핵심

1. 자동화
   • 코드가 변경되면 빌드, 테스트, 배포가 자동으로 실행되도록 구성한다.
   • 반복적인 작업을 사람이 직접 하지 않아도 되기 때문에 작업 속도를 높이고 휴먼 에러를 줄일 수 있다.
2. 안정성
   • 배포 중 문제가 발생하면 중단하거나 이전 버전으로 롤백할 수 있어야 한다.
   • 운영 환경에 바로 전체 배포하는 것이 아니라 단계적으로 배포해 위험을 줄이는 방식과도 잘 연결된다.
3. 표준화
   • 팀마다 다른 배포 방식 대신 공통된 파이프라인을 사용해 일관성을 유지한다.
   • 새로운 팀원이 들어와도 배포 절차를 문서만 읽는 것이 아니라, 이미 정리된 흐름 안에서 따라갈 수 있다는 장점이 있다.
4. 가시성
   • 현재 배포가 어느 단계인지, 어떤 단계에서 실패했는지 쉽게 확인할 수 있어야 한다.
   • 배포 이력과 실패 지점을 빠르게 확인할 수 있어 장애 대응이나 원인 분석에도 도움이 된다.

핵심 기능 예시

• Harness에서 중요하게 볼 수 있는 기능은 다음과 같다.

1. 파이프라인 구성
   • 빌드, 테스트, 배포, 승인, 검증 단계를 순서대로 정의할 수 있다.
2. 승인 단계 추가
   • 운영 배포 전에 특정 담당자의 승인을 거치도록 설정할 수 있다.
3. 배포 후 검증
   • 배포 직후 애플리케이션 상태나 주요 지표를 확인해 이상 여부를 판단할 수 있다.
4. 롤백
   • 배포 후 문제가 발생하면 이전 안정 버전으로 되돌릴 수 있다.
5. 환경 분리
   • 개발, 스테이징, 운영 환경을 나누어 같은 파이프라인을 환경별로 다르게 적용할 수 있다.

예시로 이해하기

• 예를 들어 쇼핑몰 서비스에서 결제 기능을 수정했다고 가정한다.
• 개발자가 코드를 수정하고 main 브랜치에 머지하면 다음과 같은 흐름이 자동으로 실행될 수 있다.

1. 애플리케이션 빌드
2. 자동 테스트 실행
3. 스테이징 서버 배포
4. 정상 동작 여부 확인
5. 운영 서버 배포
6. 오류 발생 시 자동 롤백

• 이처럼 Harness는 사람이 직접 하나씩 처리하던 작업을 자동화하고, 배포를 더 안전하게 만드는 역할을 한다.
• 만약 운영 배포 이후 결제 실패율이 갑자기 높아졌다면, 배포를 즉시 중단하거나 이전 버전으로 되돌리는 식으로 대응할 수 있다.
• 이런 흐름이 정리되어 있지 않으면 장애가 발생했을 때 누가 무엇을 해야 하는지 혼란이 생길 수 있지만, Harness는 이 과정을 더 명확하게 만들어준다.

CI/CD와의 관계

• Harness는 CI/CD를 구현하고 운영하는 데 자주 사용되는 플랫폼이다.
• CI는 코드 변경 사항을 지속적으로 통합하고 빌드/테스트하는 과정이다.
• CD는 검증된 결과물을 실제 환경에 지속적으로 배포하는 과정이다.
• Harness를 활용하는 과정은 결국 이 CI/CD 흐름을 더 효율적이고 안정적으로 설계하는 일이라고 이해할 수 있다.
• 즉, CI/CD가 개념이라면 Harness는 그 개념을 실제 운영 흐름 속에서 구현하고 관리하도록 돕는 도구라고 정리할 수 있다.

DevOps와의 관계

• DevOps는 개발과 운영이 분리되지 않고 협업하면서 빠르고 안정적으로 서비스를 운영하려는 문화와 방식이다.
• Harness는 이 DevOps 문화를 실제 배포 프로세스에서 실행 가능하게 만들어주는 플랫폼 중 하나다.
• 따라서 Harness를 이해하려면 단순한 배포 툴로 보기보다, 개발부터 운영까지 이어지는 흐름을 관리하는 도구로 보는 것이 더 적절하다.

장점

• 반복적인 배포 작업을 줄일 수 있다.
• 사람의 실수를 줄일 수 있다.
• 배포 속도를 높일 수 있다.
• 문제 발생 시 빠르게 원인을 파악할 수 있다.
• 운영 안정성을 높일 수 있다.
• 팀 전체가 동일한 배포 기준을 공유할 수 있다.

주의할 점

1. 자동화가 많아질수록 파이프라인 설계가 복잡해질 수 있다.
2. 툴을 도입하는 것보다 어떤 기준으로 배포를 관리할 것인지가 더 중요하다.
3. 무조건 빠른 배포보다 안전한 배포를 우선해야 한다.
4. 도구만 도입한다고 DevOps가 완성되는 것은 아니며, 팀의 운영 방식과 함께 정리되어야 한다.

요약

최종 결론

Harness는 단순히 배포를 수행하는 도구가 아니라, 배포 과정을 시스템으로 만들고 자동화하는 플랫폼이다.

결국 중요한 것은 코드를 잘 작성하는 것뿐만 아니라, 그 코드가 운영 환경까지 안전하게 전달되도록 만드는 것이다.

따라서 Harness는 개발과 운영을 연결하는 실전적인 DevOps 도구라고 정리할 수 있다.

• 기존: Random Hex String 방식

• 변경: JWT + Metadata JSON 방식

• 이전에는 특정 토큰을 찾기 위해 Redis를 순회해야 할 수 있어 조회 비용이 O(N)에 가까워질 수 있었습니다.
• 현재는 JWT 내부의 사용자 정보와 디바이스 정보를 활용해 O(1) 수준의 직접 조회가 가능해졌습니다.
• 성능뿐 아니라 운영 편의성과 보안 검증 수준도 함께 개선되었습니다.

버전별 상세 비교

주요 개선 사항

성능 최적화: O(N) -> O(1)

• 이전에는 특정 디바이스 토큰을 찾기 위해 KEYS 혹은 SCAN으로 Redis 전체를 탐색해야 했습니다.
• 현재는 JWT 내부 sub(userId)를 즉시 추출한 뒤 refresh_token:{userId}:{deviceId} 키로 직접 접근합니다.
• Full Scan을 제거하면서 조회 비용을 단건 조회 수준으로 줄일 수 있었습니다.

운영 편의성 및 데이터 가시성

• 이전에는 Redis에 토큰 문자열만 저장되어 있어 어떤 사용자의 어떤 디바이스 토큰인지 바로 파악하기 어려웠습니다.
• 현재는 메타데이터 JSON을 함께 저장해 Redis GUI에서도 사용자 이메일, 생성일, 디바이스 정보를 즉시 확인할 수 있습니다.

저장 예시는 다음과 같습니다.

{
  "token": "eyJhbGci...",
  "userId": "user-123",
  "email": "user@example.com",
  "deviceId": "device-456",
  "createdAt": 1709123456789
}

보안 로직 고도화

• 서명 검증: 위변조된 토큰은 Redis를 조회하기도 전에 서버에서 차단합니다.
• 만료 검증: JWT의 만료 정보를 기준으로 유효성을 검사합니다.
• 타입 검증: Payload 내 type: "refresh"를 확인해 Access Token 오용을 방지합니다.

예상 성능 지표

• 검증 속도: 기존 약 100ms -> 변경 후 5ms 미만
• Redis 부하: Full Scan 제거로 CPU 사용량 감소
• 트레이드오프: 저장 공간은 약간 늘어나지만 성능 이득이 더 큼

핵심 코드 변경 포인트

• 생성: randomBytes(64) 대신 jwtService.sign(payload) 사용
• 검증: keys() 패턴 매칭 루프 제거
• 검증 흐름: jwtService.verify() 후 redis.get() 단건 처리

정리

• 이번 변경의 핵심은 단순히 Refresh Token의 포맷만 바꾼 것이 아닙니다.

• 찾기 어려운 토큰을 검증 가능하고 식별 가능한 토큰으로 바꾼 것이 핵심입니다.

• 기존: Random Hex String + 단순 저장
• 변경: JWT + Metadata JSON
• 효과: O(N) 탐색 제거, O(1) 조회 구조 확보
• 추가 이점: 보안 검증 강화, 운영 가시성 향상, 디버깅 편의성 개선

• JWT 기반 인증 시스템을 구현하면서 로그아웃 기능을 추가하려 했습니다.
• 하지만 JWT는 기본적으로 서버가 상태를 저장하지 않는 무상태(stateless) 구조이기 때문에, 사용자가 로그아웃을 하더라도 서버는 해당 토큰이 유효한지 아닌지를 판단할 수 없습니다.
• 처음에는 이 문제를 해결하기 위해 Redis를 도입해 사용자의 토큰을 저장하고, 블랙리스트 방식으로 로그아웃 시 해당 토큰을 무효화하려고 했습니다.

고민한 점

• Redis에 토큰을 저장하면 로그아웃 처리를 쉽게 할 수 있고, 토큰 유효성 검사 시 블랙리스트에 있는지 체크하면 되므로 보안 측면에서 유리합니다.
• 하지만 이 방식은 결국 토큰 상태를 서버가 관리하게 되므로 JWT의 핵심인 무상태성(stateless)을 깨는 문제가 생깁니다.
• 또한 Redis 관리 부담, 토큰 만료 처리 로직, 블랙리스트 갱신 등 추가적인 복잡도가 생깁니다.

선택한 해결 방향

• 고민 끝에 다음과 같은 기준을 세웠습니다:

• 무상태성을 유지하는 방향을 우선시한다면:
  1. Access Token의 만료 시간을 짧게 설정
  2. Refresh Token을 사용해 토큰 재발급 API 제공
  3. 로그아웃 시 클라이언트가 로컬 토큰을 삭제하는 방식
• 보안이 더 중요한 상황이라면:
  1. Redis를 사용해 블랙리스트 방식으로 로그아웃된 토큰을 저장하고 인증 필터에서 차단
• 저는 이번 프로젝트에서는 무상태성을 유지하는 방향을 택하고, 보안을 강화할 필요가 있을 때 블랙리스트 방식을 보완적으로 도입하는 쪽으로 결정했습니다.

Redis 블랙리스트를 활용한 JWT 로그아웃 처리 사례

• 배경 : JWT는 서버가 토큰을 저장하지 않기 때문에 무상태(stateless) 인증 방식입니다. 하지만 이로 인해 로그아웃 시 토큰을 서버 측에서 강제로 무효화할 수 없는 단점이 있습니다. 이를 해결하기 위해 Redis를 활용한 블랙리스트 방식을 적용했습니다.

구현 방식

1. 로그아웃 시 토큰을 Redis에 저장

// 로그아웃 시 호출되는 서비스
public void logout(String accessToken) {
    long expiration = jwtUtil.getExpiration(accessToken); // 토큰의 남은 만료 시간 계산
    redisTemplate.opsForValue().set("BL:" + accessToken, "logout", expiration, TimeUnit.MILLISECONDS);
}
토큰 키 앞에 "BL:"를 붙여 블랙리스트로 식별

토큰의 남은 유효시간만큼 Redis에 저장 → 메모리 낭비 방지

1. JWT 필터에서 요청 토큰 확인

String token = jwtUtil.resolveToken(request);

if (token != null && jwtUtil.validateToken(token)) {
    Boolean isBlacklisted = redisTemplate.hasKey("BL:" + token);
    if (Boolean.TRUE.equals(isBlacklisted)) {
        throw new JwtException("로그아웃된 토큰입니다.");
    }
}
요청이 들어올 때 Redis에서 블랙리스트 토큰인지 검사

로그아웃된 토큰이라면 인증 실패 처리

장점

• 서버가 토큰의 상태를 알 수 있어 로그아웃 구현이 가능
• RefreshToken 탈취 등 보안 문제 발생 시 즉시 차단 가능
• Redis의 TTL을 활용해 자동 만료 관리

단점

• 서버가 일부 상태를 저장하게 되어 무상태성(stateless) 손상
• Redis 의존성 증가 → 장애 시 인증 전체 영향
• 토큰마다 Redis 조회 필요 → 성능 부담 고려 필요

요약

최종 결론

처음엔 Redis로 토큰을 관리하려 했지만, 이는 JWT의 무상태성을 해치기 때문에 Access Token은 짧게, Refresh Token으로 재발급 구조를 선택했습니다. 보안이 특히 중요한 서비스에서는 블랙리스트 방식도 함께 고려할 수 있습니다.

• JPA는 SQL을 추상화한 JPQL이라는 개체 지향 쿼리 언어를 제공한다
• 테이블을 대상으로 쿼리 하는 것이 아닌 엔티티 객체를 대항으로 쿼리한다
• JPQL은 SQL을 추상화했기 때문에 특정 데이터베이스 SQL에 의존하지 않는 장점이 있다
• JPQL은 SQL과 문법이 유사하며, SELECT, FROM, WHERE, GROUP BY, HAVING, JOIN을 지원한다
• JPQL은 결국 SQL로 변환된다

JPQL 예제

// 예: Member 엔티티에서 이름이 '홍길동'인 멤버 조회
@Query("SELECT m FROM Member m WHERE m.name = :name")
List<Member> findByName(@Param("name") String name);

• 위 쿼리에서 Member는 자바 엔티티 클래스이고, name은 필드명입니다.
• SQL에서는 SELECT * FROM member WHERE name = '홍길동'이지만, JPQL에서는 객체 중심으로 표현한다.

JPQL 사용 방식

1. @Query 어노테이션 사용

@Query("SELECT m FROM Member m WHERE m.name = :name")
List<Member> findByName(@Param("name") String name);

1. EntityManager 직접 사용

TypedQuery<Member> query = em.createQuery("SELECT m FROM Member m", Member.class);
List<Member> resultList = query.getResultList();

TypedQuery, Query

• JPQL을 실행하려면 쿼리 객체를 만들어야한다. 쿼리 객체로는 TypedQuery와 Query가 있는데,
  반환할 타입을 명확하게 지정할 수 있으면 TypedQuery와 객체를, 명확하게 지정할 수 없으면 Query 객체를 사용한다

TypedQuery

public static void typedQuery(EntityManager em) {    
    String jpql = "select m from Member m";	
    TypedQuery<Member> query = em.createQuery(jpql, Member.class);		
    List<Member> list = query.getResultList();	
    for( Member member : list) {		
        System.out.println("Member : " + member);	
        }
    }

• EntityManager 객체에서 createQuery() 메소드를 호출하면 쿼리가 생성된다.
• em.createQuery 메소드를 호출할 때 두 번째 인자로 엔티티 클래스를 넘겨준다.

Query

public static void Query(EntityManager em) {   
    String jpql = "select m.name, m.age from Member m";	
    Query query = em.createQuery(jpql);		
    List<Object> list = query.getResultList();	   
    for( Object object : list ) {
        	Object[] results = (Object[]) object;	      	      
                for( Object result : results ) {	          
                    System.out.print ( result );	     
                }	     
            System.out.println();	  
        }
    }

• Query 타입은 데이터 검색 결과의 타입을 명시하지 않는다.

파라미터 바인딩

• 파라미터 바인딩에는 이름 기준 파라미터와 위치 기준 파라미터가 있다.
• 위치 기준 파라미터 보다 이름 기준 파라미터가 더 명확하다.

이름 기준 파라미터

public static void namedParameter(EntityManager em, String param) {    
    String jpql = "select m from Member m where m.name = :name";	
    TypedQuery<Member> query = em.createQuery(jpql, Book.class);	
    query.setParameter("name", param);		
    List<Member> list = query.getResultList();
    }

• 이름을 기준으로 파라미터를 바인딩 한다. 콜론( : ) 을 사용해 데이터가 추가될 곳을 지정하고, query.setParameter() 메소드를 호출해 데이터를 동적으로 바인딩 한다.

위치 기준 파라미터

• 엔티티를 대상을 조회하려면 편리하겠지만, 꼭 필요한 데이터들만 선택해서 조회해야 할 때도 있다.
• 이럴때 MemberDto 처럼 의미있는 객체로 변환해서 사용한다.

@AllArgsConstructor
@NoArgsConstructor
@Getter 
@Setter
public class MemberDto {
    	private String name;	private int age;
    }

public static void useDto (EntityManager em) { 
    // Dto 사용 ( new 명령어 )	
    String jpql = "select new com.coco.example.MemberDto(m.name, m.age) from Member m";	
    TypedQuery<MemberDto> query = em.createQuery(jpql, MemberDto.class);		
    List<MemberDto> list = query.getResultList();	
    for( BookDTO dto : list) {		
        System.out.println("dto : " + dto);	
        }
    }

• select 와 from 사이에 new 라는 키워드 뒤에 Dto의 패키지명까지 작성해야 한다.
• 이 때 new는 객체를 생성하라는 의미가 아니라 JPQL에서 지원하는 new 키워드이다.

JPQL vs SQL

JPQL 주의사항

1. 테이블명 대신 클래스명, 컬럼명 대신 필드명을 사용
2. SELECT 필드명은 항상 엔티티 기준
3. 엔티티가 아닌 테이블을 직접 조회할 수는 없음
4. 엔티티 매핑이 잘못돼 있으면 쿼리가 실패

• AOP는 OOP( Object Oriented Programming )를 돕는 보조적인 기술로, 관심사의 분리( 기능의 분리 )의 문제를 해결하기 위해 만들어진 프로그래밍 패러다임이다.
• AOP는 기능을 핵심 관심 사항( Core Concern )과 공통 관심 사항( Cross - Cutting Concern )으로 분리시키고 각각을 모듈화 하는것을 의미한다.

AOP의 핵심 개념

1. 관심사 ( Concern )
   • 애플리케이션에서 어떤 기능이나 책임을 말한다
   • 예 : 비즈니스 로직, 보안, 로깅 등..
2. 횡단 관심사 ( Cross - Cutting Concern )
   • 여러 모듈에서 공통적으로 사용되는 기능
   • 예 : 로그출력, 트랜잭션 처리, 인증/인가 등..
3. Aspect
   • 횡단 관심사를 모듈화한 단위
   • 예 : 로깅 기능을 LoggingAspect라는 클래스로 작성

AOP의 주요 용어

AOp 클래스 정의 하는 방법

// 밑의 두개의 어노테이션을 작성하면 된다.
@Aspect // AOP 클래스임을 명시하는 어노테이션
@Component
public class LoggingAspect {

    @Before("execution(* com.example.service.*.*(..))")
    public void beforeMethod(JoinPoint joinPoint) {
        System.out.println("Before: " + joinPoint.getSignature().getName());
    }

    @AfterReturning(pointcut = "execution(* com.example.service.*.*(..))", returning = "result")
    public void afterMethod(JoinPoint joinPoint, Object result) {
        System.out.println("After: " + joinPoint.getSignature().getName() + " Result: " + result);
    }
}

Advice 종류 요약

AOP의 장점과 주의점

• 장점
  1. 코드 중복 제거
  2. 모듈화 개선
  3. 유지보수 용이
  4. 핵심 로직과 부가 로직 분리 가능 ( 재사용성을 높임 )
• 주의점
  1. 너무 남용하면 로직 추적이 어려워짐
  2. Spring AOP는 기본적으로 프록시 기반이므로 인터페이스 기반 또는 클래스 기반 프록시임을 이해하고 사용해야함
  3. private 매서드에는 적용 X ( Spring AOP 기준 )

프록시(Proxy)

• 다른 객체에 대한 접근을 제어하는 대리자이다.
• 즉, 클라이언트는 진짜 객체 대신 프록시 객체를 사용하고, 프록시가 진짜 객체에 요청을 전달하면서 추가기능 ( 로깅, 보안, 트랜잭션 등 )을 수행할 수 있다.

• 소프트웨어 개발 후 기능과 동작을 테스트하는 데 사용되는 코드이다.
• 개발자가 예상한대로 프로그램이 실행하는지 확인하는 역할을 한다.
• 어떤 기능을 테스트할 것인지에 대해 각각 테스트 케이스를 분류하고, 다양한 라이브러리와 프레임워크를 이용해 작성할 수 있다.

테스트 코드의 종류

1. 단위 테스트 ( Unit Test )
   • 하나의 메서드나 클래스 등 작은 단위를 독립적으로 테스트하는 방법이다.
   • 외부 의존성( DB, 네트워크 등 )은 mock이 처리
   • 예 : 회원가입 시 이메일 형식을 검사하는 함수만 따로 테스트
2. 통합 테스트 ( Integration Test )
   • 여러 컴포넌트( 예 : controller, Service, Repository )가 함께 동작하는지 확인
   • 실제 데이터베이스나 서버와 연결되는 경우가 많음
   • 예 : 회원가입 요청 -> DB저장까지 전체 흐름 테스트
3. 엔드 투 엔드 테스트 ( E2E, End-to-End )
   • 사용자 관점에서 전체 시스템을 테스트 (브라우저 자동화 등 포함)
   • UI -> 백앤드 -> DB 등 실제 사용 흐름 전체 검증

그래서 테스트 코드를 사용하는 이유?

1. 버그 예방 및 조기 발견
   • 개발 중 실수나 논리 오류를 빠르게 발견할 수 있다.
   • 코드가 예상대로 동작하는지 확인할 수 있어, 배포 전에 문제를 줄일 수 있다.
2. 리팩토링의 안정성 확보
   • 기존 기능을 망가뜨리지 않고 코드를 개선할 수 있다.
   • 테스트 코드가 변경 전/후의 동작을 비교해주는 보호막 역할을 한다.
3. 자동화된 검증으로 생산성 향상
   • 수동 테스트 대신 자동으로 실행되므로 반복 작업을 줄여준다.
   • CI/DI 파이프라인에서 테스트 자동 실행으로 배포 안정성 확보가 가능하다.
4. 문서화 역학
   • 테스트 코드를 보면 해당 기능이 어떤 입력과 출력을 갖는지 알 수 있어, 일종의 실행 가능한 명세서 역할을 한다.
5. 협업과 유지보수에 유리
   • 다른 개발자가 코드를 변경할 때 테스트가 실패하면 영향을 인지할 수 있다.
   • 코드 변경 시 의도치 않은 부작용을 방지할 수 있어 유지보수에 매우 유리하다.
6. 디자인 품질 향상
   • 테스트 가능한 구조를 만들기 위해 결합도를 낮추고, 의존성을 분리하게 되어 설계 품질이 좋아진다.

테스트 코드 작성 예시

@SpringBootTest
class UserServiceTest {

    @Autowired
    private UserService userService;

    @Test
    void 회원가입_성공() {
        // given
        UserDto userDto = new UserDto("test@example.com", "password123");

        // when
        User user = userService.register(userDto);

        // then
        assertEquals("test@example.com", user.getEmail());
    }
}

테스트 코드의 구성 요소

테스트 코드의 장점

테스트 코드 작성 시 유의사항

• 작고 명확한 테스트: 한 번에 하나의 기능만 테스트
• 독립적 테스트: 테스트 간 의존성이 없어야 함
• 실행 시간 고려: 너무 오래 걸리면 테스트를 자주 안 하게 됨
• 실제 데이터 조심: 테스트 DB 또는 Mock 사용 권장

TDD ( Test-Driven Development )

• TDD는 테스트 코드를 먼저 작성한 후, 해당 테스트를 통과하도록 실제 코드를 구현하는 개발 방식입니다.

• 순서:
  1. 실패하는 테스트 작성 (Red)
  2. 테스트 통과하는 최소한의 코드 작성 (Green)
  3. 중복 제거, 리팩토링 (Refactor)
• 이 방식은 설계 품질과 안정성을 동시에 확보할 수 있도록 도와줍니다.

• Servlet Filter는 서블릿 스펙의 일부로, 웹 애플리케이션의 요정(Request) 또는 응답(Response)을 가로채고 가공할 수 있는 재사용 가능한 컴포넌트이다.
• Spring에서도 이를 활용해 인증/인가 필터, 로깅 필터, CORS 필터 등을 만들 수 있다.

Filter 동작 순서

1. 클라이언트의 요청이 먼저 필터를 통과함
2. 각 필터는 doFilter() 메서드를 통해 요청을 가로채고 필요 시 후속 필터 또는 서블릿으로 넘김
3. 서블릿/컨트롤러가 응답을 생성한 후 필터로 다시 돌아옴
4. 필터가 응답을 후처리하고 클라이언트로 전달

[HTTP 요청]
   ↓
[FilterChain: 여러 필터]
   ↓
[DispatcherServlet 또는 서블릿]
   ↓
[Controller 등 비즈니스 로직]
   ↓
[응답 생성]
   ↑
[Filter: 응답 후처리]
   ↑
[클라이언트]

Filter 사용 예시

• 로그인 검증
• JWT 토큰 검사
• CORS 처리
• 요청/응답 로깅
• 응답 캐싱

Filter 구현 예제

@WebFilter(urlPatterns = "/*")
public class LoggingFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        HttpServletRequest req = (HttpServletRequest) request;
        System.out.println("Request URI: " + req.getRequestURI());

        chain.doFilter(request, response); // 다음 필터 또는 서블릿으로 전달

        System.out.println("Response processed");
    }
}

• Spring에서 필터 등록 ( Spring boot )

@Configuration
public class FilterConfig {
    @Bean
    public FilterRegistrationBean<LoggingFilter> loggingFilter() {
        FilterRegistrationBean<LoggingFilter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new LoggingFilter());
        registration.addUrlPatterns("/*");
        return registration;
    }
}

Filter 주요 사용 예

Filter의 장단점

• 장점
  1. 요청/응답 흐름 제어 가능 (컨트롤러 밖에서 동작)
  2. 관심사 분리 (예: 인증, 로깅 등을 독립적으로 관리)
  3. 다양한 URL에 공통 처리 적용 가능
• 단점
  1. 순서를 잘못 구성하거나 무분별하게 사용하면 디버깅이 어려움
  2. 비즈니스 로직과 동떨어져 있어 테스트가 어려울 수 있음
  3. Spring Security 필터와 충돌 우려가 있음 (주의 필요)

관련 개념

Spring 환경에서의 필터 순서

• Spring Boot에서는 다음과 같은 순서로 필터가 실행된다:
  1. Servlet Filter (javax.servlet.Filter)
  2. Spring Security Filter (내부에서 여러 FilterChain 구성됨)
  3. DispatcherServlet
  4. Interceptor
  5. Controller
• 필터 순서 조정이 필요하다면 FilterRegistrationBean#setOrder()를 통해 설정 가능하다.