Структура проекта и зависимости
Структура проекта влияет на скорость. Если ты каждый раз ищешь, где лежит логика - ты теряешь время и мотивацию.
Принцип
Логика должна быть ближе к домену, а инфраструктура - по краям.
Это основа слоистой архитектуры: бизнес-правила в центре, детали реализации (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/