백엔드 데이터 인프라 78편 — Redis Client 라이브러리 종합

이 글은 백엔드 데이터 인프라 시리즈 130편 중 78편이에요. 77편 까지 Redis 의 서버 기능 을 다 풀었으니, 마지막 Part 4-8 (2편) 은 클라이언트 — 애플리케이션이 Redis 와 어떻게 통신하는지 살펴볼 차례예요. 78편은 언어별 클라이언트 종합 + connection 모델·풀 패턴 을, 79편은 Java 의 Jedis vs Lettuce 를 깊이 다뤄요.

클라이언트 선택이 어렵게 느껴지는 이유

각 언어마다 클라이언트가 2~5개씩 있고, 거기에 공식 vs 비공식 갈래, 기능 차이, connection 모델 차이가 한꺼번에 겹쳐요.

첫째, 동기 vs 비동기 vs 반응형 모델 차이예요. 전통적 동기는 호출 하나하나가 블로킹이고, 비동기는 Future 로 응답을 받고, 반응형은 Reactive Streams (비동기 + 스트림 처리 표준) 로 흐름을 다뤄요. 어플리케이션 모델에 맞춰 골라야 해요.

둘째, Connection 모델 이에요. 어떤 클라이언트는 connection 하나에 클라이언트 하나가 붙고, 어떤 클라이언트는 connection 하나를 여러 요청이 multiplexing (한 연결을 여러 요청이 나눠 쓰기) 으로 공유해요. Connection Pool 사용법도 클라이언트마다 다르고요.

셋째, Cluster·Sentinel 지원 도 클라이언트마다 달라요. 오래된 클라이언트는 Cluster 자체를 지원하지 않거나, MOVED 응답 (다른 슬롯 노드로 이동하라는 redirect) 을 자동으로 처리하지 못해요.

언어별 공식 클라이언트

Redis 가 공식 maintain 하는 클라이언트:

각 클라이언트는 Redis 가 직접 유지하거나 공식 endorse 한 것들이라, 보통은 공식 추천 = 우선 선택 으로 보면 돼요.

연결 기본

대부분 클라이언트가 공통으로 받는 설정이에요.

• Host (localhost)
• Port (6379)
• DB number (0~15, ACL (Access Control List, 사용자별 권한) 환경에서는 사용 안 함)
• Username + Password (ACL) 또는 Password only (구버전)
• Unix Socket (같은 머신 통신, 빠름)

# Python redis-py
import redis
r = redis.Redis(host='localhost', port=6379, db=0,
                username='app', password='pass')

// Node.js node-redis
import { createClient } from 'redis';
const client = await createClient({
    url: 'redis://app:pass@localhost:6379/0'
}).connect();

// Java Jedis
Jedis jedis = new Jedis("localhost", 6379);
jedis.auth("app", "pass");

// Go go-redis
import "github.com/redis/go-redis/v9"
rdb := redis.NewClient(&redis.Options{
    Addr:     "localhost:6379",
    Username: "app",
    Password: "pass",
    DB:       0,
})

Connection Pool — 표준 패턴

TCP 연결을 매번 만들고 끊는 비용은 작지 않아요. 요청마다 새 connection 을 열면 성능이 크게 떨어져요. 그래서 Pool 로 재사용 하는 게 표준이에요.

Python redis-py — 기본 내장

pool = redis.ConnectionPool(host='localhost', port=6379, max_connections=20)
r = redis.Redis(connection_pool=pool)

redis.Redis() 자체가 내부적으로 pool 을 써요. 별도 설정 없이 그대로 써도 괜찮은 경우가 많아요.

Node.js — single connection or pool

// 단일 connection (multiplexing 내장)
const client = await createClient({...}).connect();

// 명시적 pool 은 ioredis 사용
import Redis from 'ioredis';
const cluster = new Redis.Cluster([{...}], {
    redisOptions: { password: '...' }
});

Java Jedis — Pool 필수

JedisPoolConfig config = new JedisPoolConfig();
config.setMaxTotal(50);
config.setMaxIdle(10);
config.setMinIdle(2);

JedisPool pool = new JedisPool(config, "localhost", 6379, 2000, "pass");
try (Jedis jedis = pool.getResource()) {
    jedis.set("key", "value");
}

Jedis 는 thread-safe 가 아니라서 Pool 을 반드시 써야 해요.

Java Lettuce — 공유 Connection

RedisClient client = RedisClient.create("redis://pass@localhost:6379");
StatefulRedisConnection<String, String> connection = client.connect();
RedisCommands<String, String> sync = connection.sync();
sync.set("key", "value");

Lettuce 는 thread-safe 라서 connection 하나를 여러 스레드가 같이 써요. Pool 이 따로 필요 없는 경우가 많고요.

Go go-redis — 내장 Pool

rdb := redis.NewClient(&redis.Options{
    Addr:         "localhost:6379",
    PoolSize:     20,
    MinIdleConns: 5,
})

동기 vs 비동기 vs 반응형

동기 (Synchronous)

가장 단순한 모델이에요. 각 명령이 응답이 올 때까지 블로킹돼요.

val = r.get('key')      # 응답 올 때까지 대기
process(val)

장점은 학습 곡선이 낮다는 점이고, 단점은 스레드를 점유한다는 점이에요. Tomcat 처럼 스레드 풀 모델로 동작하는 서버에는 영향이 커요.

비동기 (Asynchronous)

Future·Promise·Coroutine 기반이라, 응답을 기다리는 동안 스레드를 잡고 있지 않아요.

// Node.js
const val = await client.get('key');    // event loop 대기

// Lettuce async
RedisAsyncCommands<String, String> async = connection.async();
RedisFuture<String> future = async.get("key");
future.thenAccept(val -> process(val));

장점은 동시성이 높다는 점이에요. 적은 스레드로 많은 요청을 받을 수 있어요. 단점은 코드 복잡도가 올라간다는 점이고요.

반응형 (Reactive)

Reactive Streams (Mono/Flux) 모델이에요. 비동기에 backpressure (소비자가 감당할 수 있는 속도로 데이터 흐름을 조절) 가 더해진 형태예요.

// Spring WebFlux + Lettuce reactive
ReactiveRedisCommands<String, String> reactive = connection.reactive();
Mono<String> mono = reactive.get("key");

장점은 WebFlux·Reactor 환경에서 자연스럽게 녹는다는 점이고, 단점은 학습 곡선이 가장 높다는 점이에요.

선택

• 단순 백엔드 (Spring MVC·Express·Django) → 동기 (Jedis·redis-py 동기·node-redis)
• 고동시성·이벤트 기반 (WebFlux·Node.js·고성능 API) → 비동기 / 반응형 (Lettuce reactive·node-redis·ioredis)
• 이미 reactive stack → 반응형 (Lettuce reactive)

Cluster · Sentinel 지원

각 클라이언트의 지원 정도가 다르니 확인하고 골라야 해요.

오래된 버전은 지원이 부실해서 최신 버전 사용 권장 이에요.

RESP 프로토콜 — Wire 형식

여기까지 따라오셨다면 한 가지 의문이 생겨요. "클라이언트들이 어떤 형식으로 통신하나?". 답은 RESP (REdis Serialization Protocol, Redis 의 텍스트 기반 통신 규약) 예요.

예제

Client → Server: SET key value
실제 wire:
  *3\r\n
  $3\r\n
  SET\r\n
  $3\r\n
  key\r\n
  $5\r\n
  value\r\n

• *N = N 개 원소의 배열
• $N = N 바이트 bulk string
• +OK = simple string
• -ERR = error
• :N = integer

매우 단순한 텍스트 기반 프로토콜이라, telnet (원격 텍스트 통신용 기본 도구) 으로 Redis 에 직접 명령을 보내는 것도 가능해요.

$ telnet localhost 6379
SET key value
+OK
GET key
$5
value

RESP2 vs RESP3

• RESP2 = 기본
• RESP3 = Redis 6+, 더 풍부한 타입 (Map·Set·Push·Big Number 등)

HELLO 3 명령으로 RESP3 를 협상해요. 클라이언트가 지원하면 자동으로 올라가요.

Best Practices

1. Connection Reuse

매 요청마다 새 connection 을 여는 건 절대 금지예요. Pool 또는 공유 connection 으로 가야 해요.

2. Timeout 설정

connect timeout 과 read timeout 을 꼭 명시해 두세요. 기본값이 무한 대기인 경우가 많아서, 네트워크가 막히면 응답이 영영 안 올 수 있어요.

r = redis.Redis(socket_connect_timeout=5, socket_timeout=2)

3. Pipelining 적극 활용

57편에서 깊이 다뤘어요. 반복되는 명령은 Pipelining 으로 묶어 보내세요.

4. Error 처리

Connection error·timeout·NOAUTH·CROSSSLOT·NOSCRIPT 같은 에러를 각각 구체적으로 잡아 처리해야 해요.

5. Cluster-aware 클라이언트

Cluster 환경이라면 반드시 Cluster-aware 클라이언트를 써야 해요. 단일 노드 클라이언트로 Cluster 에 붙으면 MOVED 가 무한히 redirect 돼요.

6. Monitoring

CLIENT LIST·INFO clients·SLOWLOG 같은 명령으로 연결 상태와 느린 명령을 모니터링하세요.

한계·실무 함정

1. Connection leak

try-with-resources 같은 자동 해제 패턴을 안 쓰면 connection 이 계속 쌓여서 pool exhaustion 으로 이어져요.

2. 동기 클라이언트로 blocking 명령

Jedis 같은 동기 클라이언트로 BLPOP 0 처럼 영원히 대기하는 명령을 쓰면, 스레드가 영원히 묶여요. 별도 connection 을 쓰거나 timeout 을 설정해야 해요.

3. Pub/Sub 모드의 connection 제약

58편에서 본 대로, Pub/Sub 모드에 들어간 connection 에서는 일반 명령을 쓸 수 없어요. 별도 connection 이 필요하고요.

4. Cluster 환경 multi-key

위에서도 짚었지만, 클라이언트가 MOVED 를 자동으로 처리하더라도 multi-key 명령 (한 번에 여러 키를 다루는 MGET·MSET·SINTER 등) 은 CROSSSLOT 에러를 내요.

5. 오래된 클라이언트 버전

보안 패치가 빠져 있거나 신규 기능이 없을 수 있어서, 정기적으로 업데이트해 주세요.

시험 직전 한 번 더 — Redis Client 함정 압축 노트

• 공식 클라이언트 — Python redis-py / Node node-redis / Java Jedis·Lettuce / Go go-redis / .NET StackExchange.Redis
• 비공식 인기 = ioredis (Node) · Redisson (Java HA)
• 연결 기본 = host·port·db·username·password (ACL)
• Connection Pool 필수 — 매 요청 새 connection 금지
• redis-py = 자동 pool / Node = multiplexing / Jedis = JedisPool 필수 / Lettuce = thread-safe 공유 / Go = 내장 pool
• 동기 vs 비동기 vs 반응형 — Spring MVC = 동기 / WebFlux = 반응형 / 고동시성 = 비동기
• Cluster·Sentinel 지원 = 최신 버전만 풍부
• RESP 프로토콜 = Redis wire 형식, 텍스트 기반 단순
• *N 배열 / $N bulk string / +OK / -ERR / :N
• RESP2 vs RESP3 = Redis 6+ 풍부한 타입 (HELLO 3 협상)
• Best Practice — Connection reuse, Timeout 명시, Pipelining 적극, Error 구체적, Cluster-aware, 모니터링
• 함정 — Connection leak (try-with-resources)
• 함정 — 동기 클라이언트 blocking 명령 = 스레드 점유
• 함정 — Pub/Sub 모드 = 별도 connection
• 함정 — Cluster multi-key = CROSSSLOT
• 함정 — 오래된 버전 = 보안·기능 누락

공식 문서: Redis Client Libraries 에서 모든 공식 클라이언트 목록과 가이드를 확인할 수 있어요.

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 73편 — Spring Data Redis (RedisTemplate · @Cacheable)
• 74편 — RedisJSON (JSON.SET · JSONPath · PG JSONB 비교)
• 75편 — RediSearch (FT.CREATE · FT.SEARCH · FT.AGGREGATE)
• 76편 — Redis Time Series (TS.ADD · Labels · Compaction)
• 77편 — Redis Vector Database (HNSW · 코사인 유사도 · RAG)

다음 글:

• 79편 — Java Redis Client (Jedis vs Lettuce 깊이)
• 80편 — Apache Kafka란 + 이벤트 스트리밍의 표준
• 81편 — Kafka 활용 영역 7가지 (메시징·활동 추적·로그·이벤트 소싱)
• 82편 — Kafka Quickstart (5분 hands-on · topic·producer·consumer)
• 83편 — Kafka Design: Motivation (왜 이렇게 설계됐나)