캐싱 전략 (Redis, in-memory)

9장에서는 성능 최적화와 확장을 다룹니다. 첫 글인 이 글에서는 캐싱 전략을 설명합니다.

캐시는 자주 읽는 데이터나 계산 결과를 원본보다 가까운 저장소에 두어 응답 시간을 줄이고 원본 시스템의 부하를 낮춥니다. 하지만 저장소를 고르는 것만으로는 충분하지 않습니다. 같은 요청을 알아보는 key, 값을 믿을 수 있는 기간인 TTL, 쓰기 뒤에 지울 범위, 캐시 미스가 몰릴 때의 동시성 제어를 함께 설계해야 합니다.

위 그림은 이 글에서 쓸 cache-aside 읽기 흐름입니다. 요청의 key로 캐시를 조회해 유효한 값이 있으면(hit) 원본을 건드리지 않고 바로 반환하고, 없으면(miss) 같은 key의 요청을 하나로 합친 뒤 원본을 조회해 TTL과 함께 저장하고 반환합니다. 왼쪽의 긴 선은 hit가 원본을 호출하지 않고 지나가는 경로입니다. 같은 key의 요청을 합치는 single-flight는 운영에서 추가할 설계이며, 이 글의 수동 캐시 코드에는 따로 구현해야 한다는 점이 그림 위에 적혀 있습니다. 아래쪽은 key, TTL, 삭제, 지표가 각각 어떤 실패를 막는지 정리합니다.

캐싱이란

cache-aside 패턴에서 애플리케이션은 다음 순서로 데이터를 읽습니다.

1. 요청 조건, 사용자 범위, 스키마 버전을 반영해 캐시 key를 만듭니다.
2. 캐시에서 key를 조회합니다. 값이 있고 업무상 유효하면 바로 반환합니다.
3. 값이 없거나 만료되었다면, 같은 key의 동시 요청을 single-flight 같은 방식으로 하나로 합쳐 원본 조회가 몰리지 않게 합니다.
4. 원본에서 가져온 값을 TTL과 함께 캐시에 저장한 뒤 반환합니다.
5. 원본 쓰기가 성공하면 영향받는 key를 del()로 지우고, hit 비율, miss일 때의 지연 시간, 원본 부하를 함께 지켜봅니다.

캐싱의 장점은 다음과 같습니다.

• 응답 시간 단축: 캐시 hit에서는 네트워크 I/O나 반복 계산을 줄일 수 있습니다.
• 원본 부하 감소: 데이터베이스나 외부 API 호출 횟수를 낮춥니다.
• 비용 절감: 원본 처리량과 네트워크 사용량이 줄면 운영 비용도 낮아질 수 있습니다.

캐시를 쓸 때는 다음을 고려해야 합니다.

• key의 범위: tenant, 사용자 권한, 언어, 페이지, 데이터 버전이 다른 요청이 같은 key를 공유하면 안 됩니다.
• TTL: 데이터가 바뀌는 주기와 오래된 값을 허용할 수 있는 시간을 기준으로 짧게 시작하고, 지표를 보며 조정합니다.
• 무효화: 원본 쓰기가 성공한 뒤 관련 key를 지우는 경로와, 지우기에 실패했을 때의 재시도 정책이 필요합니다.
• 캐시 미스 비용: 같은 key가 동시에 만료될 때 원본 요청이 몰리지 않도록 동시성 제어를 둡니다.
• 장애 대응: 캐시가 있다고 원본 장애 때 오래된 값을 자동으로 돌려주지는 않습니다. 필요하다면 오래된 값을 허용하는 정책을 따로 설계합니다.

NestJS 기본 인메모리 캐시

NestJS 캐시 통합에는 @nestjs/cache-manager와 cache-manager가 필요합니다. store를 따로 지정하지 않으면 기본값은 인메모리 캐시입니다.

npm install @nestjs/cache-manager cache-manager

현재 버전은 @nestjs/cache-manager 12.0, cache-manager 7.2이며, @nestjs/cache-manager 12는 NestJS 12를 지원합니다. 이 글의 수동 캐시 예제는 miss일 때 undefined를 반환하는 cache-manager 7을 기준으로 합니다. 공식 캐싱 문서에 따르면 cache-manager 6에서는 miss가 null이었으므로, 6에서 옮겨 오는 동안에는 둘 다 miss로 취급해야 합니다.

CacheModule과 전역 CacheInterceptor 등록

import { Module } from '@nestjs/common';
import { CacheInterceptor, CacheModule } from '@nestjs/cache-manager';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { AppController } from './app.controller';

@Module({
  imports: [
    CacheModule.register({
      ttl: 5_000, // 밀리초: 5초
    }),
  ],
  controllers: [AppController],
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: CacheInterceptor,
    },
  ],
})
export class AppModule {}

HTTP 애플리케이션의 CacheInterceptor는 기본적으로 GET 엔드포인트만 자동으로 캐싱합니다. 다만 공식 문서의 경고대로, route에 @CacheKey()를 명시하면 이 HTTP 메서드 검사를 건너뜁니다. 그래서 POST 같은 상태 변경 작업도 무조건 제외된다고 판단하면 안 됩니다. 이 예제는 조회용 GET에만 적용하고, 변경 작업에는 응답 캐싱을 붙이지 않습니다. 또 Express의 응답 객체를 직접 주입하는 @Res() route에는 CacheInterceptor를 쓸 수 없습니다.

route별 key와 TTL 지정

CacheKey, CacheTTL, CacheInterceptor, CacheModule, CACHE_MANAGER는 모두 @nestjs/cache-manager에서 가져옵니다. ttl과 @CacheTTL()의 숫자는 밀리초입니다.

import { Controller, Get } from '@nestjs/common';
import { CacheKey, CacheTTL } from '@nestjs/cache-manager';

@Controller('app')
export class AppController {
  @Get('hello')
  @CacheKey('hello_world')
  getHello(): string {
    return 'Hello World!';
  }

  @Get('cached-sum')
  @CacheKey('sum_10_20')
  @CacheTTL(10_000) // 밀리초: 10초
  sumNumbersCached(): number {
    return 10 + 20;
  }
}

첫 요청은 handler를 실행하고 응답을 저장합니다. TTL 안에 들어온 같은 key의 요청은 캐시에서 반환되고, 만료된 뒤의 요청은 handler를 다시 실행합니다. 자동으로 만드는 key 대신 @CacheKey()를 쓸 때는, 서로 다른 사용자나 요청 조건이 같은 응답을 공유해도 되는지 먼저 확인해야 합니다.

더 깊이: 자동으로 만든 key에 들어가지 않는 것

전역 CacheInterceptor가 HTTP 요청에 자동으로 붙이는 key는 요청 URL입니다. @nestjs/cache-manager의 소스를 보면 trackBy()는 허용된 메서드(기본은 GET)일 때 HTTP 어댑터가 돌려준 요청 URL을 그대로 key로 쓰며, Authorization 헤더나 쿠키는 key에 들어가지 않습니다. 그래서 같은 GET /profile이 로그인한 사용자마다 다른 응답을 돌려준다면, 전역 캐시는 처음 저장된 한 사용자의 응답을 TTL 동안 다른 사용자에게도 돌려줄 수 있습니다. 캐싱 문서는 이런 경우 CacheInterceptor를 상속해 trackBy()를 다시 정의하라고 안내하며, 이 메서드가 key 대신 빈 값을 돌려주면 그 요청은 캐시를 거치지 않고 handler로 바로 갑니다.

TTL을 빠뜨렸을 때의 기본값도 알아 둡니다. 문서에 따르면 register()에 ttl을 주지 않으면 값을 0으로 준 것과 같아서, 저장된 항목이 만료되지 않습니다. 이 글의 예제처럼 모듈 수준의 ttl을 명시하거나 route마다 @CacheTTL()을 붙이지 않으면, 원본이 바뀌어도 프로세스를 다시 시작하거나 key를 지울 때까지 예전 응답이 계속 나갈 수 있습니다.

Redis를 쓰는 분산 캐시

여러 애플리케이션 인스턴스가 하나의 캐시를 함께 써야 한다면 Redis 같은 외부 store를 씁니다. 공유 store는 인스턴스마다 캐시가 달라지는 문제를 줄이지만, 올바른 key 범위와 무효화까지 저절로 해결해 주지는 않습니다.

로컬 실습용 Redis는 다음처럼 실행할 수 있습니다.

docker run --name nest-redis -p 6379:6379 -d redis:8-alpine

-p 6379:6379로 호스트의 6379번 포트를 열었으므로, 아래 코드의 기본 주소 redis://localhost:6379로 이 컨테이너에 접속할 수 있습니다. 볼륨을 연결하지 않았으므로 컨테이너를 지우면 캐시 데이터도 사라지지만, 캐시는 원본에서 다시 만들 수 있는 데이터이므로 실습에는 충분합니다. cache-manager는 내부적으로 Keyv를 쓰므로, Redis를 쓰려면 Keyv용 Redis adapter인 @keyv/redis를 설치합니다.

npm install @keyv/redis@5

@keyv/redis의 최신 6 버전은 peer dependency로 keyv 6을 요구하지만, cache-manager 7.2는 keyv 5를 의존성으로 씁니다. 두 쪽의 keyv 주 버전을 맞추기 위해 keyv 5를 요구하는 @keyv/redis 5를 설치합니다. 설치한 뒤에는 npm ls keyv로 한 가지 주 버전만 쓰이는지 확인합니다.

아래 코드는 Redis store를 연결하는 CacheModule 등록입니다. 앞 예제의 CacheModule.register(...)를 registerAsync(...)로 바꾸고, 전역 CacheInterceptor 등록은 그대로 둡니다.

import { Module } from '@nestjs/common';
import { CacheInterceptor, CacheModule } from '@nestjs/cache-manager';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { createKeyv } from '@keyv/redis';
import { AppController } from './app.controller';

@Module({
  imports: [
    CacheModule.registerAsync({
      useFactory: () => {
        const redisStore = createKeyv(
          process.env.REDIS_URL ?? 'redis://localhost:6379',
        );
        // 연결이 끊기면 error 이벤트가 발생합니다. 듣는 곳이 없으면 앱이 종료될 수 있습니다.
        redisStore.on('error', (error: unknown) => {
          console.error('Redis cache error:', error);
        });

        return {
          stores: [redisStore],
          ttl: 5_000, // 밀리초: 5초
        };
      },
    }),
  ],
  controllers: [AppController],
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: CacheInterceptor,
    },
  ],
})
export class AppModule {}

createKeyv()는 @keyv/redis가 제공하는 함수로, Redis 연결 문자열을 받아 Keyv 인스턴스를 만듭니다. stores 배열의 첫 번째 store가 기본 store이고, 나머지는 대체 store로 쓰입니다. 공식 문서는 Redis store에 반드시 'error' 리스너를 붙이라고 경고합니다. Redis 연결이 끊기면 store가 'error' 이벤트를 내는데, 듣는 곳이 없으면 Keyv가 예외를 던져 애플리케이션이 멈출 수 있기 때문입니다. 실제 환경에서는 연결 문자열을 설정 서비스와 secret으로 주입하고, timeout, 재연결, 장애 때 원본을 보호하는 정책을 함께 정합니다.

인메모리 store와 Redis store는 값을 다루는 방식도 다릅니다. 공식 문서에 따르면 기본 인메모리 store는 값을 복사하지 않고 참조를 보관하므로, get()이 set()에 넘긴 바로 그 객체를 돌려줍니다. 반면 Keyv store는 값을 JSON으로 직렬화하므로 클래스 인스턴스는 일반 객체로, Date는 문자열로 돌아옵니다.

CACHE_MANAGER로 직접 캐시 관리하기

route 응답 전체가 아니라 서비스의 결과를 캐싱하거나, 쓰기가 성공한 뒤 정확한 key를 지워야 한다면 CACHE_MANAGER를 주입해 직접 다룹니다.

위 그림은 Client, Service, CACHE_MANAGER, Origin 사이의 순서를 시퀀스로 보여 줍니다. Service가 get(key)을 호출해 값이 undefined가 아니면 원본 조회와 저장을 건너뛰고 바로 응답합니다. undefined이면 Origin에서 값을 읽어 60_000밀리초 TTL로 set()한 뒤 같은 응답으로 합류합니다. 그림의 false도 값으로 취급된다는 표시는, 이 판정이 truthy 검사가 아니라 undefined와의 비교라는 뜻입니다.

아래는 이미 상품 저장소가 있는 프로젝트의 Service 부분입니다. ProductRepository의 findOne()과 update(), UpdateProductDto, 두 provider의 모듈 등록은 따로 있어야 하며, 이 파일만으로 상품 HTTP route나 DB 연결이 완성되지는 않습니다.

import { Inject, Injectable } from '@nestjs/common';
import { CACHE_MANAGER, Cache } from '@nestjs/cache-manager';
import { ProductRepository } from './product.repository';
import { UpdateProductDto } from './update-product.dto';

@Injectable()
export class ProductsService {
  constructor(
    @Inject(CACHE_MANAGER) private readonly cache: Cache,
    private readonly products: ProductRepository,
  ) {}

  async findOne(id: string) {
    const key = `product:v1:${id}`;
    const cached = await this.cache.get(key);

    if (cached !== undefined) {
      return cached;
    }

    const product = await this.products.findOne(id);
    await this.cache.set(key, product, 60_000); // 밀리초: 60초
    return product;
  }

  async update(id: string, input: UpdateProductDto) {
    const product = await this.products.update(id, input);
    await this.cache.del(`product:v1:${id}`);
    return product;
  }
}

cache-manager 7에서 get()이 key를 찾지 못하면 undefined를 반환합니다. 그래서 truthy 검사 대신 cached !== undefined로 hit를 판정하면 0, false, 빈 문자열 같은 값도 올바르게 캐싱할 수 있습니다.

직접 다루는 API의 핵심은 다음과 같습니다.

• get(key): 저장된 값을 읽고, miss면 undefined를 반환합니다.
• set(key, value, 60_000): 세 번째 인자로 밀리초 단위 TTL을 넘깁니다.
• del(key): 특정 key를 지웁니다. 일반적인 쓰기 경로에서는 관련 key만 좁게 지웁니다.
• clear(): store 전체를 비웁니다. 운영 복구나 관리 작업처럼 범위가 분명할 때만 씁니다.

예제의 get()부터 원본 조회까지의 구간은 동시에 여러 요청이 들어오면 중복으로 실행될 수 있습니다. 같은 key에 대해 진행 중인 Promise를 공유하거나 검증된 single-flight 방식을 추가하고, hit 비율뿐 아니라 miss일 때의 지연 시간과 원본 부하도 함께 측정해야 합니다.

쓰기 뒤 삭제만으로 막지 못하는 경합

위 코드는 원본 쓰기 뒤 캐시를 지우지만, 이미 진행 중인 읽기가 있는 경우도 생각해야 합니다. 캐시는 비어 있고 원본 가격은 100이라고 가정합니다. 요청 A가 원본에서 100을 읽은 뒤, 캐시에 저장하기 직전에 잠시 멈췄습니다. 그 사이 요청 B가 가격을 120으로 저장하고 해당 key를 지웠습니다. 그 뒤 A가 다시 진행하면 예전 값 100을 캐시에 넣으므로, B의 삭제가 성공했는데도 다음 읽기는 오래된 값을 받게 됩니다.

TTL은 이런 값이 남아 있는 시간을 제한할 수 있지만, 쓰기 직후의 일관성을 보장하지는 않습니다. single-flight도 같은 key의 읽기 중복을 합칠 뿐, 쓰기와의 경합을 해결하지는 않습니다. 쓰기 직후 새 값을 반드시 보여 줘야 하는 업무라면, 읽어 온 revision이 현재 revision과 같을 때만 캐시에 저장하는 조건, 읽기와 쓰기의 조정, 버전이 들어간 key 같은 장치를 추가로 고르고 검증해야 합니다.

캐싱은 읽기 속도만 높이는 기능이 아니라 key, TTL, 무효화, 동시성, 관측을 함께 운영하는 일입니다. 한 프로세스 안의 빠른 임시 저장이면 기본 인메모리 store로 시작하고, 여러 인스턴스가 캐시를 공유해야 하면 Keyv 호환 Redis store를 고릅니다.

정리

• cache-aside 패턴은 캐시를 먼저 조회하고, miss일 때만 원본을 읽어 TTL과 함께 저장하며, 원본 쓰기 뒤에는 관련 key를 지웁니다.
• @nestjs/cache-manager의 CacheInterceptor는 기본적으로 GET만 캐싱하지만, @CacheKey()를 붙이면 이 검사를 건너뛰므로 변경 작업에 붙이지 않습니다.
• TTL은 밀리초 단위이며, cache-manager 7의 miss는 undefined이므로 cached !== undefined로 판정합니다.
• Redis store는 @keyv/redis의 createKeyv()로 만들고 반드시 'error' 리스너를 붙이며, cache-manager 7과 keyv 주 버전을 맞추려면 @keyv/redis 5를 씁니다.
• 쓰기 뒤 삭제만으로는 진행 중인 읽기와의 경합을 막지 못하므로, 즉시 일관성이 필요하면 revision 조건이나 버전 key를 추가합니다.

연습 문제

1. false가 저장되어 있다면

위 수동 코드에서 cache.get(key)이 false를 반환했습니다. 원본 조회와 set()이 실행될까요? miss인 undefined와 같은 분기로 갈까요? 값이 상품 응답으로 유효한지는 따로 판단한다고 가정합니다. TTL 인자 60_000은 몇 초일까요?

2. 꺼낸 객체를 고쳤더니

기본 인메모리 store에서 const product = await this.cache.get(key);로 꺼낸 상품 객체의 price를 화면 표시용으로 product.price = product.price * 1.1처럼 바꾼 뒤 응답했습니다. 다음 요청이 같은 key로 hit하면 가격은 어떻게 보일까요? store를 Redis로 바꾸면 결과가 달라질까요?

3. POST에 @CacheKey를 붙이면

전역 CacheInterceptor가 등록된 앱에서 누군가 주문 생성 route인 @Post('orders')에 @CacheKey('orders')를 붙였습니다. 두 사용자가 5초 안에 서로 다른 주문을 생성하면 어떤 일이 생길 수 있을까요?

다음 글 데이터베이스 쿼리 최적화에서는 캐시 앞단이 아니라 원본인 데이터베이스 쪽에서 느린 쿼리를 찾고 개선하는 방법을 다룹니다.