From 553095d5ba6f25bbfcdc0e26bde6ed00131fc4ed Mon Sep 17 00:00:00 2001
From: anatolypaw <anatolypaw@gmail.com>
Date: Sun, 11 Aug 2024 22:13:51 +0600
Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?=
 =?UTF-8?q?=D0=BD=20=D0=BF=D0=B5=D1=80=D0=B5=D0=B2=D0=BE=D0=B4=20=D0=BD?=
 =?UTF-8?q?=D0=B0=20=D1=80=D1=83=D1=81=D1=81=D0=BA=D0=BE=D0=BC=20=D1=8F?=
 =?UTF-8?q?=D0=B7=D1=8B=D0=BA=D0=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md    |  50 +++++++-
 README_RU.md | 325 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 370 insertions(+), 5 deletions(-)
 create mode 100644 README_RU.md

diff --git a/README.md b/README.md
index 56a55fc7..082b977b 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 ![Go Clean Template](docs/img/logo.svg)
 
 # Go Clean template
-[🇨🇳中文](README_CN.md)
+
+[🇨🇳 中文](README_CN.md)
+[🇷🇺 RU](README_RU.md)
 
 Clean Architecture template for Golang services
 
@@ -11,7 +13,9 @@ Clean Architecture template for Golang services
 [![codecov](https://codecov.io/gh/evrone/go-clean-template/branch/master/graph/badge.svg?token=XE3E0X3EVQ)](https://codecov.io/gh/evrone/go-clean-template)
 
 ## Overview
+
 The purpose of the template is to show:
+
 - how to organize a project and prevent it from turning into spaghetti code
 - where to store business logic so that it remains independent, clean, and extensible
 - how not to lose control when a microservice grows
@@ -21,13 +25,16 @@ Using the principles of Robert Martin (aka Uncle Bob).
 [Go-clean-template](https://evrone.com/go-clean-template?utm_source=github&utm_campaign=go-clean-template) is created & supported by [Evrone](https://evrone.com/?utm_source=github&utm_campaign=go-clean-template).
 
 ## Content
+
 - [Quick start](#quick-start)
 - [Project structure](#project-structure)
 - [Dependency Injection](#dependency-injection)
 - [Clean Architecture](#clean-architecture)
 
 ## Quick start
+
 Local development:
+
 ```sh
 # Postgres, RabbitMQ
 $ make compose-up
@@ -36,17 +43,21 @@ $ make run
 ```
 
 Integration tests (can be run in CI):
+
 ```sh
 # DB, app + migrations, integration tests
 $ make compose-up-integration-test
 ```
 
 ## Project structure
+
 ### `cmd/app/main.go`
+
 Configuration and logger initialization. Then the main function "continues" in
 `internal/app/app.go`.
 
 ### `config`
+
 Configuration. First, `config.yml` is read, then environment variables overwrite the yaml config if they match.
 The config structure is in the `config.go`.
 The `env-required: true` tag obliges you to specify a value (either in yaml, or in environment variables).
@@ -59,15 +70,18 @@ reading the entire config from ENV.
 It is assumed that default values are in yaml, and security-sensitive variables are defined in ENV.
 
 ### `docs`
+
 Swagger documentation. Auto-generated by [swag](https://github.com/swaggo/swag) library.
 You don't need to correct anything by yourself.
 
 ### `integration-test`
+
 Integration tests.
 They are launched as a separate container, next to the application container.
 It is convenient to test the Rest API using [go-hit](https://github.com/Eun/go-hit).
 
 ### `internal/app`
+
 There is always one _Run_ function in the `app.go` file, which "continues" the _main_ function.
 
 This is where all the main objects are created.
@@ -89,19 +103,24 @@ $ go run -tags migrate ./cmd/app
 ```
 
 ### `internal/controller`
+
 Server handler layer (MVC controllers). The template shows 2 servers:
+
 - RPC (RabbitMQ as transport)
 - REST http (Gin framework)
 
 Server routers are written in the same style:
+
 - Handlers are grouped by area of application (by a common basis)
 - For each group, its own router structure is created, the methods of which process paths
 - The structure of the business logic is injected into the router structure, which will be called by the handlers
 
 #### `internal/controller/http`
+
 Simple REST versioning.
 For v2, we will need to add the `http/v2` folder with the same content.
 And in the file `internal/app` add the line:
+
 ```go
 handler := gin.New()
 v1.NewRouter(handler, t)
@@ -113,11 +132,14 @@ Instead of Gin, you can use any other http framework or even the standard `net/h
 In `v1/router.go` and above the handler methods, there are comments for generating swagger documentation using [swag](https://github.com/swaggo/swag).
 
 ### `internal/entity`
+
 Entities of business logic (models) can be used in any layer.
 There can also be methods, for example, for validation.
 
 ### `internal/usecase`
+
 Business logic.
+
 - Methods are grouped by area of application (on a common basis)
 - Each group has its own structure
 - One file - one structure
@@ -126,20 +148,25 @@ Repositories, webapi, rpc, and other business logic structures are injected into
 (see [Dependency Injection](#dependency-injection)).
 
 #### `internal/usecase/repo`
+
 A repository is an abstract storage (database) that business logic works with.
 
 #### `internal/usecase/webapi`
+
 It is an abstract web API that business logic works with.
 For example, it could be another microservice that business logic accesses via the REST API.
 The package name changes depending on the purpose.
 
 ### `pkg/rabbitmq`
+
 RabbitMQ RPC pattern:
+
 - There is no routing inside RabbitMQ
 - Exchange fanout is used, to which 1 exclusive queue is bound, this is the most productive config
 - Reconnect on the loss of connection
 
 ## Dependency Injection
+
 In order to remove the dependence of business logic on external packages, dependency injection is used.
 
 For example, through the New constructor, we inject the dependency into the structure of the business logic.
@@ -178,23 +205,28 @@ It will also allow us to do auto-generation of mocks (for example with [mockery]
 > If the new component implements the interface, nothing needs to be changed in the business logic.
 
 ## Clean Architecture
+
 ### Key idea
+
 Programmers realize the optimal architecture for an application after most of the code has been written.
 
 > A good architecture allows decisions to be delayed to as late as possible.
 
 ### The main principle
-Dependency Inversion (the same one from SOLID) is the principle of dependency inversion.
+
+Dependency Inversion (the same one from SOLID) is the principle of dependency injection.
 The direction of dependencies goes from the outer layer to the inner layer.
 Due to this, business logic and entities remain independent from other parts of the system.
 
 So, the application is divided into 2 layers, internal and external:
+
 1. **Business logic** (Go standard library).
 2. **Tools** (databases, servers, message brokers, any other packages and frameworks).
 
 ![Clean Architecture](docs/img/layers-1.png)
 
 **The inner layer** with business logic should be clean. It should:
+
 - Not have package imports from the outer layer.
 - Use only the capabilities of the standard library.
 - Make calls to the outer layer through the interface (!).
@@ -203,6 +235,7 @@ The business logic doesn't know anything about Postgres or a specific web API.
 Business logic has an interface for working with an _abstract_ database or _abstract_ web API.
 
 **The outer layer** has other limitations:
+
 - All components of this layer are unaware of each other's existence. How to call another from one tool? Not directly, only through the inner layer of business logic.
 - All calls to the inner layer are made through the interface (!).
 - Data is transferred in a format that is convenient for business logic (`internal/entity`).
@@ -217,12 +250,14 @@ The communication between them is carried out through `usecase` (business logic)
            usecase < repository (Postgres)
     HTTP < usecase
 ```
+
 The symbols > and < show the intersection of layer boundaries through Interfaces.
 The same is shown in the picture:
 
 ![Example](docs/img/example-http-db.png)
 
 Or more complex business logic:
+
 ```
     HTTP > usecase
            usecase > repository
@@ -237,13 +272,14 @@ Or more complex business logic:
 ```
 
 ### Layers
+
 ![Example](docs/img/layers-2.png)
 
 ### Clean Architecture Terminology
+
 - **Entities** are structures that business logic operates on.
   They are located in the `internal/entity` folder.
   In MVC terms, entities are models.
-  
 - **Use Cases** is business logic located in `internal/usecase`.
 
 The layer with which business logic directly interacts is usually called the _infrastructure_ layer.
@@ -251,6 +287,7 @@ These can be repositories `internal/usecase/repo`, external webapi `internal/use
 In the template, the _infrastructure_ packages are located inside `internal/usecase`.
 
 You can choose how to call the entry points as you wish. The options are:
+
 - controller (in our case)
 - delivery
 - transport
@@ -260,6 +297,7 @@ You can choose how to call the entry points as you wish. The options are:
 - input
 
 ### Additional layers
+
 The classic version of [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) was designed for building large monolithic applications and has 4 layers.
 
 In the original version, the outer layer is divided into two more, which also have an inversion of dependencies
@@ -267,21 +305,23 @@ to each other (directed inward) and communicate through interfaces.
 
 The inner layer is also divided into two (with separation of interfaces), in the case of complex logic.
 
-_______________________________
+---
 
 Complex tools can be divided into additional layers.
 However, you should add layers only if really necessary.
 
 ### Alternative approaches
+
 In addition to Clean architecture, _Onion architecture_ and _Hexagonal_ (_Ports and adapters_) are similar to it.
 Both are based on the principle of Dependency Inversion.
 _Ports and adapters_ are very close to _Clean Architecture_, the differences are mainly in terminology.
 
-
 ## Similar projects
+
 - [https://github.com/bxcodec/go-clean-arch](https://github.com/bxcodec/go-clean-arch)
 - [https://github.com/zhashkevych/courses-backend](https://github.com/zhashkevych/courses-backend)
 
 ## Useful links
+
 - [The Clean Architecture article](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
 - [Twelve factors](https://12factor.net/ru/)
diff --git a/README_RU.md b/README_RU.md
new file mode 100644
index 00000000..139d4164
--- /dev/null
+++ b/README_RU.md
@@ -0,0 +1,325 @@
+![Go Clean Template](docs/img/logo.svg)
+
+# Go Чистая Архитектура
+
+Шаблон Чистой Архитектурой для приложений на Golang
+
+[![Go Report Card](https://goreportcard.com/badge/github.com/evrone/go-clean-template)](https://goreportcard.com/report/github.com/evrone/go-clean-template)
+[![License](https://img.shields.io/github/license/evrone/go-clean-template.svg)](https://github.com/evrone/go-clean-template/blob/master/LICENSE)
+[![Release](https://img.shields.io/github/v/release/evrone/go-clean-template.svg)](https://github.com/evrone/go-clean-template/releases/)
+[![codecov](https://codecov.io/gh/evrone/go-clean-template/branch/master/graph/badge.svg?token=XE3E0X3EVQ)](https://codecov.io/gh/evrone/go-clean-template)
+
+## Обзор
+
+Цель этого шаблона - показать принципы Чистой Архитектуры Роберта Мартина (дядюшки Боба):
+
+- как структурировать проект и не дать ему превратиться в спагетти-код
+- где хранить бизнес-логику, что бы она оставалась независимой, чистой и расширяемой
+- как не потерять контроль при росте проекта
+
+[Go-clean-template](https://evrone.com/go-clean-template?utm_source=github&utm_campaign=go-clean-template) создан и поддерживается [Evrone](https://evrone.com/?utm_source=github&utm_campaign=go-clean-template).
+
+## Содержание
+
+- [Быстрый старт](#быстрый-старт)
+- [Структура проекта](#структура-проекта)
+- [Внедрение зависимостей](#внедрение-зависимостей)
+- [Чистая Архитектура](#чистая-архитектура)
+
+## Быстрый старт
+
+Локальная разработка:
+
+```sh
+# Postgres, RabbitMQ
+$ make compose-up
+# Запуск приложения и миграций
+$ make run
+```
+
+Интеграционные тесты (может быть использовано с CI):
+
+```sh
+# DB, app + migrations, integration tests
+$ make compose-up-integration-test
+```
+
+## Структура проекта
+
+### `cmd/app/main.go`
+
+Инициализация конфигурации и логгера. Здесь вызывается основаная часть приложения из `internal/app/app.go`.
+
+### `config`
+
+Конфигурация. Сначала читается `config.yml`, а затем переменные окружения.
+Переменные окружения имеют больший приоритет, чем конфигурация из yaml файла
+и при совпадении ключа, значение берется из переменных окружения.
+Структура конфигурации объявлена в файле `config.go`.
+Тег `env-required: true` указывает, что значение обязательно. (либо в yaml, либо в переменных среды).
+
+Для конфигурации мы используем библиотеку [cleanenv](https://github.com/ilyakaznacheev/cleanenv).
+Она простая и соответствует всем нашим требования.
+
+Чтение конфигурации из yaml файла противоречит идеологии `Twelve-Factor App`, но на практике это более удобно,
+чем получение значений из ENV.
+Предполагается, что в yaml указываются значения по умолчанию, а переменные, чувствительные к безопасности
+задаются в переменных ENV.
+
+### `docs`
+
+Документация Swagger. Генерируется автоматически с помощью библиотеки [swag](https://github.com/swaggo/swag).
+Вам не нужно ничего редактировать вручную.
+
+### `integration-test`
+
+Интеграционные тесты.
+Они запускаются в отдельном контейнере, рядом с контейнером приложения.
+Rest API удобно тестировать с помощью [go-hit](https://github.com/Eun/go-hit).
+
+### `internal/app`
+
+Здесь находится только одна _Run_ функция. Она размещена в файле `app.go` и является логическим продолжением функции _main_.
+
+Здесь создаются все основные объекты.
+[Внедрение Зависимостей](#внедрение-зависимостей) происходит через конструктор "New ...".
+Эта позволяет слоировать приложение, делая бизнес-логику независимой от других слоев.
+
+Далее, запускается сервер и ожидается сигнал в _select_ для корректного завершения работы.
+Если `app.go` стал слишком большим, вы можете разделить его на несколько файлов.
+
+Если зависимостей много, то для удобства можно использовать [wire](https://github.com/google/wire).
+
+Файл `migrate.go` испольузется для автоматической миграции базы данных.
+Он включается в компиляцию только при указании тега _migrate_.
+Пример:
+
+```sh
+$ go run -tags migrate ./cmd/app
+```
+
+### `internal/controller`
+
+Слой хэндлеров сервера (MVC контроллеры). В шаблоне показана работа 2х серверов:
+
+- RPC (RabbitMQ as transport)
+- REST http (Gin framework)
+
+Маршрутизаторы http сервера пишутся в едином стиле:
+
+- Хэндлеры сгруппируются по области применения (по общему критерию)
+- Для каждый группы создается свой маршрутизатор
+- Объект бизнес-логики передается в маршрутизатор, что бы быть доступным внутри хэндлеров
+
+#### `internal/controller/http/v1`
+
+Папка, как простой способ версионировать REST API.
+Для создания версии v2, нужно создать папку `http/v2` с таким же содержимым.
+Добавить в файл `internal/app/app.go` строки:
+
+```go
+handler := gin.New()
+v1.NewRouter(handler, t)
+v2.NewRouter(handler, t)
+```
+
+Вместо Gin можно использовать любой другой http фреймворк или стандартную `net/http` библиотеку.
+
+В файле `v1/router.go` над хэндлером написаны комментарии для генерации документации через swagger [swag](https://github.com/swaggo/swag).
+
+### `internal/entity`
+
+Сущности бизнес-логики (модели). Могут быть использованы в любом слое.
+Также они могуть иметь методы, например, для валидации.
+
+### `internal/usecase`
+
+Бизнес-логика.
+
+- Методы сгруппированы по области применения (по общему критерию)
+- У каждой группы своя отдельная структура
+- Один файл - одна структура
+
+Репозитории, webapi, rpc и другие структуры передаются в слой бизнес-логики в связующем файле `internal/app/app.go`
+(смотрите [Внедрение Зависимостей](#внедрение-зависимостей)).
+
+#### `internal/usecase/repo`
+
+Репозиторий — это абстрактное хранилище (база данных), с которым взаимодействует бизнес-логика.
+
+#### `internal/usecase/webapi`
+
+Это абстрактное web API, с которым взаимодействует бизнес-логика.
+Например, это может быть внешний микросервис, к которому бизнес-логика обращается через REST API.
+Название пакета выбирается таким, что бы соответствовать его назначению.
+
+### `pkg/rabbitmq`
+
+RabbitMQ RPC паттерн:
+
+- Внутри RabbitMQ не используется маршрутизация
+- Используется fanout-обмен, к которому привязана одна эксклюзивная очередь - это наиболее производительная конфигурация
+- Переподключение при потере соединения
+
+## Внедрение Зависимостей
+
+Для устранения зависимости бизнес-логики от внешних пакетов используется внедрение зависимостей.
+
+Например, через конструктор "New" внедряется репозиторий в слой бизнес-логики.
+Это делает бизнес-логику независимой и переносимой.
+Мы можем переписать реализацию интерфейса репозитория не внося изменения в пакет бизнес-логики `usecase`.
+
+```go
+package usecase
+
+import (
+    // Nothing!
+)
+
+type Repository interface {
+    Get()
+}
+
+type UseCase struct {
+    repo Repository
+}
+
+func New(r Repository) *UseCase{
+    return &UseCase{
+        repo: r,
+    }
+}
+
+func (uc *UseCase) Do()  {
+    uc.repo.Get()
+}
+```
+
+Благодаря разделению через интерфейсы можно генерировать моки (например, используя [mockery](https://github.com/vektra/mockery)) и легко писать юнит-тесты.
+
+> Мы не привязаны к конкретным реализациям и всегда можем заменить один компонент на другой.
+> Если новый компонент реализует интерфейс, то в бизнес-логике ничего не нужно менять.
+
+## Чистая Архитектура
+
+### Ключевая идея
+
+Программисты создают оптимальную архитектуру приложения после написания основной части кода.
+
+> Хорошая архитектура позволяет отклыдывать изменение как можно дольше.
+
+### Основной принцип
+
+Инверсия зависимостей (та же, что и в SOLID) используется как принцип для внедрения зависимостей.
+Зависимости направлены от внешнего слоя к внутреннему.
+Благодаря этому бизнес-логика и сущности остаются независимыми от других частей системы.
+
+Например, приложение можно разделить на два слоя - внутренний и внешний:
+
+1. **Бизнес-логика** (например, стандартная библиотека Go).
+2. **Инструменты** (базы данных, сервера, брокеры сообщений и другие библиотеки и фреймворки).
+
+![Чистая архитектура](docs/img/layers-1.png)
+
+**Внутренний слой** с бизнес-логикой должен быть чистым. Он обязан:
+
+- Не импортировать пакеты с внешних слоев.
+- Использовать только стандартную библиотеку.
+- Взаимодействовать с внешними слоями через интерфейсы (!).
+
+Бизнес-логика не должна ничего знать о Postgres или о реализации web API.
+Бизнес-логика имеет интерфейс для взаимодейсвтия с _абстрактной_ базой данных или _абстрактным_ web API.
+
+**Внешний слой** имеет ограничения:
+
+- Компоненты этого слоя не могут знать друг о друге и взаимодействать напрямую. Обращение друг к другу происходит через внутренний слой - слой бизнес-логики.
+- Вызовы во внутренний слой выполняются через интерфейсы (!).
+- Данные передаются в формате, удобном для бизнес-логики (структуры хранятся в `internal/entity`).
+
+Например, нужно обратиться к базе данных из HTTP хэндера (в слое контроллер).
+База данных и HTTP находятся во внешнем слое. Они не знаю друг о друге ничего и не могут взаимодействовать напрямую.
+Взаимодействие будет происходить через слой бизнес-логики `usecase`:
+
+```
+    HTTP > usecase
+           usecase > repository (Postgres)
+           usecase < repository (Postgres)
+    HTTP < usecase
+```
+
+Символы > и < показывают пересечения слоев через интерфейсы и направления.
+Это же показано на схеме:
+
+![Пример](docs/img/example-http-db.png)
+
+Пример более сложного пути данных:
+
+```
+    HTTP > usecase
+           usecase > repository
+           usecase < repository
+           usecase > webapi
+           usecase < webapi
+           usecase > RPC
+           usecase < RPC
+           usecase > repository
+           usecase < repository
+    HTTP < usecase
+```
+
+### Слои
+
+![Пример](docs/img/layers-2.png)
+
+### Терминология в Чистой Архитектуре
+
+- **Entities** (сущности) - это структуры, с которыми работает бизнес логика.
+  Они располагаются в папке `internal/entity`.
+  В терминологии MVC сущности - это модели.
+- **Use Cases** это бизнес-логика. Располагается в папке `internal/usecase`.
+
+Слой, с которым бизнес-логика взаимодействует напрямую, обычно, называется _инфраструктурным_ слоем.
+Это может быть репозиторий `internal/usecase/repo`, внешнее webapi `internal/usecase/webapi`, любой пакет или микросервис.
+В шаблоне пакеты _infrastructure_ размещены внутри `internal/usecase`.
+
+Вы можете выбирать, как называть точки входа, по своему усмотрению. Варианты такие:
+
+- controller (в нашем случае)
+- delivery
+- transport
+- gateways
+- entrypoints
+- primary
+- input
+
+### Дополнительные слои
+
+В классической версии [Чистой Архитектуры](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) для создания больших монолитных приложений предложено 4 слоя.
+
+В исходной версии внешний слой делится на два, которые также имеют инверсию зависимостей в другие слои и взаимодействуют через интерфесы.
+
+Внутренний слой также делится на два (с использованием интерфейсов) в случае сложной логики.
+
+---
+
+Сложные инструменты могут быть разделены на дополнительные слои.
+Однако добавлять слои следует только в том случае, если это действительно необходимо.
+
+### Другие подходы
+
+Кроме Чистой Архитектуры есть и другие подоходы:
+
+- Луковая Архитектура
+- Гексогональная (_Порты и адаптеры_ также на неё похожа)
+  Они обе основаны на на принципе инверсии зависимостей.
+  _Порты и адаптеры_ очень похожи на _Чистую Архитектуру_. Различия в основном заключаются в терминологии.
+
+## Похожие проекты
+
+- [https://github.com/bxcodec/go-clean-arch](https://github.com/bxcodec/go-clean-arch)
+- [https://github.com/zhashkevych/courses-backend](https://github.com/zhashkevych/courses-backend)
+
+## Дополнительная информация
+
+- [The Clean Architecture article](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
+- [Twelve factors](https://12factor.net/ru/)