Учимся разрабатывать REST API на Go на примере сокращателя ссылок

• мы выберем для него актуальный http-роутер,
• позаботимся о логах,
• напишем тесты: unit-тесты, тесты хэндлеров и функциональные,
• настроим автоматический деплой через GitHub Actions и др.

• go-chi/chi — для обработки HTTP-запросов,
• slog — для логирования,
• stretchr/testify — для покрытия проекта тестами,
• ilyakaznacheev/cleanenv — для конфигурирования,
• SQLite — для хранения данных, СУБД.

HTTP-роутер

Логирование

Другое

# config/local.yaml

env: "local" # Окружение - local, dev или prod
storage_path: "./storage/storage.db" # файл, в котором будет храниться наша БД
http_server: # конфигурация нашего http-сервера
  address: "localhost:8082"
  timeout: 4s
  idle_timeout: 30s

Не забудьте освободить выбранный порт и создать папку, в которой будет размещен db-файл. Сам файл создавать не нужно, он появится автоматически.

mkdir -p internal/config && touch internal/config/config.go

// internal/config/config.go

type Config struct {
    Env         string `yaml:"env" env-default:"development"`
    StoragePath string `yaml:"storage_path" env-required:"true"`
    HTTPServer
}

type HTTPServer struct {
    Address     string        `yaml:"address" env-default:"0.0.0.0:8080"`
    Timeout     time.Duration `yaml:"timeout" env-default:"5s"`
    IdleTimeout time.Duration `yaml:"idle_timeout" env-default:"60s"`
}

• yaml — имя соответствующего параметра в Yaml-файле,
• env-default — дефолтное значение,
• env-required — делает параметры обязательными. Если такой параметр не указан, мы будем получать ошибку.

go get -u github.com/ilyakaznacheev/cleanenv

// internal/config/config.go

func MustLoad() *Config {
    // Получаем путь до конфиг-файла из env-переменной CONFIG_PATH
    configPath := os.Getenv("CONFIG_PATH")
    if configPath == "" {
        log.Fatal("CONFIG_PATH environment variable is not set")
    }

    // Проверяем существование конфиг-файла
    if _, err := os.Stat(configPath); err != nil {
        log.Fatalf("error opening config file: %s", err)
    }

    var cfg Config

    // Читаем конфиг-файл и заполняем нашу структуру
    err := cleanenv.ReadConfig(configPath, &cfg)
    if err != nil {
        log.Fatalf("error reading config file: %s", err)
    }

    return &cfg
}

CONFIG_PATH=./config/local.yaml ./your-app

Есть и более удобные способы, но они зависят от вашего окружения, используемой IDE и т.п. Советую изучить этот вопрос самостоятельно.

// cmd/url-shortener/main.go

package main

import (
    "url-shortener/internal/config"
)

func main() {
    cfg := config.MustLoad()
}

go get golang.org/x/exp/slog

import "log/slog"

// cmd/url-shortener/main.go
const (
    envLocal = "local"
    envDev   = "dev"
    envProd  = "prod"
)

func main() {
    // ...
}

func setupLogger(env string) *slog.Logger {
    var log *slog.Logger

    switch env {
    case envLocal:
        log = slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug}))
    case envDev, envProd:
        log = slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug}))
    case envProd:
        log = slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
    }

    return log
}

В зависимости от окружения эта функция создает логгер с разными параметрами — TextHandler / JSONHandler и уровень LevelDebug / LevelInfo.

// cmd/url-shortener/main.go

func main() {
    cfg := config.MustLoad()

    log := setupLogger(cfg.Env)
    log = log.With(slog.String("env", cfg.Env)) // к каждому сообщению будет добавляться поле с информацией о текущем окружении

    log.Info("initializing server", slog.String("address", cfg.Address)) // Помимо сообщения выведем параметр с адресом
    log.Debug("logger debug mode enabled")
}

time=2023-06-18T19:27:41.720+06:00 level=INFO msg="initializing server" env=local address=localhost:8082
time=2023-06-18T19:27:41.720+06:00 level=DEBUG msg="logger debug mode enabled" env=local

Благодаря функции With к каждому сообщению будет добавлено поле env с информацией о текущем окружении. Это очень удобно, советую получше изучить эту механику и обогащать свой логгер необходимой информацией.

// internal/lib/logger/handlers/slogdiscard/slogdiscard.go
package slogdiscard

import (
    "context"

    "golang.org/x/exp/slog"
)

func NewDiscardLogger() *slog.Logger {
    return slog.New(NewDiscardHandler())
}

type DiscardHandler struct{}

func NewDiscardHandler() *DiscardHandler {
    return &DiscardHandler{}
}

func (h *DiscardHandler) Handle(_ context.Context, _ slog.Record) error {
    // Просто игнорируем запись журнала
    return nil
}

func (h *DiscardHandler) WithAttrs(_ []slog.Attr) slog.Handler {
    // Возвращает тот же обработчик, так как нет атрибутов для сохранения
    return h
}

func (h *DiscardHandler) WithGroup(_ string) slog.Handler {
    // Возвращает тот же обработчик, так как нет группы для сохранения
    return h
}

func (h *DiscardHandler) Enabled(_ context.Context, _ slog.Level) bool {
    // Всегда возвращает false, так как запись журнала игнорируется
    return false
}

// internal/lib/logger/sl/sl.go
package sl

import (
    "golang.org/x/exp/slog"

    "url-shortener/internal/lib/logger/handlers/slogdiscard"
)

func Err(err error) slog.Attr {
    return slog.Attr{
        Key:   "error",
        Value: slog.StringValue(err.Error()),
    }
}

• url — длинный адрес, который мы сохраняем,
• alias — короткий идентификатор, по которому будем искать оригинальный адрес.

CREATE TABLE IF NOT EXISTS url(
        id INTEGER PRIMARY KEY,
        alias TEXT NOT NULL UNIQUE,
        url TEXT NOT NULL);
CREATE INDEX IF NOT EXISTS idx_alias ON url(alias);

• поле alias уникальное (параметр UNIQUE), чтобы не было коллизий,
• все поля обязательные,
• для быстрого поиска записей создаем индекс idx_alias.

// internal/storage/storage.go

package storage

import "errors"

var (
    ErrURLNotFound = errors.New("url not found")
    ErrURLExists   = errors.New("url exists")
)

go get github.com/mattn/go-sqlite3

// internal/storage/sqlite/sqlite.go

type Storage struct {
    db *sql.DB
}

// internal/storage/sqlite/sqlite.go

func New(storagePath string) (*Storage, error) {
    const op = "storage.sqlite.NewStorage" // Имя текущей функции для логов и ошибок

    db, err := sql.Open("sqlite3", storagePath) // Подключаемся к БД
    if err != nil {
        return nil, fmt.Errorf("%s: %w", op, err)
    }

    // Создаем таблицу, если ее еще нет
    stmt, err := db.Prepare(`
    CREATE TABLE IF NOT EXISTS url(
        id INTEGER PRIMARY KEY,
        alias TEXT NOT NULL UNIQUE,
        url TEXT NOT NULL);
    CREATE INDEX IF NOT EXISTS idx_alias ON url(alias);
    `)
    if err != nil {
        return nil, fmt.Errorf("%s: %w", op, err)
    }

    _, err = stmt.Exec()
    if err != nil {
        return nil, fmt.Errorf("%s: %w", op, err)
    }

    return &Storage{db: db}, nil
}

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

Методы хранилища

// internal/storage/sqlite/sqlite.go

func (s *Storage) SaveURL(urlToSave string, alias string) (int64, error) {
    const op = "storage.sqlite.SaveURL"

    // Подготавливаем запрос
    stmt, err := s.db.Prepare("INSERT INTO url(url,alias) values(?,?)")
    if err != nil {
        return 0, fmt.Errorf("%s: prepare statement: %w", op, err)
    }

    // Выполняем запрос
    res, err := stmt.Exec(urlToSave, alias)
    if err != nil {
        if sqliteErr, ok := err.(sqlite3.Error); ok && sqliteErr.ExtendedCode == sqlite3.ErrConstraintUnique {
            return 0, fmt.Errorf("%s: %w", op, storage.ErrURLExists)
        }

        return 0, fmt.Errorf("%s: execute statement: %w", op, err)
    }

    // Получаем ID созданной записи
    id, err := res.LastInsertId()
    if err != nil {
        return 0, fmt.Errorf("%s: failed to get last insert id: %w", op, err)
    }

    // Возвращаем ID
    return id, nil
}

if sqliteErr, ok := err.(sqlite3.Error); ok && sqliteErr.ExtendedCode == sqlite3.ErrConstraintUnique {
// …

// internal/storage/sqlite/sqlite.go

func (s *Storage) GetURL(alias string) (string, error) {
    const op = "storage.sqlite.GetURL"

    stmt, err := s.db.Prepare("SELECT url FROM url WHERE alias = ?")
    if err != nil {
        return "", fmt.Errorf("%s: prepare statement: %w", op, err)
    }

    var resURL string
    
    err = stmt.QueryRow(alias).Scan(&resURL)
    if errors.Is(err, sql.ErrNoRows) {
        return "", storage.ErrURLNotFound
    }
    if err != nil {
        return "", fmt.Errorf("%s: execute statement: %w", op, err)
    }

    return resURL, nil
}

Надеюсь, здесь пояснения не нужны. Метод DeleteURL можете написать самостоятельно, в качестве упражнения.

// cmd/url-shortener/main.go

func main() {
    // ...
    storage, err := sqlite.New(cfg.StoragePath)
    if err != nil {
        log.Error("failed to initialize storage", sl.Err(err))
    }

Подготовка HTTP Server

go get -u github.com/go-chi/chi/v5

go get github.com/go-chi/render

Middleware

// cmd/url-shortener/main.go

router := chi.NewRouter()  
  
router.Use(middleware.RequestID) // Добавляет request_id в каждый запрос, для трейсинга
router.Use(middleware.Logger) // Логирование всех запросов
router.Use(middleware.Recoverer)  // Если где-то внутри сервера (обработчика запроса) произойдет паника, приложение не должно упасть
router.Use(middleware.URLFormat) // Парсер URLов поступающих запросов

// internal/http-server/middleware/logger/logger.go

package logger

import (
    "net/http"
    "time"

    "github.com/go-chi/chi/v5/middleware"
    "golang.org/x/exp/slog"
)

func New(log *slog.Logger) func(next http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        log = log.With(
            slog.String("component", "middleware/logger"),
        )

        log.Info("logger middleware enabled")

        // код самого обработчика
        fn := func(w http.ResponseWriter, r *http.Request) {
            // собираем исходную информацию о запросе
            entry := log.With(
                slog.String("method", r.Method),
                slog.String("path", r.URL.Path),
                slog.String("remote_addr", r.RemoteAddr),
                slog.String("user_agent", r.UserAgent()),
                slog.String("request_id", middleware.GetReqID(r.Context())),
            )
            
            // создаем обертку вокруг `http.ResponseWriter`
            // для получения сведений об ответе
            ww := middleware.NewWrapResponseWriter(w, r.ProtoMajor)

            // Момент получения запроса, чтобы вычислить время обработки
            t1 := time.Now()
            
            // Запись отправится в лог в defer
            // в этот момент запрос уже будет обработан
            defer func() {
                entry.Info("request completed",
                    slog.Int("status", ww.Status()),
                    slog.Int("bytes", ww.BytesWritten()),
                    slog.String("duration", time.Since(t1).String()),
                )
            }()

            // Передаем управление следующему обработчику в цепочке middleware
            next.ServeHTTP(ww, r)
        }

        // Возвращаем созданный выше обработчик, приведя его к типу http.HandlerFunc
        return http.HandlerFunc(fn)
    }
}

router.Use(mwLogger.New(log))

Save — сохранение нового URL

// internal/http-server/handlers/url/save/save.go

type Request struct {
    URL   string `json:"url" validate:"required,url"`
    Alias string `json:"alias,omitempty"`
}

type Response struct {
    Status string `json:"status"`
    Error  string `json:"error,omitempty"`
    Alias string `json:"alias"`
}

// internal/lib/api/response/response.go

type Response struct {
    Status string `json:"status"`
    Error  string `json:"error,omitempty"`
}

const (
    StatusOK    = "OK"
    StatusError = "Error"
)

// internal/http-server/handlers/url/save/save.go

import (
    // ...

    // для краткости даем короткий алиас пакету
    resp "url-shortener/internal/lib/api/response"
)

type Response struct {
    resp.Response
    Alias string `json:"alias,omitempty"`
}

type URLSaver interface {
    SaveURL(URL, alias string) (int64, error)
}

// internal/http-server/handlers/url/save/save.go

import (
    // ...
    
    // Напоминаю, что тут мы используем алиас для краткости
    resp "url-shortener/internal/lib/api/response"
)

func New(log *slog.Logger, urlSaver URLSaver) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        const op = "handlers.url.save.New"


        // Добавляем к текущму объекту логгера поля op и request_id
        // Они могут очень упростить нам жизнь в будущем
        log = log.With(
            slog.String("op", op),
            slog.String("request_id", middleware.GetReqID(r.Context())),
        )

        // Создаем объект запроса и анмаршаллим в него запрос
        var req Request

        err := render.DecodeJSON(r.Body, &req)
        if errors.Is(err, io.EOF) {
            // Такую ошибку встретим, если получили запрос с пустым телом
            // Обработаем её отдельно
            log.Error("request body is empty")

            render.JSON(w, r, render.JSON(w, r, resp.Response{
                Status: resp.StatusError,
                Error:  "empty request",
            }))

            return
        }
        if err != nil {
            log.Error("failed to decode request body", sl.Err(err))

            render.JSON(w, r, render.JSON(w, r, resp.Response{
                Status: resp.StatusError,
                Error:  "failed to decode request",
            }))

            return
        }

        // Лучше больше логов, чем меньше - лишнее мы легко сможем почистить,
        // при необходимости. А вот недостающую информацию мы уже не получим.
        log.Info("request body decoded", slog.Any("req", req))

        // ...
    }
}

// internal/lib/api/response/response.go

func Error(msg string) Response {
    return Response{
        Status: StatusError,
        Error:  msg,
    }
}

func OK() Response {
    return Response{
        Status: StatusOK,
    }
}

// internal/http-server/handlers/url/save/save.go

err := render.DecodeJSON(r.Body, &req)
if errors.Is(err, io.EOF) {
    log.Error("request body is empty")

    render.JSON(w, r, resp.Error("empty request")) // <----

    return
}
if err != nil {
    log.Error("failed to decode request body", sl.Err(err))

    render.JSON(w, r, resp.Error("failed to decode request")) // <----

    return
}

// internal/http-server/handlers/url/save/save.go

func New(log *slog.Logger, urlSaver URLSaver) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {

    // ...

    // Создаем объект валидатора
    // и передаем в него структуру, которую нужно провалидировать
    if err := validator.New().Struct(req); err != nil {
        // Приводим ошибку к типу ошибки валидации
        validateErr := err.(validator.ValidationErrors)
    
        log.Error("invalid request", sl.Err(err))
    
        render.JSON(w, r, resp.Error(validateErr.Error()))
    
        return
    }

{
    "status": "Error",
    "error": "Key: 'Request.URL' Error:Field validation for 'URL' failed on the 'url' tag"
}

// internal/lib/api/response/response.go

func ValidationError(errs validator.ValidationErrors) Response {
    var errMsgs []string

    for _, err := range errs {
        switch err.ActualTag() {
        case "required":
            errMsgs = append(errMsgs, fmt.Sprintf("field %s is a required field", err.Field()))
        case "url":
            errMsgs = append(errMsgs, fmt.Sprintf("field %s is not a valid URL", err.Field()))
        default:
            errMsgs = append(errMsgs, fmt.Sprintf("field %s is not valid", err.Field()))
        }
    }

    return Response{
        Status: StatusError,
        Error:  strings.Join(errMsgs, ", "),
    }
}

render.JSON(w, r, resp.ValidationError(validateErr))
{
    "status": "Error",
    "error": "field URL is not a valid URL"
}

// internal/http-server/handlers/url/save/save.go

// TODO: move to config when needed
const aliasLength = 6

func New(log *slog.Logger, urlSaver URLSaver) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // ...
    
        alias := req.Alias
        if alias == "" {
            alias = random.NewRandomString(aliasLength)
        }
    }
}

// internal/lib/random/random.go

// NewRandomString generates random string with given size.
func NewRandomString(size int) string {
    rnd := rand.New(rand.NewSource(time.Now().UnixNano()))

    chars := []rune("ABCDEFGHIJKLMNOPQRSTUVWXYZ" +
        "abcdefghijklmnopqrstuvwxyz" +
        "0123456789")

    b := make([]rune, size)
    for i := range b {
        b[i] = chars[rnd.Intn(len(chars))]
    }

    return string(b)
}

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

// internal/http-server/handlers/url/save/save.go

func New(log *slog.Logger, urlSaver URLSaver) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // ...

        id, err := urlSaver.SaveURL(req.URL, alias)
        if errors.Is(err, storage.ErrURLExists) {
            // Отдельно обрабатываем ситуацию,
            // когда запись с таким Alias уже существует
            log.Info("url already exists", slog.String("url", req.URL))

            render.JSON(w, r, resp.Error("url already exists"))

            return
        }
        if err != nil {
            log.Error("failed to add url", sl.Err(err))

            render.JSON(w, r, resp.Error("failed to add url"))

            return
        }

        log.Info("url added", slog.Int64("id", id))

        responseOK(w, r, alias)
    }
}

// internal/http-server/handlers/url/save/save.go

func responseOK(w http.ResponseWriter, r *http.Request, alias string) {
    render.JSON(w, r, Response{
        Response: resp.OK(),
        Alias:    alias,
    })
}

//go:generate go run github.com/vektra/mockery/v2@v2.28.2 --name=URLSaver
type URLSaver interface {
    SaveURL(URL, alias string) (int64, error)
}

./internal/http-server/handlers/url/save/save.go

// internal/http-server/handlers/url/save/save_test.go
func TestSaveHandler(t *testing.T) {
    cases := []struct {
        name      string // Имя теста
        alias     string // Отправляемый alias
        url       string // Отправляемый URL
        respError string // Какую ошибку мы должны получить?
        mockError error  // Ошибку, которую вернёт мок
    }{
        {
            name:  "Success",
            alias: "test_alias",
            url:   "https://google.com",
            // Тут поля respError и mockError оставляем пустыми,
            // т.к. это успешный запрос
        },
        // Другие кейсы ...
    }

    for _, tc := range cases {  
        t.Run(tc.name, func(t *testing.T) {
            // Создаем объект мока стораджа
            urlSaverMock := mocks.NewURLSaver(t)

            // Если ожидается успешный ответ, значит к моку точно будет вызов
            // Либо даже если в ответе ожидаем ошибку,
            // но мок должен ответить с ошибкой, к нему тоже будет запрос:
            if tc.respError == "" || tc.mockError != nil {
                // Сообщаем моку, какой к нему будет запрос, и что надо вернуть
                urlSaverMock.On("SaveURL", tc.url, mock.AnythingOfType("string")).
                    Return(int64(1), tc.mockError).
                    Once() // Запрос будет ровно один
            }

            // Создаем наш хэндлер
            handler := save.New(sl.NewDiscardLogger(), urlSaverMock)

            // Формируем тело запроса
            input := fmt.Sprintf(`{"url": "%s", "alias": "%s"}`, tc.url, tc.alias)

            // Создаем объект запроса
            req, err := http.NewRequest(http.MethodPost, "/save", bytes.NewReader([]byte(input)))
            require.NoError(t, err)

            // Создаем ResponseRecorder для записи ответа хэндлера
            rr := httptest.NewRecorder()
            // Обрабатываем запрос, записывая ответ в рекордер
            handler.ServeHTTP(rr, req)

            // Проверяем, что статус ответа корректный
            require.Equal(t, rr.Code, http.StatusOK)

            body := rr.Body.String()

            var resp save.Response

            // Анмаршаллим тело, и проверяем что при этом не возникло ошибок
            require.NoError(t, json.Unmarshal([]byte(body), &resp))

            // Проверяем наличие требуемой ошибки в ответе
            require.Equal(t, tc.respError, resp.Error)

            // Другие проверки
        })
    }
}

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

router.Post("/", save.New(log, storage))

Redirect — перенаправление на сохраненный URL

// cmd/url-shortener/main.go

//go:generate go run github.com/vektra/mockery/v2@v2.28.2 --name=URLGetter
//
// URLGetter is an interface for getting url by alias.
type URLGetter interface {
    GetURL(alias string) (string, error)
}

func New(log *slog.Logger, urlGetter URLGetter) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        const op = "handlers.url.redirect.New"

        log = log.With(
            slog.String("op", op),
            slog.String("request_id", middleware.GetReqID(r.Context())),
        )

        // Роутер chi позволяет делать вот такие финты -
        // получать GET-параметры по их именам.
        // Имена определяются при добавлении хэндлера в роутер, это будет ниже.
        alias := chi.URLParam(r, "alias")
        if alias == "" {
            log.Info("alias is empty")

            render.JSON(w, r, resp.Error("not found"))

            return
        }

        // Находим URL по алиасу в БД
        resURL, err := urlGetter.GetURL(alias)
        if errors.Is(err, storage.ErrURLNotFound) {
            // Не нашли URL, сообщаем об этом клиенту
            log.Info("url not found", "alias", alias)

            render.JSON(w, r, resp.Error("not found"))

            return
        }
        if err != nil {
            // Не удалось осуществить поиск
            log.Error("failed to get url", sl.Err(err))

            render.JSON(w, r, resp.Error("internal error"))

            return
        }

        log.Info("got url", slog.String("url", resURL))

        // Делаем редирект на найденный URL
        http.Redirect(w, r, resURL, http.StatusFound)
    }
}

router.Get("/{alias}", redirect.New(log, storage))

Здесь формируем путь для обращения и именуем его параметр — {alias}. В хендлере можно получить этот параметр по указанному имени, что мы и сделали выше.

router.Get("/v1/{user_id}/uid", redirect.New(log, storage))

r.Delete("/{alias}", remove.New(log, storage))

// internal/config/config.go

type HTTPServer struct {
    Address     string        `yaml:"address" env-default:"0.0.0.0:8080"`
    Timeout     time.Duration `yaml:"timeout" env-default:"5s"`
    IdleTimeout time.Duration `yaml:"idle_timeout" env-default:"60s"`
    // Добавляем:
    User        string        `yaml:"user" env-required:"true"`
    Password    string        `yaml:"password" env-required:"true" env:"HTTP_SERVER_PASSWORD"`
}

# config/local.yaml

env: "local"
storage_path: "./storage/storage.db"
http_server:
  address: "localhost:8082"
  timeout: 4s
  idle_timeout: 30s
  user: "my_user"
  password: "my_pass"

Обратите внимание: в продакшен-конфиг добавляем только логин. Пароль важно хранить более безопасным образом — подробнее в разделе про деплой.

// cmd/url-shortener/main.go

// Все пути этого роутера будут начинаться с префикса `/url`
router.Route("/url", func(r chi.Router) {
    // Подключаем авторизацию
    r.Use(middleware.BasicAuth("url-shortener", map[string]string{
        // Передаем в middleware креды
        cfg.HTTPServer.User: cfg.HTTPServer.Password,
        // Если у вас более одного пользователя,
        // то можете добавить остальные пары по аналогии.
    }))

    r.Post("/", save.New(log, storage))
})

// Хэндлер redirect остается снаружи, в основном роутере
router.Get("/{alias}", redirect.New(log, storage))

• httpexpect — для тестирования REST API,
• gofakeit — для генерации случайных данных разного формата (имена, имейлы, номера телефонов, URL и другое).

> go get github.com/brianvoe/gofakeit/v6
> go get github.com/gavv/httpexpect/v2

// tests/url_shortener_test.go

const (
    host = "localhost:8082"
)

func TestURLShortener_HappyPath(t *testing.T) {
    // Универсальный способ создания URL
    u := url.URL{
        Scheme: "http",
        Host:   host,
    }

    // Создаем клиент httpexpect
    e := httpexpect.Default(t, u.String())

    e.POST("/url"). // Отправляем POST-запрос, путь - '/url'
        WithJSON(save.Request{ // Формируем тело запроса
            URL:   gofakeit.URL(), // Генерируем случайный URL
            Alias: random.NewRandomString(10), // Генерируем случайную строку
        }).
        WithBasicAuth("myuser", "mypass"). // Добавляем к запросу креды авторизации
        Expect(). // Далее перечисляем наши ожидания от ответа
        Status(200). // Код должен быть 200
        JSON().Object(). // Получаем JSON-объект тела ответа
        ContainsKey("alias") // Проверяем, что в нём есть ключ 'alias'
}

Аренда облачного сервера

ssh-keygen -t rsa -b 4096 -C "some comment"

Настройка GitHub Workflow

• name — название процесса workflow, которое будет отображаться в разделе Actions,
• on — условия, при которых будет запускаться workflow,
• jobs — действия, которые необходимо проделать.

# .github/workflows/deploy.yaml

name: Deploy App # Даем осмысленное имя

on:
  workflow_dispatch: # Ручкой запуск
    inputs: # Что нужно ввести вручную при запуске
      tag: # Мы будем указывать тег для деплоя
        description: 'Tag to deploy'
        required: true

В такой конфигурации workflow будет запускаться только вручную. Притом нужно будет указать git-тег, по которому будем деплоить сервис. Можно было бы сделать намного проще — деплоить при каждом пуше/мерже в основную ветку, но мне такой вариант не нравится. Хочу сам контролировать это дело.

# .github/workflows/deploy.yaml

# name: ..., on: ...

jobs:
  deploy:
    runs-on: ubuntu-latest # ОС для runner
    env: # Вводим переменные, которые будем использовать далее
      HOST: root@<your_ip> # логин / хост сервера, на которые деплоим
      DEPLOY_DIRECTORY: /root/apps/url-shortener # папка проекта на сервере
      CONFIG_PATH: /root/apps/url-shortener/config/prod.yaml # конфиг сервиса на сервере
      ENV_FILE_PATH: /root/apps/url-shortener/config.env # env-файл на сервере

# .github/workflows/deploy.yaml

# name: ..., on: ...

jobs:
    # deploy: ...
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
        with:
          ref: ${{ github.event.inputs.tag }}
      - name: Check if tag exists
        run: |
          git fetch --all --tags
          if ! git tag | grep -q "^${{ github.event.inputs.tag }}$"; then
            echo "error: Tag '${{ github.event.inputs.tag }}' not found"
            exit 1
          fi
      - name: Set up Go
        uses: actions/setup-go@v2
        with:
          go-version: 1.20.2
      - name: Build app
        run: |
          go mod download
          go build -o url-shortener ./cmd/url-shortener
      - name: Deploy to VM
        run: |
          sudo apt-get install -y ssh rsync
          echo "$DEPLOY_SSH_KEY" > deploy_key.pem
          chmod 600 deploy_key.pem
          ssh -i deploy_key.pem -o StrictHostKeyChecking=no ${{ env.HOST }} "mkdir -p ${{ env.DEPLOY_DIRECTORY }}"
          rsync -avz -e 'ssh -i deploy_key.pem -o StrictHostKeyChecking=no' --exclude='.git' ./ ${{ env.HOST }}:${{ env.DEPLOY_DIRECTORY }}
        env:
          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
      - name: Remove old systemd service file
        run: |
          ssh -i deploy_key.pem -o StrictHostKeyChecking=no ${{ env.HOST }} "rm -f /etc/systemd/system/url-shortener.service"
      - name: List workspace contents
        run: |
          echo "Listing deployment folder contents:"
          ls -la ${{ github.workspace }}/deployment
      - name: Create environment file on server
        run: |
          ssh -i deploy_key.pem -o StrictHostKeyChecking=no ${{ env.HOST }} "touch ${{ env.ENV_FILE_PATH }}"
          ssh -i deploy_key.pem -o StrictHostKeyChecking=no ${{ env.HOST }} "chmod 600 ${{ env.ENV_FILE_PATH }}"
          ssh -i deploy_key.pem -o StrictHostKeyChecking=no ${{ env.HOST }} "echo 'CONFIG_PATH=${{ env.CONFIG_PATH }}' > ${{ env.ENV_FILE_PATH }}"
          ssh -i deploy_key.pem -o StrictHostKeyChecking=no ${{ env.HOST }} "echo 'HTTP_SERVER_PASSWORD=${{ secrets.AUTH_PASS }}' >> ${{ env.ENV_FILE_PATH }}"
      - name: Copy systemd service file
        run: |
          scp -i deploy_key.pem -o StrictHostKeyChecking=no ${{ github.workspace }}/deployment/url-shortener.service ${{ env.HOST }}:/tmp/url-shortener.service
          ssh -i deploy_key.pem -o StrictHostKeyChecking=no ${{ env.HOST }} "mv /tmp/url-shortener.service /etc/systemd/system/url-shortener.service"
      - name: Start application
        run: |
          ssh -i deploy_key.pem -o StrictHostKeyChecking=no ${{ env.HOST }} "systemctl daemon-reload && systemctl restart url-shortener.service"

• name — имя шага, будет выводиться в процессе выполнения workflow, пишем что-то осмысленное.
• uses — использование внешней команды. Например, uses: actions/setup-go@v2 указывает, что шаг будет использовать действие setup-go, доступное в репозитории actions на GitHub.
• with — параметры, которые передаются в действие.
• env — определяет переменные окружения для этого шага.
• run — выполняемая команда.

• Checkout repository: клонируем репозиторий в runner.
• Check if tag exists: проверяем, существует ли указанный тег.
• Set up Go: устанавливаем определенную версию Go.
• Build app: Скачиваем зависимости и собираем приложение.
• Deploy to VM: Загружаем файлы из репозитория на виртуальную машину.
• Remove old systemd service file: Удаляем старый файл сервиса systemd на сервере.
• List workspace contents: Выводим содержимое рабочего каталога на runner.
• Create environment file on server: Создаем файл окружения на сервере.
• Copy systemd service file: Копируем файл сервиса systemd на сервер.
• Start application: Перезапускаем приложение на сервере.

[Unit]
Description=Url Shortener
After=network.target

[Service]
User=root
WorkingDirectory=/root/apps/url-shortener
ExecStart=/root/apps/url-shortener/url-shortener
Restart=always
RestartSec=4
StandardOutput=inherit
EnvironmentFile=/root/apps/url-shortener/config.env

[Install]
WantedBy=multi-user.target

# config/prod.yaml

env: "prod"
storage_path: "./storage.db"
http_server:
  address: "0.0.0.0:8082" # 0.0.0.0 вместо localhost, чтобы работали внешние запросы
  timeout: 4s
  idle_timeout: 30s
  user: "some_username" # указываем только user, но не password. О пароле поговорим ниже

GitHub, Settings → Secrets and variables →Actions. Имена обязательно должны совпадать, так как они используются в нашем файле workflow.

Деплой в продакшен

git tag v0.0.1 && git push origin v0.0.1