Дисциплина context: отмена, дедлайны и значения, текущие вниз по цепочке вызовов

Одно дерево на запрос

context.Context несёт по цепочке вызовов три вещи: сигнал отмены, дедлайн и маленький набор request-scoped значений. Конвенция жёсткая намеренно — ctx идёт первым параметром каждой функции, которая делает I/O или может блокироваться, чтобы канал нигде не рвался посреди цепочки:

func (s *Server) handleCheckout(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context() // уже отменяется при разрыве соединения клиентом

	ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
	defer cancel() // освобождает таймер и отцепляет ребёнка от родителя

	order, err := s.orders.Load(ctx, orderID) // ctx первым, везде
	// ...
}

WithCancel, WithTimeout и WithDeadline не мутируют контекст — они выводят ребёнка и регистрируют его в наборе детей родителя. Отмените родителя — отменится каждый потомок; ребёнок никогда не отменит родителя и не переживёт его. Именно форма дерева делает инцидент из крючка неизбежным: WithTimeout(parent, 10*time.Second) при родителе с пятью оставшимися секундами даёт эффективный дедлайн пять — всегда побеждает минимум вдоль пути к корню. Щедрый таймаут глубоко в стеке не значит ничего, если предок был скупее.

Забытый cancel — тихая утечка. WithTimeout аллоцирует time.Timer и вцепляет ребёнка в родителя; пока вы не вызовете cancel, оба остаются достижимыми — для десятиминутного таймаута на джобе, которая завершается за 200 мс, это десять минут мёртвого груза на джобу, умноженные на ваш RPS. Выведите от долгоживущего родителя через WithCancel и забудьте cancel — утечка станет вечной. defer cancel() следующей строкой — идиома, а go vet (проверка lostcancel) ловит нарушение.

Выводите, не храните

Анти-паттерн, ломающий скоупинг отмены, — хранение контекста в поле структуры. Контекст представляет время жизни одного вызова; структура обычно переживает много вызовов. Заморозьте контекст запроса в объекте — и каждый последующий вызов метода унаследует мёртвый или чужой скоуп отмены: работа для запроса B отменяется, когда отваливается клиент запроса A, или не отменяется вообще никогда. Правило команды Go прямолинейно: передавайте ctx параметром в каждый метод, которому он нужен; не храните. Единственное санкционированное исключение подтверждает правило — http.Request держит контекст, потому что Request и есть один вызов: создаётся и выбрасывается вместе с ним.

Отмена кооперативна

Когда вы вызываете cancel(), ничего не убивается — и это удивляет большинство инженеров в первый раз, когда они трейсят осиротевший запрос. cancel() не убивает ничего. Он закрывает канал Done контекста и заставляет ctx.Err() возвращать context.Canceled (или context.DeadlineExceeded, если сработал таймер). Всё остальное — работа вашего кода: блокирующие операции должны принимать ctx и уважать его — database/sql, net/http, net.Dialer это делают, — а CPU-bound циклы обязаны проверять ctx.Err() между итерациями, потому что никто их не прервёт. Классический прод-запах — осиротевший запрос: хендлер вернул 504, клиент давно ушёл, а SQL-запрос продолжает молотить базу, потому что кто-то вызвал единственный метод без контекста. Дисциплина отмены ровно настолько сильна, насколько кооперативен самый ленивый фрейм в стеке.

Values: метаданные, а не зависимости

Прежде чем тянуться к context.Value, спросите себя: это метаданные запроса, которым нужно пересечь API-границу, — или зависимость, которая должна жить в конструкторе? От ответа зависит, получится ли у вас устойчивый код или невидимая мина. context.Value отвечает на один узкий вопрос: какие request-scoped факты должны пересекать границы API, не спроектированные их нести? Trace id, request id, аутентифицированный принципал — данные, описывающие этот запрос, которые middleware прикрепляет для слоёв, которых не видит. Паттерн типизированного ключа исключает коллизии:

type principalKey struct{} // неэкспортируемый: другой пакет не столкнётся

func WithPrincipal(ctx context.Context, p Principal) context.Context {
	return context.WithValue(ctx, principalKey{}, p)
}

func PrincipalFrom(ctx context.Context) (Principal, bool) {
	p, ok := ctx.Value(principalKey{}).(Principal)
	return p, ok
}

Чему там не место: зависимостям. Хэндл базы, конфиг, API-клиент в context.Value — это невидимый, нетипизированный, не проверяемый компилятором параметр: сигнатура функции декларирует независимость, а тело падает на nil-ассершене, когда какой-то вызывающий забыл магическое заклинание. Зависимости живут в полях структур, прошитых при конструировании; к тому же поиск — это проход по связному списку вверх по дереву: нормально для трёх значений, неверно как универсальное хранилище.

Отцепление: работа, которая должна пережить запрос

Иногда отмена запроса не должна отменять работу: аудит-запись попытки платежа обязана быть записана, даже если клиент отвалился на середине — особенно тогда. context.WithoutCancel(ctx) (Go 1.21) выводит контекст, который сохраняет значения родителя — ваш trace id всё ещё течёт в аудит-запись, — но игнорирует его отмену и дедлайн. Дайте отцепленной работе собственную границу, чтобы она не жила вечно:

// Аудит-запись переживает запрос, но не процесс: свой таймаут, значения родителя.
auditCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
defer cancel()
audit.Record(auditCtx, event)