Понятия чистой архитектуры для GO

(04.12.2025 in LOG)

Главное! 
Все эти понятия самостоятельны и их нельзя обобщать. 

Dependency rule предлагает подход к решению вопросов separation of concerns, а three-layered architecture (при использовании DI) удачно реализует dependency rule в GO.

1. “Separation of concerns. They all (architectures of systems) achieve this separation by dividing the software into layers”. Разделение обязанностей достигаемое (архитектурами систем) путём деления программного обеспечения на слои. 

Это цель при создании программы.1️⃣ 

Each of these architectures produce systems that are (каждая из этих (перечисленных в статье) архитектур создаёт системы, которые):

1. Independent of Frameworks (независимы от фреймворков). 

2. Testable.

3. Independent of UI (независимы от пользовательского интерфейса)

4. Independent of Database.

5. Independent of any external agency. Независимы от каких-либо внешних факторов. Фактически, ваши бизнес-правила просто ничего не знают о внешнем мире.

2. Dependency Rule (правило зависимости, это о круговой диаграмме дяди Боба). 

Это правило помогает достичь цели из п.1️⃣, 

предлагая выделить определенные слои (на диаграмме) и соблюдать определенные подходы.

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

3. Dependency Injection (DI) это шаблон проектирования позволяющий реализовать в GO правило из п.2️⃣ 

4. Three-layered architecture (N-tier architecture) это популярный архитектурный подход к проектированию приложений, который обеспечивает четкое разделение обязанностей (separation of concerns1️⃣), масштабируемость и простоту поддержки. В GO этот подход широко использует DI3️⃣.

В контексте Go, эта архитектура обычно делится на три логических слоя:

1. Уровень обработчиков/представления (Handler/Presentation Layer)

Этот слой отвечает за взаимодействие с внешним миром и является точкой входа в приложение. 

“Обязанности”:

1. Прием входящих запросов (например, HTTP-запросов).

2. Парсинг и валидация входящих данных (JSON, параметры URL и т.д.).

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

4. Маршрутизация запросов к соответствующему сервису.

5. Подготовка и отправка ответа клиенту.

В Go: Обычно реализуется с помощью функций HTTP-обработчиков (handlers) из стандартной библиотеки net/http или сторонних фреймворков/маршрутизаторов.

2. Уровень сервисов/бизнес-логики (Service/Business Logic Layer)

Этот слой содержит основную бизнес-логику приложения и управляет потоком операций. 

“Обязанности”:

1. Реализация бизнес-правил и логики предметной области.

2. Оркестрация процессов и координация между различными компонентами.

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

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

В Go: Представляется в виде структур (structs) с методами, которые принимают интерфейсы репозиториев в качестве зависимостей (Dependency Injection) для обеспечения тестируемости и слабой связанности. 

3. Уровень доступа к данным/хранилища (Data Access/Repository Layer)

Этот слой отвечает исключительно за взаимодействие с источниками данных, такими как базы данных, файловые системы или внешние API. 

“Обязанности”:

1. Выполнение операций CRUD (Create, Read, Update, Delete).

2. Работа с SQL-запросами или ORM.

3. Абстрагирование бизнес-логики от деталей конкретной базы данных.

В Go: Обычно реализуется через интерфейсы репозиториев (Repository interfaces), а конкретные реализации этих интерфейсов отвечают за фактическое хранение или извлечение данных.

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

/go-service/

├── cmd/                  # Точки входа приложения (main функции)

├── internal/

│   ├── handler/      # Обработчики HTTP (презентационный слой)

│   ├── service/      # Бизнес-логика (слой сервисов)

│   └── repository/ # Доступ к данным (слой хранилища)

├── model/              # Общие структуры данных/модели предметной области

└── pkg/                   # Переиспользуемые утилиты (логирование, конфиг и т.д.)

Проблема с переносом строк в Windows/WSL

Если вы редактировали скрипт (участвующий в процедуре make) типа wait-for-postgres.sh в среде Windows, он может использовать окончания строк в стиле Windows (CRLF), которые вызывают проблемы в Linux-контейнерах (которые ожидают LF). Интерпретатор /bin/sh видит символ возврата каретки как часть имени команды, и в результате файл не может быть выполнен.
Решение: Преобразовать файл в формат LF.

Можно открыть файл в редакторе, например VS Code, и в правом нижнем углу выбрать формат окончания строк LF.

Git не сохраняет такое изменение, надо проводить изменение во всех экземплярах.

docker-compose

 В случае необходимости пересборки контейнеров (или если они больше не нужны), находясь в папке с файлом docker-compose даем команду:

docker-compose down

# Принудительно пересоберите образ
make build

# Запустите снова
make run

Ошибка типа '/var/lib/postgresql/data': Operation not permitted, при запуске контейнеров в docker-compose при использовании WSL

Это очень распространенная проблема при использовании Docker в Windows с WSL 2, особенно если файлы проекта находятся в смонтированном разделе Windows (/mnt/c/...), а не в файловой системе Linux WSL (~/...).

Если вы используете WSL 2 и ваши файлы находятся на разделе NTFS (например, в директории /mnt/c/Users/...), то стандартные команды Linux chmod и chown не могут изменить реальные права доступа для процессов внутри контейнера Docker из-за ограничений монтирования WSL/NTFS.

Решение- использование именованных томов Docker (рекомендуется)
Вместо того чтобы монтировать конкретную локальную папку на вашем хосте (./.database/postgres/data) внутрь контейнера, мы позволим Docker управлять хранилищем данных самостоятельно через "именованный том" (named volume). Docker Volumes хранятся в специальном управляемом Docker'ом месте, где проблем с правами доступа не возникает.
Это самый чистый и надежный способ для работы с базами данных в Docker.

В файле docker-compose.yml надо заменить 

volumes:

    - ./.database/postgres/data:/var/lib/postgresql/data

на

volumes:

    - pgdata:/var/lib/postgresql/data

и добавить в конец файла:

volumes:

  pgdata:

Как выполнить команду make в Visual Studio Code (Windows)

Правильнее установить Debian (к примеру) для WSL и уже там запускать make

Другой вариант- в Visual Studio Code необходимо установить расширение Makefile Tools и произвести настройки 

API clients, an alternative to Postman

Bruno Habr about Bruno (rus)

Disable redirection in GET requests from Bruno:

req.setMaxRedirects(0)

hoppscotch

GO отладка VSCode. Формат строки в launch.json

"version": "0.2.0",

    "configurations": [

        {

            "name": "Launch Package",

            "type": "go",

            "request": "launch",

            "mode": "auto",

            "program": "${workspaceFolder}/cmd", // указывает, что запускать

// (пакет main)

            "cwd": "${workspaceFolder}" // (current working directory)

// устанавливает рабочий каталог в корень проекта

        }

    ]

"version": "0.2.0",

    "configurations": [

        {

            "name": "My debug",

            "type": "go",

            "request": "launch",

            "mode": "debug",

            "program": "${workspaceFolder}/cmd/shortener"

        }

    ]

{

                "name": "Launch Package",

                "type": "go",

                "request": "launch",

                "mode": "debug",

                "program": "${fileDirname}", // Or specify the path to your main Go file

                "args": [

                    "-flag1",

                    "value1",

                    "--another-flag",

                    "another_value"

                ]

            }