Skip to content

Latest commit

 

History

History
168 lines (129 loc) · 11.4 KB

1.md

File metadata and controls

168 lines (129 loc) · 11.4 KB

Задание 1

Цель этого задания - подготовить каркас проекта, содержащего основную рутину, для дальнейшего добавления нового функционала.

❗ Структура проекта может меняться и усложняться по мере его развития. Не пытайтесь сразу построить идеальный проект! Лучше сделать структуру простой и гибкой для внесения изменений, чем сложной и запутанной, но соответствующей неким стандартам из идеального мира.

Функциональные требования

  1. Сервис предоставляет HTTP API по адресу 127.0.0.1:8080.

  2. Сервис должен предоставить эндпоинт GET http://127.0.0.1:8080/api/v1/health (в дальнейшем будет использоваться для проверки готовности сервиса принимать запросы). Эндпоинт должен возвращать ответ со следующими характеристиками:

    Content-Type: text/plain.
Code: HTTP 200 (OK)

Body:
HEALTHY

Нефункциональные требования

  1. Разместить проект в отдельном репозитории на github (структуру проекта сформировать самостоятельно).
  2. Использовать Go modules при установке зависимостей.
  3. Проект должен компилироваться, результат сборки должен быть доступен в директории dist.
  4. Команды компиляции проекта необходимо разместить в Makefile.
  5. Проект должен содержать короткую документацию в README.md описывающую как работать с проектом и как его собрать.
  6. Все изменения необходимо делать в отдельной ветке в git. Когда работа будет закончена, необходимо послать pool request в ветку main и добавить ментора в ревьюверы.

Ограничения

  1. Для построения api допускается использовать только библиотеку net/http и предлагаемый ею роутер.

  2. Рекомендуется использовать самую последнюю стабильную версии языка Go.

Об идиоматической структуре проекта

В Go нет устоявшейся структуры приложения, за исключением каталогов cmd, internal и pkg. Кроме того, большое количество старого кода написано по принципу "все файлы лежат в корне проекта". В этом курсе мы будем стараться следовать современным практикам организации проекта и написания кода.

В настоящее время существует несколько негласных правил формирования структуры проекта. Им не обязательно следовать, но многие коллеги-программисты будут ожидать, что ваш проект устроен именно таким образом.

  1. В проектах на Go (если это не библиотеки) принято стартовую точку выносить в каталог cmd и начинать сборку от него. Например, для нашей библиотеки это могло бы выглядеть как cmd/homelibrary/main.go. У такого подхода есть существенный плюс: можно легко добавить новый исполняемый файл в сборку. Более подробное объяснение можно посмотреть тут.

  2. Минимальные main-файлы и функции, которые содержат 5-7 строк кода: объявление пакета, функция main, вызов некой абстракции, которая запускает приложение, например:

    package main

// Здесь импортируем модуль, в котором живет логика инициализации и запуска
// приложения (в примере ниже это app).

func main() {
    if err := app.Run();err != nil {
        log.Printf("App failed: %v\n", err)
        os.Exit(1)
     }
}

  3. Весь код лежит в каталоге internal (в редких случаях в pkg). Для чего нужен такой каталог можно прочитать тут. На текущий момент импорт кода проекта в других репозиториях не планируется, поэтому весь исходный код рекомендуется сделать приватным.

  4. Код внутри каталога internal имеет структуру/слои. Стоит заранее обдумать где будут жить хэндлеры HTTP API, куда положить основной код приложения и т.д. Если сейчас это не очевидно, ничего страшного, эти решения все равно придется принять по мере работы над проектом.
    В Go особенно популярна чистая архитектура, поэтому на нее обязательно стоит хотя бы обратить внимание, например, в проектах из материалов для ознакомления.

  5. В Go при именовании файлов и каталогов принято использовать буквы в нижнем регистре даже если это комбинация из нескольких слов. Исключением может быть использование нижнего подчеркивания, но его чаще вводят как идентификатор группы файлов. В качестве примера рассмотрим возможную структуру одного из модулей проекта:

    └── internal
    └─── storage
        ├── inmemory.go
        ├── inmemory_mock.go
        └── inmemory_test.go

    Рядом с файлом inmemory.go, отвечающим за реализацию хранилища объектов в памяти, расположены inmemory_test.go, содержащий юнит-тесты, и inmemory_mock.go, представляющий собой mock-реализацию хранилища. Использование нижнего подчеркивания для разделения составного имени на части (например, in_memory.go) допускается в ряде случаев, но не приветствуется.

    Кроме того, то, что это хранилище (storage), следует из названия модуля. Дублирование названия модуля в имени сущностей, из которых он состоит, допускается, но не поощряется. Более детально о соглашении по именованию можно прочитать в Naming Conventions in Golang.

  6. В Go принято именовать модули в единственном числе, например: notification, model, test. Однако из этого правила есть и исключения: utils, docs.

На многие другие вопросы о назначении, расположении и именовании каталогов сможет ответить Go Project Layout. Но будьте осторожны: не стоит слепо следовать его рекомендациям. Многое из описанного в Go Project Layout все еще под вопросом и горячо обсуждается в сообществе. Поэтому при создании структуры в первую очередь руководствуйтесь целесообразностью.

Материалы для ознакомления

  • Naming Conventions in Golang - содержит рекомендации по именованию модулей, файлов, функций и структур.

  • Go Project Layout - содержит рекомендуемую структуру типичного проекта на Go и описание назначения основных директорий.

  • Clean architecture by Rober C. Martin - оригинальная статья от Роберта Мартина, кратко объясняющая основные идеи чистой архитектуры.

  • Clean architecture with SOLID - шаблон реализации чистой архитектуры с применением принципов SOLID.

  • Go clean template - шаблон реализации проекта по чистой архитектуре Роберта Мартина.

  • Creatly backend - еще один шаблон проекта, построенного по чистой архитектуре.

  • Документация net/http

  • Manage Go tools via Go modules - описывает управление зависимостями с помощью go mod.

  • Direct vs Indirect Dependencies in go.mod file - об отличии прямых (direct) от непрямых (indirect) зависимостей в go.mod.