Бережная обработка ошибок в микросервисах

package mysql
import "github.com/pkg/errors" func (r *repository) FindOne(...)
}

Это легко сделать, если следовать правилам: Мы рекомендуем каждую ошибку оборачивать только один раз.

• любые внешние ошибки оборачиваются один раз в одном из инфраструктурных пакетов
• любые ошибки, порождаемые правилами бизнес-логики, дополняются stacktrace в момент создания

Первопричина ошибки

Пример, к котором мы извлекаем первопричину и прямо сравниваем её с sentinel error:

func (s *service) SaveCake(...) error { state, err := s.repo.FindOne(...) if errors.Cause(err) == ErrNoCake { err = nil // No cake is OK, create a new one // ... } else if err != nil { // ... }
}

Обработка ошибок в defer

В этом случае вас наверняка бесит, когда linter просит проверять ошибки методах . Возможно, вы используете linter, который заставляет вас маниакально проверять все ошибки. Вы когда нибудь пробовали корректно обработать ошибку в defer, особенно если до этого была ещё одна ошибка? Close() и других методах, которые вы вызываете только в defer. А мы — пробовали и спешим поделиться рецептом.

Согласно правилу зависимостей, уровни app и domain не должны прямо или косвенно зависеть от infrastructure и технологии SQL. Представим, что у нас вся работа с БД происходит строго через транзакции. Это означает, что на уровнях app и domain нет слова "транзакция".

В нашей реализации сервис в пакете app получает фабрику по интерфейсу UnitOfWorkFactory, и при выполнении каждой операции создаёт объект UnitOfWork, скрывающий за собой транзакцию. Самое простое решение — заменить слово "транзакция" на что-то абстрактное; так рождается паттерн Unit of Work. Объект UnitOfWork позволяет получить Repository.

Подробнее про UnitOfWork

Чтоб лучше понять использование Unit of Work, взгляните на диаграмму:

• Repository представляет абстрактную персистентную коллекцию объектов (например, аггрегатов уровня domain) опрелённого типа
• UnitOfWork скрывает за собой транзакцию и создаёт объекты Repository
• UnitOfWorkFactory просто позволяет сервису создавать новые транзакции, ничего не зная о транзакциях

Вам решать; мы считаем, что сохранение независимости бизнес-логики важнее, чем экономия на создании транзакции. Не является ли чрезмерным создание транзакции на каждую операцию, даже изначально атомарную?

Можно, но мы считаем, что это нарушит принцип Single Responsibility. Можно ли объединить UnitOfWork и Repository?

Так выглядт интерфейс:

type UnitOfWork interface { Repository() Repository Complete(err *error)
}

Да, именно указатель, и именно in-out параметр — в любых других вариантах код на вызывающей стороне окажется гораздо более сложным. Интефейс UnitOfWork предоставляет метод Complete, принимающий один in-out параметр: указатель на интерфейс error.

Пример операции с unitOfWork:

Если вместо именованного возвращаемого значения err вы примените локальную переменную err, то использовать её в defer нельзя! Внимание: ошибка должна быть объявлена как named return value. go-critic#801 И ни один linter этого пока не обнаружит — см.

func (s *service) CookCake() (err error) { unitOfWork, err := s.unitOfWorkFactory.New() if err != nil { return err } defer unitOfWork.Complete(&err) repo := unitOfWork.Repository()
}
// ... выполняем операцию

Так реализуется завершение транзакции UnitOfWork:

func (u *unitOfWork) Complete(err *error) { if *err == nil { // Ошибки ранее не было - выполняем commit txErr := u.tx.Commit() *err = errors.Wrap(txErr, "cannot complete transaction") } else { // Ранее была ошибка - выполняем rollback txErr := return u.tx.Rollback() // При rollback могла произойти ошибка, выполняем слияние ошибок *err = mergeErrors(*err, errors.Wrap(txErr, "cannot rollback transaction")) }
}

При этом мы считаем, что обе ошибки случились при выполнении одной операции на разных этапах, и первая ошибка является более важной — поэтому, когда обе ошибки не nil, мы сохраняем первую, а от второй ошибки сохраняем только сообщение: Функция mergeErrors выполняет слияние двух ошибок, но без проблем обработает nil вместо одной или обоих ошибок.

package errors func mergeErrors(err error, nextErr error) error { if err == nil { err = nextErr } else if nextErr != nil { err = errors.Wrap(err, nextErr.Error()) } return err
}

Возможно, вам стоит добавить функцию mergeErrors в свою корпоративную библиотеку для языка Go

Подсистема логирования

Статья Чек-лист: что нужно было делать до того, как запускать микросервисы в prod советует:

• логи пишутся в stderr
• логи должны быть в JSON, по одному компактному JSON-объекту на строку
• должен быть стандартный набор полей:
  • timestamp — время события с миллисекундами, желательно в формате RFC 3339 (пример: "1985-04-12T23:20:50.52Z")
  • level — уровень важности, например, "info" или "error"
  • app_name — имя приложения
  • и другие поля

Мы предпочитаем к сообщениям об ошибке добавлять ещё два поля: "error" и "stacktrace".

Но мы не применяем библиотеку напрямую. Для языка Golang есть много качественных библиотек логирования, например, sirupsen/logrus, которую мы используем. В первую очередь, мы в своём пакете log сокращаем черезчур обширный интерфейс библиотеки до одного интерфейса Logger:

package log type Logger interface { WithField(string, interface{}) Logger WithFields(Fields) Logger Debug(...interface{}) Info(...interface{}) Error(error, ...interface{})
}

Интерфейс логгера лаконичен: Если программист хочет писать логи, он должен получать извне интерфейс Logger, причём делать это следует на уровне инфраструктуры, а не app или domain.

• он уменьшает количество уровей важности до debug, info и error, как советует статья Давайте поговорим о ведении логов
• он вводит особые правила для метода Error: метод всегда принимает объект ошибки

Такая строгость позволяет направить программистов в правильное русло: если кто-то хочет внести улучшение в саму систему ведения логов, он должен сделать это с учётом всей инфраструктуры их сбора и обработки, которая в микросервисе только начинается (а заканчивается обычно где-нибудь в Kibana и Zabbix).

Впрочем, в пакете log есть ещё один интерфейс, который позволяет прервать работу программы при фатальной ошибке и потому может использоваться только в пакете main:

package log type MainLogger interface { Logger FatalError(error, ...interface{})
}

Пакет jsonlog

Схематично выглядит так: Реализует интерфейс Logger наш пакет jsonlog, выполняющий настройку библиотеки logrus и абстрагирующий работу с ней.

Например, мы используем ELK (Elastic Search, Logstash, Kibana), и поэтому в пакете jsonlog мы:

• устанавливаем для logrus формат logrus.JSONFormatter
  • при этом задаём опцию FieldMap, с помощью которой превращаем поле "time" в "@timestamp", а поле "msg" — в "message"
• выбираем log level
• добавляем hook, извлекающий stacktrace из переданного в метод Error(error, ...interface{}) объекта ошибки

Микросервис инициализирует логгер в функции main:

func initLogger(config Config) (log.MainLogger, error) { logLevel, err := jsonlog.ParseLevel(config.LogLevel) if err != nil { return nil, errors.Wrap(err, "failed to parse log level") } return jsonlog.NewLogger(&jsonlog.Config{ Level: logLevel, AppName: "cookingservice" }), nil
}

Обработка ошибок и логирование с помощью Middleware

Но даже если вы используете HTTP API, общие принципы вам подойдут. Мы переходим на GRPC в своих микросервисах на Go.

Обрабатывать ошибки и вести логи удобно с помощью паттерна Middleware (Middleware — это название паттерна Decorator в мире Golang и Node.js):

Сколько их должно быть? Куда следует добавлять Middleware?

Есть разные варианты добавления Middleware, выбирать вам:

• Вы можете декорировать интерфейс app.Service, но мы не рекомендуем так делать, потому что данный интерфейс не получает информации транспортного уровня, такой как IP клиента
• С GRPC вы можете повесить один обработчик на все запросы (точнее, два — unary и steam), но тогда все методы API будут логироваться в одинаковом стиле с одинаковым набором полей
• С GRPC генератор кода создаёт для нас интерфейс сервера, в котором мы вызываем метод app.Service — именно этот интерфейс мы декорируем, потому что в нём есть информация уровня транспорта и возможность по-разному логировать разные методы API

Схематично выглядит так:

Можете скрестить всё в один. Вы можете создать разные Middleware для обработки ошибок (и panic) и для логирования. Мы рассмотрим пример, в котором всё скрещивается в один Middleware, который создаётся так:

func NewMiddleware(next api.BackendService, logger log.Logger) api.BackendService { server := &errorHandlingMiddleware{ next: next, logger: logger, } return server
}

Произвольный метод API в Middleware реализуется так:

func (m *errorHandlingMiddleware) ListCakes( ctx context.Context, req *api.ListCakesRequest) (*api.ListCakesResponse, error) { start := time.Now() res, err := m.next.ListCakes(ctx, req) m.logCall(start, err, "ListCakes", log.Fields{ "cookIDs": req.CookIDs, }) return res, translateError(err)
}

Здесь мы выполняем три задачи:

1. Вызываем метод ListCakes декорируемого объекта
2. Вызываем свой метод logCall, передавая в него всю важную информацию, в том числе индивидуально подобранный набор полей, попадающих в лог
3. В конце подменяем ошибку путём вызова translateError.

А запись лога выполняет метод logCall, который просто вызывает правильный метод интерейса Logger: Трансляцию ошибок обсудим позже.

func (m *errorHandlingMiddleware) logCall(start time.Time, err error, method string, fields log.Fields) { fields["duration"] = fmt.Sprintf("%v", time.Since(start)) fields["method"] = method logger := m.logger.WithFields(fields) if err != nil { logger.Error(err, "call failed") } else { logger.Info("call finished") }
}

Трансляция ошибок

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

В первом приближении трансляция ошибки выглядит так:

// !ПЛОХАЯ ВЕРСИЯ! - не обработает err типа status.Error
func translateError(err error) error { switch errors.Cause(err) { case app.ErrNoCake: err = status.Errorf(codes.NotFound, err.Error()) default: err = status.Errorf(codes.Internal, err.Error()) } return err
}

Смастерим улучшенную версию с помощью приведения к типу интерфейса (да здравствует утиная типизация!):

type statusError interface { GRPCStatus() *status.Status
} func isGrpcStatusError(er error) bool { _, ok := err.(statusError) return ok
} func translateError(err error) error { if isGrpcStatusError(err) { return err } switch errors.Cause(err) { case app.ErrNoCake: err = status.Errorf(codes.NotFound, err.Error()) default: err = status.Errorf(codes.Internal, err.Error()) } return err
}

Функция translateError создаётся индивидуально для каждого контекста (независимого модуля) в вашем микросервисе и транслирует ошибки бизнес-логики в ошибки транспортного уровня.

Подведём итоги

Следовать им или нет, решать вам. Мы предлагаем вам несколько правил обработки ошибок и работы с логами.

1. Следуйте принципам Clean Architecture, не позволяйте прямо или косвенно нарушать правило зависимостей. Бизнес-логика должна зависеть только от языка программирования, а не от внешних технологий.
2. Используйте пакет, предлагающий композицию ошибок и создание stacktrace. Например, "github.com/pkg/errors" или пакет xerrors, который скоро войдёт в стандартную библиотеку Go
3. Не используйте в микросервисе сторонние библиотеки логирования — создайте свою библиотеку с пакетами log и jsonlog, которая скроет детали реализации логирования
4. Используйте паттерн Middleware, чтобы обрабатывать ошибки и писать логи на транспортном направлении инфраструктурного уровня программы

Вы и сами с этим разберётесь, мы в вас верим . Здесь мы ничего не говорили о технологиях трассировки запросов (например, OpenTracing), мониторинга метрик (например, производительности запросов к БД) и других вещах, подобных логированию.