Чистая архитектура на go

Создание масштабных и поддерживаемых приложений на Go требует не только глубокого понимания языка, но и продуманной архитектуры. Без четкой структуры даже самый производительный код быстро превращается в трудночитаемый лабиринт, где каждое изменение грозит новыми багами. Архитектурные принципы помогают отделить бизнес-логику от инфраструктуры, упрощают тестирование и обеспечивают долгосрочную жизнеспособность проекта.

Что такое чистая архитектура?

Чистая архитектура (Clean Architecture) была предложена Робертом Мартином (Uncle Bob) как универсальный способ построения программного обеспечения, независимо от используемых технологий. Основная идея — создание системы, в которой бизнес-правила изолированы от внешних факторов: баз данных, фреймворков, пользовательских интерфейсов и операционных систем.

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

Архитектура визуализируется как концентрические круги: наружные слои зависят от внутренних, но не наоборот. Внутренний круг содержит сущности (entities), следующий — бизнес-логику (use cases), затем — адаптеры (interface adapters), и, наконец, внешние слои — драйверы и фреймворки.

Слои чистой архитектуры в Go

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

• Entities — это бизнес-сущности, содержащие основные правила домена. Например, структура User с методами валидации или расчета прав доступа.
• Use Cases — описывают сценарии использования. Они координируют взаимодействие сущностей и определяют, какие данные нужны и как обрабатываются.
• Interface Adapters — адаптируют данные между внешним миром и внутренними слоями. Сюда входят хендлеры HTTP, сериализаторы, мапперы DTO.
• Frameworks and Drivers — внешние технологии: Gin или Echo для HTTP, GORM или pgx для БД, логгеры и т.д.

В Go эти слои можно организовать через пакеты (packages). Например:

1. /internal/domain — сущности и интерфейсы.
2. /internal/usecase — бизнес-логика.
3. /internal/delivery/http — HTTP-адаптеры.
4. /internal/repository — репозитории для работы с БД.
5. /cmd — точка входа, запуск сервера.

Такая структура делает проект понятным для новых разработчиков и позволяет заменять компоненты без переписывания всего кода.

Правило зависимостей и инверсия контролла

Ключевой принцип чистой архитектуры — правило зависимостей: код может зависеть только от того, что находится ближе к центру. То есть, внешние слои могут импортировать внутренние, но не наоборот.

В Go это реализуется через интерфейсы. Например, use case не должен напрямую использовать репозиторий PostgreSQL. Вместо этого он зависит от интерфейса, который реализуется во внешнем слое.

// internal/usecase/user_usecase.go
type UserRepository interface {
    Create(user *User) error
}

type UserUsecase struct {
    repo UserRepository
}

func (uc *UserUsecase) CreateUser(name string) error {
    user := &User{Name: name}
    return uc.repo.Create(user)
}

Реализация интерфейса остаётся во внешнем пакете:

// internal/repository/postgres_user_repo.go
type PostgresUserRepo struct {
    db *sql.DB
}

func (r *PostgresUserRepo) Create(user *User) error {
    // SQL-запрос
}

Инъекция зависимостей происходит при инициализации:

// cmd/main.go
repo := &PostgresUserRepo{db: dbConn}
uc := &UserUsecase{repo: repo}
handler := NewUserHandler(uc)

Практическая реализация в Go

Рассмотрим пример создания API для управления пользователями. Начнём с доменной модели.

Создадим сущность в internal/domain/user.go:

type User struct {
    ID   int
    Name string
    Role string
}

func (u *User) IsValid() bool {
    return u.Name != "" && u.Role != ""
}

Далее — интерфейс репозитория и use case:

// internal/domain/user_repository.go
type UserRepository interface {
    Save(*User) error
    FindByID(int) (*User, error)
}

// internal/usecase/user_usecase.go
type UserUsecase struct {
    repo domain.UserRepository
}

func (uc *UserUsecase) Register(name, role string) error {
    user := &domain.User{Name: name, Role: role}
    if !user.IsValid() {
        return errors.New("invalid user data")
    }
    return uc.repo.Save(user)
}

HTTP-адаптер в internal/delivery/http/user_handler.go:

type UserHandler struct {
    usecase *usecase.UserUsecase
}

func (h *UserHandler) HandleCreate(w http.ResponseWriter, r *http.Request) {
    var input struct {
        Name string `json:"name"`
        Role string `json:"role"`
    }
    json.NewDecoder(r.Body).Decode(&input)

    err := h.usecase.Register(input.Name, input.Role)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

В cmd/main.go происходит сборка:

func main() {
    db, _ := sql.Open("postgres", "...")
    repo := repository.NewPostgresUserRepo(db)
    uc := usecase.NewUserUsecase(repo)
    handler := delivery.NewUserHandler(uc)

    mux := http.NewServeMux()
    mux.HandleFunc("/users", handler.HandleCreate)
    http.ListenAndServe(":8080", mux)
}

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

Несмотря на простоту концепции, при внедрении чистой архитектуры в Go часто допускаются ошибки.

• Слишком много интерфейсов — создание интерфейсов «на всякий случай» усложняет код. Создавайте интерфейс только тогда, когда он реально используется в нескольких местах или нужен для тестирования.
• Нарушение правила зависимостей — импорт внешнего пакета (например, net/http) во внутреннем слое. Решение — выносить HTTP-специфичные типы в адаптеры.
• Жесткая связанность с ORM — использование моделей ORM напрямую в бизнес-логике. Лучше использовать DTO и маппинг между слоями.
• Игнорирование тестирования — если архитектура построена правильно, unit-тесты должны быть простыми. Используйте моки для интерфейсов репозиториев.

Пример плохого подхода:

func (uc *UserUsecase) CreateUser(w http.ResponseWriter, r *http.Request) { ... }

Хендлер должен обрабатывать HTTP, а use case — бизнес-логику. Разделение обязанностей — ключ к тестируемости.

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

Мы поговорили с Дмитрием Сидоровым, архитектором с 15-летним опытом, который внедрял чистую архитектуру в более чем 20 проектах на Go.

«В начале карьеры я считал, что чистая архитектура — это избыточно для маленьких сервисов. Но практика показала обратное: даже минимальный MVP с правильной структурой легче масштабировать. В одном из проектов мы начали с трёх эндпоинтов, а через год стало 150. Благодаря слоистости мы смогли добавить микросервисную архитектуру без полной переписки.»

Он отмечает, что главный вызов — дисциплина команды. «Go позволяет писать простой, но спагетти-подобный код. Архитектура не спасёт, если разработчики игнорируют правила. Поэтому важно иметь code review, линтеры и документацию по структуре проекта.»

Дмитрий рекомендует начинать с шаблонов: «Используйте готовые boilerplate-проекты, например, go-clean-template на GitHub. Это экономит время и задаёт правильные паттерны с первого дня.»

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

Заключение

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

Разделение на слои, строгое соблюдение правила зависимостей и использование интерфейсов делают код гибким и понятным. Даже начинающие разработчики могут быстро ориентироваться в проекте, а рефакторинг становится безопасным процессом.

• Строите архитектуру концентрическими кругами: сущности → use cases → адаптеры → фреймворки.
• Используйте интерфейсы для инверсии зависимостей и тестируемости.
• Не импортируйте внешние пакеты (например, net/http) во внутренних слоях.
• Тестируйте use case с моками, а не с реальной базой данных.
• Начинайте с простой структуры, но закладывайте основу для роста.