Distributed Cache Library
build workflow
PkgGoDev
GitHub License
GitHub Repo stars
GitHub commit activity
Go Report Card
codecov
Maintainability
Redis를 백킹 스토어로 사용하고 set/invalidation 이벤트를 위해 pub/sub 기능을 사용하여 여러 서비스 인스턴스 간의 로컬 LFU/LRU 캐시를 동기화하는 고성능 분산 인메모리 캐시 라이브러리입니다.
Version: v1.0.4
기능 (Features)
- 2단계 캐싱 (Two-Level Caching): Redis 백킹 스토어(내장) 또는 사용자 정의 구현과 함께 로컬 인프로세스 LFU(Ristretto)/LRU(golang-lru)를 사용한 2단계 캐싱.
- 자동 동기화 (Automatic Synchronization): 분산 서비스 간의 캐시 set/invalidation을 위한 Redis Pub/Sub 자동 동기화 기능.
- 고성능 (High Performance): LFU/LRU는 우수한 히트율(hit ratios)과 처리량(throughput)을 제공합니다.
- Kubernetes Ready: pod-aware invalidation 기능을 갖추어 컨테이너 환경에 최적화되었습니다.
- 간단한 API (Simple API): Get, Set, Delete, Clear 작업을 위한 사용하기 쉬운 인터페이스를 제공합니다.
- 메트릭스 (Metrics): 캐시 성능 모니터링을 위한 내장 통계 수집 기능이 있습니다.
- 유연한 설정 (Flexible Configuration): 간편한 배포를 위해 환경 변수(Environment variable)를 지원합니다.
아키텍처 (Architecture)
distributed-cache 라이브러리는 로컬 인프로세스 캐시를 Redis pub/sub을 통해 동기화하는 2단계 캐싱 아키텍처를 사용합니다.
값 전파를 통한 Set 작업 (Set with Value Propagation)
Pod가 값을 설정하면, 해당 값은 로컬과 Redis에 저장된 후 모든 다른 Pod로 전파되어, 다른 Pod들이 Redis에서 데이터를 가져오지 않고도 즉시 로컬 캐시를 업데이트할 수 있습니다.
sequenceDiagram
participant AppA as Application (Pod A)
participant CacheA as SyncedCache (Pod A)
...
2. 무효화만 포함한 설정(Set with Invalidation Only)
대용량 값 또는 지연 로딩(lazy loading) 시나리오의 경우 SetWithInvalidate()를 사용합니다. 다른 파드(pod)들은 무효화 이벤트만 수신하고 필요할 때 Redis에서 값을 가져옵니다.
sequenceDiagram
participant AppA as Application (Pod A)
participant CacheA as SyncedCache (Pod A)
...
3. Get - 로컬 캐시 적중(Local Cache Hit)
가장 빠른 경로입니다: 값이 로컬 인프로세스 캐시(local in-process cache)에서 발견됩니다 (~100ns).
sequenceDiagram
participant App as Application
participant Cache as SyncedCache
...
4. Get - 원격 캐시 적중(Remote Cache Hit)
값은 로컬 캐시에 없지만 Redis에서 발견된 경우입니다. 값을 가져와서 향후 요청을 위해 로컬에 저장합니다.
sequenceDiagram
participant App as Application
participant Cache as SyncedCache
...
5. Get - 캐시 미스(Cache Miss)
값은 로컬 캐시나 Redis 어느 곳에서도 발견되지 않은 경우입니다.
sequenceDiagram
participant App as Application
participant Cache as SyncedCache
...
6. 삭제 작업(Delete Operation)
값을 로컬 캐시와 Redis에서 제거한 후, 모든 파드(pod)로 삭제를 브로드캐스트합니다.
sequenceDiagram
participant AppA as Application (Pod A)
participant CacheA as SyncedCache (Pod A)
...
7. 클리어 작업(Clear Operation)
로컬 캐시와 Redis의 모든 값을 지운 후, 모든 파드(pod)로 클리어 이벤트를 브로드캐스트합니다.
sequenceDiagram
participant AppA as Application (Pod A)
participant CacheA as SyncedCache (Pod A)
...
주요 구성 요소 (Key Components)
- SyncedCache: Get, Set, Delete, Clear 작업을 제공하는 메인 API입니다.
- Local Cache: 빌트인 인프로세스 캐시(Ristretto를 통한 LFU 또는 golang-lru를 통한 LRU) 또는 사용자 정의 구현체입니다.
- Redis Store: 캐시 데이터를 위한 영구 백업 저장소입니다.
- Redis Pub/Sub: 캐시 무효화 및 값 전파를 위한 동기화 채널입니다.
- Marshaller: 플러그 가능한 직렬화(JSON, MessagePack, Protobuf 등) 기능입니다.
- Logger: 플러그 가능한 로깅 인터페이스(Console, Zap, Slog 등)입니다.
데이터 흐름 (Data Flow)
- Set 작업: 로컬 캐시에 저장된 값 → Redis를 거쳐 다른 서비스 인스턴스(파드, pods)로 Pub/Sub 이벤트 전송
- Get 작업 (로컬 히트): 로컬 캐시에서 값 검색 (~100ns)
- Get 작업 (원격 히트): Redis에서 값을 가져와서 로컬 캐시에 저장 (~1-5ms)
- 동기화: 다른 서비스 인스턴스(파드, pods)가 Pub/Sub 이벤트를 수신 → 로컬 캐시 업데이트/무효화
설치 (Installation)
go get github.com/huykn/distributed-cache
빠른 시작 (Quick Start)
package main
import (
...
)
설정 (Configuration)
프로그래밍 방식 설정 (Programmatic Configuration)
opts := cache.Options{
PodID: "pod-1",
RedisAddr: "redis.default.svc.cluster.local:6379",
...
}
API 참조 (API Reference)
캐시 인터페이스 (Cache Interface)
type Cache interface {
Get(ctx context.Context, key string) (any, bool)
Set(ctx context.Context, key string, value any) error
...
}
- 로컬 캐시 히트: ~100ns (인프로세스, in-process)
- 원격 캐시 히트: ~1-5ms (Redis 왕복 시간, round-trip)
- 캐시 미스: ~1-5ms (Redis 조회, lookup)
- Set 작업: ~1-5ms (Redis + Pub/Sub)
예제 (Examples)
이 라이브러리는 다양한 기능과 사용 사례를 보여주는 포괄적인 예제를 포함하고 있습니다:
시작하기 (Getting Started)
- 기본 예제 - 핵심 기능, 다중 파드 동기화 및 값 전파
- 디버그 모드 - 상세 로깅 및 문제 해결 기법
캐시 전략 (Cache Strategies)
- LFU 캐시 - 다양한 접근 패턴을 위한 최소 빈도 사용(Least Frequently Used, LFU) 캐시 (기본값)
- LRU 캐시 - 순차적 접근 패턴을 위한 최소 최근 사용(Least Recently Used, LRU) 캐시
- LFU 대 LRU 비교 - 적절한 전략 선택에 도움을 주는 나란히 비교
사용자 정의 (Customization)
프로덕션 배포 (Production Deployment)
각 예제에는 다음 내용이 포함됩니다:
- 설명이 담긴 상세한 README
- 기능을 시연하는 실행 가능한 코드
- 예상 출력 및 동작 방식
- 설정 옵션 및 모범 사례
- 문제 해결 팁
빠른 시작(Quick Start): 핵심 개념을 이해하려면 기본 예제(Basic Example)부터 시작하고, 필요에 따라 다른 예제를 탐색하세요.
기여하기 (Contributing)
기여를 환영합니다! 지침은 CONTRIBUTING.md 파일을 참조하십시오.
라이선스 (License)
MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하십시오.
