🧭 context
context.Context несёт через цепочку вызовов три вещи: сигнал отмены, дедлайн и немного данных запроса. Клиент закрыл вкладку, истёк таймаут, сервис получил SIGTERM — и все горутины, запросы в базу и исходящие HTTP-вызовы этого запроса узнают об этом и останавливаются. Без контекста сервис продолжает считать отчёт для человека, который давно ушёл. На собеседовании про context спрашивают почти всегда: как устроена отмена, что будет, если не вызвать cancel, почему контекст не хранят в структуре и что можно класть в WithValue
🧠 Как это устроено
Четыре метода
Context — интерфейс, и в нём всего четыре метода:
| Метод | Что возвращает |
|---|---|
Done() | канал, который закрывается при отмене. У контекста, который нельзя отменить, это nil |
Err() | nil, пока не отменён. Потом context.Canceled или context.DeadlineExceeded |
Deadline() | время дедлайна и ok == false, если его нет |
Value(key) | значение по ключу или nil |
Отмена построена на закрытии канала. Закрытый канал читается сразу и любым числом горутин, поэтому одна отмена будит всех, кто ждёт на <-ctx.Done() в select. Механика закрытия разобрана на странице про каналы и select
Корень дерева — context.Background(). Его никогда не отменяют, у него нет дедлайна и значений. context.TODO() устроен так же, а отличается только смыслом: «здесь должен быть настоящий контекст, но его ещё не протащили». Документация просит никогда не передавать nil и в сомнительном месте ставить TODO
Дерево контекстов
Контекст неизменяем, новые свойства добавляют обёрткой. WithCancel, WithTimeout, WithDeadline и WithValue берут родителя и возвращают дочерний контекст. Отмена идёт только вниз: отменили узел, отменились все его потомки, а родитель и соседи живут дальше
root, cancelRoot := context.WithCancel(context.Background())
a, cancelA := context.WithCancel(root)
b, cancelB := context.WithCancel(a)
defer cancelB()
cancelA() // отменяем середину дерева
fmt.Println("root:", root.Err()) // <nil>
fmt.Println("a: ", a.Err()) // context canceled
fmt.Println("b: ", b.Err()) // context canceled
cancelRoot()
cancelRoot() // повторный вызов ничего не делаетВнутри context.go это обычная структура cancelCtx: мьютекс, канал done (он создаётся при первом вызове Done()), ошибка, причина и мапа children с потомками. Когда создают дочерний контекст, функция propagateCancel находит ближайшего отменяемого предка и записывает потомка в его children. Если родитель уже отменён, ребёнок отменяется сразу
При вызове cancel происходит четыре шага:
- Если контекст уже отменён, выход. Поэтому
cancelможно звать сколько угодно раз - Записываются ошибка и причина, закрывается канал
done - Под тем же замком рекурсивно отменяются все потомки, мапа
childrenобнуляется - Контекст удаляет себя из
childrenродителя
Последний шаг объясняет главное правило. Пока cancel не вызван, родитель держит ссылку на ребёнка в своей мапе, а у WithTimeout ещё и живёт таймер. Если родитель — долгоживущий контекст сервиса, такие дети копятся до его отмены. Поэтому cancel вызывают всегда, обычно через defer cancel() сразу после создания, даже если работа успела закончиться раньше таймаута
Дедлайны и таймауты
WithTimeout(parent, d) — это WithDeadline(parent, time.Now().Add(d)). Дедлайн ребёнка не бывает позже дедлайна родителя: если родитель отменится через 100 мс, дочерний таймаут в 5 секунд ничего не продлит
parent, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()
// дочерний просит 5 секунд, но родитель отменится раньше
child, cancelChild := context.WithTimeout(parent, 5*time.Second)
defer cancelChild()
<-child.Done()
fmt.Println(child.Err()) // context deadline exceeded, примерно через 100 мсВ исходнике это видно прямо: если дедлайн родителя раньше запрошенного, WithDeadline возвращает обычный WithCancel(parent) без своего таймера. Иначе он заводит time.AfterFunc, который в нужный момент отменит контекст с ошибкой DeadlineExceeded. Ранний cancel таймер останавливает
Две ошибки различают по смыслу. context.Canceled (текст context canceled) — кто-то вызвал cancel: клиент отключился, соседняя горутина в errgroup упала. context.DeadlineExceeded (context deadline exceeded) — кончилось время. У второй есть метод Timeout() bool, который возвращает true, поэтому код, проверяющий сетевые таймауты через net.Error, узнаёт и её. Сравнивают их через errors.Is: драйверы и HTTP-клиент оборачивают ошибку, и err == context.Canceled промахнётся
Причина отмены
Err() говорит только «отменён» или «время вышло», а в логах хочется видеть, почему. Для этого в Go 1.20 появились WithCancelCause и context.Cause, а в Go 1.21 — WithTimeoutCause и WithDeadlineCause:
var errSlowDB = errors.New("бюджет на запрос к БД исчерпан")
ctx, cancel := context.WithTimeoutCause(context.Background(), 10*time.Millisecond, errSlowDB)
defer cancel()
<-ctx.Done()
fmt.Println(ctx.Err()) // context deadline exceeded
fmt.Println(context.Cause(ctx)) // бюджет на запрос к БД исчерпанErr() при этом не меняется, и старый код, который проверяет errors.Is(err, context.DeadlineExceeded), работает как раньше. Причину задаёт первая отмена контекста или любого его предка. Если её не передали, Cause возвращает то же, что Err(). С Go 1.26 так отменяет контекст и signal.NotifyContext: в причине видно, какой сигнал пришёл
Отмена добровольная
Контекст ничего не прерывает силой. Он закрывает канал, а горутина сама должна это заметить: проверить ctx.Err() между шагами или ждать на <-ctx.Done() в select. Функция, которая контекст принимает и не смотрит в него, работает до конца
func work(ctx context.Context, checks bool) int {
n := 0
for i := 0; i < 10; i++ {
if checks && ctx.Err() != nil {
return n
}
time.Sleep(50 * time.Millisecond) // кусок работы
n++
}
return n
}С таймаутом 120 мс версия без проверки сделала все 10 шагов примерно за 510 мс, версия с проверкой остановилась после 3 шагов на 150–160 мс. Стандартная библиотека контекст проверяет сама: http.Client рвёт запрос, database/sql передаёт контекст драйверу и откатывает транзакцию при отмене. Свой долгий цикл ты проверяешь сам
🛠️ На практике
HTTP: сервер и клиент
У входящего запроса контекст уже есть: r.Context(). Сервер отменяет его, когда клиент закрыл соединение, когда клиент отменил поток в HTTP/2 и когда ServeHTTP вернулся. Этот контекст передают дальше во все вызовы обработчика
У исходящего запроса контекст задаёт http.NewRequestWithContext. Он ограничивает весь запрос целиком: получение соединения, отправку, заголовки и чтение тела ответа. Ниже клиент ждёт 200 мс, а обработчик готовит ответ 2 секунды:
Go · Клиент уходит по таймауту, сервер это видит
done := make(chan string)
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
select {
case <-time.After(2 * time.Second): // медленный отчёт
fmt.Fprintln(w, "готово")
done <- "доделал"
case <-r.Context().Done():
done <- "сервер: " + r.Context().Err().Error()
}
}))
defer srv.Close()
ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL, nil)
_, err := http.DefaultClient.Do(req)
fmt.Println("клиент:", err) // Get "http://127.0.0.1:...": context deadline exceeded
fmt.Println(<-done) // сервер: context canceledКлиент получил context deadline exceeded, а сервер — context canceled: для него это не таймаут, а закрытое соединение. Обработчик бросил работу через 200 мс, а не через 2 секунды
База данных
В database/sql у каждого метода есть вариант с контекстом: QueryContext, ExecContext, BeginTx. Методы без Context в названии внутри работают с context.Background() и не отменятся никогда. Для транзакции правило жёстче: если контекст, который передали в BeginTx, отменили, пакет сам откатывает транзакцию, и Commit вернёт ошибку
На практике таймаут на запрос в базу делают дочерним от контекста запроса: ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second). Запрос к базе тогда остановится по любой из двух причин: кончились 2 секунды или ушёл клиент
Работа после ответа: WithoutCancel
Иногда после ответа нужно что-то доделать в фоне: записать аудит, отправить событие. Если запустить горутину с r.Context(), она получит отмену в момент, когда обработчик вернётся. Если взять context.Background(), потеряются request ID и трейс. Для этого в Go 1.21 появился context.WithoutCancel: значения родителя остаются, а отмены и дедлайна нет
type ctxKey struct{}
reqCtx, cancel := context.WithCancel(context.WithValue(context.Background(), ctxKey{}, "req-42"))
bg := context.WithoutCancel(reqCtx)
cancel() // запрос завершился
fmt.Println(reqCtx.Err()) // context canceled
fmt.Println(bg.Err(), bg.Done() == nil, bg.Value(ctxKey{})) // <nil> true req-42Свой таймаут фоновой работе всё равно нужен: context.WithTimeout(bg, 3*time.Second). Иначе зависший вызов внешнего сервиса держит горутину бесконечно
В той же версии появился context.AfterFunc(ctx, f): запускает f в отдельной горутине после отмены ctx и возвращает stop, который отменяет эту подписку. Им удобно прерывать то, что про контексты не знает, например выставить conn.SetReadDeadline(time.Now()) и разбудить чтение из сокета. С Go 1.24 в тестах есть t.Context(): контекст, который отменяется после теста и до функций t.Cleanup
Значения в контексте
WithValue создаёт ещё один узел дерева с одной парой ключ–значение. Value идёт от текущего узла вверх к корню и сравнивает ключи по одному, так что поиск линейный по глубине цепочки. Контекст не словарь, и много значений туда не кладут
Документация называет, что туда класть: данные запроса, которые проходят через границы процессов и API. Это request ID, данные трейса, пользователь, прошедший аутентификацию. Пул соединений с базой, логгер с настройками, конфиг и необязательные параметры функции туда не кладут: они становятся невидимыми зависимостями, которые не проверит компилятор и не найдёт тот, кто читает сигнатуру
Ключ — неэкспортируемый тип, а не строка. Строковые ключи двух разных пакетов совпадут, и один перетрёт значение другого. Свой тип из чужого пакета не создать:
// неэкспортируемый тип ключа: чужой пакет такой ключ не создаст
type requestIDKey struct{}
func WithRequestID(ctx context.Context, id string) context.Context {
return context.WithValue(ctx, requestIDKey{}, id)
}
func RequestID(ctx context.Context) (string, bool) {
id, ok := ctx.Value(requestIDKey{}).(string)
return id, ok
}Пакет отдаёт наружу пару функций с типами, а сам ключ прячет. Тип struct{} выбирают потому, что такое значение не выделяет память при упаковке в any
⚠️ Где ошибаются
Не вызывают cancel. ctx, _ := context.WithTimeout(parent, time.Second) оставляет таймер и запись в children родителя до его отмены. Под нагрузкой это медленная утечка памяти. go vet ловит такой код: the cancel function returned by context.WithTimeout should be called, not discarded, to avoid a context leak
Хранят контекст в структуре. Сервис с полем ctx живёт дольше одного запроса, и все его методы работают с контекстом, который отменён или принадлежит чужому запросу. Документация прямо запрещает это и отсылает к статье в блоге Go. Исключение там названо одно: обратная совместимость. Так сделали http.Request в Go 1.7, чтобы не ломать сигнатуру Client.Do, но и там советуют сначала добавить функцию с суффиксом Context
Рвут цепочку через Background. В глубине кода кто-то пишет context.Background(), потому что контекста под рукой не было. Запрос к базе в этом месте больше не отменится ни по таймауту, ни при уходе клиента. Если контекста нет, его протаскивают через сигнатуры, а на время переделки ставят context.TODO(), чтобы место было видно в поиске
Отправляют фоновую работу с контекстом запроса. go sendEvent(r.Context(), e) почти всегда падает с context canceled: обработчик вернул ответ раньше, чем горутина дошла до сети. Нужен context.WithoutCancel(r.Context()) и собственный таймаут
Сравнивают ошибку через ==. if err == context.DeadlineExceeded промахивается, когда ошибку обернули: Get "http://...": context deadline exceeded — уже *url.Error. Правильно errors.Is(err, context.DeadlineExceeded)
🎯 Вопросы с собеседований
Зачем нужен context?
Он переносит через цепочку вызовов отмену, дедлайн и данные запроса. Когда клиент ушёл или истёк таймаут, все горутины и вызовы этого запроса получают сигнал и останавливаются, а не тратят CPU и соединения с базой впустую. Контекст передают первым параметром в функции, которые ходят в сеть, в базу или ждут
Как работает отмена внутри?
Каждый отменяемый контекст хранит канал done и мапу дочерних контекстов. При создании ребёнок регистрируется у ближайшего отменяемого предка. cancel закрывает канал, рекурсивно отменяет детей и удаляет себя из родителя. Закрытый канал читается всеми сразу, поэтому одна отмена будит всех, кто ждёт на ctx.Done()
Что будет, если не вызвать cancel?
Дочерний контекст останется в мапе детей у родителя, а у WithTimeout ещё и таймер проживёт до срабатывания. Если родитель живёт долго, такие контексты копятся, это утечка. go vet предупреждает о выброшенном cancel. Поэтому сразу после создания пишут defer cancel(), даже если работа закончится раньше таймаута
Отмена дочернего контекста отменит родителя?
Нет. Отмена идёт только вниз по дереву: отменённый узел отменяет всех потомков, а родитель и соседние ветки продолжают работать. Ребёнок при отмене только удаляет себя из списка детей родителя
Родитель с таймаутом 1 секунда, ребёнок с таймаутом 5 секунд. Когда отменится ребёнок?
Через секунду, вместе с родителем. Дедлайн дочернего контекста не может быть позже родительского. В исходнике WithDeadline в этом случае даже не заводит свой таймер, а возвращает обычный WithCancel от родителя
Чем context.Canceled отличается от DeadlineExceeded?
Canceled значит, что кто-то вызвал cancel: клиент отключился, соседняя задача упала. DeadlineExceeded значит, что кончилось время. Сравнивать нужно через errors.Is, потому что HTTP-клиент и драйверы оборачивают ошибку. Чтобы узнать конкретную причину, есть WithCancelCause и context.Cause с Go 1.20
Почему контекст нельзя хранить в структуре?
Контекст принадлежит одному вызову, а структура обычно живёт дольше. Методы такой структуры будут работать с контекстом, который уже отменён или относится к другому запросу, и по сигнатуре этого не видно. Явный параметр ctx показывает, что функция умеет останавливаться, и даёт вызывающему решать, сколько ей ждать
Что можно класть в context.WithValue, а что нельзя?
Данные запроса, которые проходят через границы API: request ID, трейс, пользователь после аутентификации. Нельзя зависимости и параметры: пул базы, логгер, конфиг, флаги поведения функции. Ключ делают неэкспортируемым типом, а не строкой, чтобы два пакета не перетёрли значения друг друга. Поиск значения линейный по глубине цепочки
Функция получила ctx, но работает дальше после отмены. Почему?
Отмена добровольная: контекст только закрывает канал, а код должен его проверить. Если функция не зовёт ctx.Err() между шагами, не ждёт ctx.Done() в select и не передаёт ctx в вызовы ниже, она доработает до конца. Стандартная библиотека и драйверы контекст проверяют, свои долгие циклы проверяют сами
Как запустить фоновую задачу после ответа на HTTP-запрос?
Контекст r.Context() отменится, как только обработчик вернётся, поэтому горутина с ним упадёт. context.Background() потеряет request ID и трейс. С Go 1.21 берут context.WithoutCancel(r.Context()): значения остаются, отмены нет. Поверх обязательно ставят свой таймаут, иначе зависший вызов держит горутину вечно
📚 Что почитать
- Пакет context — правила использования, все функции с версиями и примеры с
AfterFunc - Go Concurrency Patterns: Context — статья из блога Go: зачем появился пакет и как контекст идёт через сервер поиска
- Contexts and structs — почему контекст передают параметром и что ломается, когда его кладут в поле
- Request.Context в net/http — когда сервер отменяет контекст входящего запроса