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

Разберём, как добавить контекст к ошибке, не теряя возможность распознать её тип или категорию.

Ошибка внутри ошибки: обёртка, цепочка, sentinel

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

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

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

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

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 у самой ошибки и ветвление на Unwrap() []error. Как Is ходит по цепочке, спрашивают почти всегда, а про эти две точки почти всегда забывают.

// 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" { ... }

Что стоит запомнить

• %w сохраняет причину в error chain.
• errors.Is проверяет категорию, errors.As извлекает типизированную ошибку.
• Публичная цепочка ошибок задаёт контракт библиотеки.

Частые ошибки

• Не сравнивай текст Error().
• %v не поддерживает errors.Is/As.

dir, err := os.MkdirTemp("", "errors-")
if err != nil { panic(err) }
defer os.RemoveAll(dir)
_, err = os.Open(filepath.Join(dir, "missing"))
err = fmt.Errorf("read config: %w", err)
fmt.Println(errors.Is(err, fs.ErrNotExist))

func load() error {
  if err := read(); err != nil { return fmt.Errorf("read config: %v", err) }
  return nil
}