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.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.