Сервис и его границы: код, ошибки, остановка, кэш

Первая часть капстона: сервис коротких ссылок на Go и четыре его границы, проверенные опытом. Неверная конфигурация не должна открыть порт, остановка не должна оборвать запросы в работе, отказ базы не должен вытечь наружу текстом драйвера, а залп по холодной ссылке не должен уйти в базу сотней одинаковых запросов

Отдельные статьи разбирают части стека по одной: конфигурацию, остановку, кэш, брокер, образы, 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

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

Присоединиться →