Go + Redis: библиотека go-redis
Стандартный клиент для Go - github.com/redis/go-redis/v9. Он официальный, поддерживает все возможности Redis 7, имеет встроенный connection pool, pipeline, transactions, pub/sub, streams, cluster.
go get github.com/redis/go-redis/v9
В PHP два основных варианта: predis/predis (чистый PHP, ставится через composer без extension) и ext-redis (C-расширение, быстрее, но требует pecl). В Symfony-проектах удобно использовать \Redis через Symfony\Component\Cache\Adapter\RedisAdapter - получаешь PSR-6/PSR-16 API поверх любого из двух драйверов.
composer require predis/predis
# или
composer require symfony/cache
Подключение и connection pool
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
Password: "",
DB: 0,
PoolSize: 10, // максимум коннектов
MinIdleConns: 5, // прогретые коннекты
DialTimeout: 5 * time.Second,
ReadTimeout: 3 * time.Second,
WriteTimeout: 3 * time.Second,
PoolTimeout: 4 * time.Second, // ожидание свободного коннекта
MaxRetries: 3, // retry на network errors
// Без этого флага go-redis игнорирует дедлайн и отмену ctx при сетевом I/O
// и ждёт ответа до ReadTimeout (см. раздел «Context и timeouts»)
ContextTimeoutEnabled: true,
})
if err := rdb.Ping(ctx).Err(); err != nil {
log.Fatal("redis connection failed:", err)
}
<?php
declare(strict_types=1);
use Predis\Client;
$redis = new Client(
parameters: [
'scheme' => 'tcp',
'host' => 'localhost',
'port' => 6379,
'timeout' => 5.0,
'read_write_timeout' => 3.0,
],
options: [
'parameters' => ['database' => 0],
// connection pool в FPM/CLI обычно не нужен:
// каждый запрос - свой процесс, коннект живёт пока обрабатывается запрос.
// Для persistent connection см. 'persistent' => true в parameters.
],
);
try {
$redis->ping();
} catch (Predis\Connection\ConnectionException $e) {
throw new RuntimeException('redis connection failed: ' . $e->getMessage(), previous: $e);
}
import logging
import redis
from redis.backoff import ExponentialBackoff
from redis.retry import Retry
# Пул соединений встроен в redis.Redis: один клиент на приложение,
# коннект берётся из пула на время команды и возвращается обратно.
rdb = redis.Redis(
host="localhost",
port=6379,
password=None,
db=0,
max_connections=10, # максимум коннектов
socket_connect_timeout=5.0, # DialTimeout
socket_timeout=3.0, # Read/WriteTimeout
retry=Retry(ExponentialBackoff(), 3), # retry на network errors
retry_on_error=[redis.ConnectionError, redis.TimeoutError],
decode_responses=True, # str вместо bytes в ответах
)
# Прогретых коннектов (MinIdleConns) в redis-py нет: пул ленивый.
# Ожидание свободного коннекта (PoolTimeout) даёт только
# redis.BlockingConnectionPool(timeout=4.0); обычный пул сразу бросает
# ConnectionError, когда все max_connections заняты.
try:
rdb.ping()
except redis.ConnectionError as e:
logging.critical("redis connection failed: %s", e)
raise SystemExit(1) from e
В PHP-FPM нет горутин и общего pool - каждый воркер держит свой коннект. Persistent connection ('persistent' => true) реюзает TCP между запросами в рамках одного FPM-воркера. Под высокой нагрузкой это даёт основной выигрыш, аналогичный MinIdleConns в Go.
PoolSize обычно ставят равным числу одновременных горутин, которые могут активно выполнять Redis-команды. Для типичного HTTP-сервиса с 100 RPS и операциями <1ms подойдёт 10-20.
Основные операции
Strings
rdb.Set(ctx, "key", "value", 5*time.Minute)
val, err := rdb.Get(ctx, "key").Result()
if errors.Is(err, redis.Nil) {
// ключ не существует - это нормальный кейс, не ошибка
}
redis.Nil - sentinel error. Игнорируйте его как «нет данных», а не как «сбой».
<?php
declare(strict_types=1);
$redis->setex('key', 300, 'value'); // TTL = 5 минут
$val = $redis->get('key');
if ($val === null) {
// ключ отсутствует - предсказуемый cache miss, не ошибка
}
В predis get() возвращает null при отсутствии ключа (в phpredis - false). Это аналог redis.Nil в Go: не путай с настоящей ошибкой - проверяй явно тип возврата, а не пытайся ловить исключение.
from datetime import timedelta
rdb.set("key", "value", ex=timedelta(minutes=5))
val = rdb.get("key")
if val is None:
# ключ не существует - это нормальный кейс, не ошибка
...
В redis-py get() возвращает None при отсутствии ключа - аналог redis.Nil. Отдельного исключения нет: проверяй значение явно, исключения клиент бросает только на сетевые и серверные ошибки.
Hashes со scan-ом в struct
rdb.HSet(ctx, "user:1", map[string]any{"name": "Alice", "age": 30})
var user struct {
Name string `redis:"name"`
Age int `redis:"age"`
}
if err := rdb.HGetAll(ctx, "user:1").Scan(&user); err != nil {
return err
}
Тег redis: мапит поле структуры на ключ хеша. Поля без тега Scan молча пропускает (они останутся нулевыми), поэтому тег нужен на каждом поле. Удобно для структур с десятками полей.
<?php
declare(strict_types=1);
// HSET принимает несколько пар поле-значение; HMSET устарел с Redis 4.0
$redis->hset('user:1', 'name', 'Alice', 'age', 30);
$data = $redis->hgetall('user:1');
// $data = ['name' => 'Alice', 'age' => '30'] - все значения строки
final readonly class User
{
public function __construct(
public string $name,
public int $age,
) {}
public static function fromHash(array $hash): self
{
return new self(
name: $hash['name'] ?? '',
age: (int) ($hash['age'] ?? 0),
);
}
}
$user = User::fromHash($data);
В PHP нет тегов на полях, как в Go-struct. Стандартный приём - именованный конструктор fromHash() (или Symfony Serializer с NameConverterInterface) для каста типов из Redis-строк.
from dataclasses import dataclass
rdb.hset("user:1", mapping={"name": "Alice", "age": 30})
@dataclass(slots=True)
class User:
name: str
age: int
@classmethod
def from_hash(cls, data: dict[str, str]) -> "User":
# Redis хранит все значения хеша строками: типы приводим здесь
return cls(name=data.get("name", ""), age=int(data.get("age", 0)))
user = User.from_hash(rdb.hgetall("user:1"))
Тегов на полях, как в Go-struct, здесь тоже нет: приведение типов из Redis-строк делает именованный конструктор from_hash() (или pydantic-модель через model_validate, она приведёт "30" к int сама).
Counter
views, err := rdb.Incr(ctx, "page:views").Result()
// атомарный инкремент, не нужен мьютекс
<?php
declare(strict_types=1);
$views = $redis->incr('page:views');
// атомарный инкремент, безопасен между FPM-воркерами
views = rdb.incr("page:views")
# атомарный инкремент, не нужен threading.Lock
Pipelining
Каждая команда - round-trip (RTT). 100 SET = 100 RTT × 0.5ms = 50ms. С pipeline всё в одном запросе:
pipe := rdb.Pipeline()
for i := 0; i < 100; i++ {
pipe.Set(ctx, fmt.Sprintf("key:%d", i), i, time.Hour)
}
cmds, err := pipe.Exec(ctx) // 1 RTT
Exec возвращает все ответы. Каждый cmd.Err() нужно проверить - pipeline не fail-fast: если одна команда упала, остальные всё равно выполнятся.
<?php
declare(strict_types=1);
$responses = $redis->pipeline(static function ($pipe): void {
for ($i = 0; $i < 100; $i++) {
$pipe->setex('key:' . $i, 3600, (string) $i);
}
});
// $responses - массив ответов в порядке команд, 1 RTT
В predis pipeline() принимает замыкание - все команды внутри буферизуются и отправляются одним батчем. В phpredis есть multi(\Redis::PIPELINE) ... exec() - семантика та же.
from datetime import timedelta
with rdb.pipeline(transaction=False) as pipe:
for i in range(100):
pipe.set(f"key:{i}", i, ex=timedelta(hours=1))
responses = pipe.execute() # 1 RTT
execute() возвращает список ответов в порядке команд. По умолчанию pipeline() в redis-py оборачивает батч в MULTI/EXEC; transaction=False даёт чистый pipeline, как в Go. Ошибка одной команды поднимается исключением после выполнения всех остальных, а с execute(raise_on_error=False) вернётся элементом списка - проверять нужно каждый ответ, как cmd.Err().
Transactions через MULTI/EXEC
err := rdb.Watch(ctx, func(tx *redis.Tx) error {
n, err := tx.Get(ctx, "counter").Int()
if err != nil && !errors.Is(err, redis.Nil) {
return err
}
_, err = tx.TxPipelined(ctx, func(pipe redis.Pipeliner) error {
pipe.Set(ctx, "counter", n+1, 0)
return nil
})
return err
}, "counter")
Watch реализует optimistic locking: если ключ изменился между Get и Exec, транзакция проваливается с redis.TxFailedErr и можно повторить.
<?php
declare(strict_types=1);
use Predis\Transaction\AbortedMultiExecException;
try {
$responses = $redis->transaction(['cas' => true, 'watch' => 'counter'], static function ($tx): void {
$current = (int) ($tx->get('counter') ?? 0);
$tx->multi();
$tx->set('counter', (string) ($current + 1));
});
} catch (AbortedMultiExecException) {
// counter изменили между WATCH и EXEC - повторяем
}
В predis опция 'cas' => true (Check-And-Set) включает режим оптимистической блокировки: WATCH + чтение происходят до MULTI, а при изменении ключа транзакция отменяется через исключение. В phpredis это watch() + multi() + exec() напрямую.
import redis
def increment(pipe: redis.client.Pipeline) -> None:
# после WATCH pipe выполняет команды сразу, до multi() - это чтение
current = pipe.get("counter")
n = int(current) if current is not None else 0
pipe.multi()
pipe.set("counter", n + 1)
# transaction(): WATCH counter, вызов функции, EXEC. Если ключ изменился,
# EXEC падает с WatchError - хелпер ловит его и повторяет функцию сам.
rdb.transaction(increment, "counter")
transaction() - аналог Watch в go-redis, только retry уже встроен. Без хелпера то же самое делается вручную: pipe.watch("counter"), чтение, pipe.multi(), pipe.execute() в цикле с except redis.WatchError.
Сериализация структур
type Session struct {
UserID string `json:"user_id"`
CreatedAt time.Time `json:"created_at"`
}
func SetSession(ctx context.Context, rdb *redis.Client, id string, sess Session) error {
data, err := json.Marshal(sess)
if err != nil {
return err
}
return rdb.Set(ctx, "session:"+id, data, 24*time.Hour).Err()
}
func GetSession(ctx context.Context, rdb *redis.Client, id string) (*Session, error) {
data, err := rdb.Get(ctx, "session:"+id).Bytes()
if errors.Is(err, redis.Nil) {
return nil, nil
}
if err != nil {
return nil, err
}
var sess Session
return &sess, json.Unmarshal(data, &sess)
}
Для бо́льшей плотности и скорости - msgpack или protobuf. Бинарные форматы экономят 30-50% памяти Redis.
<?php
declare(strict_types=1);
use Predis\Client;
final readonly class Session
{
public function __construct(
public string $userId,
public DateTimeImmutable $createdAt,
) {}
}
final readonly class SessionRepository
{
public function __construct(private Client $redis) {}
public function set(string $id, Session $session): void
{
$payload = json_encode([
'user_id' => $session->userId,
'created_at' => $session->createdAt->format(DateTimeInterface::ATOM),
], JSON_THROW_ON_ERROR);
$this->redis->setex('session:' . $id, 86400, $payload);
}
public function get(string $id): ?Session
{
$raw = $this->redis->get('session:' . $id);
if ($raw === null) {
return null;
}
$data = json_decode($raw, associative: true, flags: JSON_THROW_ON_ERROR);
return new Session(
userId: $data['user_id'],
createdAt: new DateTimeImmutable($data['created_at']),
);
}
}
Для бинарных форматов в PHP: msgpack/msgpack-php (extension) или rybakit/msgpack (чистый PHP). В Symfony - Symfony\Component\Serializer с MessagePackEncoder решает то же самое декларативно.
import json
from dataclasses import dataclass
from datetime import datetime, timedelta
import redis
@dataclass(slots=True)
class Session:
user_id: str
created_at: datetime
def set_session(rdb: redis.Redis, session_id: str, sess: Session) -> None:
data = json.dumps({
"user_id": sess.user_id,
"created_at": sess.created_at.isoformat(),
})
rdb.set(f"session:{session_id}", data, ex=timedelta(hours=24))
def get_session(rdb: redis.Redis, session_id: str) -> Session | None:
data = rdb.get(f"session:{session_id}")
if data is None:
return None
raw = json.loads(data)
return Session(
user_id=raw["user_id"],
created_at=datetime.fromisoformat(raw["created_at"]),
)
Для бинарных форматов - пакет msgpack или protobuf. pickle для кеша не бери: он выполняет код при десериализации, а содержимое Redis могли подменить. Декларативно сериализацию решает pydantic: model_dump_json() / model_validate_json().
Context и timeouts
context.Context пробрасывается во все методы - это критично:
ctx, cancel := context.WithTimeout(r.Context(), 100*time.Millisecond)
defer cancel()
val, err := rdb.Get(ctx, "key").Result()
Если HTTP-handler отменён (клиент закрыл соединение) или истёк дедлайн, отменяется и Redis-команда. Это спасает от накопления зависших коннектов в pool, когда Redis тормозит.
Важная оговорка: в go-redis v9 это работает только с ContextTimeoutEnabled: true в redis.Options (как в примере подключения выше). По умолчанию флаг выключен: клиент берёт из ctx только отмену до отправки команды, а ответ ждёт по своим ReadTimeout/WriteTimeout (3 секунды в нашем примере). Без флага 100ms-таймаут из примера фактически не действует.
<?php
declare(strict_types=1);
// В predis timeout задаётся на уровне коннекта - per-command таймаута нет.
$redis = new Predis\Client([
'host' => 'localhost',
'port' => 6379,
'timeout' => 5.0, // connection timeout
'read_write_timeout' => 0.1, // read timeout - 100ms на команду
]);
try {
$val = $redis->get('key');
} catch (Predis\Connection\ConnectionException $e) {
// таймаут чтения - fallback на источник правды
$val = null;
}
В PHP-FPM нет context.Context: модель «один запрос = один воркер» уже изолирует время жизни. Таймаут задаётся на уровне TCP-сокета через read_write_timeout. Если клиент отключился - проверь через connection_aborted() или включи ignore_user_abort(false) для досрочного выхода.
import redis
# В redis-py нет context.Context: таймаут задаётся на уровне сокета
# при создании клиента и действует на каждую команду.
rdb = redis.Redis(
host="localhost",
port=6379,
socket_connect_timeout=5.0, # connection timeout
socket_timeout=0.1, # 100ms на ответ каждой команды
)
try:
val = rdb.get("key")
except redis.TimeoutError:
# таймаут чтения - fallback на источник правды
val = None
Отмены по разрыву HTTP-соединения в синхронном клиенте нет: команда доработает до ответа или до socket_timeout. Ближайший аналог context.WithTimeout - в asyncio-стеке: redis.asyncio.Redis плюс asyncio.wait_for(rdb.get("key"), timeout=0.1); там отмена задачи обработчика (FastAPI, aiohttp) отменяет и ожидание ответа Redis.
Error handling
Типичные ошибки:
val, err := rdb.Get(ctx, "key").Result()
switch {
case errors.Is(err, redis.Nil):
// нет ключа - нормальный путь cache miss
case errors.Is(err, context.DeadlineExceeded) || isNetTimeout(err):
// timeout - fallback на БД, метрика
case err != nil:
// сетевая ошибка, OOM на сервере и т. д.
log.Error("redis", "err", err)
}
// Таймаут сокета (ReadTimeout) приходит не как context.DeadlineExceeded,
// а как net.Error с Timeout() == true ("i/o timeout")
func isNetTimeout(err error) bool {
var netErr net.Error
return errors.As(err, &netErr) && netErr.Timeout()
}
<?php
declare(strict_types=1);
use Predis\Connection\ConnectionException;
use Predis\Response\ServerException;
try {
$val = $redis->get('key');
if ($val === null) {
// нормальный cache miss - идём в БД
return $this->loadFromDatabase($key);
}
return $val;
} catch (ConnectionException $e) {
// сеть/таймаут - читаем источник правды и логируем
$this->logger->warning('redis unavailable', ['error' => $e->getMessage()]);
return $this->loadFromDatabase($key);
} catch (ServerException $e) {
// OOM, WRONGTYPE, READONLY на реплике - тоже fallback
$this->logger->error('redis server error', ['error' => $e->getMessage()]);
return $this->loadFromDatabase($key);
}
В Go ошибки возвращаются значениями, в PHP - кидаются исключениями. Симметрия в обработке: redis.Nil = null, ConnectionException/DeadlineExceeded = timeout, ServerException = всё прочее. Логика fallback одинакова.
import logging
import redis
logger = logging.getLogger(__name__)
def get_cached(key: str) -> str:
try:
val = rdb.get(key)
except redis.TimeoutError as e:
# timeout - fallback на БД, метрика
logger.warning("redis timeout", extra={"err": str(e)})
return load_from_database(key)
except redis.ConnectionError as e:
# сетевая ошибка - читаем источник правды и логируем
logger.warning("redis unavailable", extra={"err": str(e)})
return load_from_database(key)
except redis.ResponseError as e:
# OOM, WRONGTYPE, READONLY на реплике - ошибка от сервера, тоже fallback
logger.error("redis server error", extra={"err": str(e)})
return load_from_database(key)
if val is None:
# нет ключа - нормальный путь cache miss, идём в БД
return load_from_database(key)
return val
Та же симметрия: redis.Nil = None, DeadlineExceeded = redis.TimeoutError, сетевой сбой = redis.ConnectionError, ответ сервера с -ERR = redis.ResponseError. Все они наследуют redis.RedisError, так что общий fallback можно написать одним except redis.RedisError, если различать причины не нужно.
Правило: при ошибке Redis в кеше - fallback на источник правды (БД), а не ошибка пользователю. Кеш - оптимизация, не зависимость.
OpenTelemetry instrumenting
import "github.com/redis/go-redis/extra/redisotel/v9"
if err := redisotel.InstrumentTracing(rdb); err != nil {
log.Fatal(err)
}
if err := redisotel.InstrumentMetrics(rdb); err != nil {
log.Fatal(err)
}
Каждая Redis-команда станет client span с атрибутами db.system=redis, db.statement=GET key. Это ценно для трассировки: видно, сколько RTT в кеш ушло на запрос.
<?php
declare(strict_types=1);
use OpenTelemetry\API\Trace\TracerInterface;
use Predis\Client;
final readonly class TracedRedis
{
public function __construct(
private Client $redis,
private TracerInterface $tracer,
) {}
public function get(string $key): ?string
{
$span = $this->tracer->spanBuilder('redis.GET')
->setAttribute('db.system', 'redis')
->setAttribute('db.statement', 'GET ' . $key)
->startSpan();
try {
return $this->redis->get($key);
} finally {
$span->end();
}
}
}
Готовый OpenTelemetry-инструментатор для predis есть в open-telemetry/opentelemetry-auto-predis (auto-instrumentation через расширение ext-opentelemetry). Альтернатива - явная обёртка, как в примере, или middleware-pattern в Symfony через декорацию CacheInterface.
import redis
from opentelemetry.instrumentation.redis import RedisInstrumentor
# пакет opentelemetry-instrumentation-redis: патчит клиент один раз на процесс,
# вызывать до создания redis.Redis
RedisInstrumentor().instrument()
rdb = redis.Redis(host="localhost", port=6379)
Инструментатор делает из каждой команды client span с db.system=redis и db.statement=GET key - как InstrumentTracing. Аналога InstrumentMetrics в нём нет: метрики пула (pool_hits/pool_misses) собирай через prometheus_client поверх rdb.connection_pool или бери их со стороны сервера через redis-exporter.
Типичные ошибки
- Сравнение
err == nilбез обработкиredis.Nil- cache miss возвращает неnil, а специальныйredis.Nil. Безerrors.Is(err, redis.Nil)будешь логировать «ошибки» при штатном промахе кеша. - Reuse одного
*redis.Clientзабыт - создаётся новый клиент в каждом handler-е. Каждый - свой connection pool, под нагрузкой ловишьEMFILE: too many open files. Один клиент на приложение, передавать через DI. PoolSizeпо умолчанию (10× CPU) - для большинства API избыточно: коннекты простаивают, БД-кеш растёт. На малом сервисе ставь 10-20, наблюдай заpool_hits/pool_missesв метриках.- Команды без
ctx-rdb.Get(context.Background(), key)игнорирует отмену запроса. HTTP-handler закрыл клиент - Redis-команда висит в pool ещё секунды. Всегда пробрасывайr.Context()илиctxсо своим deadline. - Pipelining как «магия скорости» вне batch-сценариев - для одиночной команды pipeline ничего не ускоряет; зато код становится сложнее (обработка ошибок на каждый Cmd). Используй когда есть ≥10 независимых команд на один HTTP-запрос.
- MULTI/EXEC ≠ acid-транзакция как в SQL - внутри блока команды копятся локально, выполняются атомарно одним блоком, но не откатываются при ошибке одной команды. Это «pipeline с гарантией порядка», не SQL TRANSACTION.
- JSON в каждый запрос -
json.Marshal/Unmarshalкрупных структур на горячем пути ест CPU больше самого Redis. Если кеш - горячий и часто читаемый -msgpack/gob/protobufсокращают и payload, и CPU в 2-5 раз.
Мини-практика
Напиши сервис сессий: создание, чтение, удаление через go-redis. TTL 30 минут, обновляется при каждом обращении (sliding session). Используй pipeline для batch-операций, обработай redis.Nil как cache miss, добавь timeout 100ms через context. Подключи OpenTelemetry-инструментирование и посмотри спаны в Jaeger.