Структура проекта и зависимости

Структура проекта влияет на скорость. Если ты каждый раз ищешь, где лежит логика - ты теряешь время и мотивацию.

Принцип

Логика должна быть ближе к домену, а инфраструктура - по краям.

Это основа слоистой архитектуры: бизнес-правила в центре, детали реализации (HTTP, база, кэш) - на периферии. Центр не знает о краях. Архитектурное обоснование этого правила - DIP (Dependency Inversion Principle), а граница между слоями обычно реализуется паттерном Adapter.

Типичная структура проекта

Раскладка по каталогам зависит от языка, но идея одна: точки входа отдельно, домен в центре, инфраструктура по краям.

Официального «стандарта» структуры в Go нет. Есть официальное руководство go.dev/doc/modules/layout: точки входа в cmd/, приватный код в internal/. Популярный шаблон golang-standards/project-layout - неофициальный, команда Go прямо говорила, что это не стандарт. Каталог pkg/ в нём необязателен и часто лишний. Вот типичная структура, которая выросла из этих конвенций:

myapp/
├── cmd/                    # точки входа (main.go)
│   └── server/
│       └── main.go
├── internal/               # приватный код (не импортируется извне)
│   ├── domain/             # сущности, бизнес-правила
│   │   ├── user.go
│   │   └── order.go
│   ├── usecase/            # сценарии (application layer)
│   │   ├── register.go
│   │   └── place_order.go
│   └── adapter/            # инфраструктура
│       ├── http/           # хендлеры, роутер
│       ├── postgres/       # реализации репозиториев
│       └── email/          # отправка писем
├── pkg/                    # публичные библиотеки (опционально)
├── migrations/             # SQL-миграции
├── go.mod
└── go.sum

В Symfony-проектах сложилась похожая, но своя структура. PSR-4 диктует namespace=директория, поэтому имена кричат о слоях:

myapp/
├── bin/                       # CLI-точки входа (console, worker)
│   └── console
├── public/                    # web-точка входа (index.php)
│   └── index.php
├── src/                       # приложение (namespace App\)
│   ├── Domain/                # сущности, value objects, доменные сервисы
│   │   ├── User/
│   │   │   ├── User.php
│   │   │   └── UserRepositoryInterface.php
│   │   └── Order/
│   ├── Application/           # use cases / command handlers
│   │   ├── Register/
│   │   │   ├── RegisterUserCommand.php
│   │   │   └── RegisterUserHandler.php
│   │   └── PlaceOrder/
│   └── Infrastructure/        # инфраструктурные адаптеры
│       ├── Http/              # контроллеры, requests
│       ├── Persistence/       # Doctrine репозитории, миграции
│       └── Notification/      # email, sms
├── config/                    # YAML-конфиги (services, packages)
├── migrations/                # Doctrine migrations
├── tests/                     # PHPUnit
├── var/                       # cache, logs (gitignore)
└── composer.json

Жёсткого стандарта нет и здесь. Распространённый вариант - «src-раскладка», где код приложения лежит пакетом внутри src/:

myapp/
├── src/
│   └── myapp/
│       ├── __main__.py         # точка входа (python -m myapp)
│       ├── domain/             # сущности, бизнес-правила, Protocol-интерфейсы
│       │   ├── user.py
│       │   └── order.py
│       ├── usecase/            # сценарии (application layer)
│       │   ├── register.py
│       │   └── place_order.py
│       └── adapter/            # инфраструктура
│           ├── http/           # роуты FastAPI/Flask
│           ├── postgres/       # реализации репозиториев
│           └── email/
├── migrations/                 # Alembic
├── tests/                      # pytest
└── pyproject.toml

Аналога internal/ у Python нет: «приватность» модуля обозначают ведущим подчёркиванием (_utils.py), и это соглашение, а не проверка интерпретатора.

Что где живёт

На примере Go-раскладки; в Symfony те же роли у Domain/, Application/ и Infrastructure/, в Python - у domain/, usecase/ и adapter/.

Директория     Что внутри                    Зависит от
─────────────  ───────────────────────────   ─────────────
cmd/           main, wire, конфигурация      internal/*
internal/domain   сущности, интерфейсы       ничего
internal/usecase  бизнес-сценарии            domain
internal/adapter  http, db, cache, email     domain + usecase

ℹ️ internal/ - защита на уровне компилятора

Пакеты из internal/ может импортировать только код из каталога, в котором лежит этот internal/, и его подкаталогов. Для internal/ в корне модуля это значит: извне модуля импорт невозможен, сборка упадёт. Это не конвенция - это гарантия компилятора. Всё, что не должно быть публичным API, кладётся в internal/.

Слоистая архитектура: направление зависимостей

Ключевое правило: зависимости направлены внутрь - от инфраструктуры к домену, но не наоборот.

┌─────────────────────────────────┐
│  adapter (http, db, cache)      │  ← знает о usecase и domain
│  ┌───────────────────────────┐  │
│  │  usecase (бизнес-сценарии) │  │  ← знает о domain
│  │  ┌─────────────────────┐  │  │
│  │  │  domain (сущности)   │  │  │  ← не знает ни о ком
│  │  └─────────────────────┘  │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘
// domain/ - определяет интерфейс и свои ошибки, НЕ знает про PostgreSQL
var ErrUserNotFound = errors.New("user not found")

type UserRepository interface {
    GetByID(ctx context.Context, id int) (*User, error)
    Create(ctx context.Context, user *User) error
}

// adapter/postgres/ - реализует интерфейс
type PostgresUserRepo struct {
    db *gorm.DB
}

func (r *PostgresUserRepo) GetByID(ctx context.Context, id int) (*domain.User, error) {
    var user domain.User
    err := r.db.WithContext(ctx).First(&user, id).Error
    if errors.Is(err, gorm.ErrRecordNotFound) {
        // ошибку gorm переводим в доменную: use case не должен импортировать gorm
        return nil, domain.ErrUserNotFound
    }
    if err != nil {
        return nil, fmt.Errorf("get user %d: %w", id, err)
    }
    return &user, nil
}

// usecase/ - зависит от интерфейса, не от реализации
type RegisterUC struct {
    userRepo domain.UserRepository  // интерфейс, не *PostgresUserRepo
}
<?php
declare(strict_types=1);

// src/Domain/User/UserRepositoryInterface.php - интерфейс, НЕ знает про Doctrine
namespace App\Domain\User;

interface UserRepositoryInterface
{
    public function findById(int $id): ?User;

    public function save(User $user): void;
}

// src/Infrastructure/Persistence/DoctrineUserRepository.php - реализует интерфейс
namespace App\Infrastructure\Persistence;

use App\Domain\User\User;
use App\Domain\User\UserRepositoryInterface;
use Doctrine\ORM\EntityManagerInterface;

final readonly class DoctrineUserRepository implements UserRepositoryInterface
{
    public function __construct(private EntityManagerInterface $em) {}

    public function findById(int $id): ?User
    {
        return $this->em->find(User::class, $id);
    }

    public function save(User $user): void
    {
        $this->em->persist($user);
        $this->em->flush();
    }
}

// src/Application/Register/RegisterUserHandler.php - зависит от интерфейса
namespace App\Application\Register;

use App\Domain\User\UserRepositoryInterface;

final readonly class RegisterUserHandler
{
    public function __construct(
        private UserRepositoryInterface $userRepo, // интерфейс, не DoctrineUserRepository
    ) {}
}

В Symfony привязка интерфейса к реализации - в config/services.yaml:

services:
    App\Domain\User\UserRepositoryInterface:
        alias: App\Infrastructure\Persistence\DoctrineUserRepository
# domain/repository.py - определяет интерфейс (Protocol), НЕ знает про PostgreSQL
from dataclasses import dataclass
from typing import Protocol


class UserRepository(Protocol):
    def get_by_id(self, user_id: int) -> User: ...
    def create(self, user: User) -> None: ...


# adapter/postgres/user_repo.py - реализует интерфейс.
# Наследовать Protocol не нужно: достаточно совпадения методов (как в Go)
import psycopg


class PostgresUserRepo:
    def __init__(self, conn: psycopg.Connection) -> None:
        self._conn = conn

    def get_by_id(self, user_id: int) -> User:
        row = self._conn.execute(
            "SELECT id, email FROM users WHERE id = %s", (user_id,)
        ).fetchone()
        if row is None:
            raise UserNotFoundError(user_id)
        return User(*row)

    def create(self, user: User) -> None:
        self._conn.execute(
            "INSERT INTO users (id, email) VALUES (%s, %s)", (user.id, user.email)
        )


# usecase/register.py - зависит от интерфейса, не от реализации
@dataclass(slots=True)
class RegisterUC:
    user_repo: UserRepository  # Protocol, не PostgresUserRepo

Почему это важно: если завтра ты решишь заменить PostgreSQL на MongoDB - меняется только Infrastructure/, бизнес-логика не трогается. Тонкие интерфейсы Go делают эту инверсию практически бесплатной.

⚠️ Не мешай уровни

Если в handler у тебя SQL-запросы и бизнес-правила - потом тестировать и менять будет больно. Handler должен: распарсить запрос → вызвать use case → вернуть ответ. Всё.

Организация пакетов

По слоям vs по фичам

По слоям (стандарт):              По фичам (для больших проектов):
internal/                         internal/
  domain/                           user/
    user.go                           domain.go
    order.go                          usecase.go
  usecase/                            handler.go
    register.go                       repo.go
    place_order.go                  order/
  adapter/                            domain.go
    http/handler.go                   usecase.go
    postgres/user.go                  handler.go
                                      repo.go

Для проектов до 20-30 сущностей - структура по слоям проще и понятнее. Для больших проектов (50+ сущностей) - структура по фичам уменьшает связность.

Правила именования пакетов

Хорошо                   Плохо
──────────────────────   ─────────────────────
auth                     authPackage
postgres                 postgresAdapter
email                    emailUtils
order                    orderHelpers

Пакет в Go - это единица абстракции. Имя пакета - существительное, не глагол. Без суффиксов -utils, -helpers, -common.

Пример структуры фронтенда

src/
├── pages/          # страницы (роуты)
│   ├── Home.tsx
│   └── Profile.tsx
├── components/     # переиспользуемые компоненты
│   ├── Button.tsx
│   └── Card.tsx
├── features/       # фичи с логикой
│   ├── auth/
│   └── cart/
├── shared/         # утилиты, хуки, типы
│   ├── hooks/
│   └── api/
└── App.tsx

Принцип тот же: бизнес-логика (features/) отделена от UI (components/) и инфраструктуры (shared/api/).

Что ломает структуру

Антипаттерн                      Почему плохо
───────────────────────────────  ─────────────────────────────
utils/ с 50 функциями            «Свалка» без смысловой группировки
Циклические импорты              Пакеты A и B зависят друг от друга
God-пакет на 5000 строк          Слишком много ответственности
handler знает про SQL            Нарушение слоёв
domain импортирует adapter       Зависимость направлена наружу

Мини-задание

  • Нарисуй текущую структуру своего проекта (3 уровня)
  • Проверь: есть ли циклические зависимости между пакетами?
  • Если handler содержит SQL - вынеси в отдельный репозиторий
  • Убедись, что domain/ не импортирует пакеты из adapter/

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.