docs/architecture/golang/README.md

# Архитектура сервиса/микросервиса на Golang

## Основа:

```
├── cmd            - Основные приложения проекта
├── deployments    - Директория для деплоя сервиса
├── docs           - Директория с документацией
├── internal       - Директория с внутренним кодом приложения
├── migrations     - Директория с миграциями изменений БД
├── pkg            - Директория с общими пакетами приложения
├── proto          - Директория с описанием прототипа интерфейса gRPC
├── tests          - Директория с тестами проекта (integration/e2e)
├── .dockerignore  - Файл для перечисления игнорирования докером файлов/директорий
├── .gitignore     - Файл для перечисления игнорирования гитом файлов/директорий
├── .gitlab-ci.yml - Файл настройки Gitlab CI
├── .golangci.yaml - Файл настройки линтера для Golang
├── .mockery.yaml  - Файл настройки пакета mockery для генерации моков на Golang
├── .buf.gen.yaml  - https://buf.build/docs/configuration/v1/buf-gen-yaml
├── .buf.work.yaml - https://buf.build/docs/configuration/v1/buf-work-yaml/
├── .buf.yaml      - https://buf.build/docs/configuration/v1/buf-yaml/
├── Dockerfile     - Файл контейнеризации сервиса
├── go.mod         - Корень управления зависимостями в GoLang
├── go.sum         - Файл содержащий хеши для нескольких версий модуля
├── Makefile       - Набор команд
├── openapi.yaml   - Файл описания REST документации в формате OpenAPI (swagger)
├── README.md      - Общий файл документации (путеводитель)
```

## Структура `/cmd`:

```
├── [app name]  - Название приложения (app)
│   ├── main.go - Точка входа в приложение
```

## Структура `/docs`:

```
├── [group]       - Группа документации
│   ├── README.md - Файл документации
```

## Структура `/internal`:

Здесь хранится внутренний код приложения и библиотек. Это код, который не должен быть применен в других приложениях и библиотеках. Стоит отметить, что этот шаблон использования internal навязан самим компилятором Golang. Ознакомьтесь с release notes Go 1.4. Также, вы вольны использовать internal директорию на разных уровнях своего проекта.

```
├── app                        - Пакет приложения
│   ├── [app name].go          - Приложение
├── dto                        - Data Transfer Object
│   ├── [group]                - Группа DTO объектов
│   │   ├── [name].go          - Название файла, содержащий структуры для DTO объектов
├── errors                     - Пакет для обработки и создания ошибок приложения (желательно вынести в pkg)
├── initialize                 - Пакет для инициализации модулей (контроллеров, репозиториев, клиентов)
├── interface                  - Данная директория хранит адаптеры для взаимодействия с внешними сервисами
│   ├── client                 - Пакет клиента для взаимодействия с другими приложениями (REST, gRPC)
│   │   ├── [name].go          - Сам клиент
│   ├── controller             - Директория контроллеров
│   │   ├── [name]             - Директория контроллера
│   │   │   ├── mocks          - Директория, которая хранит сгенерированные моки для контроллера
│   │   │   ├── [name].go      - Сам контроллер. Хранит в себе обработчики внешних запросов
│   │   │   ├── [name]_test.go - Файл тестов для контроллера
│   ├── repository             - Директория репозиториев для взаимодействия с базой данных
│   │   ├── [name].go          - Файл репозитория (user.go)
├── models                     - Пакет моделей данных
│   ├── [name].go              - Файл структур, которые относятся к определённой модели (user.go)
├── proto                      - Директория, содержащая сгенерированные proto файлы
├── server                     - Пакет хранящий инициализации серверов (http/tcp/grpc)
│   ├── [name].go              - Файл инициализации сервера (http/tcp/grpc)
├── utils                      - Пакет внутренних функций/утилит приложения
│   ├── [name].go              - Утилита
│   ├── [name]_test.go         - Тесты утилиты
├── worker                     - Пакет, для запуска и инициализации воркеров
│   ├── [name]                 - Пакет воркера
│   │   ├── mocks              - Пакет, содержащий сегенированные моки для воркера
│   │   ├── [name].go          - Файл воркера
│   │   ├── [name]_test.go     - Файл тестов воркера
│   ├── run.go                 - Файл запуска воркеров
```

## Структура `/pkg`:

Код библиотек, пригодных для использования в сторонних приложениях. (например, `/pkg/mypubliclib`). Другие проекты будут импортировать эти библиотеки, ожидая их автономной работы, поэтому стоит подумать дважды, прежде чем класть сюда какой-нибудь код. Использование директории `internal` - более оптимальный способ не дать импортировать внутренние пакеты, потому что это обеспечит сам `Golang`. Директория `/pkg` - всё еще хороший путь дать понять, что код в этой директории могут безопасно использовать другие.

Код из директории `/pkg` желательно в будущем выносить в отдельный репозиторий общих пакетов.

```
├── utils                  - Пакет утилит, доступные разным приложениям
│   ├── [name].go          - Утилита
```

## Тесты:

В каждом пакете присутствует файл, хранящий выполняемый код, рядом с этим файлом должен находится файл тестов, которые будет содержать имя этого файла и постфикс `_test`.

```
│   controller             - Директория контроллеров
│   ├── [name]             - Пакет контроллера
│   │   ├── mocks          - Пакет сгенерированных моков для тестов контроллера
│   │   ├── [name].go      - Сам контроллер
│   │   ├── [name]_test.go - Файл тестов контроллера
├── utils                  - Пакет внутренних функций/утилит приложения
│   ├── [name].go          - Утилита
│   ├── [name]_test.go     - Файл тестов утилиты
```