Отдельные статьи разбирают части стека по одной: конфигурацию, остановку, кэш, брокер, образы, Kubernetes, трейсы. Эта серия собирает их на одном сервисе и проводит его от первой строки кода до кластера и нагрузки. Сервис — короткие ссылки с аналитикой кликов: создать ссылку, отдать редирект, посчитать клики. Домен нарочно простой: за ним не прячутся решения, которые надо принять в любом backend.
Первая статья серии «От кода до прода: сервис с нуля» — про сам процесс сервиса. У него четыре границы, где чаще всего ломается то, что «работало у меня»: старт с неверной конфигурацией, остановка под трафиком, отказ зависимости и залп запросов по холодному ключу. Каждая граница проверена опытом на стенде, у каждого опыта есть контроль — тот же сценарий там, где защита выключена.
Сервис
Два процесса. Сервис на Go 1.27 принимает API и отдаёт редиректы, клики публикует в NATS JetStream. Consumer на Java 25 читает клики из брокера и складывает их в агрегат по минутам в PostgreSQL. Почему consumer на Java: в реальной системе аналитику часто пишет другая команда на другом стеке, и стыки между языками — заголовки трейсов, форматы событий, семантика доставки — проверяются только так.
flowchart LR
C[клиент] -->|POST /links| S[service · Go]
C -->|GET /code| S
S -->|cache-aside| R[(Redis)]
S -->|ссылки, outbox| P[(PostgreSQL)]
S -->|клики| N[[NATS JetStream]]
N --> J[consumer · Java]
J -->|clicks_by_minute| P
API — три маршрута и две пробы:
| маршрут | что делает |
|---|---|
POST /links |
создаёт ссылку, отвечает кодом из 7 символов base62 |
GET /{code} |
редирект 302, клик уходит в брокер |
GET /links/{code}/stats |
число кликов из агрегата consumer’а |
GET /healthz |
процесс жив |
GET /readyz |
процесс готов принимать трафик; при остановке — 503 |
Горячий путь — редирект: он идёт через Redis, и база видит его только при промахе кэша. Клик не должен задерживать редирект, поэтому публикация асинхронная, через ограниченный буфер; что при этом теряется и как outbox меняет картину — во второй статье.
Код разложен по пакетам с одной ответственностью: links — домен и его
ошибки, store — PostgreSQL, cache — Redis, events — брокер, httpapi —
маршруты и отображение ошибок в коды ответа, config — конфигурация. Домен не
знает ни про HTTP, ни про Redis: links.Service получает хранилище,
резолвер кэша и публикатор кликов через интерфейсы, и тесты домена обходятся
без инфраструктуры.
Стенд — digital-cookbook/capstone/shortlinks: сервис, consumer, docker compose для осей этой статьи и манифесты для кластера из третьей. Все опыты запускает одна команда, результат каждой оси — строка фикстуры с пороговыми признаками.
Граница первая: старт
Конфигурация — только переменные окружения, как
в статье о конфигурации из env.
Важно не то, откуда её читать, а когда она признана верной. Сервис, который
стартовал, открыл порт, прошёл проверку готовности и упал на первом запросе
из-за опечатки в PUBLISH_MODE, хуже сервиса, который не стартовал вовсе:
выкатка уже признала его здоровым и начала гасить старую версию.
Поэтому конфигурация читается целиком и проверяется до того, как создано хоть одно соединение, а ошибки собираются все, а не до первой:
// internal/config/config.go
// LoadService собирает конфигурацию и возвращает все ошибки сразу, а не первую.
func LoadService() (Service, error) {
r := reader{}
c := Service{
Addr: r.str("HTTP_ADDR", ":8080"),
DatabaseURL: r.required("DATABASE_URL"),
RedisAddr: r.str("REDIS_ADDR", ""),
NatsURL: r.str("NATS_URL", ""),
PublishMode: r.oneOf("PUBLISH_MODE", "async", "async", "sync"),
PublishBuffer: r.intRange("PUBLISH_BUFFER", 1024, 1, 1<<20),
Неверное значение не заменяется молча значением по умолчанию: oneOf,
intRange и duration записывают ошибку, и main выходит с кодом 2 до
открытия порта. Кроме значений проверяются связи между ними: пауза перед
остановкой должна быть меньше общего времени остановки, иначе на дренаж не
останется ничего.
Опыт — контейнер с тремя ошибками сразу: нет DATABASE_URL,
PUBLISH_MODE=fast, DB_MAX_CONNS=0. Контроль — тот же образ с верной
конфигурацией:
$ python3 scripts/run-checks.py config
{"variant": "config", "outcome": "match", "detail": "неверная конфигурация: код выхода 2, названы все ошибки сразу — да, порт не открывался — да; верная — сервис готов: да"}
Сообщение, с которым процесс вышел до открытия порта:
конфигурация: DATABASE_URL не задана; PUBLISH_MODE=“fast”: допустимо async, sync; DB_MAX_CONNS=“0”: целое от 1 до 1000
Все три ошибки в одном сообщении — это не косметика: при ошибке по одной каждая следующая обнаруживается только после исправления предыдущей и нового деплоя.
Граница вторая: остановка
Остановка — штатная часть жизни сервиса: каждая выкатка гасит все старые экземпляры. Разбор механики — в статье о graceful shutdown; здесь — порядок шагов, который выдерживает и балансировщик, и брокер:
// cmd/service/main.go
// 1. снять готовность: балансировщик перестаёт слать новые запросы;
// 2. подождать, пока он это заметит (в Kubernetes — период опроса readiness);
// 3. закрыть приём и дождаться незавершённых запросов;
// 4. опубликовать клики, оставшиеся в буфере, и только потом закрыть соединения.
// Всё — в одном сроке SHUTDOWN_TIMEOUT: что не уложилось, прерывается и считается.
ready.Store(false)
slog.Info("готовность снята", "delay", cfg.ShutdownDelay)
time.Sleep(cfg.ShutdownDelay)
// Бюджет остановки делится: HTTP и публикатор — до deadline-telemetryShare, выгрузка трейсов — последняя
// доля. Иначе медленный Collector держал бы процесс после SHUTDOWN_TIMEOUT: Shutdown SDK ждёт выгрузку.
deadline := time.Now().Add(cfg.ShutdownTimeout - cfg.ShutdownDelay)
reserve := time.Duration(0)
if cfg.OtelEndpoint != "" {
reserve = telemetryShare
}
sctx, cancel := context.WithDeadline(context.Background(), deadline.Add(-reserve))
defer cancel()
inTime := true
if err := srv.Shutdown(sctx); err != nil && !errors.Is(err, http.ErrServerClosed) {
// срок истёк, а запросы ещё в работе: отменить их контексты и закрыть соединения. Без этого
// отложенный pool.Close() ждал бы запрос, застрявший в базе, сколько бы тот ни длился.
inTime = false
abort()
_ = srv.Close()
slog.Warn("срок остановки истёк: незавершённые запросы прерваны", "err", err)
}
if pub != nil {
// тот же срок sctx: если он уже истёк, остаток буфера не публикуется, а считается
if unsent := pub.Close(sctx); unsent > 0 {
slog.Warn("клики не опубликованы до срока остановки", "unsent", unsent)
}
}
tctx, tcancel := context.WithDeadline(context.Background(), deadline)
defer tcancel()
tracingDone = true
if err := shutdownTracing(tctx); err != nil {
slog.Warn("трейсы не выгружены до срока остановки", "err", err)
}
if inTime {
slog.Info("остановлен штатно")
} else {
slog.Info("остановлен по сроку")
}
Шаг 2 кажется лишним, пока сервис стоит за одним балансировщиком на той же машине. В кластере между «под перестал быть готовым» и «трафик на него больше не идёт» проходит время: kubelet опрашивает пробу, контроллер обновляет EndpointSlice, kube-proxy или Cilium перестраивают правила. Без паузы сервис закрывает приём раньше, чем его перестают звать. Сколько запросов это стоит на живом кластере — в третьей статьеготовится, с 2 декабря.
Шаг 4 — порядок закрытия зависимостей: буфер кликов опустошается после того,
как HTTP-сервер дождался последнего запроса (запрос может ещё положить клик),
и до закрытия соединения с брокером. И у этого шага тот же срок, что у
остальных. Каждая публикация ждёт брокер до двух секунд; без общего срока
полный буфер при недоступном брокере ждал бы его по очереди для каждого
клика и пережил бы и SHUTDOWN_TIMEOUT, и terminationGracePeriodSeconds —
процесс убил бы SIGKILL посреди дренажа, и о потере не осталось бы следа.
Close получает контекст остановки: по истечении срока остаток буфера не
публикуется, а считается и попадает в лог и в метрику
clicks_unsent_on_shutdown_total.
Тот же срок держит и сами запросы. srv.Shutdown по истечении срока
возвращает ошибку, но обработчики, которые ещё работают, не останавливает: их
контексты живы. Если такой обработчик ждёт PostgreSQL, отложенный
pool.Close() будет ждать его соединение, сколько бы ни длился запрос. Поэтому
контексты всех запросов наследуются от общего base (BaseContext у
http.Server), и после ошибки Shutdown он отменяется, а соединения
закрываются. pgx отменяет запрос к базе, соединение возвращается в пул, и
закрытие пула укладывается в срок. Публикатор при этом всё равно получает
свой Close — раньше ошибка Shutdown выходила из функции до него.
Два места в этом порядке легко пропустить. Первое — клик, который приходит
после закрытия буфера. Отмена контекста не останавливает горутину
обработчика: тот, кто уже дошёл до публикации, может положить клик в очередь
после close, и Go ответит паникой «send on closed channel». Проверка «закрыт
ли буфер» и сама отправка поэтому идут под одной блокировкой чтения, а
закрытие — под блокировкой записи; поздний клик отклоняется и считается в
clicks_late_after_close_total. Гонку ловит тест: двести раундов, шестнадцать
горутин шлют клики, пока идёт Close, — без блокировки он падает с паникой,
с ней каждый клик учтён ровно в одном исходе.
Второе — трейсы. SDK OpenTelemetry при остановке выгружает накопленные спаны и
ждёт Collector, и без срока медленный Collector держал бы процесс уже после
SHUTDOWN_TIMEOUT. Последняя секунда срока отдана выгрузке, остальное —
HTTP-серверу и публикатору; не успели — предупреждение в лог. Опыт: в буфере
спанов есть данные, Collector недоступен, SIGTERM при SHUTDOWN_TIMEOUT=4s;
контроль — тот же сценарий с работающим Collector’ом.
Graceful shutdown не обещает завершить всё — он обещает уложиться в срок и
сказать, что прервано и что не доставлено. При SIGKILL — если срок kubelet
кончился раньше, чем процесс вышел, — не обещает и этого: содержимое буфера
в памяти пропадает без учёта.
Опыт: редирект искусственно медленный (500 мс), 20 одновременных запросов,
SIGTERM через 150 мс после их начала. Контроль — тот же сценарий с
GRACEFUL=false, выход сразу по сигналу. Отдельно — пауза 2 с после снятия
готовности: что отвечает /readyz, обслуживаются ли запросы, дошли ли до
consumer’а клики из буфера. И последнее — SIGTERM при полном буфере кликов
(PUBLISH_BUFFER=100) и остановленном NATS, SHUTDOWN_TIMEOUT=5s; контроль
— то же с работающим брокером. И запрос, который ждёт базу дольше срока:
стенд берёт LOCK TABLE links в отдельной транзакции на 20 секунд,
POST /links упирается в блокировку, SIGTERM при SHUTDOWN_TIMEOUT=3s;
контроль — что запрос к моменту сигнала действительно ждал.
$ python3 scripts/run-checks.py shutdown
{"variant": "shutdown", "outcome": "match", "detail": "SIGTERM при 20 запросах в работе: graceful — завершено 20, оборвано 0; выход сразу — завершено 0; во время паузы /readyz 503 — да, запросы обслуживаются — да; буфер кликов дописан — да; полный буфер, брокер недоступен: уложилась в SHUTDOWN_TIMEOUT — да, остаток посчитан — да, выход штатный — да; брокер доступен: остатка нет — да; запрос ждёт базу дольше срока: ждал на момент SIGTERM — да, выход в срок — да, прерывание в логе — да, клиент не получил успеха — да; Collector не отвечает: выход в срок — да, невыгруженные трейсы в логе — да; Collector работает: в срок — да, без предупреждения — да"}
Без дренажа оборваны все 20 запросов в работе. За паузу после снятия готовности и из буфера до consumer’а дошли все клики: 210 из 210. С полным буфером и остановленным брокером процесс вышел через 5,2 с при сроке 5 с, не опубликовав и посчитав 98 кликов; с работающим брокером — через 0,1 с, остатка нет. Запрос, ждавший базу, прерван, и процесс вышел через 3,2 с при сроке 3 с. С недоступным Collector’ом — выход через 4,2 с при сроке 4 с и предупреждение о невыгруженных трейсах, с работающим — через 0,1 с, без предупреждения.
Пауза после снятия готовности — не простой: сервис продолжает отвечать на всё, что до него доходит, он только просит балансировщик больше не слать новое.
Граница третья: отказ зависимости
Ошибка, которая дошла до клиента, — часть контракта API. Правило здесь одно: клиент получает код, по которому можно решить, что делать дальше, и текст, который не раскрывает устройство сервиса. Отображение — в одном месте:
// internal/httpapi/httpapi.go
func writeError(w http.ResponseWriter, r *http.Request, err error) {
status, msg := http.StatusInternalServerError, "внутренняя ошибка"
switch {
case errors.Is(err, links.ErrInvalidURL):
status, msg = http.StatusBadRequest, err.Error()
case errors.Is(err, links.ErrNotFound):
status, msg = http.StatusNotFound, err.Error()
case errors.Is(err, context.Canceled):
status, msg = 499, "клиент ушёл" // nginx-код: ответ уже некому отдать
case errors.Is(err, context.DeadlineExceeded):
status, msg = http.StatusServiceUnavailable, "не успели"
}
if status >= 500 {
slog.Error("запрос не обработан", "path", r.URL.Path, "err", err)
}
writeJSON(w, status, map[string]string{"error": msg})
}
Значение по умолчанию — 500 с общим текстом, а не err.Error(). Ошибка
драйвера PostgreSQL содержит адрес базы, имя пользователя и иногда фрагмент
запроса; ей место в логе, где она и оказывается, а не в ответе. Ошибки
домена — неверный URL, нет такого кода — безопасны и полезны клиенту, их текст
отдаётся как есть.
Вторая половина — что делать, когда упала зависимость. Redis в этом сервисе ускоряет, но не держит: при его недоступности резолвер идёт в базу, а не отказывает. С базой наоборот: без неё сервис может отдать только то, что уже лежит в кэше.
Опыт: ошибки ввода, затем остановленный PostgreSQL — редирект по ссылке, которая есть в кэше, и по ссылке, которой в кэше нет:
$ python3 scripts/run-checks.py errors
{"variant": "errors", "outcome": "match", "detail": "неверный URL — 400, битый JSON — 400, нет кода — 404; база недоступна: ссылка из кэша — 302, вне кэша — 500; внутренние детали скрыты — да"}
Тело ответа на ссылку вне кэша при остановленной базе:
{"error":"внутренняя ошибка"}
Отказ базы не обрушил горячий путь целиком: ссылки из кэша продолжают работать, и это прямое следствие cache-aside. Создание ссылок при этом недоступно — запись без базы невозможна, и сервис честно отвечает 500.
Граница четвёртая: залп по холодному ключу
Cache-aside ломается в одном предсказуемом месте. Ссылку опубликовали в рассылке, в кэше её ещё нет, и в одну секунду приходят сотни переходов. Каждый промахивается мимо кэша, каждый идёт в базу за одной и той же строкой, и база получает столько одинаковых запросов, сколько пришло клиентов. Это cache stampede, и защита от него — склеить одновременные промахи по одному ключу в один запрос:
// internal/cache/redis.go
if r.Singleflight {
ch := r.group.DoChan(code, func() (any, error) {
// общая загрузка не наследует ни отмену, ни срок первого клиента — у неё свой срок
lctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), r.LoadTimeout)
defer cancel()
return r.load(lctx, code, true)
})
select {
case res := <-ch:
if res.Err != nil {
return "", res.Err
}
return res.Val.(string), nil
case <-ctx.Done():
// клиент ушёл или истёк его срок: перестаём ждать, загрузка для остальных продолжается
return "", ctx.Err()
}
}
singleflight.Group пропускает в функцию первый вызов по ключу, остальные
ждут его результат. Тонкость — в контекстах, и их здесь два.
Контекст загрузки. Если передать контекст первого запроса как есть, его
отмена — клиент закрыл вкладку — отменит загрузку для всех, кто ждёт тот же
ключ, и они получат ошибку чужого запроса. context.WithoutCancel сохраняет
значения контекста (в том числе трейс), но отвязывает не только отмену, но и
срок. Загрузка без срока при зависшей базе держала бы всех ожидающих
бесконечно, поэтому у неё свой таймаут — LoadTimeout, общий для всех, а не
взятый у первого клиента.
Контекст ожидания. Do блокирует, пока загрузка не кончится, и клиент со
своим сроком ждал бы чужую загрузку дольше него. DoChan отдаёт канал, и
каждый ожидающий выходит по своему контексту, не мешая остальным. Оба
свойства проверены модульными тестами internal/cache, ось стенда их
запускает.
Опыт: свежая ссылка, 200 одновременных редиректов, счётчик чтений из базы
до и после. Залп даёт Go-клиент cmd/probe изнутри сети compose: все 200
запросов лежат в очереди до общего старта. Контроль — тот же залп с
SINGLEFLIGHT=false и повторный залп по прогретой ссылке.
Первые варианты опыта дали урок про сам опыт. Залп из потоков Python на
хосте через проброс порта не был одновременным: первый запрос успевал
прогреть кэш, и без singleflight база видела одно чтение — отрицательная
проверка без положительного контроля этого бы не показала. Залп из Go внутри
сети одновременнее, но чтение ссылки из базы длится около миллисекунды, а
разброс прихода 200 горутин на Docker Desktop больше. С singleflight база
видела то одно чтение, то три, без него — от трёх до ста двадцати, от прогона
к прогону. Второе чтение с singleflight — не ошибка: группа склеивает только
одновременные загрузки, и запрос, промахнувшийся мимо Redis до того, как
первая загрузка записала значение, но дошедший до group.Do уже после неё,
запускает вторую.
Поэтому в опыте чтение при промахе кэша искусственно медленное —
SLOW_LOAD=50ms, как у холодной ссылки, когда база под нагрузкой. Так весь
залп приходит, пока идёт первая загрузка, и результат перестаёт зависеть от
планировщика:
$ python3 scripts/run-checks.py cache
{"variant": "cache", "outcome": "match", "detail": "залп по холодной ссылке, чтение из базы 50 мс: с singleflight чтений базы 1; без него — по чтению на каждый запрос: да; тёплый кэш — 0 чтений; все редиректы 302 — да; тесты срока загрузки и ухода ожидающего — да"}
С singleflight — 1 чтение из базы на весь залп, без него — 200, по одному на каждый запрос.
Это и есть stampede в чистом виде: без склейки каждый промах — отдельный
запрос в базу, и чем медленнее база, тем больше промахов успевает
накопиться и тем сильнее её добивают. Склейка превращает залп в одно
чтение, сколько бы клиентов ни пришло. Все пересмотры опыта и прогоны, которые
их вызвали, записаны в expected.json стенда.
Что дальше
Сервис стартует только с верной конфигурацией, останавливается, не обрывая запросов, не выдаёт наружу устройство зависимостей и не пропускает залп в базу. Следующая граница — путь записи: клик уходит в брокер, а брокер может быть недоступен, процесс может упасть между записью ссылки и публикацией события, consumer может получить одно сообщение дважды. Это — вторая статья. Дальше — образ, подпись и выкатка на кластерготовится, с 2 декабря и трейсы, SLO и нагрузкаготовится, с 8 декабря.
Обсуждение в Telegram
Присоединиться →