Чистая архитектура golang

Чистая архитектура в Go — это не просто набор правил, а философия построения программного обеспечения, ориентированная на масштабируемость, тестируемость и долгосрочную поддержку. Она позволяет отделить бизнес-логику от технических деталей реализации, таких как базы данных, сетевые протоколы или внешние API. В экосистеме Go, где простота и производительность стоят во главе угла, применение принципов чистой архитектуры помогает избежать типичных ловушек: спагетти-кода, жёсткой связанности и труднотестируемых пакетов.

Что такое чистая архитектура и зачем она нужна в Go

Термин «чистая архитектура» популяризировал Роберт Мартин (Uncle Bob) как универсальную модель организации кода, при которой система делится на концентрические слои. Центральный слой содержит чистую бизнес-логику, не зависящую ни от баз данных, ни от фреймворков, ни от пользовательского интерфейса. Этот подход особенно актуален в Go, где язык поощряет минимализм, композицию и явные зависимости.
Представьте, что вы разрабатываете сервис управления заказами. Без чистой архитектуры легко допустить, чтобы логика расчёта скидок зависела от конкретной реализации PostgreSQL-репозитория. Это создаёт проблему: изменение способа хранения данных требует переписывания бизнес-правил. В чистой архитектуре такой сценарий невозможен — скидки рассчитываются в изоляции, а доступ к данным происходит через абстракции.
Go идеально подходит для реализации этой модели благодаря встроенной поддержке интерфейсов, отсутствию наследования и мощной системе пакетов. Вы можете определить интерфейс `OrderRepository` в доменном слое, а его реализацию — в инфраструктурном, не создавая циклических зависимостей. Это повышает гибкость: например, можно заменить PostgreSQL на MongoDB или добавить кэширование без изменения ядра логики.

Основные слои и их роли в Go

Классическая чистая архитектура включает четыре основных слоя: Entity, Use Case, Interface Adapters и Frameworks & Drivers. Каждый из них имеет строго определённую зону ответственности и направление зависимостей — всегда внутрь, от периферии к ядру.

Entity — ядро бизнес-логики

Этот слой содержит доменные объекты и правила, которые остаются актуальными независимо от контекста использования. В Go это обычно структуры и методы, описывающие поведение сущностей.
Например, структура `Order` может иметь метод `CalculateTotal()`, который применяет скидки, проверяет налоги и возвращает итоговую сумму. Этот метод не знает, откуда взялись данные, и не зависит от HTTP или базы данных.

Use Case — сценарии использования

На этом уровне реализуются конкретные операции над сущностями: «оформить заказ», «отменить бронирование», «начислить бонусы». Use Case координирует взаимодействие между доменными объектами и внешними репозиториями.
В Go use case часто реализуется как структура с внедрёнными интерфейсами:
«`go
type OrderService struct {
repo OrderRepository
}
func (s *OrderService) PlaceOrder(items []Item) (*Order, error) {
order := NewOrder(items)
if err := order.Validate(); err != nil {
return nil, err
}
return s.repo.Save(order)
}
«`
Обратите внимание: `OrderRepository` — это интерфейс, объявленный в том же пакете, что и use case, а не импортируемый извне. Это ключевой момент.

Interface Adapters — адаптеры для внешнего мира

Здесь находятся преобразователи данных: HTTP-хендлеры, сериализаторы, ORM-обёртки. Их задача — превратить входящие запросы (например, JSON из HTTP) в вызовы use case и вернуть результат в нужном формате.
Пример HTTP-адаптера:
«`go
func (h *OrderHandler) Create(w http.ResponseWriter, r *http.Request) {
var input CreateOrderRequest
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
http.Error(w, «Invalid JSON», http.StatusBadRequest)
return
}
order, err := h.service.PlaceOrder(input.Items)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(order)
}
«`

Frameworks & Drivers — внешние технологии

Самый внешний слой включает фреймворки (Gin, Echo), драйверы баз данных (pgx, mysql), очереди сообщений (NATS, Kafka). Они используются только для запуска приложения и передачи данных внутрь.

Как применять чистую архитектуру на практике

Реализация начинается с проектирования домена. Не спешите создавать HTTP-роуты или таблицы в БД. Сначала определите ключевые сущности и правила. Например, для интернет-магазина это могут быть `Product`, `Cart`, `Order`, `User`.
Далее — определите основные use case. Для каждого действия («добавить в корзину», «оформить заказ») создайте интерфейс и структуру-сервис. Важно: интерфейсы репозиториев должны объявляться в слое use case, а не в infrastructure.

Шаги внедрения

1. Создайте структуру папок: /internal/domain, /internal/usecase, /internal/adapters/http, /internal/infrastructure/db.
2. Определите доменные структуры: User, Product, Order — с методами, отражающими поведение.
3. Объявите интерфейсы репозиториев: например, UserRepository в пакете usecase.
4. Реализуйте use case: сервисы, использующие эти интерфейсы для выполнения операций.
5. Напишите адаптеры: HTTP-обработчики, которые вызывают use case и обрабатывают ошибки.
6. Соберите всё в main(): подключите зависимости, запустите сервер.

Пример композиции в main.go

«`go
func main() {
db, _ := sql.Open(«postgres», «…»)

userRepo := postgres.NewUserRepository(db)
userService := usecase.NewUserService(userRepo)

handler := http.NewUserHandler(userService)
http.HandleFunc(«/users», handler.Get)

log.Fatal(http.ListenAndServe(«:8080», nil))
}
«`
Здесь все зависимости собираются в одной точке. Это делает поток данных очевидным и упрощает тестирование — в тестах вы можете подставить мок-репозиторий.

Типичные ошибки и как их избежать

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

Ошибка 1: Интерфейсы в инфраструктуре

Когда интерфейс `UserRepository` объявляется в `/internal/infrastructure/postgres`, а use case зависит от него, возникает обратная зависимость. Это блокирует замену реализации.
Решение: Перенесите интерфейс в слой use case. Пусть инфраструктура реализует его, а не наоборот.

Ошибка 2: Глобальные переменные и синглтоны

Использование глобальных подключений к БД или HTTP-клиентов затрудняет тестирование и создаёт скрытые зависимости.
Решение: Передавайте зависимости явно через конструкторы. Это делает код предсказуемым.

Ошибка 3: Слишком много слоёв ради слоёв

Не каждому проекту нужны все слои чистой архитектуры. Микросервис с парой эндпоинтов можно организовать проще.
Решение: Начинайте с минимальной структуры. Добавляйте слои по мере роста сложности. Принцип YAGNI (You Aren’t Gonna Need It) работает и здесь.

Ошибка 4: Жёсткая привязка к фреймворкам

Когда хендлеры Gin или Echo содержат бизнес-логику, становится невозможно переиспользовать код вне HTTP-контекста.
Решение: Хендлер должен лишь парсить входные данные, вызывать use case и формировать ответ. Всё остальное — за его пределами.

Экспертное мнение

Чистая архитектура эффективна, когда команда понимает её цель — защита бизнес-логики от изменений внешнего мира. В Go это достигается не через абстракции ради абстракций, а через дисциплину: каждый пакет должен иметь одну причину для изменения.
Ключевой индикатор зрелости архитектуры — скорость внесения изменений. Если вы можете добавить новый способ аутентификации (например, OAuth) за час, не трогая домен, значит, вы на правильном пути. Тесты на уровне use case должны выполняться без запуска базы данных — это гарантирует, что они проверяют именно логику, а не инфраструктуру.
Инструменты вроде Wire или Digger могут помочь при управлении зависимостями в крупных проектах, но для большинства случаев достаточно ручного DI в функции main(). Автоматизация не должна стоить сложности понимания.
Главное — не стремитесь к идеальной архитектуре с первого дня. Развивайте её итеративно. Сегодня вы можете обойтись двумя слоями: domain и handlers. Завтра добавите use case, когда почувствуете необходимость в переиспользовании логики.

Вопросы и ответы

type MockUserRepo struct {
 users map[string]*User
}
func (m *MockUserRepo) FindByID(id string) (*User, error) {
 u, ok := m.users[id]
 if !ok {
 return nil, ErrNotFound
 }
 return u, nil
}

Заключение

Чистая архитектура в Go — это не догма, а инструмент для создания поддерживаемых, тестируемых и гибких систем. Она особенно эффективна в условиях, когда требования меняются, а команда растёт. Ключевой принцип — направление зависимостей: от периферии к ядру, а не наоборот.

• Бизнес-логика должна быть независимой от баз данных и фреймворков.
• Интерфейсы репозиториев объявляются в use case, а реализуются в инфраструктуре.
• Тесты уровня use case не должны требовать запуска внешних сервисов.
• Архитектура развивается итеративно — не перегружайте простые проекты.
• Go позволяет реализовать чистую архитектуру без сложных инструментов — достаточно пакетов и интерфейсов.