Приложение на Go шаг за шагом. Часть первая: скелет, НТТР-сервер и конфигурация

Современные курсы стараются максимально охватить спектр технологий, которые используют компании. Ориентироваться в этом океане модных фич всё труднее, особенно это касается новичков, которые только начали знакомство с программированием. В итоге может случиться так, что выпускник курса вроде бы всё знает, а применять не может. 

Привет! Я Владислав Попов, автор курса «Go-разработчик с нуля» в Яндекс Практикуме. В серии статей я хочу помочь начинающим разработчикам упорядочить знания и написать приложение на Go с нуля: мы вместе пройдём каждый шаг и создадим API для получения информации о книгах и управления ими. 

---

Серия статей ни в коем случае не претендует на звание универсального руководства по созданию сервисов. Тем не менее я надеюсь, она поможет собрать весь (или почти весь) пазл из полученных знаний.

Предполагается, что вы знакомы с языком программирования Go и он у вас установлен. Также вам потребуются: VS Code с установленным плагином Go, инструмент для работы с HTTP-запросами и ответами в терминале curl, система контроля версий Git и веб-браузер.

Настройка проекта и основная структура папок

Начнём с создания директории проекта. Назовем её itbookworm. Я создам директорию проекта в $HOME/go/src/github.com/lekan-pvp/itbookworm, но вы можете сделать это там, где вам нравится:

$ mkdir -p $HOME/go/src/github.com/lekan-pvp/itbookworm

Перейдём в каталог проекта и создадим модуль с помощью go mod init:

$ cd $HOME/go/src/github.com/lekan-pvp/itbookworm $ go mod init github.com/lekan-pvp/itbookworm go: creating new go.mod: module github.com/lekan-pvp/itbookworm

В итоге мы видим, что был создан файл go.mod со следующим содержимым (название модуля и версия Go могут отличаться):

module github.com/lekan-pvp/itbookworm  go 1.23.2

Итак, каталог проекта и файл go.mod созданы. Продолжим создавать структуру проекта, запуская следующие команды:

$ mkdir -p bin cmd/api internal migrations remote $ touch Makefile $ touch cmd/api/main.go

На данный момент структура проекта выглядит так:

. |---bin |---cmd |   +---api |       +---main.go |---internal |---migrations |---remote |---go.mod |---Makefile

Разберёмся, что будет содержать каждый каталог:

• bin — скомпилированные двоичные файлы, готовые к развёртыванию на рабочем сервере;

• cmd/api —  основная функция приложения;

• internal — различные вспомогательные пакеты;

• migrations — файлы миграции для базы данных;

• remote — файлы конфигурации и сценарии настроек для производственного сервера;

• go.mod — информация о зависимостях проекта, версиях и путях к модулям;

• Makefile — инструкции по автоматизации частых административных задач — проверка кода, создание двоичных файлов и выполнения миграций.

Прежде чем продолжить, проверим, что все наши настройки корректны. Откроем cmd/api/main.go и добавим код:

// cmd/api/main.go  package main  import "fmt"  func main() {    fmt.Println("hello world!") } 

Сохраним файл и запустим его:

$ go run ./cmd/api hello world!

Простой HTTP-сервер

Теперь, когда структура проекта готова, сосредоточимся на создании и запуске HTTP-сервера. Сначала будет только один эндпоинт /v1/healthcheck, который будет возвращать основную информацию об API: текущую версию и производственную среду (разработка, этап, производство; development, stage, production).

Снова откроем cmd/api/main.go в редакторе и заменим приложение hello world следующим кодом:

// cmd/api/main.go  package main  import (    "flag"    "fmt"    "log"    "net/http"    "os"    "time" )  // Объявим строковую константу, которая содержит номер версии приложения. // Позже мы будем генерировать версию автоматически во время сборки, а пока // просто сохраним жёстко заданную глобальную константу. const version = "1.0.0"  // Определим структуру конфигурации, которая будет содержать все параметры // конфигурации для нашего приложения. На данный момент параметрами будут порт, // который должен прослушивать сервер, и название производственной среды (разработка, производство и т.д.). Эти параметры будут считываться из флагов командной строки. type config struct {    port int    env  string }  // Определим структуру приложения, которая будет содержать зависимости для // обработчиков HTTP, вспомогательных функций и middleware. На данный момент // она содержит копию структуры конфигурации и логгер. По мере развития проекта // она будет включать в себя гораздо больше. type application struct {    config config    logger *log.Logger }  func main() {    // Объявляем экземпляр структуры config.    var cfg config     // Записываем значения флагов командной строки port и env в структуру    // конфигурации. По умолчанию мы используем номер порта 8000 и среду development.    flag.IntVar(&cfg.port, "port", 8000, "API server port")    flag.StringVar(&cfg.env, "env", "development", "Environment (development|staging|production)")    flag.Parse()     // Инициализируем новый логгер, который записывает сообщения в стандартный вывод    // с указанием текущей даты и времени.    logger := log.New(os.Stdout, "", log.Ldate|log.Ltime)     // Объявляем экземпляр структуры приложения, которая содержит структуру    // конфигурации и логгер.    app := &application{        config: cfg,        logger: logger,    }     // Объявляем новый мультиплексор и добавляем маршрут `/v1/healthcheck`,    // который будет перенаправлять запросы в метод `healhcheckHandler`    // (мы создадим его чуть позже).    mux := http.NewServeMux()    mux.HandleFunc("/v1/healthcheck", app.healthcheckHandler)     // Объявляем HTTP-сервер с настройками тайм-аута, который прослушивает порт,    // указанный в структуре конфигурации, и использует созданный выше мультиплексор.    srv := &http.Server{        Addr:         fmt.Sprintf(":%d", cfg.port),        Handler:      mux,        IdleTimeout:  time.Minute,        ReadTimeout:  10 * time.Second,        WriteTimeout: 30 * time.Second,    }     // Запускаем HTTP-сервер    logger.Printf("starting %s server on %s", cfg.env, srv.Addr)    err := srv.ListenAndServe()    logger.Fatal(err) } 

Хендлер для проверки работоспособности приложения

Следующее, что нам нужно сделать, — создать метод healthcheckHandler для обработки HTTP-запросов. Сейчас обработчик будет возвращать простой текст, который будет содержать:

• Строку status: available;

• Версию API из жёстко запрограммированной константы version;

• Название среды разработки, которая будет взята из флага командной строки env.

Создадим новый файл cmd/api/healthcheck.go:

$ touch cmd/api/healthcheck.go

И добавим в него код:

// cmd/api/healthcheck.go  package main  import (    "fmt"    "net/http" )  func (app *application) healthcheckHandler(w http.ResponseWriter, r *http.Request) {    fmt.Fprintln(w, "status: available")    fmt.Fprintf(w, "environment: %s\n", app.config.env)    fmt.Fprintf(w, "version: %s\n", version) 

Самое важное в приведённом коде: понимание, что healhcheckHandler — это метод для структуры application. Это самый эффективный и общепринятый способ сделать зависимости доступными для обработчиков, не используя глобальные переменные или замыкания. 

Чтобы добавить нужную обработчику зависимость, достаточно включить её в структуру приложения. В нашем коде мы применили этот паттерн, когда использовали app.config.env.

Снова запустите сервер командой go run cmd/app/ и в браузере перейдите по адресу localhost:4000/healthcheck. Сервер вернёт:

status: available environment: development version: 1.0.0

Или используйте curl в терминале, где -i говорит curl выводить заголовок и тело ответа от сервера:

$ curl -i localhost:4000/v1/healthcheck  HTTP/1.1 200 OK Date: Mon, 14 Oct 2024 18:52:38 GMT Content-Length: 58 Content-Type: text/plain; charset=utf-8 status: available environment: development version: 1.0.0

Попробуйте запустить сервер с флагами, которые вы запрограммировали, и другими значениями для них.

Конечные точки API и маршрутизация REST

Теперь мы постепенно будем создавать API, чтобы конечные точки выглядели так:

Выбор роутера

Одним из первых препятствий, с которыми вы столкнётесь при создании API, будет ограниченный функционал маршрутизатора из стандартной библиотеки http.ServeMux. 

Этот роутер не позволяет перенаправлять запросы на разные обработчики в зависимости от методов запроса (GET, POST и т.д.) и не поддерживает чистые URL-адреса со встроенными в путь параметрами. 

Например, чтобы получить сведения о конкретной книге, клиент отправляет запрос GET /v1/books/1 вместо того, чтобы добавлять идентификатор книги в качестве параметра строки запроса GET /v1/books?id=1.

Мы будем использовать популярный маршрутизатор chi. Чтобы его получить, выполним команду:

$ go get github.com/go-chi/chi/v5 go: downloading github.com/go-chi/chi/v5 v5.1.0 go: added github.com/go-chi/chi/v5 v5.1.0

Начнём работу с chi, добавив в наше приложение два эндпоинта: первый для создания новой книги, второй — для вывода сведений о конкретной книге. К концу этой статьи у нас будет три конечные точки и три обработчика.

Чтобы функция main() не стала слишком громоздкой, выделим все правила маршрутизации в отдельный файл cmd/api/routes.go.

$ touch cmd/api/routes.go

И добавим в него код:

// cmd/api/routes.go  package main  import (    "github.com/go-chi/chi/v5" )  func (app *application) routes() *chi.Mux {    // Инициализируем новый маршрутизатор chi.    router := chi.NewRouter()     // Регистрируем шаблоны URL и методы обработчиков.    router.Get("/v1/healthcheck", app.healthcheckHandler)    router.Post("/v1/books", app.createBookHandler)    router.Get("/v1/books/{id}", app.showBookHandler)     // Возвращаем экземпляр chi.Mux    return router } 

Обновим функцию main(), удалив из неё объявление `http.ServeMux`. Используем экземпляр `chi.Mux`, который возвращает метод app.routes():

// cmd/api/main.go  package main  import (    "flag"    "fmt"    "log"    "net/http"    "os"    "time" )  const version = "1.0.0"  type config struct {    port int    env string }  type application struct {    config config    logger *log.Logger }  func main() {    var cfg config     flag.IntVar(&cfg.port, "port", 4000, "API server port")    flag.StringVar(&cfg.env, "env", "development", "Environment (development|staging|production)")    flag.Parse()     logger := log.New(os.Stdout, "", log.Ldate|log.Ltime)     app := &application {        config: cfg,        logger: logger,    }     srv := &http.Server {        Addr: fmt.Sprintf(":%d",cfg.port),        Handler: app.routes(),        IdleTimeout: time.Minute,        ReadTimeout: 10 * time.Second,        WriteTimeout: 30 * time.Second,    }     logger.Printf("starting %s server on %s", cfg.env, srv.Addr)    err := srv.ListenAndServe()    logger.Fatal(err) } 

Добавление новых функций-обработчиков

Теперь, когда правила маршрутизации настроены, мы можем создать методы createBookHandler и showBookHandler для новых эндпоинтов. Метод showBookHandler представляет некоторый интерес, потому что в нём мы будем извлекать параметр id из URL-адреса и использовать его в HTTP-ответе.

Создадим файл cmd/api/books.go:

touch cmd/api/books.go

И добавим в него код:

// cmd/api/books.go  package main  import (    "fmt"    "net/http"    "strconv"     "github.com/go-chi/chi/v5" )  // Добавляем обработчик createBookHandler для эндпоинта `POST /v1/books`. // Пока мы просто возвращаем текст. func (app *application) createBookHandler(w http.ResponseWriter, r *http.Request) {    fmt.Fprintf(w, "create a new book") }  // Добавляем обработчик showBookHandler для конечной точки `GET /v1/books/:id`. // На данный момент мы получаем параметр id из URL-адреса и включаем его в ответ. func (app *application) showBookHandler(w http.ResponseWriter, r *http.Request) {     // Мы можем использовать функцию chi.URLParam(), чтобы получить параметр id из URL.    // Первый параметр в функции — это http.Request.    param := chi.URLParam(r, "id")     // В нашем проекте все книги будут иметь уникальный положительный идентификатор,    // но возвращаемое значение метода URLParam() всегда является строкой,    // поэтому мы пытаемся преобразовать её в целое число. Если не удаётся    // её преобразовать или id меньше 1, то идентификатор является недействительным, и мы    // вызываем http.NotFound() для возврата ошибки 404.    id, err := strconv.ParseInt(param, 10, 64)    if err != nil || id < 1 {        http.NotFound(w, r)        return    }     // Если идентификатор валидный, мы возвращаем его в ответе.    fmt.Fprintf(w, "show the details of book %d\n", id) } 

Давайте проверим, как всё работает. Перезапустите приложение:

$ go run ./cmd/api 2024/10/21 17:13:52 starting development server on :4000

Пока сервер запущен, откройте другой терминал и введите запросы для каждого обработчика с помощью команды curl:

$ curl localhost:4000/v1/healthcheck status: available environment: development version: 1.0.0  $ curl -X POST localhost:4000/v1/books create a new book  $ curl localhost:4000/v1/books/12 show the details of book 12

Обратите внимание, что в последнем запросе значение параметра 12 было успешно получено из URL и включено в ответ.

А что, если сделать запрос с неподдерживаемым методом:

$ curl -i -X POST localhost:4000/v1/healthcheck HTTP/1.1 405 Method Not Allowed Allow: GET, OPTIONS Content-Type: text/plain; charset=utf-8 X-Content-Type-Options: nosniff Date: Mon, 21 Oct 2024 14:28:52 GMT Content-Length: 19  Method Not Allowed

Получили ошибку 405 Method Not Allowed — метод не поддерживается.

А теперь попробуем передать в запросе отрицательный id, чтобы получить ошибку 404 Not Found:

$ curl -i localhost:4000/v1/books/-3 HTTP/1.1 404 Not Found Content-Type: text/plain; charset=utf-8 X-Content-Type-Options: nosniff Date: Mon, 21 Oct 2024 14:37:01 GMT Content-Length: 19  404 page not found

В качестве самостоятельной работы сделайте запрос, где id будет строкой, которую невозможно преобразовать в целое положительное число. Обратите внимание на ошибку.

Создание помощника для чтения параметра id

Код для извлечения параметра id из URL, например, из /v1/books/{id}, понадобится нам неоднократно. Поэтому давайте вынесем эту логику в небольшой вспомогательный метод, который можно будет использовать повторно.

Создадим новый файл cmd/api/helpers.go:

$ touch cmd/api/helpers.go

И добавим новый метод для структуры application:

// cmd/api/helpers.go  package main  import (    "errors"    "net/http"    "strconv"     "github.com/go-chi/chi/v5" ) // readIDParam получает параметр id из контекста запроса, преобразует его в // целое число и возвращает его. Если операция не удалась, возвращает 0 и сообщение // об ошибке. func (app *application) readIDParam(r *http.Request) (int64, error) {    param := chi.URLParam(r, "id")     id, err := strconv.ParseInt(param, 10, 64)    if err != nil || id < 1 {        return 0, errors.New("invalid parameter")    }     return id, nil }

С помощью нового метода readIDParam() упростим код в обработчике showBookHandler():

// cmd/api/books.go  package main  // ...  func (app *application) showBookHandler(w http.ResponseWriter, r *http.Request) {    id, err := app.readIDParam(r)    if err != nil {        http.NotFound(w, r)        return    }     fmt.Fprintf(w, "show the details of book %d\n", id) } 

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

В следующей части начнём работать с JSON. Мы обновим наши обработчики, чтобы он возвращали JSON вместо обычного текста.