Архитектура координатора

Карта кода. Читать сверху вниз: сначала «где что лежит», потом «как проходит запрос», в конце — «куда добавлять новое».

1. Четыре слоя

   infra       конфиг, пул БД, часы, HTTP-сервер, reaper    ← драйверы
   transport   HTTP-хендлеры          ← входящее: кто зовёт нас
   storage     репозитории на SQL     ← исходящее: кого зовём мы
   usecase     операции + ПОРТЫ (интерфейсы)                ← прикладные правила
   domain      Task, Job и их инварианты                    ← бизнес-правила

                       ┌── transport ──┐
   domain ◄── usecase ◄┤               ├◄── infra
                       └── storage ────┘

transport и storage — один и тот же слой (в книгах он зовётся «адаптеры»), просто разделённый по направлению: транспорт принимает запросы снаружи, storage обращается наружу сам. Так путь к файлу говорит о его роли, а не о категории.

Единственное правило: зависимости идут только внутрь. domain не импортирует ничего из проекта. usecase видит только domain. transport и storage не знают друг о друге.

Проверить в любой момент:

go list -f '{{range .Imports}}{{.}}{{"\n"}}{{end}}' ./internal/domain | grep internal
# пусто = правило соблюдено

2. Где что лежит

Файл	Что внутри	Строк
`domain/task.go`	`Task` и все переходы состояний: аренда, завершение, провал, истечение	~245
`domain/job.go`	`Job`, разбиение на чанки, вывод статуса из счётчиков задач	~107
`domain/errors.go`	Нарушения бизнес-правил (`ErrLeaseConflict`, `ErrStaleAttempt`, …)	~18
`usecase/ports.go`	Порты: `TaskRepository`, `JobRepository`, `TxManager`, `Clock`	~79
`usecase/task.go`	Операции над задачей: claim, renew, complete, fail, expire	~200
`usecase/job.go`	Операции над job: create, status, results, stitch	~180
`usecase/dto.go`	Входные структуры юзкейсов	~51
`transport/http/server.go`	Роутер и сборка middleware	~60
`transport/http/handlers.go`	По хендлеру на эндпоинт	~180
`transport/http/dto.go`	JSON-форматы запросов и ответов	~118
`transport/http/middleware.go`	request-ID, access-лог, bearer-авторизация	~103
`transport/http/errors.go`	Маппинг доменных ошибок в HTTP-коды	~55
`storage/postgres/task_repo.go`	SQL по задачам, включая атомарный claim	~109
`storage/postgres/job_repo.go`	SQL по job'ам	~39
`storage/postgres/tx.go`	`TxManager`: транзакция через контекст	~65
`infra/*.go`	Конфиг, пул, часы, сервер, reaper	~240
`cmd/coordinator/main.go`	Composition root — единственное место со всеми конкретными типами	~73

3. Трасса запроса: `POST /tasks/claim`

Как воркер получает задачу. Четыре остановки, по одной на слой:

  ①  transport/http/handlers.go → handleClaim
        разбирает JSON, отдаёт usecase.ClaimTaskInput
        │
        ▼
  ②  usecase/task.go → ClaimTask.Execute
        сначала подчищает протухшие аренды, потом просит одну задачу
        через ПОРТ TaskRepository (реализацию не знает)
        │
        ▼
  ③  usecase/ports.go → TaskRepository.ClaimNext
        контракт: «атомарно выдай одну задачу»
        │
        ▼
  ④  storage/postgres/task_repo.go → claimNextSQL
        SELECT ... FOR UPDATE SKIP LOCKED + UPDATE одним запросом

Обратно поднимается *domain.Task, юзкейс сужает его до domain.ClaimedTask (воркеру не отдаём version, max_attempts и чужие ошибки), хендлер превращает в JSON. Пустая очередь — это nil, nil на шаге ② и 204 на ①.

Трасса POST /tasks/{id}/result такая же, но с одним отличием: решение принимает сущность, а не юзкейс.

  handlers.go → CompleteTask.Execute → tx.WithinTx(
        GetForUpdate  →  task.CompleteWith(...)  ←── ЗДЕСЬ правила
                              │                      (чужая аренда? устаревший
        Update  ←─────────────┘                       attempt? повтор того же
        syncJobStatus                                 манифеста?)
  )

4. Куда добавлять новое

Хочу…	Правлю
новое бизнес-правило (когда задачу можно повторить)	`domain/task.go` + тест рядом
новую операцию (отменить job)	`usecase/job.go` + порт в `ports.go`, если нужен новый запрос к БД
новый HTTP-эндпоинт	`transport/http/handlers.go` + маршрут в `server.go` + DTO в `dto.go`
новый SQL-запрос	`storage/postgres/*_repo.go`
новую настройку	`infra/config.go` + `.env.example`
поменять код ответа на ошибку	`transport/http/errors.go`

Правило при сомнении: если код можно описать фразой «когда X, то Y» без упоминания HTTP, SQL и конфигов — это domain. Если он оркеструет несколько шагов и транзакцию — usecase. Если знает про JSON — transport, про SQL — storage.

5. Три вещи, которые надо понять один раз

Порты объявляет потребитель. TaskRepository описан в usecase/ports.go, а реализован в storage/postgres. Поэтому usecase не импортирует storage — стрелка зависимости смотрит внутрь, хотя вызов на рантайме идёт наружу.

Транзакция едет в контексте. TxManager.WithinTx кладёт pgx.Tx в контекст по неэкспортируемому ключу; репозитории достают её через conn(ctx, pool). Благодаря этому юзкейс говорит «сделай это атомарно», ни разу не упомянув pgx.

Атомарный claim нельзя разложить на шаги. ClaimNext — один SQL-запрос, потому что SELECT + отдельный UPDATE вернул бы гонку, при которой одну задачу выдают двум воркерам. Поэтому ClaimTask.Execute выглядит тонким: там нечего оркестровать, вся гарантия — внутри запроса.

6. Что уже работает, а что заглушка

Работает: слои и проводка, роутинг, авторизация, access-лог, маппинг ошибок, транзакции, graceful shutdown, миграции, весь domain с 12 юнит-тестами без БД.

Заглушки (ErrNotImplemented → HTTP 501): методы репозиториев. SQL для двух главных операций уже написан в task_repo.go — claimNextSQL и expireLeasesSQL, осталось их подключить.

8.4 KiB Raw Blame History Unescape Escape