К содержимому
Войти

Go Road Map

🧭 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 происходит четыре шага:

  1. Если контекст уже отменён, выход. Поэтому cancel можно звать сколько угодно раз
  2. Записываются ошибка и причина, закрывается канал done
  3. Под тем же замком рекурсивно отменяются все потомки, мапа children обнуляется
  4. Контекст удаляет себя из 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 — когда сервер отменяет контекст входящего запроса