Cache Presets - Sonamu

Sonamu는 자주 사용하는 Cache-Control 패턴을 CachePresets으로 제공합니다. 직접 설정을 작성하는 대신 프리셋을 사용하면 일관되고 검증된 캐시 전략을 쉽게 적용할 수 있습니다.

CachePresets 개요

import { CachePresets } from "sonamu";

// API에서 사용
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.shortLived,
})

// SSR에서 사용
registerSSR({
  path: '/products',
  cacheControl: CachePresets.ssr,
});

전체 프리셋 목록

noStore

캐시 저장 금지

noCache

매번 재검증

shortLived

1분 캐시

ssr

SSR 최적화 (10초 + SWR)

mediumLived

5분 캐시

longLived

1시간 캐시

immutable

영구 캐시 (정적 파일)

private

개인화 데이터

프리셋 상세

noStore

캐시 저장을 완전히 금지합니다.

CachePresets.noStore
// 생성되는 헤더: Cache-Control: no-store

설정
사용 시기
예제

{
  noStore: true
}

// 결제 API
@api({
  httpMethod: 'POST',
  cacheControl: CachePresets.noStore,
})
async createPayment(data: PaymentSave) {
  return this.processPayment(data);
}

// 개인 정보 조회
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.noStore,
})
async getPrivateData(ctx: Context) {
  return this.getSensitiveData(ctx.user.id);
}

noCache

캐시는 저장하되 매번 재검증합니다.

CachePresets.noCache
// 생성되는 헤더: Cache-Control: no-cache

설정
사용 시기
예제

{
  noCache: true
}

// 재고 정보 (자주 변경)
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.noCache,
})
async getInventory(productId: number) {
  return this.checkStock(productId);
}

no-cache의 장점:

1차 요청: GET /api/data → 200 OK + ETag: "abc123"
2차 요청: GET /api/data (If-None-Match: "abc123")
→ 304 Not Modified (body 없음, 빠름)

shortLived

1분 캐시 - 자주 변경되는 데이터에 적합합니다.

CachePresets.shortLived
// 생성되는 헤더: Cache-Control: public, max-age=60

설정
사용 시기
예제

{
  visibility: 'public',
  maxAge: 60  // 60초 = 1분
}

// 게시글 목록
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.shortLived,
})
async getPosts(page: number) {
  return this.findMany({ page, num: 20 });
}

// CSR fallback
registerSSR({
  path: '/*',  // catch-all
  cacheControl: CachePresets.shortLived,
});

ssr

SSR 페이지 최적화 - 10초 캐시 + Stale-While-Revalidate 30초

CachePresets.ssr
// 생성되는 헤더: Cache-Control: public, max-age=10, stale-while-revalidate=30

설정
작동 방식
사용 시기
예제

{
  visibility: 'public',
  maxAge: 10,  // 10초 동안 Fresh
  staleWhileRevalidate: 30  // 이후 30초 동안 Stale 사용
}

// 상품 상세 페이지
registerSSR({
  path: '/products/:id',
  cacheControl: CachePresets.ssr,
  Component: ProductDetail,
});

// 블로그 글
registerSSR({
  path: '/blog/:slug',
  cacheControl: CachePresets.ssr,
  Component: BlogPost,
});

mediumLived

5분 캐시 - 거의 변경되지 않는 데이터에 적합합니다.

CachePresets.mediumLived
// 생성되는 헤더: Cache-Control: public, max-age=300

설정
사용 시기
예제

{
  visibility: 'public',
  maxAge: 300  // 300초 = 5분
}

// 카테고리 트리
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.mediumLived,
})
async getCategoryTree() {
  return this.buildTree();
}

// 약관
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.mediumLived,
})
async getTerms() {
  return this.findOne(['type', 'terms']);
}

longLived

1시간 캐시 - 정적 컨텐츠에 적합합니다.

CachePresets.longLived
// 생성되는 헤더: Cache-Control: public, max-age=3600

설정
사용 시기
예제

{
  visibility: 'public',
  maxAge: 3600  // 3600초 = 1시간
}

// 국가 목록
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.longLived,
})
async getCountries() {
  return this.findMany({});
}

// 정적 설정
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.longLived,
})
async getConfig() {
  return this.config;
}

immutable

영구 캐시 - 해시가 포함된 정적 파일용

CachePresets.immutable
// 생성되는 헤더: Cache-Control: public, max-age=31536000, immutable

설정
사용 시기
예제

{
  visibility: 'public',
  maxAge: 31536000,  // 1년 (초 단위)
  immutable: true  // 절대 변경 안됨
}

해시가 포함된 파일명
- bundle-abc123.js
- styles-def456.css
- image-789xyz.png
내용이 변경되면 파일명도 변경되는 경우

// 빌드된 정적 파일
server.get('/assets/:filename', (req, reply) => {
  const filename = req.params.filename;
  
  // 해시 포함 파일은 immutable
  if (/\-[a-f0-9]{8,}\.(js|css|png)$/.test(filename)) {
    applyCacheHeaders(reply, CachePresets.immutable);
  }
  
  return reply.sendFile(filename);
});

immutable의 장점:

재검증 없이 캐시만 사용 (가장 빠름)
파일이 변경되면 새 해시 → 새 파일명 → 자동 캐시 갱신

private

개인화 데이터 - 사용자별로 다른 응답

CachePresets.private
// 생성되는 헤더: Cache-Control: private, no-cache

설정
사용 시기
예제

{
  visibility: 'private',
  noCache: true
}

// 내 프로필
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.private,
})
async getMyProfile(ctx: Context) {
  return this.findOne(['id', ctx.user.id]);
}

// 내 주문 목록
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.private,
})
async getMyOrders(ctx: Context) {
  return this.findMany({ 
    where: [['user_id', ctx.user.id]] 
  });
}

private vs public:

private: 브라우저에만 캐싱 (CDN에는 안 됨)
public: 모든 캐시(브라우저 + CDN)에 캐싱

프리셋 비교표

프리셋	헤더	용도	TTL
`noStore`	`no-store`	민감한 데이터, Mutation	없음
`noCache`	`no-cache`	매번 재검증 필요	없음 (재검증)
`shortLived`	`public, max-age=60`	자주 변경	1분
`ssr`	`public, max-age=10, stale-while-revalidate=30`	SSR 페이지	10초 + SWR 30초
`mediumLived`	`public, max-age=300`	거의 변경 안됨	5분
`longLived`	`public, max-age=3600`	정적 콘텐츠	1시간
`immutable`	`public, max-age=31536000, immutable`	해시 파일	1년 (영구)
`private`	`private, no-cache`	개인화 데이터	없음 (private)

커스텀 설정

프리셋이 맞지 않으면 직접 설정을 작성할 수 있습니다.

// CDN 최적화 (브라우저: 1분, CDN: 5분)
@api({
  httpMethod: 'GET',
  cacheControl: {
    visibility: 'public',
    maxAge: 60,      // 브라우저
    sMaxAge: 300,    // CDN
  }
})
async getData() {
  return this.findMany({});
}

// Stale-If-Error 추가
@api({
  httpMethod: 'GET',
  cacheControl: {
    visibility: 'public',
    maxAge: 300,
    staleIfError: 86400,  // 오류 시 1일간 Stale 사용
  }
})
async getCriticalData() {
  return this.getData();
}

전역 핸들러

모든 요청에 대해 동적으로 Cache-Control을 설정할 수 있습니다.

// sonamu.config.ts
export const config: SonamuConfig = {
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        // API 요청
        if (req.type === 'api') {
          if (req.method !== 'GET') {
            return CachePresets.noStore;  // Mutation은 no-store
          }
          return CachePresets.shortLived;  // GET은 1분 캐시
        }
        
        // 정적 파일
        if (req.type === 'assets') {
          if (req.path.includes('-')) {  // 해시 포함
            return CachePresets.immutable;
          }
          return CachePresets.longLived;
        }
        
        // SSR
        if (req.type === 'ssr') {
          return CachePresets.ssr;
        }
        
        return undefined;  // 기본값
      }
    }
  }
};

실전 활용

API별 전략

class ProductModelClass extends BaseModel {
  // 목록: 자주 변경 → 짧은 캐시
  @api({
    httpMethod: 'GET',
    cacheControl: CachePresets.shortLived,
  })
  async findAll() {
    return this.findMany({});
  }
  
  // 상세: 덜 변경 → 중간 캐시
  @api({
    httpMethod: 'GET',
    cacheControl: CachePresets.mediumLived,
  })
  async findById(id: number) {
    return this.findOne(['id', id]);
  }
  
  // 카테고리: 거의 변경 안됨 → 긴 캐시
  @api({
    httpMethod: 'GET',
    cacheControl: CachePresets.longLived,
  })
  async getCategories() {
    return this.categories;
  }
  
  // 생성/수정: Mutation → no-store
  @api({
    httpMethod: 'POST',
    cacheControl: CachePresets.noStore,
  })
  async create(data: ProductSave) {
    return this.saveOne(data);
  }
}

SSR 페이지

// 홈페이지: SSR 최적화
registerSSR({
  path: '/',
  cacheControl: CachePresets.ssr,
  Component: HomePage,
});

// 상품 목록: 짧은 캐시
registerSSR({
  path: '/products',
  cacheControl: CachePresets.shortLived,
  Component: ProductList,
});

// 약관: 긴 캐시
registerSSR({
  path: '/terms',
  cacheControl: CachePresets.longLived,
  Component: Terms,
});

주의사항

프리셋 사용 시 주의사항:

프리셋은 출발점: 상황에 맞게 커스터마이징 필요

// ✅ 상황에 맞게 조정
cacheControl: {
  ...CachePresets.shortLived,
  maxAge: 120,  // 1분 → 2분으로 조정
}

GET만 캐싱: POST, PUT, DELETE는 noStore 사용

// ❌ 잘못된 예
@api({
  httpMethod: 'POST',
  cacheControl: CachePresets.shortLived,
})

// ✅ 올바른 예
@api({
  httpMethod: 'POST',
  cacheControl: CachePresets.noStore,
})

개인 데이터는 private: CDN 캐싱 방지

// ❌ 위험: CDN에 개인 데이터 캐싱
@api({
  cacheControl: CachePresets.shortLived,  // public
})
async getMyData() { ... }

// ✅ 안전
@api({
  cacheControl: CachePresets.private,
})
async getMyData() { ... }

immutable은 해시 파일만: 파일명이 바뀌어야 갱신됨

// ❌ 잘못된 사용
// main.js (해시 없음) → 내용 변경해도 캐시 유지
cacheControl: CachePresets.immutable

// ✅ 올바른 사용
// main-abc123.js (해시 있음) → 내용 변경 시 파일명도 변경
cacheControl: CachePresets.immutable

다음 단계

Cache-Control이란?

HTTP 캐싱 기본 개념

API에서 사용하기

@api 데코레이터에 적용

SSR에서 사용하기

SSR 페이지에 적용

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​CachePresets 개요

​전체 프리셋 목록

noStore

noCache

shortLived

ssr

mediumLived

longLived

immutable

private

​프리셋 상세

​noStore

​noCache

​shortLived

​ssr

​mediumLived

​longLived

​immutable

​private

​프리셋 비교표

​커스텀 설정

​전역 핸들러

​실전 활용

​API별 전략

​SSR 페이지

​주의사항

​다음 단계

Cache-Control이란?

API에서 사용하기

SSR에서 사용하기

CachePresets 개요

전체 프리셋 목록

프리셋 상세

noStore

noCache

shortLived

ssr

mediumLived

longLived

immutable

private

프리셋 비교표

커스텀 설정

전역 핸들러

실전 활용

API별 전략

SSR 페이지

주의사항

다음 단계