Разработка REST-серверов на Go. Часть 5: Middleware

Это — пятый материал из серии статей, посвящённой разработке REST-серверов на Go. Здесь мы поговорим о middleware. У меня есть материал, посвящённый жизненному циклу HTTP-запросов в серверах, написанных на Go. Для того чтобы разобраться в том, о чём пойдёт речь ниже, вам нужно ориентироваться в этой теме.

Предыдущие части:

Разработка REST-серверов на Go. Часть 1: стандартная библиотека
Разработка REST-серверов на Go. Часть 2: применение маршрутизатора gorilla/mux
Разработка REST-серверов на Go. Часть 3: использование веб-фреймворка Gin
Разработка REST-серверов на Go. Часть 4: применение OpenAPI и Swagger
Вы тут — Разработка REST-серверов на Go. Часть 5: Middleware
Разработка REST-серверов на Go. Часть 6: аутентификация

Middleware, созданное с использованием стандартных средств

Пришло время снова переработать наш сервер, являющийся частью системы управления задачами. Следующий пример основан на базовой версии сервера, описанного в первой части этой серии материалов, при разработке которого используются лишь возможности стандартной библиотеки Go. Тут мы поговорим о том, как оснастить этот сервер middleware, и о том, какие у нас имеются варианты интеграции этого ПО с существующим кодом. Полный код сервера, который мы будем сейчас обсуждать, можно найти здесь.

В исходном варианте сервера в начале каждого обработчика присутствует вызов log.Printf, предназначенный для логирования обрабатываемого запроса. Это — одна из задач, которую можно решить средствами middleware, и при этом обойтись меньшими объёмами повторяющегося кода. Вот простой пример кода такого ПО, решающего задачу логирования:

func Logging(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
    start := time.Now()
    next.ServeHTTP(w, req)
    log.Printf("%s %s %s", req.Method, req.RequestURI, time.Since(start))
  })
}

Этот код, в дополнение к логированию метода и URI запроса, подсчитывает и логирует время, необходимое обработчику на решение его задачи.

Для того чтобы подключить это ПО к нашим обработчикам, приведём код main к следующему виду:

func main() {
  mux := http.NewServeMux()
  server := NewTaskServer()
  mux.HandleFunc("/task/", server.taskHandler)
  mux.HandleFunc("/tag/", server.tagHandler)
  mux.HandleFunc("/due/", server.dueHandler)

  handler := middleware.Logging(mux)

  log.Fatal(http.ListenAndServe("localhost:"+os.Getenv("SERVERPORT"), handler))
}

В данном случае middleware устанавливается на глобальном уровне, воздействуя на все обработчики. Но такое ПО можно устанавливать и для каждого конкретного маршрута. Например, если надо, чтобы логирование выполнялось бы только для server.tagHandler — мы можем поступить так:

func main() {
  mux := http.NewServeMux()
  server := NewTaskServer()
  mux.HandleFunc("/task/", server.taskHandler)
  mux.Handle("/tag/", middleware.Logging(http.HandlerFunc(server.tagHandler)))
  mux.HandleFunc("/due/", server.dueHandler)

  log.Fatal(http.ListenAndServe("localhost:"+os.Getenv("SERVERPORT"), mux))
}

Обратите внимание на то, что нам необходимо в этом случае вызывать mux.Handle, а не mux.HandleFunc. Дело в том, что наш код промежуточного уровня возвращает http.Handler, а не http.HandlerFunc. По похожей (но, в сущности, по обратной) причине мы, передавая обработчик middleware, должны подготовить его к использованию с помощью http.HandlerFunc.

Ещё два вышеописанных подхода можно использовать совместно. А именно, одно middleware может использоваться для отдельных маршрутов, а другое может применяться на глобальном уровне. Обратите внимание на то, что в двух предыдущих примерах последовательность вызова mux и кода промежуточного уровня различается. Можете сами обнаружить это различие?

В первом примере последовательность выполнения кода выглядит так:

request --> [Logging] --> [Mux] --> [Handler]

Во втором примере, для /tag/, порядок выполнения кода выглядит так:

request --> [Mux] --> [Logging] --> [tagHandler]

В целом — рекомендуется быть в курсе того, в каком порядке выполняется код middleware. В данном случае последовательность вызова mux и кода промежуточного уровня особой роли не играет, но в некоторых случаях это может быть не так.

Добавление в проект дополнительного middleware

Давайте оснастим сервер дополнительным middleware. В моём материале про жизненный цикл HTTP-запросов в Go-серверах я рассказывал о том, как обрабатывать ошибки времени выполнения категории panic. Если в обработчике возникает такая ошибка — при её обработке выполняется закрытие соединения с клиентом и логируется сообщение об ошибке. Если хочется сделать что-то другое — нужно написать собственный код middleware. Попробуем это сделать:

func PanicRecovery(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
    defer func() {
      if err := recover(); err != nil {
        http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
        log.Println(string(debug.Stack()))
      }
    }()
    next.ServeHTTP(w, req)
  })
}

В этом коде применяется оператор defer, с помощью которого к обработчику прикрепляется отложенная функция. Она выполняет обработку ошибки, отправляет клиенту HTTP-ответ с кодом 500 (Internal Server Error) и логирует результаты трассировки стека.

Вот как мы можем воспользоваться этим кодом в main:

func main() {
  mux := http.NewServeMux()
  server := NewTaskServer()
  mux.HandleFunc("/task/", server.taskHandler)
  mux.HandleFunc("/tag/", server.tagHandler)
  mux.HandleFunc("/due/", server.dueHandler)

  handler := middleware.Logging(mux)
  handler = middleware.PanicRecovery(handler)

  log.Fatal(http.ListenAndServe("localhost:"+os.Getenv("SERVERPORT"), handler))
}

Теперь порядок выполнения кода middleware выглядит так:

request --> [Panic Recovery] --> [Logging] --> [Mux] --> [tagHandler]

Тут, как и ранее, можно по-разному сочетать и комбинировать код. Например, можно сделать так, чтобы код PanicRecovery использовался бы лишь для некоторых маршрутов, а Logging — для всех.

Создание цепочек middleware

Только что было показано то, что, добавляя в сервер новое middleware, мы должны знать о том, в каком порядке вызываются соответствующие фрагменты кода. Это справедливо и для глобального ПО, и для того, которое применяется при обработке отдельных маршрутов. В результате неудивительно то, что существуют программные пакеты, ориентированные на построение «цепочек» из middleware, дающие больше удобств, чем у нас есть при вышеописанном стиле работы. Подобные пакеты, кроме того, обычно позволяют организовать многократное использование цепочек middleware в разных маршрутах. Примером такого пакета является alice.

Я, как это обычно бывает при разговорах о зависимостях, хочу напомнить о том, что к зависимостям стоит относиться очень осторожно. Не надо перегружать ими проект. Особенно — если они дают лишь незначительную выгоду. Пожалуй, без особых раздумий добавлять в проект новые зависимости может лишь тот, кто очень спешит, или тот, кто не особенно заботится о читабельности и поддерживаемости кода в долгосрочной перспективе. Если, например, оказывается, что использование для работы с middleware чего-то вроде alice выглядит для кого-то как нечто гораздо более адекватное, чем применение стандартных механизмов, он вполне может добавить в проект подобный пакет. В противном случае лучше начать с написания собственного кода (как в нашем примере), а потом, если возникнет такая необходимость, подумать о переходе на что-то другое.

В любом случае — если вы используете пакет для организации маршрутизации, вроде gorilla/mux, или полномасштабный фреймворк вроде Gin, это значит, что в вашем распоряжении уже есть стандартные средства этих инструментов, ориентированные на работу с middleware.

middleware и gorilla/mux

При использовании пакета для организации маршрутизации gorilla/mux в нашем распоряжении оказываются и некоторые вспомогательные инструменты для работы с middleware. Тип mux.Router имеет метод Use(...), использование которого облегчает настройку цепочек глобального middleware. Более того, пакет gorilla/handlers включает в себя кое-какое готовое к использованию middleware. При этом самописное ПО, вроде того, которым мы уже пользовались, тоже легко применять с gorilla/mux. Это так благодаря тому, что для обработчиков используются стандартные интерфейсы net/http. А если говорить о gorilla/handlers, то можно отметить, что там имеются, кроме прочих, аналоги наших разработок, направленных на логирование и на обработку ошибок panic.

Вот — пример кода (полный код сервера можно найти здесь):

func main() {
  router := mux.NewRouter()
  router.StrictSlash(true)
  server := NewTaskServer()

  router.HandleFunc("/task/", server.createTaskHandler).Methods("POST")
  router.HandleFunc("/task/", server.getAllTasksHandler).Methods("GET")
  router.HandleFunc("/task/", server.deleteAllTasksHandler).Methods("DELETE")
  router.HandleFunc("/task/{id:[0-9]+}/", server.getTaskHandler).Methods("GET")
  router.HandleFunc("/task/{id:[0-9]+}/", server.deleteTaskHandler).Methods("DELETE")
  router.HandleFunc("/tag/{tag}/", server.tagHandler).Methods("GET")
  router.HandleFunc("/due/{year:[0-9]+}/{month:[0-9]+}/{day:[0-9]+}/", server.dueHandler).Methods("GET")

  // Настройка middleware для логирования и обработки ошибок panic.
  router.Use(func(h http.Handler) http.Handler {
    return handlers.LoggingHandler(os.Stdout, h)
  })
  router.Use(handlers.RecoveryHandler(handlers.PrintRecoveryStack(true)))

  log.Fatal(http.ListenAndServe("localhost:"+os.Getenv("SERVERPORT"), router))
}

Функция main нового варианта сервера очень похожа на такую же функцию его исходного варианта, написанного во второй части этой серии материалов с использованием gorilla/mux. Но теперь там, где мы настраиваем middleware, добавлены два вызова router.Use. Я использовал тут два отдельных вызова Use для того чтобы сделать код понятнее. На самом деле, Use принимает произвольное количество обработчиков, вызовы которых нужно объединить в цепочку.

Middleware для обработки ошибок panic очень просто пользоваться. Тут продемонстрирован интересный подход к настройке такого ПО с использованием функциональных опций. В данном случае мы настраиваем логирование результатов трассировки стека при обработке ошибки panic (по умолчанию используется значение false).

API middleware handlers.LoggingHandler устроен немного необычно. Нам нужна маленькая функция-адаптер для использования его в router.Use. Мне не вполне ясна причина, по которой этот API устроен именно так. Полагаю, что, возможно, передачу io.writer можно организовать с применением функциональной опции — примерно так же, как это сделано в RecoveryHandler.

В этом примере показана настройка глобального middleware (затрагивающего весь маршрутизатор). А как, пользуясь gorilla/mux, настраивать такое ПО для отдельных маршрутов?

Один из способов похож на то, чем мы занимались, пользуясь возможностями стандартной библиотеки в предыдущем примере. Альтернативой ему является применение субмаршрутизаторов gorilla/mux с Use. Второй подход показался мне неоправданно сложным для тех случаев, когда нужно лишь добавить какое-то middleware к одному пути. Но если система маршрутизации уже представлена несколькими субмаршрутизаторами — эта задача решается очень просто.

Middleware и Gin

А теперь давайте переработаем сервер из третьей части этой серии материалов, основанный на Gin. В том материале было сказано, что при создании нового экземпляра Gin с использованием gin.Default() регистрируется и кое-какое middleware. В частности — это ПО для логирования и для обработки ошибок panic.

Того же эффекта можно достичь, меньше полагаясь на стандартные механизмы, создав экземпляр маршрутизатора через gin.New (при таком подходе middleware автоматически не подключается) и затем самостоятельно подключив то, что нам нужно:

func main() {
  // Ручная настройка middleware для логирования и обработки ошибок panic.
  router := gin.New()
  router.Use(gin.Logger())
  router.Use(gin.Recovery())

  server := NewTaskServer()

  router.POST("/task/", server.createTaskHandler)
  router.GET("/task/", server.getAllTasksHandler)
  router.DELETE("/task/", server.deleteAllTasksHandler)
  router.GET("/task/:id", server.getTaskHandler)
  router.DELETE("/task/:id", server.deleteTaskHandler)
  router.GET("/tag/:tag", server.tagHandler)
  router.GET("/due/:year/:month/:day", server.dueHandler)

  router.Run("localhost:" + os.Getenv("SERVERPORT"))
}

Метод Gin Use позволяет прикрепить к маршрутизатору цепочку middleware. Настройка такого ПО для отдельных маршрутов в Gin никаких сложностей не вызывает и производится с использованием групп маршрутизации. Для каждой группы можно зарегистрировать собственное ПО. Так же, как и в случае с обработчиками Gin, middleware Gin не использует стандартную сигнатуру для такого ПО. Тут используется тип, объявленный в пакете gin следующим образом:

type HandlerFunc func(*Context)

Поэтому для использования в Gin middleware со стандартной сигнатурой понадобится адаптер.

Если вы пользуетесь Gin — знайте, что в репозиториях gin-contrib представлена обширная коллекция модулей middleware, которые вы можете применить в своих проектах.

Другие варианты использования middleware

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

В реальности middleware применяется в следующих сферах: стандартизированная проверка запросов, CORS, организация логирования данных, сжатие данных, работа с сессиями, отслеживание запросов, кеширование, шифрование, аутентификация. Об аутентификации, кстати, мы поговорим в одном из следующих материалов.

Итоги

В этом материале мы подробно рассмотрели паттерн «middleware», обращая особое внимание на интеграцию такого ПО в код REST-сервера с использованием разных подходов. А именно — мы работали с таким ПО, применяя лишь средства стандартной библиотеки Go, пользовались маршрутизатором gorilla/mux и полномасштабным фреймворком Gin. Надеюсь, что вы, прочитав этот материал, разобрались с тем, как работает middleware, и с тем, как пользоваться им в собственных проектах.

В заключение этого материала хочу вас кое о чём предупредить: middleware — это не универсальный инструмент, идеально подходящий для решения всех задач. Им, как и любым другим инструментом, не стоит злоупотреблять. Использование такого ПО усложняет процесс прохождения запросов по внутренним каналам серверов, ухудшает читабельность кода и делает более сложной его отладку. Я очень порекомендовал бы описывать весь код в одном месте и избегать конструкций, где такое ПО встраивается в код обработки маршрутов динамически, условно, или внутри другого такого ПО. Если вы так и поступите, то, через некоторое время занимаясь отладкой собственного кода, будете очень себе благодарны.

Все переводы этой серии:

Разработка REST-серверов на Go. Часть 1: стандартная библиотека
Разработка REST-серверов на Go. Часть 2: применение маршрутизатора gorilla/mux
Разработка REST-серверов на Go. Часть 3: использование веб-фреймворка Gin
Разработка REST-серверов на Go. Часть 4: применение OpenAPI и Swagger
Вы тут — Разработка REST-серверов на Go. Часть 5: Middleware
Разработка REST-серверов на Go. Часть 6: аутентификация

Какой подход к работе с middleware вы используете в своих Go-серверах?