Ошибки и отказоустойчивость кода

4.1Работа с ошибками

На собесе эта часть темы самая «разговорная». Заучить сигнатуры errors.Is и errors.As мало: спрашивают про политику — что пакет обещает наружу, где ошибка получает контекст, где она умирает в логе и во что превращается на HTTP.

Сначала — четыре слова, без которых дальше будет каша

Ошибка родилась глубоко внизу и всплыла наверх. Как наверху понять, что именно там случилось, и что с этим делать? Чтобы отвечать не наугад, сначала договоримся о четырёх словах. Теории тут нет, но дальше эти слова пойдут без пояснений.

1. Обёртка — это новая ошибка, внутри которой лежит старая

Драйвер базы вернул «нет строк». Отдавать это наверх как есть репозиторий не хочет: ему надо дописать «...и случилось это, когда я искал пользователя 42». Но и потерять исходную причину нельзя — выше по стеку кто-то захочет отличить «нет строк» от «база недоступна».

Выход: сделать новую ошибку, у которой есть свой текст и поле со ссылкой на старую. Это и называется обёрткой (wrapping, «заворачивание»), а пишется одной строкой:

err = fmt.Errorf("get user 42: %w", err)   // %w = «положи то, что было, внутрь новой ошибки»

Снаружи теперь текст про пользователя 42, а внутри осталась нетронутая ошибка драйвера. Буквально ошибка внутри ошибки. Текст никто не копирует: старая ошибка лежит целиком, со всеми своими полями и своим типом.

2. Цепочка ошибок — эта матрёшка целиком

Каждый слой приложения оборачивает то, что пришло снизу, и добавляет своё слово. Три слоя дают три вложенные друг в друга ошибки. Такую конструкцию называют цепочкой ошибок: снаружи самый верхний слой, внутри него следующий, и так до первой ошибки, которая уже ничего не оборачивает. Это корень цепочки, она же первопричина (root cause).

Чего в цепочке нет, так это стектрейса. Она хранит логический путь «сервис → репозиторий → драйвер», а не список кадров стека. В какой строке какого файла всё пошло не так, стандартная библиотека не запоминает. Если это нужно, берут стороннюю библиотеку или вписывают файл и строку в текст обёртки руками.

3. Unwrap — способ снять ровно один слой матрёшки

Чтобы по цепочке можно было ходить, каждое звено обязано уметь отдать то, что лежит у него внутри. Договорённость простая: у звена есть метод Unwrap() error (буквально «развернуть»), который возвращает вложенную ошибку. У корня такого метода либо нет вовсе, либо он возвращает nil, и это сигнал «дальше пусто, цепочка кончилась».

Руками этот метод почти никогда не зовут. На нём стоят две функции, которые ходят по цепочке сами: errors.Is («лежит ли где-то в матрёшке вот эта конкретная ошибка?») и errors.As («есть ли в матрёшке ошибка вот такого типа — и если да, дай её мне, у неё внутри нужные поля»).

4. Sentinel — заранее объявленная ошибка-маркер

Sentinel по-английски значит «часовой», «сторож»; по-русски прижилось «маркерная ошибка», но чаще говорят просто «сентинел». Это одна-единственная переменная уровня пакета, объявленная раз и навсегда:

var ErrNotFound = errors.New("not found")   // объявлена один раз на весь пакет

Весь смысл в том, что она одна. Пакет всегда возвращает её, а вызывающий всегда сравнивает результат именно с ней — не с текстом сообщения и не с копией. В стандартной библиотеке так устроены io.EOF, sql.ErrNoRows, context.Canceled, и вся программная проверка «а что именно случилось?» в Go построена на сравнении с такими значениями. Их и ищет errors.Is, спускаясь по цепочке слой за слоем: «этот слой — не он? а этот?»

«Error — это значение»: что за этим стоит

Формулировка Роба Пайка «errors are values» звучит как лозунг, но у неё есть точный смысл: ошибка в Go ведёт себя как любое значение интерфейсного типа. Её можно положить в переменную, передать в функцию, сохранить в поле структуры, сложить в слайс, сравнить, обернуть и вернуть. Отдельного механизма языка под ошибки нет. Весь «фреймворк обработки ошибок» сводится к одному интерфейсу с одним методом и пакету errors на полторы сотни строк.

// Тип целиком, объявлен в builtin, живёт в universe scope:
type error interface {
    Error() string
}

Из этого вытекает всё остальное. Ошибка попадает в сигнатуру функции, а значит видна на ревью и в godoc. Компилятор знает про множественный возврат, поэтому (T, error) ничего не стоит. Управление никогда не «улетает» в неизвестное место: из функции уходят только через return или панику, причём паника в идиоматичном Go считается исключительной ситуацией, а не рабочим путём.

Почему не исключения

Обратную сторону лучше назвать самому, не дожидаясь вопроса: код становится многословным. Легендарные три строки if err != nil { return nil, err } занимают заметную долю файла. Команда Go несколько раз пыталась это починить: предложения check/handle (2018) и try() (2019) отклонили, а в 2025 году официально объявили, что синтаксического сахара для ошибок не будет. Сообщество так и не сошлось ни на одном варианте, а платить пришлось бы той самой явностью.

Что физически лежит в переменной типа error

Раз error интерфейс, в переменной лежат два машинных слова: указатель на itab (пара «тип + таблица методов») и указатель на данные. Отсюда два практических следствия, которые проверяют почти всегда.

Первое. errors.New возвращает указатель на структуру, а не значение:

// src/errors/errors.go
func New(text string) error { return &errorString{text} }

type errorString struct {
    s string
}
func (e *errorString) Error() string { return e.s }

Указатель выбран сознательно. Если бы возвращалось значение, две ошибки с одинаковым текстом сравнивались бы как равные, и errors.Is путал бы разные ошибки из разных пакетов с совпавшим сообщением. С указателем каждый вызов errors.New даёт уникальную идентичность — на этом и стоят sentinel-ошибки.

a := errors.New("EOF")
b := errors.New("EOF")
fmt.Println(a == b)          // false: разные аллокации, разные указатели
fmt.Println(a == io.EOF)     // false, хотя текст совпадает

Второе, и это классическая ловушка: интерфейс с ненулевым типом и нулевыми данными не равен nil. Функция, которая возвращает конкретный тип ошибки вместо error, ломает err != nil.

type MyErr struct {
    Code int
}
func (e *MyErr) Error() string { return "code " + strconv.Itoa(e.Code) }

func broken() error {
    var e *MyErr = nil     // конкретный тип, значение nil
    return e               // упаковали в интерфейс: itab = (*MyErr, error), data = nil
}

func main() {
    err := broken()
    fmt.Println(err == nil)          // false
    fmt.Printf("%T %v\n", err, err)  // *main.MyErr <nil>
    fmt.Println(err.Error())         // паника, точный текст ниже
}

// stdout:
//   false
//   *main.MyErr <nil>
// stderr, exit status 2:
//   panic: runtime error: invalid memory address or nil pointer dereference
//   [signal SIGSEGV: segmentation violation code=0x2 addr=0x0 pc=0x10461cd10]
//
//   goroutine 1 [running]:
//   main.(*MyErr).Error(...)
//   main.main()
// Печатать «panic: nil pointer dereference» рантайм не умеет: это всегда
// «runtime error: invalid memory address or nil pointer dereference» плюс строка про SIGSEGV.

Четыре способа создать ошибку

Есть и пятый, errors.Join(a, b) из Go 1.20, но он не создаёт ошибку, а склеивает несколько. О нём ниже отдельно.

Оборачивание: %w против %v

До Go 1.13 обёрток в стандартной библиотеке не было — все пользовались github.com/pkg/errors. В 1.13 в язык (точнее, в fmt и errors) приехали три вещи: глагол %w, соглашение о методе Unwrap() error и функции errors.Is / errors.As / errors.Unwrap.

Внутри fmt.Errorf считает, сколько раз встретился %w, и в зависимости от этого возвращает разные типы:

// упрощённая логика fmt.Errorf (Go 1.20+)
switch len(wrappedErrs) {
case 0:
    err = errors.New(s)                  // обычная строка, цепочки нет
case 1:
    err = &wrapError{msg: s, err: w}     // есть Unwrap() error
default:
    err = &wrapErrors{msg: s, errs: ws}  // есть Unwrap() []error, с Go 1.20
}

Отсюда вывод, который редко проговаривают: %w меняет публичный контракт. Обернув чужую ошибку, ты разрешил всем вызывающим писать errors.Is(err, sql.ErrNoRows) на твой результат. Заменишь потом database/sql на что-то другое — сломаешь их код, и компилятор про это не скажет. %v, наоборот, ошибку инкапсулирует: текст в логе останется, а программная зависимость не возникнет.

// %w: причина остаётся доступной
err := fmt.Errorf("get user %d: %w", id, sql.ErrNoRows)

errors.Is(err, sql.ErrNoRows)   // true
errors.Unwrap(err)              // sql.ErrNoRows
err.Error()
// "get user 42: sql: no rows in result set"

// %v: только текст, связи нет
err := fmt.Errorf("get user %d: %v", id, sql.ErrNoRows)

errors.Is(err, sql.ErrNoRows)   // false
errors.Unwrap(err)              // nil
err.Error()
// "get user 42: sql: no rows in result set"

Цепочка обёрток и как по ней ходят Is/As

Обёртки складываются в односвязный список. Каждое звено хранит указатель на предыдущее и умеет отдать его методом Unwrap() error. Стектрейса, как уже говорилось, нет: цепочка восстанавливает логический путь ошибки по слоям, а не физический путь по кадрам стека.

Алгоритм errors.Is и errors.As — точно

Внутри обеих функций цикл по цепочке и две точки расширения. Разобрать их по шагам стоит: вопрос «а как именно Is ходит по цепочке» задают почти всегда, и почти всегда забывают про метод Is у самой ошибки и про ветвление на Unwrap() []error.

// errors.Is упрощённо, но суть та же
func Is(err, target error) bool {
    if target == nil { return err == target }
    isComparable := reflect.TypeOf(target).Comparable()

    for {
        // 1. сравниваем напрямую, только если target вообще сравним
        if isComparable && err == target { return true }

        // 2. кастомная логика звена
        if x, ok := err.(interface{ Is(error) bool }); ok && x.Is(target) {
            return true
        }

        // 3. спуск по цепочке
        switch x := err.(type) {
        case interface{ Unwrap() error }:
            err = x.Unwrap()
            if err == nil { return false }
        case interface{ Unwrap() []error }:        // Go 1.20: дерево
            for _, e := range x.Unwrap() {
                if Is(e, target) { return true }   // обход в глубину
            }
            return false
        default:
            return false
        }
    }
}

errors.As устроен так же, но вместо == проверяет присваиваемость через рефлексию и записывает найденное значение по указателю. Требования к target жёсткие, и нарушение приводит к панике, а не к ошибке компиляции:

var qe *QueryError
errors.As(err, &qe)      // ок: указатель на тип, реализующий error

errors.As(err, qe)       // panic: errors: target must be a non-nil pointer
errors.As(err, &struct{}{})  // panic: errors: *target must be interface or implement error

// target может быть и указателем на интерфейс:
var te interface{ Timeout() bool }
if errors.As(err, &te) && te.Timeout() { /* сетевой таймаут где-то в глубине */ }

Go 1.26: errors.AsType — дженерик-версия As

У errors.As два врождённых неудобства, с которыми жили с 2019 года. Первое: переменную приходится объявлять заранее, отдельной строкой, даже если она нужна ровно на один if. Второе: тип проверяет не компилятор, а рефлексия в рантайме — передал не то, и получил панику там, где хотелось бы ошибку сборки. В Go 1.26 появилась дженерик-форма, которая снимает оба:

func AsType[E error](err error) (E, bool)

// Было: переменная наружу, две строки
var qe *QueryError
if errors.As(err, &qe) {
    log.Error("db", "op", qe.Op, "id", qe.ID)
}
// qe продолжает жить до конца функции

// Стало (Go 1.26): всё внутри одного if
if qe, ok := errors.AsType[*QueryError](err); ok {
    log.Error("db", "op", qe.Op, "id", qe.ID)
}
// qe виден только внутри блока

По сравнению со старой формой выигрыш в трёх местах:

• Типобезопасность вместо паники. Искомый тип задан параметром [E error], и констрейнт error проверяет компилятор. Обе классические паники As (target must be a non-nil pointer и *target must be interface or implement error) здесь невозможны: передавать нечего, значит, и ошибиться нечем.
• Быстрее. Старый As на каждом звене цепочки лезет в reflectlite: проверить присваиваемость типов и записать значение по указателю. AsType обходится обычным приведением типа err.(E) — рефлексии в его реализации нет вообще.
• Область видимости. Результат живёт внутри if, а не растекается по функции. Выигрыш тот же, что у if v, ok := m[k]; ok по сравнению с объявлением переменной строкой выше.

В остальном всё повторяет As один в один: тот же обход цепочки, тот же спуск в Unwrap() []error обходом в глубину, та же точка расширения через метод As(any) bool у звена. В качестве E можно подставить и интерфейс — errors.AsType[net.Error](err) работает так же, как As с указателем на интерфейс. Старую форму никто не удаляет и не объявляет устаревшей: она нужна коду, который обязан собираться на Go 1.25 и старше.

// Полный рабочий пример: собственный тип + Unwrap + Is + As
type QueryError struct {
    Op  string
    ID  int64
    Err error
}

func (e *QueryError) Error() string {
    return fmt.Sprintf("%s(id=%d): %v", e.Op, e.ID, e.Err)
}
func (e *QueryError) Unwrap() error { return e.Err }

// где-то в repository:
func (r *Repo) GetUser(ctx context.Context, id int64) (*User, error) {
    var u User
    err := r.db.QueryRowContext(ctx, qGetUser, id).Scan(&u.ID, &u.Name)
    if err != nil {
        return nil, &QueryError{Op: "select_user", ID: id, Err: err}
    }
    return &u, nil
}

// в service:
u, err := repo.GetUser(ctx, id)
if err != nil {
    return fmt.Errorf("service.Profile: %w", err)
}

// в handler нужны оба инструмента:
switch {
case errors.Is(err, sql.ErrNoRows):        // факт: сработал ли конкретный случай
    http.Error(w, "not found", http.StatusNotFound)
default:
    var qe *QueryError                     // данные: какая операция и по какому id
    if errors.As(err, &qe) {
        log.Error("db failed", "op", qe.Op, "id", qe.ID, "err", err)
    }
    http.Error(w, "internal", http.StatusInternalServerError)
}

// Что выходит на деле (запуск на go1.27, id=42,
// внутри QueryError лежит sql.ErrNoRows):
//
//   fmt.Println(err)                  service.Profile: select_user(id=42): sql: no rows in result set
//   errors.Is(err, sql.ErrNoRows)     true      — звено с %w и Unwrap у QueryError, цепочка насквозь
//   errors.As(err, &qe)               true, qe.Op = "select_user", qe.ID = 42
//   fmt.Printf("%T", err)             *fmt.wrapError   — верхнее звено, а не *QueryError
//
// Последняя строка объясняет, зачем вообще нужны Is/As: тип верхней ошибки
// после обёртки уже не тот, и обычный type assertion промахнётся.

Sentinel errors

Sentinel, как уже говорилось, это заранее объявленная на уровне пакета ошибка, с которой сравнивают результат. Техника в Go самая старая, стандартная библиотека ею пронизана.

// Объявляем всегда через var: const не может быть интерфейсом
var ErrInsufficientFunds = errors.New("insufficient funds")

// Используем
if err := acc.Withdraw(100); errors.Is(err, ErrInsufficientFunds) {
    return c.JSON(422, "not enough money")
}

Обычно просят описать компромисс: sentinel-ы объявляет доменный слой (domain.ErrNotFound, domain.ErrConflict, domain.ErrForbidden). Их немного, они стабильны, и весь верхний код зависит только от домена. Инфраструктурные ошибки репозиторий на своей границе переводит в доменные, а не пускает наверх как есть.

Кастомные типы ошибок

Правило простое: если вызывающему нужны данные, а не факт, заводи тип. Валидация с именем поля, HTTP-ошибка со статусом и телом, ошибка ретрая с «подожди столько-то», ошибка лимита с текущим и максимальным значением — всё это sentinel-ом не выразить.

type ValidationError struct {
    Field  string
    Value  any
    Reason string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("field %q: %s", e.Field, e.Reason)
}

// RetryableError подсказывает, когда повторить
type RetryableError struct {
    After time.Duration
    Err   error
}

func (e *RetryableError) Error() string { return "retry after " + e.After.String() + ": " + e.Err.Error() }
func (e *RetryableError) Unwrap() error { return e.Err }         // цепочка не рвётся
func (e *RetryableError) Timeout() bool { return true }          // видна проверкам на Timeout()

// Метод Is: ошибки равны по коду, а не по указателю
type APIError struct {
    Code int
}

func (e *APIError) Error() string { return "api error " + strconv.Itoa(e.Code) }
func (e *APIError) Is(target error) bool {
    t, ok := target.(*APIError)
    return ok && t.Code == e.Code
}

// теперь работает так:
errors.Is(err, &APIError{Code: 429})   // true для любой 429-ошибки

errors.Join — агрегация (Go 1.20)

До 1.20 «несколько ошибок сразу» приходилось собирать руками: []error плюс свой тип с Error(), который склеивает сообщения. В 1.20 добавили errors.Join и вторую форму Unwrap (Unwrap() []error). С этого момента цепочка ошибок формально стала деревом, а errors.Is и errors.As обходят его в глубину.

func Join(errs ...error) error   // nil-ы отбрасываются; если все nil, вернётся nil

err := errors.Join(err1, nil, err2)
// Error() = "err1\nerr2", сообщения через перевод строки
// Unwrap() []error = [err1, err2]
// errors.Unwrap(err) == nil: одноуровневый Unwrap с деревом не работает

Join реально экономит код в трёх типичных местах:

// 1) Валидация: собрать все ошибки, а не первую
func (r CreateUserReq) Validate() error {
    var errs []error
    if r.Name == "" {
        errs = append(errs, fmt.Errorf("name: %w", ErrRequired))
    }
    if r.Age < 0 || r.Age > 150 {
        errs = append(errs, fmt.Errorf("age %d: %w", r.Age, ErrRange))
    }
    if !strings.Contains(r.Email, "@") {
        errs = append(errs, &ValidationError{Field: "email", Reason: "no @"})
    }
    return errors.Join(errs...)   // если срез пуст, вернётся ровно nil
}

// 2) Закрытие нескольких ресурсов в defer: ни одну ошибку не потерять
func (s *Server) Close() error {
    return errors.Join(
        s.httpSrv.Shutdown(context.Background()),
        s.db.Close(),
        s.broker.Close(),
    )
}

// 3) Классический паттерн "не потерять ошибку Close" через именованный возврат
func writeFile(name string, data []byte) (err error) {
    f, err := os.Create(name)
    if err != nil { return err }
    defer func() { err = errors.Join(err, f.Close()) }()   // раньше здесь молча терялось
    _, err = f.Write(data)
    return err
}

То же самое, что Join, умеет и fmt.Errorf с несколькими %w — тоже с Go 1.20. Разница в том, что Errorf даёт человекочитаемое сообщение с контекстом, а Join просто склеивает через \n:

err := fmt.Errorf("создание пользователя: %w, а также %w", ErrRequired, ErrRange)
errors.Is(err, ErrRequired)   // true
errors.Is(err, ErrRange)      // true

func Flatten(err error) []error {
    switch x := err.(type) {
    case interface{ Unwrap() []error }:
        var out []error
        for _, e := range x.Unwrap() { out = append(out, Flatten(e)...) }
        return out
    case interface{ Unwrap() error }:
        if inner := x.Unwrap(); inner != nil { return Flatten(inner) }
    }
    if err == nil { return nil }
    return []error{err}
}

Ошибки в слоистом приложении

Здесь заканчивается синтаксис и начинается инженерия. У ошибки в трёхслойном сервисе есть жизненный цикл: она рождается в инфраструктуре, получает контекст при подъёме, ровно один раз логируется и превращается в код ответа на границе. За каждый шаг отвечает свой слой, и на собесе это надо уметь проговорить.

// ── domain/errors.go: словарь ошибок, от которого зависят все слои ──
package domain

var (
    ErrNotFound     = errors.New("not found")
    ErrConflict     = errors.New("conflict")
    ErrForbidden    = errors.New("forbidden")
    ErrInvalidInput = errors.New("invalid input")
    ErrUnavailable  = errors.New("dependency unavailable")
)

// ── repository: переводим инфраструктуру в домен, наружу sql не течёт ──
func (r *UserRepo) Get(ctx context.Context, id int64) (domain.User, error) {
    var u domain.User
    err := r.db.QueryRowContext(ctx, qGet, id).Scan(&u.ID, &u.Email)
    switch {
    case errors.Is(err, sql.ErrNoRows):
        return u, fmt.Errorf("user %d: %w", id, domain.ErrNotFound)
    case err != nil:
        return u, fmt.Errorf("userRepo.Get(%d): %w", id, err)   // техническую не переводим
    }
    return u, nil
}

// ── service: добавляет операцию, не логирует ──
func (s *Profile) Show(ctx context.Context, id int64) (View, error) {
    u, err := s.users.Get(ctx, id)
    if err != nil {
        return View{}, fmt.Errorf("profile.Show: %w", err)
    }
    return render(u), nil
}

// ── transport: только здесь логируем и маппим ──
func (h *Handler) Show(w http.ResponseWriter, r *http.Request) {
    v, err := h.svc.Show(r.Context(), chi.URLParamInt64(r, "id"))
    if err != nil {
        writeError(w, r, err)
        return
    }
    writeJSON(w, http.StatusOK, v)
}

func writeError(w http.ResponseWriter, r *http.Request, err error) {
    status, code := httpStatus(err)

    if status >= 500 {
        // полный контекст — только во внутренний лог
        slog.ErrorContext(r.Context(), "request failed",
            "err", err, "path", r.URL.Path, "status", status)
    } else {
        slog.InfoContext(r.Context(), "request rejected", "code", code, "err", err)
    }

    // наружу — только код и trace_id, никакого err.Error()
    writeJSON(w, status, map[string]any{
        "code":     code,
        "trace_id": trace.SpanContextFromContext(r.Context()).TraceID().String(),
    })
}

func httpStatus(err error) (int, string) {
    switch {
    case errors.Is(err, context.Canceled):
        return 499, "client_closed_request"       // nginx-код: клиент ушёл сам
    case errors.Is(err, context.DeadlineExceeded):
        return http.StatusGatewayTimeout, "timeout"
    case errors.Is(err, domain.ErrNotFound):
        return http.StatusNotFound, "not_found"
    case errors.Is(err, domain.ErrConflict):
        return http.StatusConflict, "conflict"
    case errors.Is(err, domain.ErrForbidden):
        return http.StatusForbidden, "forbidden"
    case errors.Is(err, domain.ErrInvalidInput):
        return http.StatusUnprocessableEntity, "invalid_input"
    case errors.Is(err, domain.ErrUnavailable):
        return http.StatusServiceUnavailable, "unavailable"
    default:
        return http.StatusInternalServerError, "internal"
    }
}

Антипаттерны

// плохо
_ = json.Unmarshal(b, &v)          // молча
f, _ := os.Open(path)              // молча

if strings.Contains(err.Error(), "no rows") {   // по тексту
    return nil
}

func Load() *Config {              // паника вместо ошибки
    b, err := os.ReadFile(p)
    if err != nil { panic(err) }
    ...
}

if err != nil {
    log.Println(err)               // и логируем,
    return err                     // и возвращаем
}

if err != nil {
    return err                     // контекст потерян
}

// хорошо
if err := json.Unmarshal(b, &v); err != nil {
    return fmt.Errorf("decode payload: %w", err)
}

if errors.Is(err, sql.ErrNoRows) {              // по значению
    return domain.ErrNotFound
}

func Load(p string) (*Config, error) {
    b, err := os.ReadFile(p)
    if err != nil {
        return nil, fmt.Errorf("read config %s: %w", p, err)
    }
    ...
}

if err != nil {
    return fmt.Errorf("charge order %s: %w", id, err)
}

// а если игнорируем осознанно, пишем почему:
//nolint:errcheck // best-effort: метрику потерять не страшно
_ = metrics.Push(ctx, m)

Ещё три антипаттерна встречаются реже, но назвать их на собесе выигрышно: возврат конкретного типа вместо error (typed nil, разбирали выше); panic в библиотечном коде вместо возврата ошибки (вызывающий лишается выбора политики); и обёртка всего подряд через %w — ошибка сторонней библиотеки становится частью твоего публичного контракта, и без мажорной версии её оттуда уже не убрать.

type error interface {
    Error() string
}

func New(text string) error { return &errorString{text} }

a, b := errors.New("boom"), errors.New("boom")
fmt.Println(a == b)   // false

func f() error { var e *MyErr; return e }
fmt.Println(f() == nil)   // false

base := sql.ErrNoRows

w := fmt.Errorf("get user %d: %w", 42, base)
v := fmt.Errorf("get user %d: %v", 42, base)

w.Error() == v.Error()          // true: сообщения совпадают
errors.Is(w, sql.ErrNoRows)     // true
errors.Is(v, sql.ErrNoRows)     // false
errors.Unwrap(w)                // sql.ErrNoRows
errors.Unwrap(v)                // nil

type NotFoundError struct {
    Kind string
    ID   int64
}

func (e *NotFoundError) Error() string { return e.Kind + " not found" }

var ErrNoAccess = errors.New("no access")

func find(id int64) error {
    inner := &NotFoundError{Kind: "user", ID: id}
    return fmt.Errorf("service.Load: %w", fmt.Errorf("repo.Get: %w", inner))
}

err := find(42)
fmt.Println(err)     // service.Load: repo.Get: user not found

// Is проверяет факт (здесь false: sentinel в цепочке нет)
fmt.Println(errors.Is(err, ErrNoAccess))     // false

// As достаёт данные с любой глубины
var nf *NotFoundError
if errors.As(err, &nf) {
    fmt.Println(nf.Kind, nf.ID)              // user 42
}

// Is умеет и с деревом Join
joined := errors.Join(ErrNoAccess, err)
fmt.Println(errors.Is(joined, ErrNoAccess))  // true
fmt.Println(joined)                          // две строки: Join склеивает через \n
// no access
// service.Load: repo.Get: user not found

// Unwrap снимает ровно одно звено за раз:
fmt.Println(errors.Unwrap(err))              // repo.Get: user not found
fmt.Println(errors.Unwrap(errors.Unwrap(err)))  // user not found

var nf *NotFoundError
errors.As(err, &nf)            // ок

// Точные тексты паник (go1.27), у обеих префикс "errors: ":
errors.As(err, nf)             // если nf == nil:
                               //   panic: errors: target must be a non-nil pointer
                               // если nf уже заполнен, паника другая, потому что
                               // *target это NotFoundError, а error реализует *NotFoundError:
                               //   panic: errors: *target must be interface or implement error
errors.As(err, &struct{}{})    // panic: errors: *target must be interface or implement error

// target может указывать на интерфейс, так ловят «любой таймаут»:
var ne net.Error
if errors.As(err, &ne) && ne.Timeout() { /* ретраим */ }

func AsType[E error](err error) (E, bool)

// вместо двух строк с переменной наружу:
if nf, ok := errors.AsType[*NotFoundError](err); ok {
    fmt.Println(nf.Kind, nf.ID)     // user 42
}

// с интерфейсом работает так же:
if ne, ok := errors.AsType[net.Error](err); ok && ne.Timeout() { /* ретраим */ }

var ErrNotFound = errors.New("not found")   // var, не const

type ValidationError struct {
    Field  string
    Reason string
    Err    error       // причина, если есть
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("field %q: %s", e.Field, e.Reason)
}
func (e *ValidationError) Unwrap() error { return e.Err }

// использование
var ve *ValidationError
if errors.As(err, &ve) {
    w.WriteHeader(422)
    json.NewEncoder(w).Encode(map[string]string{"field": ve.Field, "reason": ve.Reason})
}

func Join(errs ...error) error
// nil-аргументы отбрасываются
// если ненулевых не осталось, возвращается ровно nil
// Error() склеивает сообщения через "\n"

func (r Req) Validate() error {
    var errs []error
    if r.Name == "" { errs = append(errs, fmt.Errorf("name: %w", ErrRequired)) }
    if r.Age < 0    { errs = append(errs, fmt.Errorf("age: %w", ErrRange)) }
    return errors.Join(errs...)         // пусто → nil, проверять длину не нужно
}

err := Req{}.Validate()
errors.Is(err, ErrRequired)   // true
errors.Is(err, ErrRange)      // true
errors.Unwrap(err)            // nil: одноуровневый Unwrap с деревом не работает

err := fmt.Errorf("create user: %w и %w", ErrRequired, ErrRange)

// repository
if errors.Is(err, sql.ErrNoRows) {
    return u, fmt.Errorf("user %d: %w", id, domain.ErrNotFound)
}
// service
return View{}, fmt.Errorf("profile.Show: %w", err)
// transport
slog.ErrorContext(ctx, "request failed", "err", err, "path", r.URL.Path)
writeJSON(w, httpStatus(err), errBody{Code: code, TraceID: traceID})

// никогда
if strings.Contains(err.Error(), "no rows") { ... }
if err.Error() == "connection refused" { ... }

4.2panic vs error

Вопрос «когда panic, а когда error» на собесе почти всегда быстро сворачивает в практику: покажи recover-middleware, объясни, почему recover в хендлере не спасёт горутину, которую этот хендлер запустил, и что делать, если паникует чужая библиотека. Ниже разобраны механика раскрутки и все три сценария.

Сначала — три слова про стек, дальше они идут без пояснений

Что происходит с программой между строкой panic(...) и падением процесса — и где в этот промежуток можно вклиниться? Ответ целиком про устройство стека, поэтому три слова расшифруем заранее.

1. Кадр стека — «рабочий стол» одного вызова функции

Когда функция вызывается, ей выделяется на стеке кусочек памяти под её аргументы, локальные переменные и адрес возврата. Этот кусочек и называется кадром (stack frame). Вызовы вложены друг в друга (main позвал хендлер, хендлер позвал сервис, сервис позвал репозиторий), и кадры лежат стопкой: последний вызванный сверху. Функция вернулась — её кадр сняли.

2. Раскрутка стека — снятие этих кадров подряд, без возвратов

При обычном return снимается один кадр, и управление уходит туда, откуда позвали. При раскрутке (stack unwinding) кадры снимаются один за другим не потому, что функции доработали, а потому, что случилась паника и возвращаться уже некуда. По дороге паника только выполняет отложенные вызовы (defer) каждого снимаемого кадра, и только в них recover() может её остановить.

3. Дескриптор горутины (g) — служебная структура с состоянием горутины

Рантайм видит каждую горутину как структуру runtime.g: в ней лежат границы её стека, текущее состояние, список её defer и — что здесь важно — указатель на текущую панику. Слово дескриптор означает ровно это: не сама горутина, а «карточка учёта» на неё, по которой рантайм ею управляет. Из этого вырастает половина главы: у каждой горутины карточка своя. Паника подвешивается к дескриптору той горутины, где случилась, и раскручивает только её стек — поэтому recover в одной горутине физически не может увидеть панику в другой.

Что происходит внутри рантайма

Компилятор превращает panic в обычный вызов функции runtime.gopanic. Она кладёт в стек текущей горутины структуру runtime._panic (значение, флаги, указатель на предыдущую панику) и цепляет её к полю gp._panic у g, дескриптора горутины. Обычный поток управления на этом заканчивается: дальше работает только раскрутка.

Раскрутка идёт по цепочке отложенных вызовов. У каждой горутины есть односвязный список gp._defer, куда попадают defer. Но большую часть из них компилятор (Go 1.14+) в список не кладёт вовсе: если defer стоит не в цикле и их в функции немного (до восьми), вызов вшивается прямо в эпилог — это open-coded defers. Рантайм при панике находит такие вызовы по funcdata-записи самой функции _FUNCDATA_OpenCodedDeferInfo. Поэтому defer в Go стоит порядка одной наносекунды в happy path и «дорожает» только в момент паники.

Дальше рантайм идёт кадр за кадром, снизу вверх: выполняет все defer текущего кадра в порядке LIFO, снимает кадр, переходит к вызывающему. Если внутри отложенной функции вызван recover() (это runtime.gorecover), рантайм проверяет, что вызов сделан непосредственно из отложенной функции того кадра, который сейчас раскручивается, помечает _panic.recovered = true и через runtime.recovery восстанавливает SP/PC так, будто эта функция просто дошла до return. Именованные результаты функция вернёт такими, какими они остались на момент выхода из defer.

Если ни один defer не сделал recover, раскрутка доходит до вершины горутины, и рантайм вызывает runtime.fatalpanic. Та печатает panic: ..., трейсбек (по умолчанию только паникующей горутины; GOTRACEBACK=all печатает все, GOTRACEBACK=crash ещё и роняет процесс с core dump) и зовёт exit(2). Отложенные вызовы остальных горутин не выполняются — никакого «корректного завершения» при панике нет.

// Работает: recover прямо в отложенной функции
func ok() (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("panic: %v", r)
        }
    }()
    panic("boom")
}

// Тоже работает: helper сама и есть отложенная функция
func ok2() {
    defer helper()
    panic("boom")
}

// Не работает: recover на уровень глубже
func bad() {
    defer func() {
        helper()      // recover внутри вернёт nil
    }()
    panic("boom")     // процесс всё равно упадёт
}

func helper() {
    if r := recover(); r != nil {
        fmt.Println("поймал:", r)
    }
}

// Запуск bad() на go1.27: «поймал: boom» не печатается, программа падает.
// stderr, exit status 2:
//   panic: boom
//
//   goroutine 1 [running]:
//   main.bad()
//           /tmp/x/main.go:11 +0x48
//   main.main()
//           /tmp/x/main.go:20 +0x1c
// recover() возвращает не-nil, только если вызван напрямую из отложенной функции
// паникующего кадра. Здесь helper — обычный вызов внутри defer, кадром глубже.

Panic и fatal error — это не одно и то же

Половина «неперехватываемых паник», которые приносят на собес, вовсе не паники. fatal error печатает рантайм напрямую, минуя механизм _panic: никакой раскрутки нет, defer не выполняются, recover физически не может сработать, потому что его никто не позовёт. Команда Go сделала так сознательно: после гонки по map её внутренности уже могли быть испорчены, и продолжать работу опаснее, чем упасть, а при дедлоке продолжать просто некому — спят все горутины.

Когда panic допустим

Рабочее правило: error возвращают в ожидаемой ситуации, panic зовут при сломанном инварианте. Речь не о «редкой ошибке»: дальше выполнять код бессмысленно, потому что предположения, на которых он написан, уже нарушены. На практике таких случаев четыре.

// Хорошо: константа, компилируется один раз при старте пакета.
var emailRe = regexp.MustCompile(`^[^@\s]+@[^@\s]+\.[a-z]{2,}$`)

// Плохо: паттерн из конфига. Одна опечатка в regex в YAML - и сервис не стартует
// или падает на первом же запросе.
func NewFilter(cfg Config) *Filter {
    return &Filter{re: regexp.MustCompile(cfg.Pattern)}   // NO
}

// Хорошо: ошибка конфига - это обычная ошибка.
func NewFilter(cfg Config) (*Filter, error) {
    re, err := regexp.Compile(cfg.Pattern)
    if err != nil {
        return nil, fmt.Errorf("bad filter pattern %q: %w", cfg.Pattern, err)
    }
    return &Filter{re: re}, nil
}

Почему panic не должен пересекать границу пакета

Как только твоя библиотека паникует на данных вызывающего, ты отнял у него право выбрать политику. Он хотел вернуть 400, залогировать и жить дальше — а получил падение процесса. Отсюда правило: panic остаётся внутри пакета, а наружу из экспортированной функции выходит только error.

Внутри пакета паника при этом бывает очень удобна: ею быстро выходят из глубокой рекурсии, где протаскивать error через двадцать уровней противно. Так делает сама стандартная библиотека: encoding/json, text/template, go/parser (там это буквально называется bailout) кидают панику собственного приватного типа и ловят её на границе экспортированной функции.

// Приватный тип - маркер «это наша паника, а не чужая».
type bailout struct {
    err error
}

func (p *parser) fail(format string, a ...any) {
    panic(bailout{fmt.Errorf(format, a...)})
}

// Экспортированная функция: наружу - только error.
func Parse(src []byte) (ast *AST, err error) {   // именованный результат обязателен
    defer func() {
        rec := recover()
        if rec == nil {
            return
        }
        b, ok := rec.(bailout)
        if !ok {
            panic(rec)      // чужая паника - пробрасываем как есть, не глотаем
        }
        err = fmt.Errorf("parse: %w", b.err)
    }()

    p := &parser{src: src}
    return p.parseFile(), nil
}

recover-middleware в HTTP-сервере

Свой recover у net/http уже есть. В conn.serve стоит defer, который ловит панику из хендлера, печатает http: panic serving 10.0.0.5:52341: ... со стеком в Server.ErrorLog и закрывает соединение. Процесс не падает — и на этом хорошие новости заканчиваются.

• Клиент не получает ответа. Соединение обрывается: на той стороне EOF, connection reset by peer или пустой ответ. Балансировщик посчитает это 502, а может и вообще не посчитает.
• В твоих метриках ничего нет. Хендлер не вернулся, значит, middleware метрик тоже не досчитало: http_requests_total{code="500"} не вырос, алерт не сработал.
• В логе нет контекста. За Server.ErrorLog стоит обычный log.Logger, который пишет в stderr без trace_id, без пользователя, без пути, без структурированных полей. Найти этот стек в Loki по trace_id ты не сможешь.
• Keep-alive убит. Соединение закрывается, клиент открывает новое, и на всплеске паник это заметная лишняя нагрузка.

// wrapWriter нужен, чтобы знать, начали ли уже писать тело:
// после первого Write статус ответа изменить уже нельзя.
type wrapWriter struct {
    http.ResponseWriter
    status int
    wrote  bool
}

func (w *wrapWriter) WriteHeader(code int) {
    if w.wrote {
        return
    }
    w.status, w.wrote = code, true
    w.ResponseWriter.WriteHeader(code)
}

func (w *wrapWriter) Write(b []byte) (int, error) {
    if !w.wrote {
        w.WriteHeader(http.StatusOK)
    }
    return w.ResponseWriter.Write(b)
}

func Recoverer(log *slog.Logger) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            ww := &wrapWriter{ResponseWriter: w}

            defer func() {
                rec := recover()
                if rec == nil {
                    return
                }
                // http.ErrAbortHandler - служебная паника самого net/http:
                // так хендлер сообщает серверу «оборви ответ молча».
                // Её нельзя глотать, иначе сломаем контракт сервера.
                if rec == http.ErrAbortHandler {
                    panic(rec)
                }

                log.ErrorContext(r.Context(), "panic in http handler",
                    slog.Any("panic", rec),
                    slog.String("method", r.Method),
                    slog.String("path", r.URL.Path),
                    slog.String("trace_id", traceID(r.Context())),
                    slog.String("stack", string(debug.Stack())),   // стек снимаем здесь,
                )                                                  // выше по стеку он уже потерян
                panicsTotal.WithLabelValues(r.Method, routePattern(r)).Inc()

                // Если тело уже пошло клиенту, статус не переписать -
                // остаётся только оборвать ответ, чтобы клиент увидел битый payload,
                // а не «успешный» усечённый JSON.
                if ww.wrote {
                    panic(http.ErrAbortHandler)
                }
                ww.Header().Set("Content-Type", "application/json; charset=utf-8")
                ww.WriteHeader(http.StatusInternalServerError)
                _, _ = ww.Write([]byte(`{"error":"internal","trace_id":"` + traceID(r.Context()) + `"}`))
            }()

            next.ServeHTTP(ww, r)
        })
    }
}

gRPC: здесь recover обязателен, а не желателен

У grpc-go нет встроенного recover. Паника в хендлере поднимается по горутине, обслуживающей стрим, доходит до вершины и роняет весь процесс — вместе со всеми остальными активными RPC. Один кривой запрос кладёт инстанс целиком. Поэтому recovery-интерцептор в бутстрапе обязателен, без вариантов.

func RecoveryUnary(log *slog.Logger) grpc.UnaryServerInterceptor {
    return func(ctx context.Context, req any, info *grpc.UnaryServerInfo,
        handler grpc.UnaryHandler) (resp any, err error) {

        defer func() {
            rec := recover()
            if rec == nil {
                return
            }
            log.ErrorContext(ctx, "panic in grpc handler",
                slog.String("method", info.FullMethod),
                slog.Any("panic", rec),
                slog.String("stack", string(debug.Stack())))
            panicsTotal.WithLabelValues("grpc", info.FullMethod).Inc()

            resp = nil
            // Наружу - только codes.Internal без деталей: текст паники
            // может содержать данные другого пользователя.
            err = status.Error(codes.Internal, "internal error")
        }()

        return handler(ctx, req)
    }
}

// Для стримов нужен отдельный интерцептор - StreamServerInterceptor,
// unary его не покрывает.

Паника из сторонней библиотеки

Шаги идут по убыванию правильности, а не удобства.

1. Локализовать и завести issue. Паника в чужом коде почти всегда означает баг библиотеки либо неверное использование её API. Воспроизведи минимальным тестом.
2. Запинить или форкнуть версию. Если баг известен и уже починен, обновись; если нет, сделай форк с патчем и replace в go.mod. Это честнее, чем прятать.
3. Обернуть вызов в собственный recover временно, с метрикой и алертом, чтобы «мы затыкаем чужую панику N раз в сутки» было видно.
4. Изолировать процессом, если библиотека совсем нестабильна (cgo-обёртки, парсеры чужих форматов, ffmpeg-биндинги): вынести её в отдельный бинарь и общаться через unix-сокет. Только так можно пережить и fatal error, и SIGSEGV из cgo.

// Обёртка-изолятор для одного вызова.
// Возвращает ошибку вместо паники и не глотает признак того, что паника была.
var ErrLibPanic = errors.New("third-party library panicked")

func safeDecode(b []byte, v any) (err error) {
    defer func() {
        rec := recover()
        if rec == nil {
            return
        }
        libPanics.WithLabelValues("badcodec.Decode").Inc()

        // Сохраняем и текст, и стек: без стека такую панику не найти,
        // потому что она пришла из чужого кода.
        err = fmt.Errorf("%w: badcodec.Decode: %v\n%s", ErrLibPanic, rec, debug.Stack())
    }()

    return badcodec.Decode(b, v)   // паникует на некоторых битых входах
}

Паника в чужой горутине: почему recover бессилен

На этом вопросе проваливаются чаще всего. recover() читает gp._panic текущей горутины. У новой горутины свой g, своя цепочка _defer и свой список паник. Кадры родителя в ней не участвуют, да и «родителя» у горутины формально нет: go f() не создаёт никакой связи, кроме записи в трейсбеке created by ....

// Единственная точка запуска горутин в проекте.
// Правило на ревью: голый `go` разрешён только внутри этого файла.
func Go(ctx context.Context, log *slog.Logger, name string, fn func(context.Context)) {
    go func() {
        defer func() {
            rec := recover()
            if rec == nil {
                return
            }
            log.ErrorContext(ctx, "panic in goroutine",
                slog.String("goroutine", name),
                slog.Any("panic", rec),
                slog.String("stack", string(debug.Stack())))
            goroutinePanics.WithLabelValues(name).Inc()
        }()
        fn(ctx)
    }()
}

// errgroup.Group.Go панику не перехватывает. Она только считает
// горутины и запоминает первую ошибку - паника внутри f() уходит наверх
// по своей горутине и роняет процесс. Хочешь пережить - ставь recover сам.

Паника в воркере пула

Даже те, кто помнит про safeGo, валятся на вопросе, где именно поставить recover. Если он стоит в самой функции воркера, воркер после первой же паники завершится, и пул тихо усохнет с 16 горутин до нуля, продолжая при этом «работать». Очередь будет расти, на метрику живых горутин никто не смотрит, инцидент найдут через сутки.

// Плохо: recover на уровне воркера.
// Одна паника - минус один воркер навсегда.
func (p *Pool) worker(id int) {
    defer func() {
        if r := recover(); r != nil {
            p.log.Error("worker died", "id", id)
        }
    }()
    for job := range p.jobs {
        job.Run()
    }
}

// Хорошо: recover на уровне одной задачи.
// Воркер переживает любую задачу.
func (p *Pool) worker(ctx context.Context, id int) {
    for job := range p.jobs {
        p.runOne(ctx, id, job)
    }
}

func (p *Pool) runOne(ctx context.Context, id int, job Job) {
    defer func() { ... recover, лог, job.Fail(...) ... }()
    job.Run(ctx)
}

func (p *Pool) runOne(ctx context.Context, workerID int, job Job) {
    defer func() {
        rec := recover()
        if rec == nil {
            return
        }
        p.log.ErrorContext(ctx, "panic while processing job",
            slog.String("job_id", job.ID),
            slog.Int("worker", workerID),
            slog.Any("panic", rec),
            slog.String("stack", string(debug.Stack())))
        jobPanics.WithLabelValues(job.Type).Inc()

        // Что делать с задачей, решай явно:
        //  - брокер: Nack без requeue -> DLQ (паника детерминирована, requeue = вечный цикл);
        //  - своя очередь: пометить failed с причиной, не возвращать в работу;
        //  - при at-least-once обязательно ограничить delivery_count.
        job.Fail(ctx, fmt.Errorf("panic: %v", rec))
    }()

    job.Run(ctx)
}

Panic и исключения других языков

Формально panic/recover устроены как исключения: та же раскрутка стека с перехватом. Отличаются они культурой применения и парой важных ограничений.

Стандартные паники Go: как звучат сообщения

Формулировки полезно помнить дословно: на собесе часто дают текст паники из прода и просят по нему назвать причину. Все эти паники перехватываются (в отличие от fatal error из таблицы выше).

Что выведет код?

func f() (n int) {
    defer func() {
        if r := recover(); r != nil {
            n = -1
        }
    }()
    defer fmt.Println("A")

    n = 1
    panic("boom")
}

func main() {
    fmt.Println(f())
    fmt.Println("done")
}

// вывод (проверено запуском на go1.27):
// A
// -1
// done
//
// Без имени у результата (func f() int) то же самое, но вместо -1 будет 0.

type bailout struct {
    err error
}

func Parse(src []byte) (ast *AST, err error) {   // именованный результат обязателен
    defer func() {
        rec := recover()
        if rec == nil {
            return
        }
        b, ok := rec.(bailout)
        if !ok {
            panic(rec)     // чужая паника - пробрасываем, не глотаем
        }
        err = fmt.Errorf("parse: %w", b.err)
    }()
    p := &parser{src: src}
    return p.parseFile(), nil
}

var ErrLibPanic = errors.New("third-party library panicked")

func safeDecode(b []byte, v any) (err error) {
    defer func() {
        rec := recover()
        if rec == nil {
            return
        }
        libPanics.WithLabelValues("badcodec.Decode").Inc()
        // Стек обязателен: без него чужую панику не найти.
        err = fmt.Errorf("%w: badcodec.Decode: %v\n%s", ErrLibPanic, rec, debug.Stack())
    }()
    return badcodec.Decode(b, v)
}

// Единственная точка запуска горутин. На ревью правило:
// голый `go` разрешён только внутри этого файла.
func Go(ctx context.Context, log *slog.Logger, name string, fn func(context.Context)) {
    go func() {
        defer func() {
            rec := recover()
            if rec == nil {
                return
            }
            log.ErrorContext(ctx, "panic in goroutine",
                slog.String("goroutine", name),
                slog.Any("panic", rec),
                slog.String("stack", string(debug.Stack())))
            goroutinePanics.WithLabelValues(name).Inc()
        }()
        fn(ctx)
    }()
}

func (p *Pool) worker(ctx context.Context, id int) {
    for job := range p.jobs {
        p.runOne(ctx, id, job)     // воркер переживает любую задачу
    }
}

func (p *Pool) runOne(ctx context.Context, workerID int, job Job) {
    defer func() {
        rec := recover()
        if rec == nil {
            return
        }
        p.log.ErrorContext(ctx, "panic while processing job",
            slog.String("job_id", job.ID), slog.Int("worker", workerID),
            slog.Any("panic", rec), slog.String("stack", string(debug.Stack())))
        jobPanics.WithLabelValues(job.Type).Inc()

        // Судьбу задачи выбираем явно: Nack без requeue -> DLQ.
        // Возвращать в очередь нельзя: паника детерминирована, будет вечный цикл.
        job.Fail(ctx, fmt.Errorf("panic: %v", rec))
    }()
    job.Run(ctx)
}

4.3Паттерны надёжности

Здесь заканчивается язык и начинается инженерия. Retry, backoff, circuit breaker, таймауты, деградация — все паттерны этой главы нужны, чтобы отказ одной зависимости не превращался в отказ всей системы. Назвать их легко, настроить правильно трудно. При неаккуратной настройке почти каждый делает ровно наоборот и добивает то, что чинил.

Сначала — семь слов, которые дальше идут без перевода

Зависимость сломалась или затормозила. Что должен сделать твой сервис, чтобы не упасть следом и заодно не добить её окончательно? Ответ собирается из нескольких приёмов, и почти все они называются английскими словами, которые в русской речи так и не перевели. Договоримся о них сразу: дальше они идут на каждой странице без пояснений.

1. Транзиентная ошибка — та, которая может пройти сама

Транзиентной (transient: «преходящая», «временная») называют ошибку, причина которой лежит снаружи и меняется со временем: сеть моргнула, соединение оборвали, сервер перегружен и ответил 503, база поймала deadlock. Повтори ту же операцию через секунду — и она вполне может пройти. На другом полюсе стоит детерминированная ошибка: невалидный JSON, нет прав, нет такого пользователя. Сколько её ни повторяй, ответ будет тот же.

Отсюда первое правило: ретраить (повторять) имеет смысл только транзиентные ошибки. Повторяя детерминированную, ты гарантированно впустую тратишь свои и чужие ресурсы.

2. Идемпотентность — повтор не меняет результат

Операция идемпотентна, если состояние системы не зависит от того, выполнил ты её один раз или пять раз подряд. «Поставить статус = banned» идемпотентно: сколько ни ставь, статус один. А вот «списать 100 рублей» — нет, пять повторов спишут 500.

Критерий строгий: операция не меняет состояние второй раз. Если она всего лишь не падает при повторе, этого мало. Причём это свойство самой операции, а не кода, который её повторяет. Ретрай безопасен только для идемпотентной операции, потому что таймаут не говорит «не сработало», он говорит «я не знаю». Запрос мог дойти, выполниться и потеряться уже на обратном пути.

3. Backoff — растущая пауза между попытками

При backoff (буквально «отступить, сдать назад») клиент ждёт перед следующей попыткой, и пауза растёт с каждым разом. Обычно рост экспоненциальный: 100 мс, 200, 400, 800 — и так до потолка. Упавшую зависимость не долбят в полную силу, ей дают время подняться. Ретрай без backoff, сразу и в лоб, мгновенно удваивает нагрузку на то, что и так не справляется.

4. Jitter — случайный разброс этих пауз

Jitter («дрожание», слово пришло из электроники) подмешивает к паузе backoff случайность: вместо ровно 400 мс ждём случайное время где-то от нуля до 400 мс. Backoff разносит по времени попытки одного клиента, а клиентов между собой никак не разводит. Тысяча клиентов получила отказ в одну и ту же секунду и поставила одинаковые таймеры — через 400 мс на зависимость придёт ровно тысяча одновременных запросов и снова её уронит. Jitter размазывает эту волну.

5. Bulkhead — отдельная квота ресурсов на каждую зависимость

Bulkhead переводится как «переборка», глухая перегородка между отсеками корабля: пробили один отсек — затопило только его, а не весь корпус. В коде это лимит на число одновременных вызовов, свой для каждой зависимости: платёжный API получает не больше 50 горутин, поиск не больше 200. Тогда одна медленная зависимость не съест все горутины и соединения сервиса и не утащит за собой всё остальное, что вообще-то работает.

6. Load shedding — сознательный отказ части запросов при перегрузке

Load shedding, «сброс нагрузки», пришёл из энергетики: там так называют веерные отключения. Идея контринтуитивная: если входящих запросов больше, чем сервис способен переварить, правильнее честно отказать части из них сразу, чем принять все и всех обслужить плохо. Приняв всё, ты получишь растущую очередь, растущие задержки и в итоге таймаут у всех — то есть 100 % отказов вместо 10 %. И отказывать надо быстро: 429 или 503 в первую миллисекунду, а не после тридцати секунд ожидания в очереди.

7. Circuit breaker — предохранитель, который сам отключает вызовы к упавшей зависимости

Circuit breaker дословно значит «автоматический выключатель», тот самый автомат в электрощитке: пошёл ток выше нормы — он щёлкнул и разорвал цепь, чтобы не сгорела проводка. По-русски говорят «брейкер» или «предохранитель», реже «размыкатель цепи».

В коде это обёртка вокруг вызова зависимости, которая считает отказы. Пока всё хорошо, она просто пропускает вызовы насквозь. Когда доля отказов переваливает порог, она перестаёт пускать вызовы вообще и на какое-то время отвечает ошибкой мгновенно, никуда не ходя. Потом пробует пропустить один-два пробных запроса: ответили нормально — трафик возвращается, снова отказ — пауза продлевается.

Пока зависимость лежит, каждый вызов к ней впустую держит горутину и соединение на полный таймаут. Брейкер экономит их тебе и заодно снимает нагрузку с того, кто и так не справляется. Три его состояния и пороги переходов разобраны ниже, в отдельном разделе.

Ретраить или нет: классификация ошибок

Ретраить стоит, только когда одновременно выполнены два условия: ошибка транзиентная (повтор той же операции может дать другой результат) и операция идемпотентна (повтор безопасен, даже если первая попытка на самом деле прошла, а ответ потерялся). Нарушишь любое — и ретрай станет либо бесполезным, либо вредным.

Коварнее всего таймаут. Запрос мог дойти и выполниться, а ответ застрять на обратном пути, и клиент этого не узнает. Ретрай после таймаута и есть тот случай, ради которого нужна идемпотентность.

Что ретраить: конкретика по транспортам

Идемпотентность — фундамент, без которого ретрай опасен

Определение из начала главы: идемпотентная операция не меняет состояние второй раз. Обеспечивать это свойство надо первым, и способов для этого пять.

Ключ идемпотентности: рабочая схема

CREATE TABLE idempotency_keys (
    key          text        PRIMARY KEY,      -- то, что прислал клиент
    endpoint     text        NOT NULL,         -- один ключ на один эндпоинт
    request_hash bytea       NOT NULL,         -- защита от «тот же ключ, другое тело»
    state        text        NOT NULL,         -- in_progress | done
    status_code  int,
    response     jsonb,
    created_at   timestamptz NOT NULL DEFAULT now()
);
-- Ключи живут ограниченное время: сутки для платежей - разумный дефолт.
CREATE INDEX idempotency_keys_created_at_idx ON idempotency_keys (created_at);

func (s *Service) CreatePayment(ctx context.Context, key string, req Request) (Response, error) {
    hash := sha256.Sum256(req.Canonical())

    // 1. Атомарно пытаемся занять ключ. Гонку решает сама БД:
    //    выигрывает ровно один INSERT, остальным вернётся 0 строк.
    claimed, err := s.repo.ClaimKey(ctx, key, "POST /payments", hash[:])
    if err != nil {
        return Response{}, err
    }

    if !claimed {
        rec, err := s.repo.LoadKey(ctx, key)
        if err != nil {
            return Response{}, err
        }
        // 2. Тот же ключ с другим телом - это ошибка клиента, а не повтор.
        if !bytes.Equal(rec.RequestHash, hash[:]) {
            return Response{}, ErrIdempotencyKeyReuse      // 422
        }
        // 3. Первый запрос ещё в работе: не выполняем параллельно.
        //    Клиенту честно говорим «повтори позже».
        if rec.State == StateInProgress {
            return Response{}, ErrInProgress               // 409 + Retry-After: 1
        }
        return rec.Response, nil                           // 4. Отдаём готовый ответ
    }

    resp, err := s.charge(ctx, req)
    if err != nil {
        // Деньги точно не списаны — отпускаем ключ, и повтор пройдёт заново:
        // иначе ключ навсегда залипнет в in_progress. Исход неизвестен
        // (таймаут после отправки) — не отпускаем: повтор может списать
        // второй раз, такой ключ ждёт сверки с платёжкой.
        if !errors.Is(err, ErrOutcomeUnknown) {
            _ = s.repo.ReleaseKey(ctx, key)
        }
        return Response{}, err
    }

    // 5. Сохраняем ответ под ключом: повтор получит его, а не второе списание.
    if err := s.repo.CompleteKey(ctx, key, resp); err != nil {
        return Response{}, err
    }
    return resp, nil
}

Экспоненциальный backoff и jitter

Хуже всего ретраить сразу: зависимость упала под нагрузкой, а ты мгновенно удваиваешь ей нагрузку. Экспоненциальный backoff растягивает попытки: base * 2^attempt с потолком cap. Но одного backoff мало, потому что все клиенты падают одновременно — а значит, одновременно и просыпаются.

Retry storm (он же thundering herd) выглядит так. В 12:00:00 сервис зависимости отвечает 503 всей тысяче клиентов. Все ставят таймер на 1 секунду. В 12:00:01 приходит ровно тысяча одновременных запросов — сервис, который только начал вставать, снова ложится. Все ставят таймер на 2 секунды. В 12:00:03 — снова тысяча. Система входит в устойчивый автоколебательный режим и сама из него не выходит: каждая волна валит зависимость заново. Ретрай тут не помогает восстановиться, а не даёт восстановиться.

Четыре стратегии jitter

Retry, который уважает context и Retry-After

type Policy struct {
    MaxAttempts int           // всего попыток, включая первую
    Base        time.Duration // 100ms
    Cap         time.Duration // 5s
    Budget      time.Duration // потолок на всю серию; 0 - ограничивает только ctx
}

// Classifier отвечает на два вопроса сразу: повторять ли и сколько ждать,
// если сервер сам назвал паузу (Retry-After, gRPC RetryInfo).
type Classifier func(error) (retry bool, after time.Duration)

func Do(ctx context.Context, p Policy, cls Classifier, op func(context.Context) error) error {
    if p.MaxAttempts <= 0 { p.MaxAttempts = 3 }
    if p.Base <= 0        { p.Base = 100 * time.Millisecond }
    if p.Cap <= 0         { p.Cap = 5 * time.Second }

    if p.Budget > 0 {
        var cancel context.CancelFunc
        ctx, cancel = context.WithTimeout(ctx, p.Budget)
        defer cancel()
    }

    var last error
    for attempt := 0; attempt < p.MaxAttempts; attempt++ {
        // Не ходим в сеть с уже истёкшим дедлайном: это чистая трата
        // соединения и лишняя нагрузка на зависимость.
        if err := ctx.Err(); err != nil {
            return errors.Join(last, err)
        }

        last = op(ctx)
        if last == nil {
            return nil
        }

        // Отмена самого контекста - не транзиентная ошибка. Клиент ушёл.
        if ctx.Err() != nil {
            return errors.Join(last, ctx.Err())
        }

        retry, after := cls(last)
        if !retry || attempt == p.MaxAttempts-1 {
            return last
        }

        delay := after                                  // сервер назвал паузу - уважаем
        if delay <= 0 {
            delay = fullJitter(p.Base, p.Cap, attempt)
        }

        // Спать дольше, чем осталось до дедлайна, бессмысленно:
        // лучше вернуть ошибку сразу, чем разбудить таймер в пустоту.
        if dl, ok := ctx.Deadline(); ok && time.Until(dl) <= delay {
            return errors.Join(last, context.DeadlineExceeded)
        }

        t := time.NewTimer(delay)
        select {
        case <-ctx.Done():
            t.Stop()                                    // освобождаем таймер сразу, не ждём GC
            return errors.Join(last, ctx.Err())
        case <-t.C:
        }
    }
    return last
}

// math/rand/v2 (Go 1.22+): глобальный генератор без блокировок и без ручного Seed.
func fullJitter(base, cap time.Duration, attempt int) time.Duration {
    backoff := base << attempt              // base * 2^attempt
    if backoff > cap || backoff <= 0 {      // <=0 - защита от переполнения int64
        backoff = cap
    }
    return time.Duration(rand.Int64N(int64(backoff)) + 1)
}

// Классификатор для HTTP. Заодно решает вопрос с Retry-After.
func HTTPClassifier(err error) (bool, time.Duration) {
    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
        return false, 0
    }

    var he *HTTPError
    if errors.As(err, &he) {
        switch he.Code {
        case 408, 425, 429, 500, 502, 503, 504:
            return true, he.RetryAfter          // распарсен из заголовка
        default:
            return false, 0
        }
    }

    var ne net.Error
    if errors.As(err, &ne) && ne.Timeout() {
        return true, 0
    }
    return errors.Is(err, syscall.ECONNRESET) ||
        errors.Is(err, syscall.ECONNREFUSED) ||
        errors.Is(err, io.ErrUnexpectedEOF), 0
}

func parseRetryAfter(h http.Header) time.Duration {
    v := h.Get("Retry-After")
    if v == "" {
        return 0
    }
    if secs, err := strconv.Atoi(v); err == nil && secs >= 0 {
        return time.Duration(secs) * time.Second
    }
    if t, err := http.ParseTime(v); err == nil {      // HTTP-date - тоже валидная форма
        if d := time.Until(t); d > 0 {
            return d
        }
    }
    return 0
}

Circuit breaker

Ретраи с backoff вытаскивают один запрос. Circuit breaker имеет дело с потоком запросов к упавшей зависимости. Пока сервис лежит, каждый вызов к нему занимает горутину и соединение из пула на весь таймаут. Тысяча запросов в секунду × 3 секунды таймаута дают три тысячи горутин, висящих в ожидании, и исчерпанный пул соединений — после чего перестают проходить вызовы и к здоровым зависимостям. Так локальный отказ становится общим.

Брейкер даёт две вещи. Вызывающий получает fail fast: ошибку за 0,1 мс вместо таймаута на 3 секунды, ресурсы свободны, можно сразу уходить в fallback. Зависимость получает передышку: трафик срезан почти в ноль, и у неё появляется шанс встать. Поэтому брейкер помогает там, где голый retry делает только хуже.

Разбор sony/gobreaker

// gobreaker v2 - дженерик по типу результата.
var billingCB = gobreaker.NewCircuitBreaker[*Receipt](gobreaker.Settings[*Receipt]{
    Name: "billing",

    // Сколько пробных запросов пропустить в half-open одновременно.
    // 0 означает 1. Это и есть ограничение пробного трафика.
    MaxRequests: 3,

    // Как часто обнулять счётчики, пока состояние CLOSED.
    // Без этого одиночные отказы за час накопятся и откроют брейкер на ровном месте.
    Interval: 60 * time.Second,

    // Сколько держать OPEN до перехода в HALF-OPEN.
    Timeout: 30 * time.Second,

    ReadyToTrip: func(c gobreaker.Counts) bool {
        // Порог по доле, а не по числу: защищает от ложных срабатываний
        // на низком трафике, когда 3 отказа - это статистический шум.
        return c.Requests >= 20 &&
            float64(c.TotalFailures)/float64(c.Requests) >= 0.5
    },

    // Главная настройка, и её чаще всего забывают.
    IsSuccessful: func(err error) bool {
        if err == nil {
            return true
        }
        // Клиент ушёл - это не отказ зависимости.
        if errors.Is(err, context.Canceled) {
            return true
        }
        // 4xx, кроме 429, - вина запроса, а не сервиса. Иначе один бот с кривыми
        // запросами откроет брейкер всем остальным. 429 - зависимость сама
        // просит отступить, это отказ.
        var he *HTTPError
        if errors.As(err, &he) && he.Code < 500 && he.Code != 429 {
            return true
        }
        return false
    },

    OnStateChange: func(name string, from, to gobreaker.State) {
        log.Warn("circuit breaker state changed",
            "name", name, "from", from.String(), "to", to.String())
        breakerState.WithLabelValues(name).Set(float64(to))
    },
})

func chargeWithBreaker(ctx context.Context, req Request) (*Receipt, error) {
    r, err := billingCB.Execute(func() (*Receipt, error) {
        return billing.Charge(ctx, req)
    })
    if errors.Is(err, gobreaker.ErrOpenState) ||
        errors.Is(err, gobreaker.ErrTooManyRequests) {
        // Брейкер отказал мгновенно - самое время для fallback,
        // а не для ретрая: ретрай получит ровно тот же отказ.
        return nil, ErrBillingUnavailable
    }
    return r, err
}

Минимальная своя реализация — чтобы понимать, что внутри

type State int

const (
    Closed State = iota
    Open
    HalfOpen
)

var (
    ErrOpen      = errors.New("circuit breaker is open")
    ErrTooManyProbes = errors.New("circuit breaker: probe limit reached")
)

type Breaker struct {
    mu        sync.Mutex
    state     State
    fails     int
    successes int
    openedAt  time.Time
    probes    int           // пробных сейчас в полёте

    threshold int           // отказов подряд до открытия
    cooldown  time.Duration // сколько держать Open
    maxProbes int           // сколько пробных пускать в HalfOpen
    needSucc  int           // успехов подряд для закрытия
}

// allow решает, пускать ли вызов, и переводит состояние по времени.
func (b *Breaker) allow() error {
    b.mu.Lock()
    defer b.mu.Unlock()

    switch b.state {
    case Closed:
        return nil

    case Open:
        if time.Since(b.openedAt) < b.cooldown {
            return ErrOpen
        }
        // Переход ленивый: его делает первый запрос после cooldown.
        b.state, b.probes, b.successes = HalfOpen, 0, 0
        fallthrough

    case HalfOpen:
        if b.probes >= b.maxProbes {
            return ErrTooManyProbes      // пробный трафик ограничен
        }
        b.probes++
        return nil
    }
    return nil
}

func (b *Breaker) report(err error, success bool) {
    b.mu.Lock()
    defer b.mu.Unlock()

    switch b.state {
    case Closed:
        if success {
            b.fails = 0
            return
        }
        b.fails++
        if b.fails >= b.threshold {
            b.state, b.openedAt = Open, time.Now()
        }

    case HalfOpen:
        b.probes--
        if !success {
            // Один упавший пробный возвращает нас в Open.
            b.state, b.openedAt, b.successes = Open, time.Now(), 0
            return
        }
        b.successes++
        if b.successes >= b.needSucc {
            b.state, b.fails, b.successes = Closed, 0, 0
        }
    }
}

func (b *Breaker) Do(ctx context.Context, fn func(context.Context) error) error {
    if err := b.allow(); err != nil {
        return err
    }
    err := fn(ctx)
    // context.Canceled - уход клиента, а не отказ зависимости.
    b.report(err, err == nil || errors.Is(err, context.Canceled))
    return err
}

Таймауты и бюджет запроса

Правило без исключений: у каждого вызова, который уходит за пределы процесса, должен быть таймаут. Сеть, БД, кэш, файловая система на NFS, вызов внешнего API — всё. Страшно не то, что вызов «зависнет надолго», а то, что всё это время он держит ресурсы: горутину, соединение из пула, память запроса, слот в семафоре. При 1000 RPS хватит временной деградации зависимости, чтобы вызов без таймаута за считанные секунды исчерпал пул соединений. Дальше падает всё, включая то, что к этой зависимости отношения не имеет.

// Клиент: таймауты на каждой фазе, а не один общий.
tr := &http.Transport{
    DialContext: (&net.Dialer{
        Timeout:   2 * time.Second,     // установка TCP-соединения
        KeepAlive: 30 * time.Second,
    }).DialContext,
    TLSHandshakeTimeout:   2 * time.Second,
    ResponseHeaderTimeout: 3 * time.Second,   // ждём первый байт заголовков ответа
    ExpectContinueTimeout: 1 * time.Second,
    IdleConnTimeout:       90 * time.Second,
    MaxIdleConns:          100,
    MaxIdleConnsPerHost:   100,               // дефолт 2 - главное узкое место
    MaxConnsPerHost:       200,               // потолок параллелизма = грубый bulkhead
}
client := &http.Client{
    Transport: tr,
    Timeout:   5 * time.Second,   // весь цикл, включая чтение тела
}

// Сервер: без этих четырёх полей сервис уязвим к медленным клиентам.
srv := &http.Server{
    Addr:              ":8080",
    ReadHeaderTimeout: 5 * time.Second,    // защита от Slowloris
    ReadTimeout:       15 * time.Second,
    WriteTimeout:      20 * time.Second,
    IdleTimeout:       60 * time.Second,
    Handler:           http.TimeoutHandler(mux, 10*time.Second, `{"error":"timeout"}`),
}

// Слой берёт себе меньше, чем ему осталось, и оставляет резерв
// на обработку результата и запись ответа.
func childCtx(ctx context.Context, want, reserve time.Duration) (context.Context, context.CancelFunc) {
    dl, ok := ctx.Deadline()
    if !ok {
        return context.WithTimeout(ctx, want)      // бюджета сверху нет - берём свой
    }

    left := time.Until(dl) - reserve
    if left <= 0 {
        // Времени не осталось: идти в сеть бессмысленно, только зря
        // займём соединение у зависимости, которой и так тяжело.
        cancelled, cancel := context.WithDeadline(ctx, time.Now())
        return cancelled, cancel
    }
    if left < want {
        want = left
    }
    return context.WithTimeout(ctx, want)
}

// Использование: у платежа свой потолок 1800 мс, но если запросу
// осталось 600 - возьмём 600 минус резерв.
ctxPay, cancel := childCtx(ctx, 1800*time.Millisecond, 100*time.Millisecond)
defer cancel()
receipt, err := billing.Charge(ctxPay, req)

Graceful degradation и fallback

Деградация нужна, когда зависимость всё-таки недоступна, а ответить надо. Но допустима она только для некритичных зависимостей. Вместо рекомендаций разумно отдать топ популярного. С проверкой баланса перед списанием так нельзя: там корректен только отказ.

func (s *Service) Recommendations(ctx context.Context, userID int64) (Recs, bool) {
    // Некритичная зависимость - жёсткий короткий таймаут,
    // чтобы она не съедала бюджет основного ответа.
    ctx, cancel := childCtx(ctx, 150*time.Millisecond, 20*time.Millisecond)
    defer cancel()

    recs, err := s.mlCB.Do(ctx, func(ctx context.Context) (Recs, error) {
        return s.ml.Get(ctx, userID)
    })
    if err == nil {
        s.cache.Set(userID, recs, 10*time.Minute)
        return recs, false
    }

    // Каждая деградация обязана быть видна: без метрики сервис будет
    // месяцами отдавать дефолты, и никто об этом не узнает.
    degraded.WithLabelValues("recs", reasonOf(err)).Inc()
    s.log.WarnContext(ctx, "recommendations degraded", "err", err)

    if stale, ok := s.cache.GetStale(userID); ok {   // допускаем протухшее
        return stale, true
    }
    return s.topPopular(), true                       // последний рубеж
}

Fail-fast vs fault-tolerant

Fail-fast и fault-tolerance живут на разных уровнях системы и друг другу не противоречат. Внутри одной операции почти всегда правильнее fail-fast: не тянуть, а быстро освободить ресурсы. На уровне системы нужна fault-tolerance: отказ одного компонента не должен ронять целое. Вопрос закрывает одна формулировка: «fail-fast на уровне вызова, fault-tolerance на уровне архитектуры».

Отдельно стоит самому упомянуть bulkhead (те самые «переборки» из начала главы): каждой зависимости свой семафор, который ограничивает параллелизм, чтобы одна медленная не съела все горутины и все соединения. Он дешевле брейкера и срабатывает раньше него — в момент замедления, а не в момент отказа.

type Bulkhead struct{ sem chan struct{} }

var ErrOverloaded = errors.New("dependency at capacity")

func (b *Bulkhead) Do(ctx context.Context, fn func(context.Context) error) error {
    select {
    case b.sem <- struct{}{}:
        // Место есть - работаем.
    case <-ctx.Done():
        return ctx.Err()
    default:
        // Очередь не растим: копить горутины в ожидании слота -
        // это отложенный отказ вместо мгновенного. Лучше отказать сразу.
        return ErrOverloaded
    }
    defer func() { <-b.sem }()
    return fn(ctx)
}

Как всё это складывается в одну цепочку

По отдельности паттерны выглядят безобидно, а вместе легко вредят друг другу: ретрай внутри ретрая даёт умножение, брейкер снаружи ретрая не видит отдельных попыток, таймаут внутри backoff не срабатывает никогда. Рабочий порядок обёрток снаружи внутрь (retry снаружи брейкера — так же по умолчанию и в resilience4j):

// Читается снаружи внутрь: бюджет -> ретраи -> брейкер -> семафор -> таймаут попытки.
func (c *BillingClient) Charge(ctx context.Context, req Request) (*Receipt, error) {
    ctx, cancel := childCtx(ctx, 2*time.Second, 100*time.Millisecond)   // 1. бюджет
    defer cancel()

    var receipt *Receipt
    err := retry.Do(ctx, c.policy, billingClassifier, func(ctx context.Context) error {   // 2
        return c.breaker.Do(ctx, func(ctx context.Context) error {                        // 3
            return c.bulkhead.Do(ctx, func(ctx context.Context) error {                   // 4
                attemptCtx, cancel := context.WithTimeout(ctx, 600*time.Millisecond)      // 5
                defer cancel()

                r, err := c.raw.Charge(attemptCtx, req)   // req несёт Idempotency-Key
                receipt = r
                return err
            })
        })
    })
    return receipt, err
}

func billingClassifier(err error) (bool, time.Duration) {
    // Брейкер открыт - ретраить бессмысленно: получим тот же мгновенный отказ,
    // только сожжём попытки и время.
    if errors.Is(err, ErrOpen) || errors.Is(err, ErrOverloaded) {
        return false, 0
    }
    return HTTPClassifier(err)
}

// Классификатор - единственное место, где живёт знание «что ретраибельно».
// Разносить эти проверки по коду нельзя: они разъедутся в первый же месяц.
type Outcome int

const (
    Fatal      Outcome = iota // повтор бессмыслен
    Transient                 // запрос точно не выполнился - повтор безопасен всегда
    Ambiguous                 // исход неизвестен - повтор, только если операция идемпотентна
)

func classify(err error) Outcome {
    switch {
    case err == nil:
        return Fatal
    // Уход клиента и исчерпанный бюджет - это не сбой зависимости.
    case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded):
        return Fatal
    // Брейкер открыт: ретрай только сожжёт попытки.
    case errors.Is(err, ErrOpen), errors.Is(err, ErrOverloaded):
        return Fatal
    }

    // Не доехали до сервера - исход однозначный.
    var de *net.DNSError
    if errors.As(err, &de) || errors.Is(err, syscall.ECONNREFUSED) ||
        errors.Is(err, syscall.EHOSTUNREACH) {
        return Transient
    }

    var pg *pgconn.PgError
    if errors.As(err, &pg) {
        switch pg.Code {
        case "40001", "40P01":     // serialization_failure, deadlock_detected
            return Transient       // транзакция откатилась целиком
        case "23505":              // unique_violation - это уже дедупликация, а не сбой
            return Fatal
        }
        return Fatal
    }

    var he *HTTPError
    if errors.As(err, &he) {
        switch he.Code {
        case 408, 425, 429, 503:
            return Transient       // запрос не обработан — повтор безопасен
        case 500, 502, 504:
            return Ambiguous       // сервер мог успеть выполнить операцию
        }
        return Fatal               // 4xx - ошибка запроса, повтор не поможет
    }

    // Таймаут или обрыв на середине - самый опасный случай.
    var ne net.Error
    if errors.As(err, &ne) && ne.Timeout() {
        return Ambiguous
    }
    if errors.Is(err, syscall.ECONNRESET) || errors.Is(err, io.ErrUnexpectedEOF) {
        return Ambiguous
    }
    return Fatal                   // неизвестное по умолчанию не ретраим
}

// Решение зависит от пары «класс ошибки + свойство операции».
func shouldRetry(err error, idempotent bool) bool {
    switch classify(err) {
    case Transient:
        return true
    case Ambiguous:
        return idempotent
    default:
        return false
    }
}

package retry

import (
    "context"
    "errors"
    "math/rand/v2"   // Go 1.22+: глобальный генератор без блокировок и без ручного Seed
    "time"
)

type Policy struct {
    MaxAttempts    int           // всего попыток, включая первую
    Base           time.Duration // 100ms
    Cap            time.Duration // 5s - потолок одной паузы
    PerAttempt     time.Duration // таймаут одной попытки; 0 - без своего таймаута
    Budget         time.Duration // потолок на всю серию; 0 - ограничивает только ctx
}

// Классификатор отвечает сразу на два вопроса: повторять ли,
// и не назвал ли сервер паузу сам (Retry-After, gRPC RetryInfo).
type Classifier func(err error) (retry bool, after time.Duration)

func Do(ctx context.Context, p Policy, cls Classifier, op func(context.Context) error) error {
    if p.MaxAttempts <= 0 { p.MaxAttempts = 3 }
    if p.Base <= 0        { p.Base = 100 * time.Millisecond }
    if p.Cap <= 0         { p.Cap = 5 * time.Second }

    if p.Budget > 0 {
        var cancel context.CancelFunc
        ctx, cancel = context.WithTimeout(ctx, p.Budget)
        defer cancel()   // обязателен: иначе течёт таймер до конца родительского ctx
    }

    var last error
    for attempt := 0; attempt < p.MaxAttempts; attempt++ {
        // Не ходим в сеть с уже истёкшим дедлайном: соединение зависимости
        // дороже, чем наша попытка «а вдруг успеем».
        if err := ctx.Err(); err != nil {
            return errors.Join(last, err)
        }

        last = attemptOnce(ctx, p.PerAttempt, op)
        if last == nil {
            return nil
        }

        // Отмена родительского контекста - не транзиентная ошибка: клиент ушёл.
        // Проверяем до классификатора, иначе таймаут попытки спутаем с отменой запроса.
        if ctx.Err() != nil {
            return errors.Join(last, ctx.Err())
        }

        retry, after := cls(last)
        if !retry || attempt == p.MaxAttempts-1 {
            return last
        }

        delay := after                                   // сервер назвал паузу - уважаем
        if delay <= 0 {
            delay = fullJitter(p.Base, p.Cap, attempt)
        }
        if err := sleepCtx(ctx, delay); err != nil {
            return errors.Join(last, err)
        }
    }
    return last
}

// Своя граница времени на каждую попытку. Без неё одна зависшая
// попытка съедает весь бюджет, и ретраев фактически не происходит.
func attemptOnce(ctx context.Context, per time.Duration, op func(context.Context) error) error {
    if per <= 0 {
        return op(ctx)
    }
    actx, cancel := context.WithTimeout(ctx, per)
    defer cancel()
    return op(actx)
}

func sleepCtx(ctx context.Context, d time.Duration) error {
    // Спать дольше, чем осталось до дедлайна, незачем: лучше вернуть ошибку
    // сразу, чем разбудить таймер в уже мёртвый запрос.
    if dl, ok := ctx.Deadline(); ok && time.Until(dl) <= d {
        return context.DeadlineExceeded
    }
    t := time.NewTimer(d)
    defer t.Stop()          // до Go 1.23 неостановленный таймер живёт до срабатывания
    select {
    case <-ctx.Done():
        return ctx.Err()
    case <-t.C:
        return nil
    }
}

func fullJitter(base, capD time.Duration, attempt int) time.Duration {
    backoff := base << attempt                  // base * 2^attempt
    if backoff > capD || backoff <= 0 {         // <=0 - защита от переполнения int64
        backoff = capD
    }
    return time.Duration(rand.Int64N(int64(backoff)) + 1)
}

policy := retry.Policy{
    MaxAttempts: 4,
    Base:        50 * time.Millisecond,
    Cap:         1 * time.Second,
    PerAttempt:  400 * time.Millisecond,   // одна попытка
    Budget:      2 * time.Second,          // вся серия
}

var receipt *Receipt
err := retry.Do(ctx, policy, HTTPClassifier, func(ctx context.Context) error {
    req = req.WithIdempotencyKey(key)      // ключ один на всю серию, а не на попытку
    r, err := client.Charge(ctx, req)
    receipt = r
    return err
})

// Ядро автомата - вход и отчёт. Полная реализация со счётчиками
// разбиралась выше; здесь важна логика переходов.
func (b *Breaker) allow() error {
    b.mu.Lock()
    defer b.mu.Unlock()

    switch b.state {
    case Closed:
        return nil
    case Open:
        if time.Since(b.openedAt) < b.cooldown {
            return ErrOpen                       // отказ за наносекунды, в сеть не идём
        }
        b.state, b.probes, b.successes = HalfOpen, 0, 0
        fallthrough
    case HalfOpen:
        if b.probes >= b.maxProbes {             // пробных - единицы, не весь трафик
            return ErrTooManyProbes
        }
        b.probes++
        return nil
    }
    return nil
}

// Обёртка вызова. Тонкое место - что считать отказом.
func (b *Breaker) Do(ctx context.Context, fn func(context.Context) error) error {
    if err := b.allow(); err != nil {
        return err                               // fallback решает вызывающий
    }
    err := fn(ctx)
    b.report(err, isSuccess(err))
    return err
}

func isSuccess(err error) bool {
    if err == nil {
        return true
    }
    // Уход клиента - не вина зависимости, иначе массовая отмена запросов
    // сама откроет брейкер.
    if errors.Is(err, context.Canceled) {
        return true
    }
    // 4xx - ошибка запроса, а не сбой зависимости.
    var he *HTTPError
    if errors.As(err, &he) && he.Code < 500 && he.Code != 429 {
        return true
    }
    return false
}

// В Go бюджет уже встроен в context: WithTimeout не добавляет времени,
// если дедлайн родителя ближе - побеждает родитель. Глубокий вызов
// физически не может пережить запрос.
func childCtx(ctx context.Context, want, reserve time.Duration) (context.Context, context.CancelFunc) {
    dl, ok := ctx.Deadline()
    if !ok {
        return context.WithTimeout(ctx, want)     // бюджета сверху нет - берём свой
    }
    left := time.Until(dl) - reserve
    if left <= 0 {
        // Времени не осталось: идти в сеть бессмысленно - только займём
        // соединение у зависимости, которой и так тяжело. Отказываем сразу.
        c, cancel := context.WithDeadline(ctx, time.Now())
        return c, cancel
    }
    if left < want {
        want = left
    }
    return context.WithTimeout(ctx, want)
}

// Пример арифметики: ingress даёт 3 с.
//   auth      200 мс
//   профиль   400 мс
//   платёж  3 попытки по 600 мс + backoff ~200 мс = 2000 мс
//   резерв    100 мс на сериализацию и запись ответа
//   итого    2700 мс < 3000 мс - влезает
func Handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()      // дедлайн сюда приносит http.TimeoutHandler или клиент

    aCtx, cancel := childCtx(ctx, 200*time.Millisecond, 0)
    defer cancel()
    user, err := auth.Verify(aCtx, r.Header.Get("Authorization"))
    if err != nil { writeErr(w, err); return }

    pCtx, cancel2 := childCtx(ctx, 2*time.Second, 100*time.Millisecond)
    defer cancel2()
    receipt, err := billing.Charge(pCtx, user.ID)   // внутри ретраи и брейкер
    if err != nil { writeErr(w, err); return }

    writeJSON(w, receipt)
}

// Второй результат говорит вызывающему, что ответ деградировал.
// Возвращать «как будто всё хорошо» - это тихая поломка.
func (s *Service) Recommendations(ctx context.Context, userID int64) (Recs, bool) {
    // У некритичной зависимости - свой короткий таймаут, чтобы она
    // не съедала бюджет основного ответа.
    ctx, cancel := childCtx(ctx, 150*time.Millisecond, 20*time.Millisecond)
    defer cancel()

    recs, err := s.mlCB.Do(ctx, func(ctx context.Context) (Recs, error) {
        return s.ml.Get(ctx, userID)
    })
    if err == nil {
        s.cache.Set(userID, recs, 10*time.Minute)
        return recs, false
    }

    // Каждая деградация обязана быть видна. Без метрики сервис будет
    // месяцами отдавать дефолты, и никто об этом не узнает.
    degraded.WithLabelValues("recs", reasonOf(err)).Inc()
    s.log.WarnContext(ctx, "recommendations degraded", "err", err, "user", userID)

    if stale, ok := s.cache.GetStale(userID); ok {   // допускаем просроченное
        return stale, true
    }
    return s.topPopular(), true                      // последний рубеж
}

// В HTTP-слое деградация становится видимой снаружи.
func (h *Handler) Feed(w http.ResponseWriter, r *http.Request) {
    recs, degraded := h.svc.Recommendations(r.Context(), userID(r))
    if degraded {
        w.Header().Set("X-Degraded", "recommendations")
        w.Header().Set("Cache-Control", "no-store")   // не кэшируем ухудшенный ответ
    }
    writeJSON(w, FeedResponse{Recs: recs, Partial: degraded})
}

func (s *Service) ProductPage(ctx context.Context, id int64) (Page, error) {
    var page Page
    g, gctx := errgroup.WithContext(ctx)

    // Критичный источник: его отказ - отказ всей ручки.
    g.Go(func() error {
        p, err := s.catalog.Get(gctx, id)
        page.Product = p
        return err                     // вернётся из g.Wait; блоки на ctx её не заметят
    })

    // Некритичные: ошибку не возвращаем в группу, иначе один упавший
    // блок отменит контекст и убьёт весь ответ.
    // Флаги деградации — у каждого свой: общий page.Partial из двух горутин —
    // это гонка.
    var recsDeg, reviewsDeg bool
    g.Go(func() error {
        recs, deg := s.Recommendations(ctx, id)   // именно ctx, не gctx
        page.Recs, recsDeg = recs, deg
        return nil
    })
    g.Go(func() error {
        rv, err := s.reviews.Top(ctx, id)
        if err != nil {
            degraded.WithLabelValues("reviews", reasonOf(err)).Inc()
            reviewsDeg = true
            return nil                 // блок отзывов просто не покажем
        }
        page.Reviews = rv
        return nil
    })

    if err := g.Wait(); err != nil {
        return Page{}, err             // упал критичный источник
    }
    page.Partial = recsDeg || reviewsDeg
    return page, nil
}

// Приёмный контроль: три быстрых проверки до любой полезной работы.
func (s *Server) admit(ctx context.Context) error {
    // 1. Клиент уже не ждёт - работать не для кого.
    if err := ctx.Err(); err != nil {
        return err
    }
    // 2. Бюджета не хватит даже на нормальный путь - лучше отказать сразу.
    if dl, ok := ctx.Deadline(); ok && time.Until(dl) < s.minWorkTime {
        sheddedTotal.WithLabelValues("no_budget").Inc()
        return ErrNoTimeBudget          // 503 + Retry-After
    }
    // 3. Перегрузка: очередь длиннее, чем мы разгребём за отведённое время.
    if s.inflight.Load() > s.maxInflight {
        sheddedTotal.WithLabelValues("overload").Inc()
        return ErrOverloaded            // 429 или 503
    }
    return nil
}

// Bulkhead: ограничить параллелизм на каждую зависимость отдельно,
// чтобы одна медленная не съела все горутины и соединения.
type Bulkhead struct{ sem chan struct{} }

func (b *Bulkhead) Do(ctx context.Context, fn func(context.Context) error) error {
    select {
    case b.sem <- struct{}{}:
    case <-ctx.Done():
        return ctx.Err()
    default:
        // Очередь не растим: ожидание слота - это отложенный отказ.
        return ErrOverloaded
    }
    defer func() { <-b.sem }()
    return fn(ctx)
}

-- Дедупликация вставки: повтор не создаёт вторую запись и не падает.
INSERT INTO payments (order_id, amount, status)
VALUES ($1, $2, 'pending')
ON CONFLICT (order_id) DO NOTHING
RETURNING id;
-- Пустой результат = запись уже была. Это не ошибка, а штатная ветка:
-- читаем существующую строку и возвращаем её как результат.

-- Inbox: факт обработки и бизнес-эффект фиксируются одной транзакцией.
BEGIN;
  INSERT INTO processed_messages (message_id) VALUES ($1);  -- PK, повтор упадёт 23505
  UPDATE accounts SET balance = balance - $2 WHERE id = $3;
COMMIT;
-- Если вторая команда упала - откатится и первая, сообщение приедет снова.
-- Если сообщение дубль - упадёт первая, транзакция откатится, эффекта нет.

// Обработчик с ключом идемпотентности. Порядок шагов важен:
// сначала атомарно занимаем ключ, только потом делаем работу.
func (s *Service) CreatePayment(ctx context.Context, key string, req Request) (Response, error) {
    if key == "" {
        return Response{}, ErrIdempotencyKeyRequired    // 400
    }
    hash := sha256.Sum256(req.Canonical())

    // 1. Гонку решает сама БД: выигрывает ровно один INSERT.
    claimed, err := s.repo.ClaimKey(ctx, key, "POST /payments", hash[:])
    if err != nil {
        return Response{}, err
    }
    if !claimed {
        rec, err := s.repo.LoadKey(ctx, key)
        if err != nil {
            return Response{}, err
        }
        // 2. Тот же ключ с другим телом - баг клиента, а не повтор.
        if !bytes.Equal(rec.RequestHash, hash[:]) {
            return Response{}, ErrIdempotencyKeyReuse   // 422
        }
        // 3. Первый запрос ещё в работе - параллельно не выполняем.
        if rec.State == StateInProgress {
            return Response{}, ErrInProgress            // 409 + Retry-After: 1
        }
        return rec.Response, nil                        // 4. Отдаём сохранённый ответ
    }

    resp, err := s.charge(ctx, req)
    if err != nil {
        // Деньги точно не списаны — отпускаем ключ, и повтор пройдёт заново:
        // иначе ключ навсегда залипнет в in_progress. Исход неизвестен
        // (таймаут после отправки) — не отпускаем: повтор может списать
        // второй раз, такой ключ ждёт сверки с платёжкой.
        if !errors.Is(err, ErrOutcomeUnknown) {
            _ = s.repo.ReleaseKey(ctx, key)
        }
        return Response{}, err
    }

    // 5. Сохраняем ответ под ключом: повтор получит его, а не второе списание.
    if err := s.repo.CompleteKey(ctx, key, resp); err != nil {
        return Response{}, err
    }
    return resp, nil
}