Функция errors.Is

Функция errors.Is проверяет, содержится ли в цепочке ошибок (возвращаемой с помощью обертывания) заданная целевая ошибка. Она возвращает true, если ошибка или какая-либо из обернутых в ней ошибок равна целевой, и false в противном случае. Первым параметром функция принимает исходную ошибку (обычно это результат выполнения функции), вторым - целевую ошибку для сравнения.

Синтаксис

errors.Is(err, target)

Пример

Давайте создадим простую ошибку и проверим, соответствует ли она самой себе с помощью функции errors.Is:

package main

import (
	"errors"
	"fmt"
)

func main() {
	err := errors.New("error occurred")
	target := errors.New("error occurred")

	res := errors.Is(err, target)
	fmt.Println(res)
}

Результат выполнения кода:

false

Несмотря на одинаковый текст ошибок, они являются разными экземплярами, поэтому функция возвращает false.

Пример

Правильный способ использования errors.Is - это сравнение с заранее объявленной переменной (sentinel error):

package main

import (
	"errors"
	"fmt"
)

var ErrNotFound = errors.New("not found")

func main() {
	err := ErrNotFound

	res := errors.Is(err, ErrNotFound)
	fmt.Println(res)
}

Результат выполнения кода:

true

Пример

Рассмотрим работу errors.Is с обернутой ошибкой. Функция будет проходить по цепочке и проверять каждую ошибку на соответствие целевой:

package main

import (
	"errors"
	"fmt"
)

var ErrPermission = errors.New("permission denied")

func main() {
	err := fmt.Errorf("operation failed: %w", ErrPermission)

	res := errors.Is(err, ErrPermission)
	fmt.Println(res)
}

Результат выполнения кода:

true

Функция распаковывает обертку и находит целевую ошибку ErrPermission, поэтому возвращается true.

Пример

Если целевая ошибка не содержится в цепочке, функция возвращает false:

package main

import (
	"errors"
	"fmt"
)

var ErrNotFound = errors.New("not found")
var ErrTimeout = errors.New("timeout")

func main() {
	err := fmt.Errorf("connection: %w", ErrTimeout)

	res := errors.Is(err, ErrNotFound)
	fmt.Println(res)
}

Результат выполнения кода:

false

Смотрите также

функцию errors.As,
которая проверяет, соответствует ли ошибка типу
функцию errors.Unwrap,
которая возвращает следующую ошибку в цепочке
функцию errors.New,
которая создает новую ошибку с текстом
функцию fmt.Errorf,
которая форматирует ошибку и может обернуть другую ошибку