errorx

errorx

errorx — простой и удобный пакет для создания обёрток ошибок с читаемым префиксом и структурированными аргументами в стиле контекстного логирования.

Основная идея

Пакет предоставляет тип ErrorBuilder, который позволяет добавлять к ошибкам:

• Читаемый префикс (контекст или описание),
• Структурированные ключ-значение аргументы (context),
• Обёртывать исходные ошибки, сохраняя возможность использовать errors.Is, errors.As и errors.Unwrap.

Пример итогового сообщения об ошибке:

prefix: {key1=val1, key2=val2}: original error message

Установка

go get github.com/yourusername/errorx

Использование

import "github.com/yourusername/errorx"

func someFunc() error {
    err := doSomething()
    if err != nil {
        return errorx.NewBuilder("operation failed").
            WithArgs("userID", 42, "retry", true).
            Wrap(err)
    }
    return nil
}

API

Тип ErrorBuilder

Структура для построения обёрнутых ошибок с контекстом.

type ErrorBuilder struct {
    Prefix string  // Префикс ошибки — дополнительный контекст
    Args   []any   // Ключ-значение аргументы контекста: [key1, val1, key2, val2, ...]
}

Конструкторы

• NewBuilder(prefix string) ErrorBuilder

  Создаёт новый билдер с заданным префиксом.

Методы

• WithPrefix(prefix string) ErrorBuilder

  Добавляет или расширяет префикс ошибки. Возвращает новый билдера.

• WithArgs(args ...any) ErrorBuilder

  Добавляет ключ-значение аргументы к ошибке.
  Ключи преобразуются в строки через fmt.Sprintf("%v", key).
  Если для ключа отсутствует значение, используется строка "<missing>".

• Wrap(err error) error

  Оборачивает переданную ошибку, добавляя префикс и аргументы.
  Если err == nil, возвращает nil.

Пример

err := errors.New("file not found")

wrappedErr := errorx.NewBuilder("ReadFile").
    WithArgs("filename", "config.yaml", "attempt", 3).
    Wrap(err)

fmt.Println(wrappedErr.Error())
// Output:
// ReadFile: {filename=config.yaml, attempt=3}: file not found

Плюсы реализации

• Простота и удобство: быстро добавляет читаемый контекст к ошибке.
• Читаемый формат вывода с префиксом и структурированными аргументами.
• Безопасность: не паникует при неправильных аргументах, подставляет "".
• Совместимость с error интерфейсом Go: поддерживает errors.Is, errors.As, errors.Unwrap.
• Минимальные зависимости: вся логика реализована внутри пакета.

Минусы и ограничения

• Отсутствие типобезопасности аргументов — программно получить ключи/значения нельзя без парсинга строки.
• Методы используют value semantics, что может быть неочевидно и привести к ошибкам.
• Формат вывода предназначен только для человекочитаемого логирования, не интегрируется с системами структурированного логирования.
• Нет поддержки вложенных или многослойных метаданных ошибок.

Когда использовать

• Для улучшения читаемости ошибок с контекстом.
• В проектах без необходимости сложного структурированного логирования.
• Для небольших и средних проектов, где важна простота и совместимость со стандартной библиотекой.

Лицензия

MIT License — смотрите файл LICENSE для подробностей.