11.1Организация кода и принципы

Организуй код так, чтобы доменная логика зависела от нужных ей контрактов, а конкретные адаптеры собирались у границы приложения. Проверь интерфейсы, ошибки, конфиг и размер пакетов на реальные причины изменения, а не на названия архитектурных стилей.

Кто про кого знает: инверсия зависимостей и DI

Практический вопрос тут один: если я поменяю одну часть программы, сколько других частей придётся чинить следом? Ответ зависит от того, кто про кого знает, то есть от зависимостей. На схемах зависимость рисуют стрелкой от того, кто знает, к тому, кого знают, и остальное в главе сводится к тому, куда эти стрелки должны смотреть.

Инверсия зависимостей - развернуть стрелку, не меняя вызовов

Обычно тот, кто вызывает, зависит от того, кого вызывает: сервису нужен репозиторий, значит, сервис импортирует пакет репозитория. Инверсия зависимостей оставляет вызов прежним, но разворачивает стрелку импорта: сервис объявляет у себя интерфейс «мне нужен вот такой репозиторий», а пакет с реальной реализацией импортирует сервис и подписывается под этим интерфейсом.

Похоже на наём сотрудника. В обычной схеме ты идёшь к конкретному Петрову и просишь его о помощи: ты зависишь от Петрова, ушёл Петров - переписывать всё. В инвертированной ты публикуешь вакансию с требованиями, и уже кандидаты приходят под неё подстраиваться. Требования принадлежат тебе, а кто им соответствует, тебя не касается. Инверсию инверсией делает вот что: интерфейс принадлежит тому, кто им пользуется, а не тому, кто его реализует.

Внедрение зависимостей (DI) - передать готовое, а не создавать внутри

DI звучит громко, а означает до скуки простую вещь: объект не создаёт то, что ему нужно, сам, а получает это снаружи - обычно аргументом конструктора. Не repo := postgres.New(...) внутри сервиса, а NewService(repo Repository). Всё. Никакого фреймворка для этого не нужно, и в Go его обычно и не берут.

Зачем: пока сервис создаёт зависимость сам, он намертво привязан к конкретной реализации. В тесте вместо базы не подставишь заглушку, вторую реализацию не добавишь. DI и есть та механика, которой пользуются инверсия зависимостей и всё, что из неё следует.

Слои: это не про папки, это про направление стрелок

Слой - это не папка и не пакет, а роль: код, который решает задачи одного рода. Транспортный слой разбирает HTTP-запросы, слой сценариев выполняет бизнес-операции, слой хранения ходит в базу. Классическая тройка handler → service → repository существует ради одного правила: зависимости идут в одну сторону и никогда обратно. Смысл появляется, когда ты можешь удалить весь HTTP-слой, заменить его на gRPC-сервер или на консольную команду, и не тронуть ни строчки в service.

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

// internal/order/service.go: потребитель объявляет контракт, узкий и в своих терминах
package order

type Repository interface {
    ByID(ctx context.Context, id ID) (*Order, error)
    Save(ctx context.Context, o *Order) error
}

type Notifier interface {
    OrderPaid(ctx context.Context, o *Order) error
}

type Service struct {
    repo  Repository
    notif Notifier
    now   func() time.Time   // время тоже зависимость: иначе тесты будут флакать
}

// принимаем интерфейсы, возвращаем конкретный тип
func NewService(r Repository, n Notifier) *Service {
    return &Service{repo: r, notif: n, now: time.Now}
}

// internal/storage/postgres/order.go: реализация ничего не знает про order.Service
package postgres

type OrderRepo struct {
    db *sql.DB
}

func NewOrderRepo(db *sql.DB) *OrderRepo { return &OrderRepo{db: db} }

func (r *OrderRepo) ByID(ctx context.Context, id order.ID) (*order.Order, error) {
    var o order.Order
    err := r.db.QueryRowContext(ctx, `SELECT id, status, total FROM orders WHERE id = $1`, id).
        Scan(&o.ID, &o.Status, &o.Total)
    switch {
    case errors.Is(err, sql.ErrNoRows):
        return nil, fmt.Errorf("order %s: %w", id, order.ErrNotFound) // деталь БД наружу не течёт
    case err != nil:
        return nil, fmt.Errorf("select order: %w", err)
    }
    return &o, nil
}

Чистая и гексагональная: чем они отличаются от «просто слоёв»

Гексагональная архитектура (она же ports & adapters, Алистер Кокбёрн, 2005) и «чистая» архитектура (Роберт Мартин, 2012) описывают одну идею в разной упаковке. Разница со слоёнкой ровно одна, но принципиальная:

• В слоёнке стрелки идут сверху вниз. Верхний слой зависит от нижнего. Репозиторий считается «низом», и сервис зависит от него; ничто не мешает протащить *sql.DB прямо в сервис, и код будет компилироваться.
• В гексагоне стрелки идут снаружи внутрь, всегда. Внешнего мира нет вообще: есть порты и адаптеры. HTTP-сервер и Postgres оказываются на одной и той же «наружной» окружности - и то и другое всего лишь способ поговорить с ядром.

Откуда слова. Порт описывает форму разъёма, которую задаёт ядро: «мне нужен кто-то, умеющий сохранить заказ и найти его по id». Как розетка в стене - она описывает форму отверстий, но ничего не знает о том, что в неё воткнут. Адаптер работает вилкой конкретного прибора: реализация подогнана под эту форму, будь то Postgres, файл или заглушка в тесте. Аналогия держится ровно до одного места: розетка отдаёт ток одинаково всем, а порт бывает двух видов, и они противоположны по направлению.

Порты делятся на два вида, и это единственная терминология, которую стоит запомнить. Через driving (primary, ведущие) внешний мир дёргает приложение: интерфейс use-case реализует сам сервис, а вызывают его HTTP-хендлер, gRPC, консьюмер Kafka или cron. Driven (secondary, ведомые) смотрят в другую сторону, через них уже приложение дёргает мир: репозиторий, кэш, шину, почту; их объявляет ядро, а реализуют адаптеры.

Когда это оверинжиниринг

Гексагон стоит денег: каждый переход через границу требует типа DTO и функции маппинга. Три уровня моделей (OrderRequest → domain.Order → orderRow) и две функции перекладывания полей на каждый сценарий. Если у сервиса 12 CRUD-ручек и ноль бизнес-правил, ты получишь +300 % кода и ноль пользы: менять всё равно придётся все три модели сразу, они меняются по одной и той же причине.

DI: конструкторы, composition root и надо ли wire

Composition root - единственное место в программе, где все конкретные реализации создаются и соединяются друг с другом. Знание «какая именно база, какой именно почтовик» должно сидеть в программе ровно в одной точке, остальные файлы про это не знают.

Go-идиома проста до скуки: зависимости приходят аргументами конструктора, а граф собирается ровно в одном месте - в main. Никаких глобальных синглтонов, никакого service locator, никакой «магии» через теги и рефлексию. Плюс: граф зависимостей виден глазами, компилятор проверяет его целиком, а go build падает, если ты что-то забыл подключить.

// cmd/api/main.go: composition root, единственное место со всеми конкретными типами
func main() {
    cfg := config.MustLoad()

    db, err := sql.Open("pgx", cfg.DSN)
    must(err)
    db.SetMaxOpenConns(cfg.DBMaxConns)

    // снизу вверх: инфраструктура → репозитории → сервисы → транспорт
    orderRepo := postgres.NewOrderRepo(db)
    mailer    := smtp.NewMailer(cfg.SMTP)
    bus       := kafka.NewPublisher(cfg.Brokers)

    orderSvc  := order.NewService(orderRepo, notify.New(mailer, bus))
    h         := httpapi.NewHandler(orderSvc, logger)

    srv := &http.Server{Addr: cfg.Addr, Handler: h, ReadHeaderTimeout: 5 * time.Second}
    run(srv)
}

Когда граф вырастает до 40–60 узлов, main на 200 строк начинает раздражать, и тут появляются генераторы. Их два, и они принципиально разные.

Интерфейсы как контракты: объявлять у потребителя

Go отличается от Java/C# одним: интерфейсы реализуются неявно. Типу не нужно объявлять implements, достаточно иметь нужные методы. Следствие: интерфейс можно объявить после реализации и в другом пакете - том, который его использует. Это и есть DIP в практическом виде.

// плохо: интерфейс живёт у реализации
package storage

type UserRepository interface {
    Create(ctx context.Context, u *User) error
    Update(ctx context.Context, u *User) error
    Delete(ctx context.Context, id ID) error
    ByID(ctx context.Context, id ID) (*User, error)
    ByEmail(ctx context.Context, e string) (*User, error)
    List(ctx context.Context, f Filter) ([]*User, error)
}
// сервису нужен один метод -
// а мокать придётся шесть

// хорошо: контракт у потребителя, ровно по нужде
package auth

type UserByEmail interface {
    ByEmail(ctx context.Context, e string) (*domain.User, error)
}

type Service struct {
    users UserByEmail
}

// storage.UserRepo подходит автоматически,
// он ничего не знает про пакет auth

Структура проекта: cmd, internal, pkg и нарезка по домену

Внутри internal/ есть развилка, на которой валятся чаще всего. Нарезка по типам (models/, services/, handlers/, repositories/) выглядит аккуратно, но одна правка фичи задевает четыре пакета, и любой пакет знает про все домены сразу. Package-oriented design режет по предметным областям (order/, billing/, user/): внутри пакета лежат и модель, и логика, и интерфейсы хранилища. Правка фичи остаётся в одной папке, а циклы почти не возникают, потому что домены слабо связаны по смыслу.

# по типам: «горизонтальная» нарезка        # по домену: «вертикальная»
internal/                                   internal/
  models/     user.go order.go payment.go     user/     user.go service.go store.go
  services/   user.go order.go payment.go     order/    order.go service.go store.go
  handlers/   user.go order.go payment.go     billing/  payment.go service.go store.go
  repository/ user.go order.go payment.go     platform/ postgres/ kafka/ httpx/

Про монорепу спрашивают реже, но ответ короткий: она оправдана, когда общие контракты меняются часто и менять их нужно атомарно - один PR правит proto, сервер и всех клиентов. Платишь за это тулингом (нужен селективный CI, иначе каждый PR гоняет всё), правами доступа и дисциплиной: без границ монорепа за год превращается в клубок, где всё импортирует всё.

SOLID на Go: по одному честному примеру

SOLID складывается из первых букв пяти принципов проектирования (Роберт Мартин, начало 2000-х). Все пять отвечают на один вопрос: как написать код, который потом можно менять, не разбирая половину системы. SOLID придуман для языков с наследованием, и часть букв в Go звучит иначе. Каждую лучше показывать кодом, а не определением, но сначала сказать своими словами, о чём она.

S - Single Responsibility: одна причина для изменения

Принцип единственной ответственности. Формулируют его обычно как «класс должен делать одно дело», и это неточно: дел может быть много, важно другое. У куска кода должна быть одна причина меняться. За причиной стоит человек или отдел, который приходит с просьбой. Если один и тот же файл правят и когда маркетинг меняет текст письма, и когда бухгалтерия меняет правила скидок, и когда DBA переименовывает колонку - причин три, а значит, три разных повода сломать чужую работу в одном файле. Ровно этот случай в примере ниже.

// было: три причины меняться, правила заказа, формат письма, схема БД
func (s *OrderService) Place(ctx context.Context, req PlaceReq) error {
    if req.Total < 0 { return errors.New("bad total") }
    _, err := s.db.ExecContext(ctx, `INSERT INTO orders ...`)
    if err != nil { return err }
    body := "<h1>Заказ " + req.ID + "</h1>"          // вёрстка письма в сервисе
    return smtp.SendMail(s.addr, nil, "no-reply@x", []string{req.Email}, []byte(body))
}

// стало: каждая причина изменения живёт отдельно
func (s *OrderService) Place(ctx context.Context, o *domain.Order) error {
    if err := o.Validate(); err != nil { return err }   // правила проверяет домен
    if err := s.repo.Save(ctx, o); err != nil { return err } // схему знает репозиторий
    return s.notifier.OrderPlaced(ctx, o)               // письмо собирает notifier
}

O - Open/Closed: расширяем добавлением, а не правкой switch

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

// было: каждый новый провайдер = правка функции, которую все уже протестировали
switch method {
case "card":   return chargeCard(amount)
case "sbp":    return chargeSBP(amount)
case "wallet": return chargeWallet(amount)
}

// стало: стратегия + реестр. Новый провайдер = новый файл, старый код цел
type Provider interface {
    Name() string
    Charge(ctx context.Context, a Money) (TxID, error)
}

type Registry struct {
    m map[string]Provider
}

func (r *Registry) Register(p Provider) { r.m[p.Name()] = p }
func (r *Registry) Charge(ctx context.Context, name string, a Money) (TxID, error) {
    p, ok := r.m[name]
    if !ok { return "", fmt.Errorf("provider %q: %w", name, ErrUnsupported) }
    return p.Charge(ctx, a)
}

L - Liskov: реализация не имеет права ужесточать контракт

Принцип подстановки Барбары Лисков: если код работает с интерфейсом, то любая реализация этого интерфейса должна в нём работать - без «а вот с этой надо осторожнее». Бытовой пример: розетка обещает 220 вольт. Прибор, который в неё воткнули, вправе на это рассчитывать. Реализация, которая иногда выдаёт 380, формально «тоже розетка», но пользоваться ей нельзя - и не потому, что она хуже, а потому что она нарушила обещание, на которое все уже полагаются. В коде такие нарушения выглядят так.

// Нарушение LSP, которое реально встречается:
// реализация io.Writer паникует вместо ошибки
func (w *badWriter) Write(p []byte) (int, error) {
    if len(p) == 0 { panic("empty write") }  // контракт io.Writer этого не разрешает
    ...
}

// Второе нарушение, частое в репозиториях:
func (r *cachedRepo) ByID(ctx context.Context, id ID) (*User, error) {
    if u, ok := r.cache[id]; ok { return u, nil }
    return nil, nil   // вместо ErrNotFound: вызывающий получит nil-указатель и панику
}

Формулировка для собеса: подстановка реализации не должна ломать вызывающего. На практике это значит не добавлять предусловий, которых нет в контракте, не менять набор возвращаемых ошибок и не менять смысл «нулевого» результата.

I - Interface Segregation: маленькие интерфейсы

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

Формулировка Роба Пайка: the bigger the interface, the weaker the abstraction. Стандартная библиотека держит планку: io.Reader и io.Writer по одному методу, а всё остальное собирается композицией (io.ReadWriteCloser). Функция должна просить минимум:

func Backup(dst io.Writer, src io.Reader) error   // подойдёт файл, сокет, буфер, gzip-писатель
func Backup(dst *os.File, src *os.File) error      // подойдёт только файл, тест потребует диска

D - Dependency Inversion: оба зависят от абстракции

Принцип инверсии зависимостей, тот самый, с которого начиналась глава: модуль высокого уровня не должен зависеть от модуля низкого уровня; оба зависят от абстракции. «Высокий уровень» описывает то, ради чего программа написана (сценарии, правила), «низкий» - как именно она это делает (Postgres, SMTP, файлы). Правило спасает от ситуации, когда бизнес-логику переписывают из-за смены библиотеки драйвера.

Выше это уже было: order.Service зависит от order.Repository, postgres.OrderRepo - тоже от него. Ни один из них не зависит от другого напрямую. Уточнение, которое любят слышать: абстракция принадлежит верхнему уровню, а не нижнему, иначе инверсии не произошло.

Паттерны GoF в Go-идиомах

// Functional options: конструктор с обязательными аргументами и расширяемым хвостом
type Client struct {
    addr    string
    timeout time.Duration
    retries int
    log     Logger
}

type Option func(*Client)

func WithTimeout(d time.Duration) Option { return func(c *Client) { c.timeout = d } }
func WithRetries(n int) Option           { return func(c *Client) { c.retries = n } }
func WithLogger(l Logger) Option         { return func(c *Client) { c.log = l } }

func New(addr string, opts ...Option) *Client {
    c := &Client{addr: addr, timeout: 3 * time.Second, retries: 2, log: nopLogger{}}
    for _, o := range opts { o(c) }   // умолчания разумные, опции их переопределяют
    return c
}

c := New("10.0.0.1:9000", WithTimeout(time.Second), WithRetries(5))

// Decorator == middleware. Цепочка разворачивается справа налево от вызова
type Middleware func(http.Handler) http.Handler

func Chain(h http.Handler, mw ...Middleware) http.Handler {
    for i := len(mw) - 1; i >= 0; i-- { h = mw[i](h) }
    return h
}

func WithLogging(l Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            rw := &statusRecorder{ResponseWriter: w, code: 200}
            next.ServeHTTP(rw, r)
            l.Info("req", "path", r.URL.Path, "code", rw.code, "dur", time.Since(start))
        })
    }
}

// Тот же приём годится для любого интерфейса, не одного лишь http.Handler.
type cachedRepo struct {
    next order.Repository
    c    *lru.Cache
}
func (r *cachedRepo) ByID(ctx context.Context, id order.ID) (*order.Order, error) { ... }

// Singleton по-современному: sync.OnceValue (Go 1.21) вместо ручного sync.Once и глобальной переменной
var loadRates = sync.OnceValue(func() *RateTable {
    return mustParse(embeddedRates)   // выполнится ровно один раз, потокобезопасно
})

// и вариант с ошибкой:
var conn = sync.OnceValues(func() (*grpc.ClientConn, error) {
    return grpc.NewClient(addr)
})

Репозиторий: что возвращать при «не найдено»

Репозиторий прячет способ хранения за интерфейсом в терминах домена. Он даёт три вещи: тестируемость сервиса без БД, единое место маппинга «строка → доменный тип» и запрет на протекание SQL по всему коду. А вот чего он, вопреки легенде, не даёт, так это «легко сменить Postgres на Mongo»: реальные запросы, транзакции и модель консистентности так не переносятся.

package user

// Sentinel-ошибки домена: не привязаны ни к SQL, ни к HTTP
var (
    ErrNotFound      = errors.New("user not found")
    ErrAlreadyExists = errors.New("user already exists")
)

type Repository interface {
    ByID(ctx context.Context, id ID) (*User, error)
    ByEmail(ctx context.Context, email string) (*User, error)
    Create(ctx context.Context, u *User) error
    Update(ctx context.Context, u *User) error
}

// Транспорт: единственное место, где домен встречается с HTTP-кодами
func (h *Handler) get(w http.ResponseWriter, r *http.Request) {
    u, err := h.svc.Get(r.Context(), user.ID(r.PathValue("id")))  // Go 1.22 routing
    switch {
    case errors.Is(err, user.ErrNotFound):
        http.Error(w, "not found", http.StatusNotFound)
    case errors.Is(err, context.DeadlineExceeded):
        http.Error(w, "timeout", http.StatusGatewayTimeout)
    case err != nil:
        h.log.Error("get user", "err", err)
        http.Error(w, "internal", http.StatusInternalServerError)   // деталь наружу не отдаём
    default:
        writeJSON(w, u)
    }
}

Рефакторинг god-object на 1000+ строк

God-object знает и умеет всё: тысячи строк, три десятка полей, методы про базу, про HTTP, про почту и про бизнес-правила одновременно. Признак не в размере, а в том, что его правят по любому поводу: какое требование ни принеси, менять придётся этот файл. Это прямое нарушение S из SOLID в самой запущенной форме, а вредит он конфликтами в git и страхом что-либо трогать.

Правило простое: сначала сеть безопасности, потом движение. Переписать «начисто» почти всегда проигрывает, потому что в старом коде зашиты годы багфиксов, о которых никто не помнит. Порядок, который стоит проговорить на собесе:

1. Характеристические тесты (термин Майкла Физерса). Не «правильные» тесты, а фиксирующие текущее поведение, включая странности. Проще всего через golden-файлы: прогнать реальные входы, записать выходы, закоммитить, сравнивать. Цель в том, чтобы любое изменение поведения было видно как diff.
2. Найти швы - места, где можно подменить зависимость. В Go это обычно значит: вынести глобалы и прямые вызовы time.Now, http.Get, os.Getenv, db.Query в поля структуры.
3. Выделить чистые функции. Куски без ввода-вывода и без состояния вытаскиваются первыми: их легко покрыть тестами и невозможно сломать незаметно.
4. Разрезать по данным. Смотришь, какие поля используются какими методами вместе - это и есть будущие типы. Метод, который трогает только три поля из двадцати, просится наружу.
5. Переносить по одному методу, оставляя в старом объекте делегирующий вызов. Компилятор Go тут помогает: он найдёт все места использования.
6. Удалить делегаты и старый тип, когда все вызовы переехали.

Циклические зависимости пакетов

Go запрещает циклы импортов на уровне компилятора: import cycle not allowed. Это не каприз - так держится корректный порядок инициализации пакетов и возможность компилировать пакеты независимо. Причина цикла почти всегда одна: пакеты нарезаны по типам данных, а не по зонам ответственности, и два «домена» ссылаются друг на друга.

Конфигурация и 12-factor

Практический канон: флаги перекрывают переменные окружения, те перекрывают файл, файл перекрывает умолчания. Порядок можно выбрать и другой, лишь бы он был один, задокументирован и не менялся от сервиса к сервису. Конфиг разбираем один раз на старте, валидируем целиком, дальше раздаём кусками в конструкторы. os.Getenv посреди бизнес-логики работает как скрытый глобал: его не протестируешь и не увидишь в графе.

type Config struct {
    Addr        string        `env:"ADDR"              envDefault:":8080"`
    DSN         string        `env:"DATABASE_URL,required"`
    DBMaxConns  int           `env:"DB_MAX_CONNS"      envDefault:"20"`
    ReadTimeout time.Duration `env:"READ_TIMEOUT"      envDefault:"5s"`
    LogLevel    string        `env:"LOG_LEVEL"         envDefault:"info"`
}

func (c Config) Validate() error {
    if c.DSN == "" { return errors.New("DATABASE_URL is required") }
    if c.DBMaxConns <= 0 { return fmt.Errorf("DB_MAX_CONNS=%d must be > 0", c.DBMaxConns) }
    if !slices.Contains([]string{"debug", "info", "warn", "error"}, c.LogLevel) {
        return fmt.Errorf("LOG_LEVEL=%q unknown", c.LogLevel)
    }
    return nil
}

// fail fast: неправильный конфиг убивает процесс на старте,
// а не через два часа на первом обращении к необязательной ручке.

func main() {
    cfg := config.MustLoad()

    db, err := pgxpool.New(ctx, cfg.DSN)      // ресурсы создаются сверху вниз,
    if err != nil { log.Fatal(err) }
    defer db.Close()                          // закрываются снизу вверх

    repo := postgres.NewUserRepo(db)          // адаптер реализует порт
    mailer := smtp.NewMailer(cfg.SMTP)
    svc := user.NewService(repo, mailer, clock.System{})
    h := httpapi.NewHandler(svc, logger)

    srv := &http.Server{Addr: cfg.Addr, Handler: h.Routes()}
    // ... graceful shutdown
}

// Плохо: пакет-производитель объявляет широкий интерфейс "на всякий случай"
package postgres
type Storage interface {   // 20 методов; потребителю нужен один
    GetUser(...)   ; SaveUser(...)  ; ListUsers(...)
    GetOrder(...)  ; SaveOrder(...) ; /* ... */
}

// Хорошо: потребитель просит ровно то, что использует
package notify
type userGetter interface {                       // с маленькой буквы: деталь пакета
    ByID(ctx context.Context, id user.ID) (*user.User, error)
}
type Notifier struct {
    users userGetter
}
func New(u userGetter) *Notifier { return &Notifier{users: u} }

// Было: switch, который правят при каждом новом типе оплаты
switch method {
case "card":   ...
case "sbp":    ...
}

// Стало: новая оплата = новый файл, старый код не трогаем
type PaymentMethod interface {
    Charge(ctx context.Context, amount Money) (TxID, error)
}
type Registry struct {
    m map[string]PaymentMethod
}
func (r *Registry) Register(name string, p PaymentMethod) { r.m[name] = p }

type Option func(*Server)

func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } }
func WithLogger(l *slog.Logger) Option   { return func(s *Server) { s.log = l } }

func New(addr string, opts ...Option) *Server {
    s := &Server{addr: addr, timeout: 30 * time.Second, log: slog.Default()} // умолчания
    for _, o := range opts { o(s) }
    return s
}

type Middleware func(http.Handler) http.Handler

func WithLogging(log *slog.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)
            log.Info("req", "path", r.URL.Path, "dur", time.Since(start))
        })
    }
}
// Порядок важен: первый в списке становится самым внешним
func Chain(h http.Handler, ms ...Middleware) http.Handler {
    for i := len(ms) - 1; i >= 0; i-- { h = ms[i](h) }
    return h
}

// domain/user: интерфейс объявлен там, где используется
type Repository interface {
    ByID(ctx context.Context, id ID) (*User, error)
    ByEmail(ctx context.Context, email string) (*User, error)
    Create(ctx context.Context, u *User) error
    Update(ctx context.Context, u *User) error
}

var (
    ErrNotFound      = errors.New("user not found")
    ErrAlreadyExists = errors.New("user already exists")
)

// storage/postgres: адаптер переводит ошибки драйвера в доменные
func (r *UserRepo) ByID(ctx context.Context, id user.ID) (*user.User, error) {
    const q = `SELECT id, email, name, created_at FROM users WHERE id = $1`
    var u user.User
    err := r.db.QueryRow(ctx, q, id).Scan(&u.ID, &u.Email, &u.Name, &u.CreatedAt)
    switch {
    case errors.Is(err, pgx.ErrNoRows):
        return nil, fmt.Errorf("user %s: %w", id, user.ErrNotFound)  // %w сохраняет sentinel
    case err != nil:
        return nil, fmt.Errorf("select user %s: %w", id, err)
    }
    return &u, nil
}

func (r *UserRepo) Create(ctx context.Context, u *user.User) error {
    _, err := r.db.Exec(ctx, `INSERT INTO users (...) VALUES (...)`, ...)
    var pgErr *pgconn.PgError
    if errors.As(err, &pgErr) && pgErr.Code == "23505" {   // unique_violation
        return fmt.Errorf("email %s: %w", u.Email, user.ErrAlreadyExists)
    }
    return err
}

Что стоит запомнить

• Интерфейс обычно объявляет потребитель и включает только поведение, которое ему нужно.
• Composition root знает конкретные реализации и соединяет зависимости; бизнес-пакет от этого не импортирует инфраструктуру.
• Архитектура полезна, когда меняет направление зависимости или изолирует причину изменения; дополнительные слои имеют цену.

Частые ошибки

• Не создавай широкий универсальный интерфейс в storage только ради тестов, если потребитель использует один метод.
• Не возвращай nil,nil при NotFound: вызывающий код может принять отсутствие за успех и разыменовать nil.
• Не добавляй абстракцию без второй реализации, нужного test seam или независимой причины изменения.

// package order
type Repository interface { ByID(context.Context, ID) (*Order, error) }

// package postgres
type OrderRepo struct { db *sql.DB }
func NewOrderRepo(db *sql.DB) *OrderRepo { return &OrderRepo{db: db} }
func (r *OrderRepo) ByID(ctx context.Context, id order.ID) (*order.Order, error) { ... }

type UserRepository interface {
    Create(context.Context, *User) error
    Update(context.Context, *User) error
    Delete(context.Context, ID) error
    ByID(context.Context, ID) (*User, error)
    ByEmail(context.Context, string) (*User, error)
    List(context.Context, Filter) ([]*User, error)
}