Why DDD: applications && infrastructure

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

Домен описан и ни о чём внешнем не знает: у него есть агрегат, значения, факты и два порта.

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

Шаг 1 из 10

Use case: выставить счёт

Модуль issuing наконец с кодом. Сценарий делает три шага: собрать агрегат, сохранить, опубликовать факты.

Правил предметной области здесь нет ни одного — они остались в Issue. Здесь только порядок, и в этом весь application: он раздаёт работу и держит ход операции.

Сценарий принимает то, что нужно домену, — обычными параметрами. Что приходит по HTTP или с шины, досюда не доезжает: это DTO транспорта, и переводит их транспорт.

Зависимости — два порта, и ни одной реализации. Поэтому у сценария одна причина меняться — порядок операции: сменится база или шина, а он останется таким же.

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

Шаг 2 из 10

Use case: принять оплату

Второй модуль, тот же порядок, другая история: достать агрегат, вызвать метод, сохранить, опубликовать.

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

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

Шаг 3 из 10

Порты есть, реализации нет

Справа порт хранения из второй главы. Домен объявил, что ему нужно: взять счёт по номеру и сохранить целиком. Кто это делает — не его забота.

Пора сделать. И первый же вопрос реализации — не про SQL: как вернуть агрегат, у которого все поля закрыты? Issue для этого не годится, он создаёт новый счёт и записывает факт «счёт выставлен» — а мы достаём уже существующий.

Шаг 4 из 10

Как агрегат возвращается из базы

Load — второй способ появиться: не «создать», а «поднять то, что уже было». Фактов он не записывает, инвариантов не проверяет: данные уже лежали в базе, и проверять их заново — значит не доверять своей же записи.

Живёт он в домене, потому что только домен может собрать свой агрегат. Отдавать эту сборку инфраструктуре — значит открыть ей поля, а вместе с ними и возможность собрать счёт, которого предметная область не допускает.

Шаг 5 из 10

Реализация порта

Инфраструктура: database/sql, две таблицы, запросы. Домен про этот файл ничего не знает — знание идёт снаружи внутрь.

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

Соединение берётся не из поля, а функцией conn(ctx, db). Почему — следующие шаги.

Шаг 6 из 10

Сохранили и опубликовали

Вернёмся к сценарию. Он делает два вызова: сохранить и опубликовать. По отдельности оба правильные, вместе — нет.

Упал Publish — счёт в базе есть, а никто о нём не знает: доставка не начнёт собирать посылку, бухгалтерия не увидит начисления. Поменять вызовы местами — ещё хуже: упадёт Save после успешного Publish, и подписчики узнают о счёте, которого нет.

Оговорку про это я оставил ещё на первом шаге. Пора её закрыть: операция должна быть одна, а не две.

Шаг 7 из 10

Unit of work

Единица работы — это порт, который говорит одно: выполнить работу целиком или не выполнить вовсе. Ни Begin, ни Commit, ни слова «транзакция» в домене нет — есть функция, которую кто-то выполнит под своей ответственностью.

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

Шаг 8 из 10

Одна операция вместо двух

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

Транзакцию реализация кладёт в ctx, а адаптеры достают её оттуда той самой функцией conn. Поэтому сценарий не передаёт транзакцию параметром и вообще её не видит: ему нужна граница, а не соединение.

Тут легко перестараться. Единица работы — не «транзакция на каждый запрос» и не способ менять два агрегата разом: агрегат по-прежнему граница согласованности, а Do держит границу операции.

Шаг 9 из 10

Шина в транзакцию не входит

Осталась последняя ложь. Шина — не база: её нельзя откатить вместе с транзакцией. Отправь факт внутри Do, и падение на коммите оставит подписчиков с фактом о счёте, которого нет.

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

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

billing/GLOSSARY.md

Словарь

Одно значение на слово внутри контекста. Код, события, API и человек на созвоне пишут его одинаково.

«Платёж» в трёх отделах

Отдел	Что он называет платежом	Как это называется здесь
Продукт	Покупка прошла, пользователь увидел галочку	Событие заказа. Здесь его нет
Процессинг	Деньги захолдированы, списания не было	Авторизация
Бухгалтерия	Деньги пришли выпиской через два дня	Поступление

Слова

Авторизация. Эмитент согласился держать сумму. Деньги не двигались, холд истекает сам.

Списание. Команда забрать захолдированное. С этого момента деньги ушли со счёта плательщика.

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

Платёж. Попытка получить деньги за один заказ, со своим жизненным циклом: авторизован, списан, возвращён. Слово значит это и ничего больше.

Слова, которых здесь нет

Покупка. Продуктовое событие: пользователь увидел галочку. Живёт в заказах, здесь ему делать нечего.

billing/invoice/domains/invoice/invoice.go

package invoice

import (
	"time"

	"billing/invoice/domains/invoice/events"
	"billing/invoice/domains/invoice/vo"
)

// счёт: корень агрегата
type Invoice struct {
	number   Number
	customer CustomerID
	lines    []Line
	total    vo.Money
	dueOn    time.Time
	status   Status
	facts    []events.Event
}

// создаёт счёт и считает итог из строк
func Issue(
	number Number,
	customer CustomerID,
	lines []Line,
	dueOn time.Time,
) (*Invoice, error) {
	if len(lines) == 0 {
		return nil, ErrNoLines
	}

	total := vo.NewMoney(0)
	for _, line := range lines {
		total = total.Add(line.Amount())
	}

	invoice := &Invoice{
		number:   number,
		customer: customer,
		// копия строк: снаружи их не поменять
		lines:    append([]Line(nil), lines...),
		total:    total,
		dueOn:    dueOn,
		status:   StatusIssued,
	}

	// записывает факт; отправлять его — не дело агрегата
	invoice.facts = append(invoice.facts, events.Issued{
		Number:   string(number),
		Customer: string(customer),
		Total:    total,
	})

	return invoice, nil
}

// отдаёт накопленные факты наружу
func (i *Invoice) Events() []events.Event { return i.facts }

func (i *Invoice) Total() vo.Money  { return i.total }
func (i *Invoice) DueOn() time.Time { return i.dueOn }
func (i *Invoice) Status() Status   { return i.status }

billing/invoice/domains/invoice/paid.go

package invoice

import "billing/invoice/domains/invoice/events"

// отмечает счёт оплаченным; дважды оплатить нельзя
func (i *Invoice) MarkPaid() error {
	if i.status == StatusPaid {
		return ErrAlreadyPaid
	}

	i.status = StatusPaid

	// записывает факт; отправлять его — не дело агрегата
	i.facts = append(i.facts, events.Paid{Number: string(i.number)})

	return nil
}

billing/invoice/domains/invoice/charged.go

package invoice

import (
	"billing/invoice/domains/invoice/events"
	"billing/invoice/domains/invoice/vo"
)

// приписывает пеню счёту; оплаченный счёт её не берёт
func (i *Invoice) ChargePenalty(amount vo.Money) error {
	if i.status == StatusPaid {
		return ErrAlreadyPaid
	}

	if amount.Equal(vo.NewMoney(0)) {
		return nil
	}

	i.lines = append(i.lines, Line{Quantity: 1, Price: amount})
	i.total = i.total.Add(amount)

	// записывает факт; отправлять его — не дело агрегата
	i.facts = append(i.facts, events.PenaltyCharged{
		Number: string(i.number),
		Amount: amount,
	})

	return nil
}

billing/invoice/domains/invoice/events/event.go

package events

import "billing/invoice/domains/invoice/vo"

// факт домена; имя уезжает на шину как тип сообщения
type Event interface {
	FactName() string
}

// счёт выставлен
type Issued struct {
	Number   string
	Customer string
	Total    vo.Money
}

func (Issued) FactName() string { return "invoice.issued" }

// счёт оплачен
type Paid struct {
	Number string
}

func (Paid) FactName() string { return "invoice.paid" }

// счёт получил пеню
type PenaltyCharged struct {
	Number string
	Amount vo.Money
}

func (PenaltyCharged) FactName() string { return "invoice.penalty_charged" }

billing/invoice/domains/invoice/calendar.go

package invoice

import "time"

// календарь рабочих дней: часть модели, а не порт к базе
type Calendar interface {
	Workdays(from time.Time, to time.Time) int
}

billing/invoice/domains/invoice/services/penalty/penalty.go

package penalty

import (
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// правило: счёт, ставка и календарь — на выходе сумма
func Amount(
	overdue *invoice.Invoice,
	now time.Time,
	perWorkday vo.Money,
	calendar invoice.Calendar,
) vo.Money {
	// срок правило берёт у самого счёта, а не у вызывающего
	late := calendar.Workdays(overdue.DueOn(), now)
	if late <= 0 {
		return vo.NewMoney(0)
	}

	return vo.NewMoney(perWorkday.Get() * int64(late))
}

billing/invoice/domains/invoice/repository.go

package invoice

import "context"

// порт: как счёт попадает в базу и возвращается оттуда
type Repository interface {
	ByNumber(ctx context.Context, number Number) (*Invoice, error)
	Save(ctx context.Context, invoice *Invoice) error
}

billing/invoice/domains/invoice/publisher.go

package invoice

import (
	"context"

	"billing/invoice/domains/invoice/events"
)

// порт: куда уезжают факты
type Publisher interface {
	Publish(ctx context.Context, facts ...events.Event) error
}

billing/invoice/domains/invoice/vo/money.go

package vo

// сумма в копейках
type Money struct {
	minor int64
}

func NewMoney(minor int64) Money {
	return Money{minor: minor}
}

func (m Money) Add(other Money) Money {
	return Money{minor: m.minor + other.minor}
}

func (m Money) Equal(other Money) bool {
	return m.minor == other.minor
}

func (m Money) Get() int64 {
	return m.minor
}

billing/invoice/domains/invoice/rules/overdue.go

package rules

import (
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// контракт спецификации: один вопрос про один агрегат
type Specification interface {
	IsSatisfiedBy(inv *invoice.Invoice) bool
}

// предикат: этот счёт просрочен?
type Overdue struct {
	now      time.Time
	calendar invoice.Calendar
}

func NewOverdue(now time.Time, calendar invoice.Calendar) Overdue {
	return Overdue{now: now, calendar: calendar}
}

// оплаченный счёт просроченным не бывает
func (o Overdue) IsSatisfiedBy(inv *invoice.Invoice) bool {
	if inv.Status() == invoice.StatusPaid {
		return false
	}

	return o.calendar.Workdays(inv.DueOn(), o.now) > 0
}

// второй предикат: счёт больше лимита
type OverBudget struct {
	limit vo.Money
}

func NewOverBudget(limit vo.Money) OverBudget {
	return OverBudget{limit: limit}
}

func (b OverBudget) IsSatisfiedBy(inv *invoice.Invoice) bool {
	return inv.Total().Get() > b.limit.Get()
}

// сборка: требует все предикаты сразу
type All struct {
	specs []Specification
}

func AllOf(specs ...Specification) All {
	return All{specs: specs}
}

func (a All) IsSatisfiedBy(inv *invoice.Invoice) bool {
	for _, spec := range a.specs {
		if !spec.IsSatisfiedBy(inv) {
			return false
		}
	}

	return true
}

billing/invoice/applications/overdue/charge.go

package overdue

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/rules"
	"billing/invoice/domains/invoice/services/penalty"
	"billing/invoice/domains/invoice/vo"
)

// два порта, календарь и ставка — всё, что нужно сценарию
type UseCase struct {
	invoices   invoice.Repository
	publisher  invoice.Publisher
	calendar   invoice.Calendar
	perWorkday vo.Money
}

func New(
	invoices invoice.Repository,
	publisher invoice.Publisher,
	calendar invoice.Calendar,
	perWorkday vo.Money,
) *UseCase {
	return &UseCase{
		invoices:   invoices,
		publisher:  publisher,
		calendar:   calendar,
		perWorkday: perWorkday,
	}
}

// достать, посчитать, применить, сохранить, рассказать
func (u *UseCase) Run(ctx context.Context, number invoice.Number, now time.Time) error {
	overdue, err := u.invoices.ByNumber(ctx, number)
	if err != nil {
		return err
	}

	// сценарий спрашивает у правила, а не верит вызывающему
	if !rules.NewOverdue(now, u.calendar).IsSatisfiedBy(overdue) {
		return nil
	}

	// правило считает сумму по счёту, ставке и календарю
	amount := penalty.Amount(overdue, now, u.perWorkday, u.calendar)

	// приписать пеню счёту может только сам счёт
	if err := overdue.ChargePenalty(amount); err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, overdue); err != nil {
		return err
	}

	return u.publisher.Publish(ctx, overdue.Events()...)
}

billing/invoice/applications/overdue/charge.go

package overdue

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/rules"
	"billing/invoice/domains/invoice/services/penalty"
	"billing/invoice/domains/invoice/vo"
)

// два порта, календарь и ставка — всё, что нужно сценарию
type UseCase struct {
	uow        invoice.UnitOfWork
	invoices   invoice.Repository
	publisher  invoice.Publisher
	calendar   invoice.Calendar
	perWorkday vo.Money
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
	calendar invoice.Calendar,
	perWorkday vo.Money,
) *UseCase {
	return &UseCase{
		uow:        uow,
		invoices:   invoices,
		publisher:  publisher,
		calendar:   calendar,
		perWorkday: perWorkday,
	}
}

// достать, посчитать, применить, сохранить, рассказать
func (u *UseCase) Run(ctx context.Context, number invoice.Number, now time.Time) error {
	return u.uow.Do(ctx, func(ctx context.Context) error {
		overdue, err := u.invoices.ByNumber(ctx, number)
		if err != nil {
			return err
		}

		// сценарий спрашивает у правила, а не верит вызывающему
		if !rules.NewOverdue(now, u.calendar).IsSatisfiedBy(overdue) {
			return nil
		}

		// правило считает сумму по счёту, ставке и календарю
		amount := penalty.Amount(overdue, now, u.perWorkday, u.calendar)

		// приписать пеню счёту может только сам счёт
		if err := overdue.ChargePenalty(amount); err != nil {
			return err
		}

		if err := u.invoices.Save(ctx, overdue); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, overdue.Events()...)
	})
}

billing/invoice/applications/issuing/issue.go

package issuing

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
)

// зависимости — только порты домена
type UseCase struct {
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(invoices invoice.Repository, publisher invoice.Publisher) *UseCase {
	return &UseCase{invoices: invoices, publisher: publisher}
}

// порядок операции: собрать, сохранить, рассказать
func (u *UseCase) Run(
	ctx context.Context,
	number invoice.Number,
	customer invoice.CustomerID,
	lines []invoice.Line,
	dueOn time.Time,
) error {
	issued, err := invoice.Issue(number, customer, lines, dueOn)
	if err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, issued); err != nil {
		return err
	}

	// факты уезжают после сохранения, не раньше
	return u.publisher.Publish(ctx, issued.Events()...)
}

billing/invoice/applications/issuing/issue.go

package issuing

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
)

// к портам добавился ещё один: единица работы
type UseCase struct {
	uow       invoice.UnitOfWork
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
) *UseCase {
	return &UseCase{uow: uow, invoices: invoices, publisher: publisher}
}

// порядок тот же, изменилась граница
func (u *UseCase) Run(
	ctx context.Context,
	number invoice.Number,
	customer invoice.CustomerID,
	lines []invoice.Line,
	dueOn time.Time,
) error {
	issued, err := invoice.Issue(number, customer, lines, dueOn)
	if err != nil {
		return err
	}

	// сохранение и факты — внутри одной операции
	return u.uow.Do(ctx, func(ctx context.Context) error {
		if err := u.invoices.Save(ctx, issued); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, issued.Events()...)
	})
}

billing/invoice/applications/payment/pay.go

package payment

import (
	"context"

	"billing/invoice/domains/invoice"
)

// зависимости — только порты домена
type UseCase struct {
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(invoices invoice.Repository, publisher invoice.Publisher) *UseCase {
	return &UseCase{invoices: invoices, publisher: publisher}
}

// достать, вызвать метод, сохранить, рассказать
func (u *UseCase) Run(ctx context.Context, number invoice.Number) error {
	paid, err := u.invoices.ByNumber(ctx, number)
	if err != nil {
		return err
	}

	if err := paid.MarkPaid(); err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, paid); err != nil {
		return err
	}

	// факты уезжают после сохранения, не раньше
	return u.publisher.Publish(ctx, paid.Events()...)
}

billing/invoice/applications/payment/pay.go

package payment

import (
	"context"

	"billing/invoice/domains/invoice"
)

// к портам добавился ещё один: единица работы
type UseCase struct {
	uow       invoice.UnitOfWork
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
) *UseCase {
	return &UseCase{uow: uow, invoices: invoices, publisher: publisher}
}

// достать, вызвать метод, сохранить, рассказать
func (u *UseCase) Run(ctx context.Context, number invoice.Number) error {
	return u.uow.Do(ctx, func(ctx context.Context) error {
		paid, err := u.invoices.ByNumber(ctx, number)
		if err != nil {
			return err
		}

		if err := paid.MarkPaid(); err != nil {
			return err
		}

		if err := u.invoices.Save(ctx, paid); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, paid.Events()...)
	})
}

billing/invoice/domains/invoice/load.go

package invoice

import (
	"time"

	"billing/invoice/domains/invoice/vo"
)

// собирает счёт из того, что лежит в базе; фактов при этом нет
func Load(
	number Number,
	customer CustomerID,
	lines []Line,
	total vo.Money,
	dueOn time.Time,
	status Status,
) *Invoice {
	return &Invoice{
		number:   number,
		customer: customer,
		lines:    lines,
		total:    total,
		dueOn:    dueOn,
		status:   status,
	}
}

billing/invoice/domains/invoice/uow.go

package invoice

import "context"

// порт: выполнить работу целиком или не выполнить вовсе
type UnitOfWork interface {
	Do(ctx context.Context, work func(ctx context.Context) error) error
}

billing/invoice/infrastructure/postgres/invoices.go

package postgres

import (
	"context"
	"database/sql"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// реализация порта хранения
type Invoices struct {
	db *sql.DB
}

func NewInvoices(db *sql.DB) *Invoices {
	return &Invoices{db: db}
}

// достаёт счёт: строки отдельным запросом
func (r *Invoices) ByNumber(ctx context.Context, number invoice.Number) (*invoice.Invoice, error) {
	var (
		customer string
		minor    int64
		dueOn    time.Time
		status   string
	)

	err := conn(ctx, r.db).
		QueryRowContext(ctx, selectInvoice, string(number)).
		Scan(&customer, &minor, &dueOn, &status)
	if err != nil {
		return nil, err
	}

	lines, err := r.lines(ctx, number)
	if err != nil {
		return nil, err
	}

	// собирает агрегат, а не создаёт новый
	return invoice.Load(
		number,
		invoice.CustomerID(customer),
		lines,
		vo.NewMoney(minor),
		dueOn,
		invoice.Status(status),
	), nil
}

// сохраняет счёт и его строки — двумя запросами, одной транзакцией
func (r *Invoices) Save(ctx context.Context, saved *invoice.Invoice) error {
	db := conn(ctx, r.db)

	if _, err := db.ExecContext(ctx, upsertInvoice, saved); err != nil {
		return err
	}

	_, err := db.ExecContext(ctx, replaceLines, saved)

	return err
}

billing/invoice/infrastructure/postgres/uow.go

package postgres

import (
	"context"
	"database/sql"
)

type txKey struct{}

// транзакция, спрятанная за портом
type UnitOfWork struct {
	db *sql.DB
}

func NewUnitOfWork(db *sql.DB) *UnitOfWork {
	return &UnitOfWork{db: db}
}

// открыл, отдал работу, закрыл: коммит один на всю операцию
func (u *UnitOfWork) Do(ctx context.Context, work func(ctx context.Context) error) error {
	tx, err := u.db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}

	if err := work(context.WithValue(ctx, txKey{}, tx)); err != nil {
		// ошибка внутри — откат целиком
		_ = tx.Rollback()

		return err
	}

	return tx.Commit()
}

// адаптеры берут соединение отсюда: транзакция лежит в ctx
func conn(ctx context.Context, db *sql.DB) interface {
	ExecContext(context.Context, string, ...any) (sql.Result, error)
	QueryRowContext(context.Context, string, ...any) *sql.Row
} {
	if tx, ok := ctx.Value(txKey{}).(*sql.Tx); ok {
		return tx
	}

	return db
}

billing/invoice/infrastructure/postgres/outbox.go

package postgres

import (
	"context"
	"database/sql"
	"encoding/json"

	"billing/invoice/domains/invoice/events"
)

// реализация порта публикации
type Outbox struct {
	db *sql.DB
}

func NewOutbox(db *sql.DB) *Outbox {
	return &Outbox{db: db}
}

// факты не уезжают на шину, а ложатся строкой рядом со счётом
func (o *Outbox) Publish(ctx context.Context, facts ...events.Event) error {
	db := conn(ctx, o.db)

	for _, event := range facts {
		body, err := json.Marshal(event)
		if err != nil {
			return err
		}

		// та же транзакция, что у счёта
		if _, err := db.ExecContext(ctx, insertOutbox, event.FactName(), body); err != nil {
			return err
		}
	}

	return nil
}

Шаг 10 из 10

Что получилось вокруг домена

По дереву видна раскладка целиком: домен в domains/invoice, сценарии — в applications, по модулю на слайс. Щёлкни по файлу, чтобы прочитать.

applications/issuing/issue.go — выставить счёт, всё внутри одной единицы работы.
applications/payment/pay.go — принять оплату.
domains/invoice/load.go — как агрегат возвращается из базы.
domains/invoice/uow.go — порт единицы работы.
infrastructure/postgres/invoices.go — реализация хранения.
infrastructure/postgres/uow.go — транзакция и conn(ctx, db).
infrastructure/postgres/outbox.go — факты строкой в той же транзакции.

Домен за всю главу подрос на два файла: load.go — про сборку своего же агрегата, и uow.go — ещё один порт. Всё остальное легло снаружи, за портами, которые домен объявил сам.

Чего здесь ещё нет: входящего вызова и сборки приложения. Дальше — они.

billing/GLOSSARY.md

Словарь

Одно значение на слово внутри контекста. Код, события, API и человек на созвоне пишут его одинаково.

«Платёж» в трёх отделах

Отдел	Что он называет платежом	Как это называется здесь
Продукт	Покупка прошла, пользователь увидел галочку	Событие заказа. Здесь его нет
Процессинг	Деньги захолдированы, списания не было	Авторизация
Бухгалтерия	Деньги пришли выпиской через два дня	Поступление

Слова

Авторизация. Эмитент согласился держать сумму. Деньги не двигались, холд истекает сам.

Списание. Команда забрать захолдированное. С этого момента деньги ушли со счёта плательщика.

Слова, которых здесь нет

Покупка. Продуктовое событие: пользователь увидел галочку. Живёт в заказах, здесь ему делать нечего.

billing/invoice/domains/invoice/invoice.go

package invoice

import (
	"time"

	"billing/invoice/domains/invoice/events"
	"billing/invoice/domains/invoice/vo"
)

// счёт: корень агрегата
type Invoice struct {
	number   Number
	customer CustomerID
	lines    []Line
	total    vo.Money
	dueOn    time.Time
	status   Status
	facts    []events.Event
}

// создаёт счёт и считает итог из строк
func Issue(
	number Number,
	customer CustomerID,
	lines []Line,
	dueOn time.Time,
) (*Invoice, error) {
	if len(lines) == 0 {
		return nil, ErrNoLines
	}

	total := vo.NewMoney(0)
	for _, line := range lines {
		total = total.Add(line.Amount())
	}

	invoice := &Invoice{
		number:   number,
		customer: customer,
		// копия строк: снаружи их не поменять
		lines:    append([]Line(nil), lines...),
		total:    total,
		dueOn:    dueOn,
		status:   StatusIssued,
	}

	// записывает факт; отправлять его — не дело агрегата
	invoice.facts = append(invoice.facts, events.Issued{
		Number:   string(number),
		Customer: string(customer),
		Total:    total,
	})

	return invoice, nil
}

// отдаёт накопленные факты наружу
func (i *Invoice) Events() []events.Event { return i.facts }

func (i *Invoice) Total() vo.Money  { return i.total }
func (i *Invoice) DueOn() time.Time { return i.dueOn }
func (i *Invoice) Status() Status   { return i.status }

billing/invoice/domains/invoice/paid.go

package invoice

import "billing/invoice/domains/invoice/events"

// отмечает счёт оплаченным; дважды оплатить нельзя
func (i *Invoice) MarkPaid() error {
	if i.status == StatusPaid {
		return ErrAlreadyPaid
	}

	i.status = StatusPaid

	// записывает факт; отправлять его — не дело агрегата
	i.facts = append(i.facts, events.Paid{Number: string(i.number)})

	return nil
}

billing/invoice/domains/invoice/charged.go

package invoice

import (
	"billing/invoice/domains/invoice/events"
	"billing/invoice/domains/invoice/vo"
)

// приписывает пеню счёту; оплаченный счёт её не берёт
func (i *Invoice) ChargePenalty(amount vo.Money) error {
	if i.status == StatusPaid {
		return ErrAlreadyPaid
	}

	if amount.Equal(vo.NewMoney(0)) {
		return nil
	}

	i.lines = append(i.lines, Line{Quantity: 1, Price: amount})
	i.total = i.total.Add(amount)

	// записывает факт; отправлять его — не дело агрегата
	i.facts = append(i.facts, events.PenaltyCharged{
		Number: string(i.number),
		Amount: amount,
	})

	return nil
}

billing/invoice/domains/invoice/events/event.go

package events

import "billing/invoice/domains/invoice/vo"

// факт домена; имя уезжает на шину как тип сообщения
type Event interface {
	FactName() string
}

// счёт выставлен
type Issued struct {
	Number   string
	Customer string
	Total    vo.Money
}

func (Issued) FactName() string { return "invoice.issued" }

// счёт оплачен
type Paid struct {
	Number string
}

func (Paid) FactName() string { return "invoice.paid" }

// счёт получил пеню
type PenaltyCharged struct {
	Number string
	Amount vo.Money
}

func (PenaltyCharged) FactName() string { return "invoice.penalty_charged" }

billing/invoice/domains/invoice/calendar.go

package invoice

import "time"

// календарь рабочих дней: часть модели, а не порт к базе
type Calendar interface {
	Workdays(from time.Time, to time.Time) int
}

billing/invoice/domains/invoice/services/penalty/penalty.go

package penalty

import (
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// правило: счёт, ставка и календарь — на выходе сумма
func Amount(
	overdue *invoice.Invoice,
	now time.Time,
	perWorkday vo.Money,
	calendar invoice.Calendar,
) vo.Money {
	// срок правило берёт у самого счёта, а не у вызывающего
	late := calendar.Workdays(overdue.DueOn(), now)
	if late <= 0 {
		return vo.NewMoney(0)
	}

	return vo.NewMoney(perWorkday.Get() * int64(late))
}

billing/invoice/domains/invoice/repository.go

package invoice

import "context"

// порт: как счёт попадает в базу и возвращается оттуда
type Repository interface {
	ByNumber(ctx context.Context, number Number) (*Invoice, error)
	Save(ctx context.Context, invoice *Invoice) error
}

billing/invoice/domains/invoice/publisher.go

package invoice

import (
	"context"

	"billing/invoice/domains/invoice/events"
)

// порт: куда уезжают факты
type Publisher interface {
	Publish(ctx context.Context, facts ...events.Event) error
}

billing/invoice/domains/invoice/vo/money.go

package vo

// сумма в копейках
type Money struct {
	minor int64
}

func NewMoney(minor int64) Money {
	return Money{minor: minor}
}

func (m Money) Add(other Money) Money {
	return Money{minor: m.minor + other.minor}
}

func (m Money) Equal(other Money) bool {
	return m.minor == other.minor
}

func (m Money) Get() int64 {
	return m.minor
}

billing/invoice/domains/invoice/rules/overdue.go

package rules

import (
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// контракт спецификации: один вопрос про один агрегат
type Specification interface {
	IsSatisfiedBy(inv *invoice.Invoice) bool
}

// предикат: этот счёт просрочен?
type Overdue struct {
	now      time.Time
	calendar invoice.Calendar
}

func NewOverdue(now time.Time, calendar invoice.Calendar) Overdue {
	return Overdue{now: now, calendar: calendar}
}

// оплаченный счёт просроченным не бывает
func (o Overdue) IsSatisfiedBy(inv *invoice.Invoice) bool {
	if inv.Status() == invoice.StatusPaid {
		return false
	}

	return o.calendar.Workdays(inv.DueOn(), o.now) > 0
}

// второй предикат: счёт больше лимита
type OverBudget struct {
	limit vo.Money
}

func NewOverBudget(limit vo.Money) OverBudget {
	return OverBudget{limit: limit}
}

func (b OverBudget) IsSatisfiedBy(inv *invoice.Invoice) bool {
	return inv.Total().Get() > b.limit.Get()
}

// сборка: требует все предикаты сразу
type All struct {
	specs []Specification
}

func AllOf(specs ...Specification) All {
	return All{specs: specs}
}

func (a All) IsSatisfiedBy(inv *invoice.Invoice) bool {
	for _, spec := range a.specs {
		if !spec.IsSatisfiedBy(inv) {
			return false
		}
	}

	return true
}

billing/invoice/applications/overdue/charge.go

package overdue

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/rules"
	"billing/invoice/domains/invoice/services/penalty"
	"billing/invoice/domains/invoice/vo"
)

// два порта, календарь и ставка — всё, что нужно сценарию
type UseCase struct {
	invoices   invoice.Repository
	publisher  invoice.Publisher
	calendar   invoice.Calendar
	perWorkday vo.Money
}

func New(
	invoices invoice.Repository,
	publisher invoice.Publisher,
	calendar invoice.Calendar,
	perWorkday vo.Money,
) *UseCase {
	return &UseCase{
		invoices:   invoices,
		publisher:  publisher,
		calendar:   calendar,
		perWorkday: perWorkday,
	}
}

// достать, посчитать, применить, сохранить, рассказать
func (u *UseCase) Run(ctx context.Context, number invoice.Number, now time.Time) error {
	overdue, err := u.invoices.ByNumber(ctx, number)
	if err != nil {
		return err
	}

	// сценарий спрашивает у правила, а не верит вызывающему
	if !rules.NewOverdue(now, u.calendar).IsSatisfiedBy(overdue) {
		return nil
	}

	// правило считает сумму по счёту, ставке и календарю
	amount := penalty.Amount(overdue, now, u.perWorkday, u.calendar)

	// приписать пеню счёту может только сам счёт
	if err := overdue.ChargePenalty(amount); err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, overdue); err != nil {
		return err
	}

	return u.publisher.Publish(ctx, overdue.Events()...)
}

billing/invoice/applications/overdue/charge.go

package overdue

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/rules"
	"billing/invoice/domains/invoice/services/penalty"
	"billing/invoice/domains/invoice/vo"
)

// два порта, календарь и ставка — всё, что нужно сценарию
type UseCase struct {
	uow        invoice.UnitOfWork
	invoices   invoice.Repository
	publisher  invoice.Publisher
	calendar   invoice.Calendar
	perWorkday vo.Money
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
	calendar invoice.Calendar,
	perWorkday vo.Money,
) *UseCase {
	return &UseCase{
		uow:        uow,
		invoices:   invoices,
		publisher:  publisher,
		calendar:   calendar,
		perWorkday: perWorkday,
	}
}

// достать, посчитать, применить, сохранить, рассказать
func (u *UseCase) Run(ctx context.Context, number invoice.Number, now time.Time) error {
	return u.uow.Do(ctx, func(ctx context.Context) error {
		overdue, err := u.invoices.ByNumber(ctx, number)
		if err != nil {
			return err
		}

		// сценарий спрашивает у правила, а не верит вызывающему
		if !rules.NewOverdue(now, u.calendar).IsSatisfiedBy(overdue) {
			return nil
		}

		// правило считает сумму по счёту, ставке и календарю
		amount := penalty.Amount(overdue, now, u.perWorkday, u.calendar)

		// приписать пеню счёту может только сам счёт
		if err := overdue.ChargePenalty(amount); err != nil {
			return err
		}

		if err := u.invoices.Save(ctx, overdue); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, overdue.Events()...)
	})
}

billing/invoice/applications/issuing/issue.go

package issuing

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
)

// зависимости — только порты домена
type UseCase struct {
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(invoices invoice.Repository, publisher invoice.Publisher) *UseCase {
	return &UseCase{invoices: invoices, publisher: publisher}
}

// порядок операции: собрать, сохранить, рассказать
func (u *UseCase) Run(
	ctx context.Context,
	number invoice.Number,
	customer invoice.CustomerID,
	lines []invoice.Line,
	dueOn time.Time,
) error {
	issued, err := invoice.Issue(number, customer, lines, dueOn)
	if err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, issued); err != nil {
		return err
	}

	// факты уезжают после сохранения, не раньше
	return u.publisher.Publish(ctx, issued.Events()...)
}

billing/invoice/applications/issuing/issue.go

package issuing

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
)

// к портам добавился ещё один: единица работы
type UseCase struct {
	uow       invoice.UnitOfWork
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
) *UseCase {
	return &UseCase{uow: uow, invoices: invoices, publisher: publisher}
}

// порядок тот же, изменилась граница
func (u *UseCase) Run(
	ctx context.Context,
	number invoice.Number,
	customer invoice.CustomerID,
	lines []invoice.Line,
	dueOn time.Time,
) error {
	issued, err := invoice.Issue(number, customer, lines, dueOn)
	if err != nil {
		return err
	}

	// сохранение и факты — внутри одной операции
	return u.uow.Do(ctx, func(ctx context.Context) error {
		if err := u.invoices.Save(ctx, issued); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, issued.Events()...)
	})
}

billing/invoice/applications/payment/pay.go

package payment

import (
	"context"

	"billing/invoice/domains/invoice"
)

// зависимости — только порты домена
type UseCase struct {
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(invoices invoice.Repository, publisher invoice.Publisher) *UseCase {
	return &UseCase{invoices: invoices, publisher: publisher}
}

// достать, вызвать метод, сохранить, рассказать
func (u *UseCase) Run(ctx context.Context, number invoice.Number) error {
	paid, err := u.invoices.ByNumber(ctx, number)
	if err != nil {
		return err
	}

	if err := paid.MarkPaid(); err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, paid); err != nil {
		return err
	}

	// факты уезжают после сохранения, не раньше
	return u.publisher.Publish(ctx, paid.Events()...)
}

billing/invoice/applications/payment/pay.go

package payment

import (
	"context"

	"billing/invoice/domains/invoice"
)

// к портам добавился ещё один: единица работы
type UseCase struct {
	uow       invoice.UnitOfWork
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
) *UseCase {
	return &UseCase{uow: uow, invoices: invoices, publisher: publisher}
}

// достать, вызвать метод, сохранить, рассказать
func (u *UseCase) Run(ctx context.Context, number invoice.Number) error {
	return u.uow.Do(ctx, func(ctx context.Context) error {
		paid, err := u.invoices.ByNumber(ctx, number)
		if err != nil {
			return err
		}

		if err := paid.MarkPaid(); err != nil {
			return err
		}

		if err := u.invoices.Save(ctx, paid); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, paid.Events()...)
	})
}

billing/invoice/domains/invoice/load.go

package invoice

import (
	"time"

	"billing/invoice/domains/invoice/vo"
)

// собирает счёт из того, что лежит в базе; фактов при этом нет
func Load(
	number Number,
	customer CustomerID,
	lines []Line,
	total vo.Money,
	dueOn time.Time,
	status Status,
) *Invoice {
	return &Invoice{
		number:   number,
		customer: customer,
		lines:    lines,
		total:    total,
		dueOn:    dueOn,
		status:   status,
	}
}

billing/invoice/domains/invoice/uow.go

package invoice

import "context"

// порт: выполнить работу целиком или не выполнить вовсе
type UnitOfWork interface {
	Do(ctx context.Context, work func(ctx context.Context) error) error
}

billing/invoice/infrastructure/postgres/invoices.go

package postgres

import (
	"context"
	"database/sql"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// реализация порта хранения
type Invoices struct {
	db *sql.DB
}

func NewInvoices(db *sql.DB) *Invoices {
	return &Invoices{db: db}
}

// достаёт счёт: строки отдельным запросом
func (r *Invoices) ByNumber(ctx context.Context, number invoice.Number) (*invoice.Invoice, error) {
	var (
		customer string
		minor    int64
		dueOn    time.Time
		status   string
	)

	err := conn(ctx, r.db).
		QueryRowContext(ctx, selectInvoice, string(number)).
		Scan(&customer, &minor, &dueOn, &status)
	if err != nil {
		return nil, err
	}

	lines, err := r.lines(ctx, number)
	if err != nil {
		return nil, err
	}

	// собирает агрегат, а не создаёт новый
	return invoice.Load(
		number,
		invoice.CustomerID(customer),
		lines,
		vo.NewMoney(minor),
		dueOn,
		invoice.Status(status),
	), nil
}

// сохраняет счёт и его строки — двумя запросами, одной транзакцией
func (r *Invoices) Save(ctx context.Context, saved *invoice.Invoice) error {
	db := conn(ctx, r.db)

	if _, err := db.ExecContext(ctx, upsertInvoice, saved); err != nil {
		return err
	}

	_, err := db.ExecContext(ctx, replaceLines, saved)

	return err
}

billing/invoice/infrastructure/postgres/uow.go

package postgres

import (
	"context"
	"database/sql"
)

type txKey struct{}

// транзакция, спрятанная за портом
type UnitOfWork struct {
	db *sql.DB
}

func NewUnitOfWork(db *sql.DB) *UnitOfWork {
	return &UnitOfWork{db: db}
}

// открыл, отдал работу, закрыл: коммит один на всю операцию
func (u *UnitOfWork) Do(ctx context.Context, work func(ctx context.Context) error) error {
	tx, err := u.db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}

	if err := work(context.WithValue(ctx, txKey{}, tx)); err != nil {
		// ошибка внутри — откат целиком
		_ = tx.Rollback()

		return err
	}

	return tx.Commit()
}

// адаптеры берут соединение отсюда: транзакция лежит в ctx
func conn(ctx context.Context, db *sql.DB) interface {
	ExecContext(context.Context, string, ...any) (sql.Result, error)
	QueryRowContext(context.Context, string, ...any) *sql.Row
} {
	if tx, ok := ctx.Value(txKey{}).(*sql.Tx); ok {
		return tx
	}

	return db
}

billing/invoice/infrastructure/postgres/outbox.go

package postgres

import (
	"context"
	"database/sql"
	"encoding/json"

	"billing/invoice/domains/invoice/events"
)

// реализация порта публикации
type Outbox struct {
	db *sql.DB
}

func NewOutbox(db *sql.DB) *Outbox {
	return &Outbox{db: db}
}

// факты не уезжают на шину, а ложатся строкой рядом со счётом
func (o *Outbox) Publish(ctx context.Context, facts ...events.Event) error {
	db := conn(ctx, o.db)

	for _, event := range facts {
		body, err := json.Marshal(event)
		if err != nil {
			return err
		}

		// та же транзакция, что у счёта
		if _, err := db.ExecContext(ctx, insertOutbox, event.FactName(), body); err != nil {
			return err
		}
	}

	return nil
}

Листать шаги можно стрелками ← и →.