Мини-проект: события в BackendStart (LessonCompleted → Achievements/Email/Analytics)
Мини-проект: события в BackendStart (LessonCompleted → Achievements/Email/Analytics)
В этом уроке мы соберём всё, что изучили за трек, в работающую систему. Возьмём реальный сценарий BackendStart: пользователь завершает урок, и это порождает цепочку побочных эффектов - проверку ачивок, запись аналитики, отправку уведомления. Каждый эффект реализован отдельным подписчиком. Ни один из них не знает о существовании остальных. Добавление нового подписчика - это один файл и одна строка регистрации. Брокера здесь намеренно нет: всё in-process, чтобы инфраструктура не прятала логику. Тот же сценарий, но уже с RabbitMQ и Kafka в docker-compose, собран в мини-проекте трека Message Brokers.
Мы реализуем: доменное событие, EventBus (in-process), outbox-таблицу, три подписчика, wiring в main.go и unit-тесты на подставной шине (раздел «Тестирование: FakeEventBus» в конце урока). Теория по каждому куску осталась в уроках выше - здесь только сборка.
Структура проекта
backend/
├── internal/
│ ├── domain/
│ │ └── events.go # Доменные события
│ ├── eventbus/
│ │ ├── bus.go # EventBus interface + in-process реализация
│ │ └── bus_test.go # Тесты EventBus
│ ├── outbox/
│ │ ├── repository.go # Outbox-таблица (запись + чтение)
│ │ └── poller.go # Outbox poller (горутина-отправитель)
│ ├── usecase/
│ │ └── complete_lesson.go # Use-case: завершение урока
│ └── subscribers/
│ ├── achievement_checker.go # Подписчик: проверка ачивок
│ ├── analytics_recorder.go # Подписчик: запись аналитики
│ └── notification_sender.go # Подписчик: отправка уведомления
└── cmd/
└── server/
└── main.go # Wiring: bus + subscribers + use-case
Domain Event: LessonCompleted
Доменное событие - это факт, который произошёл в системе. Имя в прошедшем времени, неизменяемые поля, event_id как натуральный ключ дедупликации - все правила разобраны в уроке про доменные события. Неизменяемая структура с временной меткой:
// domain/events.go
// LessonCompleted - доменное событие: пользователь завершил урок.
type LessonCompleted struct {
EventID string `json:"event_id"`
Type string `json:"type"` // всегда "lesson.completed"
CorrelationID string `json:"correlation_id"`
OccurredAt time.Time `json:"occurred_at"`
UserID int64 `json:"user_id"`
LessonID int64 `json:"lesson_id"`
TrackSlug string `json:"track_slug"`
LessonSlug string `json:"lesson_slug"`
}
// NewLessonCompleted создаёт событие с автоматическим event_id и timestamp.
func NewLessonCompleted(correlationID string, userID, lessonID int64, trackSlug, lessonSlug string) LessonCompleted {
return LessonCompleted{
EventID: ulid.Make().String(),
Type: "lesson.completed",
CorrelationID: correlationID,
OccurredAt: time.Now().UTC(),
UserID: userID,
LessonID: lessonID,
TrackSlug: trackSlug,
LessonSlug: lessonSlug,
}
}
// EventType реализует интерфейс eventbus.Event. Метод объявляется здесь,
// в пакете domain: Go не позволяет добавлять методы к типу из другого пакета.
func (e LessonCompleted) EventType() string { return e.Type }
<?php
// src/Domain/Event/LessonCompleted.php
declare(strict_types=1);
namespace App\Domain\Event;
use Symfony\Component\Uid\Uuid;
use DateTimeImmutable;
use DateTimeZone;
// final readonly - событие immutable по определению.
final readonly class LessonCompleted implements DomainEvent
{
public function __construct(
public string $eventId,
public string $correlationId,
public DateTimeImmutable $occurredAt,
public int $userId,
public int $lessonId,
public string $trackSlug,
public string $lessonSlug,
) {}
public static function create(
string $correlationId,
int $userId,
int $lessonId,
string $trackSlug,
string $lessonSlug,
): self {
return new self(
eventId: Uuid::v4()->toRfc4122(),
correlationId: $correlationId,
occurredAt: new DateTimeImmutable('now', new DateTimeZone('UTC')),
userId: $userId,
lessonId: $lessonId,
trackSlug: $trackSlug,
lessonSlug: $lessonSlug,
);
}
public function eventType(): string
{
return 'lesson.completed';
}
public function occurredAt(): DateTimeImmutable
{
return $this->occurredAt;
}
}
# domain/events.py
from __future__ import annotations
import uuid
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Any
@dataclass(frozen=True, slots=True)
class LessonCompleted:
"""Доменное событие: пользователь завершил урок.
frozen=True - событие immutable по определению.
"""
event_id: str
event_type: str # всегда "lesson.completed"
correlation_id: str
occurred_at: datetime
user_id: int
lesson_id: int
track_slug: str
lesson_slug: str
# to_dict/from_dict - аналог json-тегов в Go: ключи те же, что в payload outbox.
def to_dict(self) -> dict[str, Any]:
return {
"event_id": self.event_id,
"type": self.event_type,
"correlation_id": self.correlation_id,
"occurred_at": self.occurred_at.isoformat(),
"user_id": self.user_id,
"lesson_id": self.lesson_id,
"track_slug": self.track_slug,
"lesson_slug": self.lesson_slug,
}
@classmethod
def from_dict(cls, data: dict[str, Any]) -> LessonCompleted:
return cls(
event_id=data["event_id"],
event_type=data["type"],
correlation_id=data["correlation_id"],
occurred_at=datetime.fromisoformat(data["occurred_at"]),
user_id=int(data["user_id"]),
lesson_id=int(data["lesson_id"]),
track_slug=data["track_slug"],
lesson_slug=data["lesson_slug"],
)
def new_lesson_completed(
correlation_id: str,
user_id: int,
lesson_id: int,
track_slug: str,
lesson_slug: str,
) -> LessonCompleted:
"""Создаёт событие с автоматическим event_id и timestamp.
В Go - ULID; здесь uuid4 из stdlib (пакет python-ulid даст сортируемые id).
"""
return LessonCompleted(
event_id=str(uuid.uuid4()),
event_type="lesson.completed",
correlation_id=correlation_id,
occurred_at=datetime.now(timezone.utc),
user_id=user_id,
lesson_id=lesson_id,
track_slug=track_slug,
lesson_slug=lesson_slug,
)
Поле Type - строковая константа. Подписчики фильтруют события по этому полю. CorrelationID приходит из HTTP-middleware (см. урок 09).
EventBus: интерфейс и in-process реализация
EventBus - это порт (interface) в терминах Hexagonal Architecture. Use-case зависит от интерфейса, а не от конкретной реализации - именно поэтому in-process шину потом можно заменить на Kafka или RabbitMQ, не трогая бизнес-код (что при этом меняется в гарантиях - в уроке Event Bus vs Message Broker):
// eventbus/bus.go
// Event - обобщённый интерфейс события.
type Event interface {
EventType() string
}
// domain.LessonCompleted реализует Event методом EventType() в пакете domain.
// Handler - функция-обработчик события.
type Handler func(ctx context.Context, event Event) error
// EventBus - порт для публикации и подписки на события.
type EventBus interface {
// Publish отправляет событие всем зарегистрированным подписчикам.
Publish(ctx context.Context, event Event) error
// Subscribe регистрирует обработчик для данного типа события.
Subscribe(eventType string, handler Handler)
}
<?php
// src/Application/Port/EventBus.php
declare(strict_types=1);
namespace App\Application\Port;
use App\Domain\Event\DomainEvent;
// final НЕ ставится на interface.
interface EventBus
{
public function publish(DomainEvent $event): void;
public function subscribe(string $eventClass, callable $handler): void;
}
# eventbus/bus.py
from __future__ import annotations
from typing import Callable, Protocol
class Event(Protocol):
"""Обобщённый интерфейс события. Protocol сверяется структурно:
LessonCompleted подходит за счёт поля event_type, отдельный метод не нужен.
"""
@property
def event_type(self) -> str: ...
# Handler - функция-обработчик события. context.Context в сигнатуре нет:
# correlation_id едет внутри события, отмена - через исключения.
Handler = Callable[[Event], None]
class EventBus(Protocol):
"""Порт для публикации и подписки на события."""
def publish(self, event: Event) -> None:
"""Отправляет событие всем зарегистрированным подписчикам."""
def subscribe(self, event_type: str, handler: Handler) -> None:
"""Регистрирует обработчик для данного типа события."""
In-process реализация - подходит для монолита и для начала разработки. Позже можно заменить на Kafka/NATS без изменения use-case:
// eventbus/bus.go
// InProcessBus - реализация EventBus через Go channels.
// Подписчики вызываются асинхронно в отдельных горутинах.
type InProcessBus struct {
mu sync.RWMutex
handlers map[string][]Handler
}
// NewInProcessBus создаёт bus.
func NewInProcessBus() *InProcessBus {
return &InProcessBus{
handlers: make(map[string][]Handler),
}
}
// Subscribe регистрирует обработчик для типа события.
func (b *InProcessBus) Subscribe(eventType string, handler Handler) {
b.mu.Lock()
defer b.mu.Unlock()
b.handlers[eventType] = append(b.handlers[eventType], handler)
}
// Publish отправляет событие всем подписчикам данного типа.
// Каждый подписчик вызывается в отдельной горутине.
// Ошибка одного подписчика не останавливает остальных, но в конце все ошибки
// возвращаются вызывающему (errors.Join): иначе poller отметил бы событие
// опубликованным, и сбой подписчика тихо потерял бы эффект.
func (b *InProcessBus) Publish(ctx context.Context, event Event) error {
b.mu.RLock()
handlers := b.handlers[event.EventType()]
b.mu.RUnlock()
var (
wg sync.WaitGroup
mu sync.Mutex
errs []error
)
for _, h := range handlers {
wg.Add(1)
go func(handler Handler) {
defer wg.Done()
if err := handler(ctx, event); err != nil {
slog.ErrorContext(ctx, "subscriber failed",
slog.String("event_type", event.EventType()),
slog.String("err", err.Error()),
)
mu.Lock()
errs = append(errs, err)
mu.Unlock()
}
}(h)
}
wg.Wait()
return errors.Join(errs...) // nil, если ошибок не было
}
<?php
// src/Infrastructure/EventBus/InProcessBus.php
declare(strict_types=1);
namespace App\Infrastructure\EventBus;
use App\Application\Port\EventBus;
use App\Domain\Event\DomainEvent;
use Psr\Log\LoggerInterface;
use Throwable;
use RuntimeException;
// PHP-FPM однопоточный per request - подписчики выполняются последовательно,
// без горутин. Для параллельной обработки используй Symfony Messenger
// с async-транспортом (Redis Streams/AMQP) и несколькими workers.
final class InProcessBus implements EventBus
{
/** @var array<string, list<callable>> */
private array $handlers = [];
public function __construct(
private readonly LoggerInterface $logger,
) {}
public function subscribe(string $eventClass, callable $handler): void
{
$this->handlers[$eventClass][] = $handler;
}
// Ошибка одного подписчика не останавливает остальных, но в конце
// бросаем исключение: иначе poller отметит событие опубликованным,
// и сбой подписчика тихо потеряет эффект.
public function publish(DomainEvent $event): void
{
$errors = [];
foreach ($this->handlers[$event::class] ?? [] as $handler) {
try {
$handler($event);
} catch (Throwable $e) {
$this->logger->error('subscriber failed', [
'event_type' => $event->eventType(),
'err' => $e->getMessage(),
]);
$errors[] = $e;
}
}
if ($errors !== []) {
throw new RuntimeException(
sprintf('%d subscriber(s) failed for %s', count($errors), $event->eventType()),
previous: $errors[0],
);
}
}
}
# eventbus/bus.py (продолжение)
import logging
import threading
from collections import defaultdict
from concurrent.futures import ThreadPoolExecutor, wait
logger = logging.getLogger(__name__)
class InProcessBus:
"""Реализация EventBus на пуле потоков (аналог горутин + WaitGroup).
Подписчики вызываются параллельно. Не asyncio, потому что подписчики
ходят в БД синхронным psycopg.
"""
def __init__(self, max_workers: int = 8) -> None:
self._lock = threading.Lock()
self._handlers: dict[str, list[Handler]] = defaultdict(list)
self._pool = ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="eventbus")
def subscribe(self, event_type: str, handler: Handler) -> None:
"""Регистрирует обработчик для типа события."""
with self._lock:
self._handlers[event_type].append(handler)
def publish(self, event: Event) -> None:
"""Отправляет событие всем подписчикам данного типа.
Каждый подписчик выполняется в отдельном потоке пула.
Ошибка одного подписчика не останавливает остальных, но в конце все
ошибки пробрасываются (ExceptionGroup): иначе poller отметит событие
опубликованным, и сбой подписчика тихо потеряет эффект.
"""
with self._lock:
handlers = list(self._handlers.get(event.event_type, []))
futures = [self._pool.submit(self._run, handler, event) for handler in handlers]
wait(futures) # аналог wg.Wait()
errors = [exc for f in futures if (exc := f.exception()) is not None]
if errors:
raise ExceptionGroup(f"{len(errors)} subscriber(s) failed", errors)
def _run(self, handler: Handler, event: Event) -> None:
try:
handler(event)
except Exception as exc:
logger.error(
"subscriber failed",
extra={"event_type": event.event_type, "err": str(exc)},
)
raise # ошибка попадёт в future и вернётся из publish
Use-case: CompleteLesson с outbox
Use-case завершает урок, сохраняет прогресс и записывает событие в outbox - всё в одной транзакции. После коммита публикует событие в in-process bus для немедленной обработки и, если все подписчики отработали, сразу отмечает строку outbox опубликованной - иначе poller через полсекунды разослал бы то же событие второй раз. Зачем этот крюк через таблицу вместо прямого Publish - в разборе dual-write проблемы в уроке про outbox и inbox:
// usecase/complete_lesson.go
// CompleteLessonUseCase - завершение урока с публикацией события.
type CompleteLessonUseCase struct {
db *sql.DB
outbox *outbox.Repository
bus eventbus.EventBus
}
// NewCompleteLessonUseCase создаёт use-case с зависимостями.
func NewCompleteLessonUseCase(db *sql.DB, outbox *outbox.Repository, bus eventbus.EventBus) *CompleteLessonUseCase {
return &CompleteLessonUseCase{db: db, outbox: outbox, bus: bus}
}
// Execute завершает урок для пользователя.
func (uc *CompleteLessonUseCase) Execute(ctx context.Context, req CompleteLessonRequest) error {
// Создаём доменное событие
evt := domain.NewLessonCompleted(
middleware.CorrelationFromCtx(ctx),
req.UserID, req.LessonID,
req.TrackSlug, req.LessonSlug,
)
// Сериализуем payload для outbox
payload, err := json.Marshal(evt)
if err != nil {
return fmt.Errorf("marshal event: %w", err)
}
// Транзакция: прогресс + outbox
tx, err := uc.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
defer tx.Rollback()
// 1. Обновляем прогресс. completed = false в условии: повторный PUT
// (двойной клик, ретрай клиента) не должен порождать новый факт.
res, err := tx.ExecContext(ctx,
`UPDATE lesson_progress
SET completed = true, completed_at = now()
WHERE user_id = $1 AND lesson_id = $2 AND completed = false`,
req.UserID, req.LessonID,
)
if err != nil {
return fmt.Errorf("update progress: %w", err)
}
n, err := res.RowsAffected()
if err != nil {
return fmt.Errorf("rows affected: %w", err)
}
if n == 0 {
return nil // урок уже завершён (или прогресса нет): события нет
}
// 2. Записываем событие в outbox (в той же транзакции)
_, err = tx.ExecContext(ctx,
`INSERT INTO outbox (event_id, event_type, payload)
VALUES ($1, $2, $3)`,
evt.EventID, evt.Type, payload,
)
if err != nil {
return fmt.Errorf("insert outbox: %w", err)
}
if err := tx.Commit(); err != nil {
return fmt.Errorf("commit: %w", err)
}
// После коммита: публикуем в in-process bus для немедленной обработки.
// Путь доставки один - строка outbox: если все подписчики отработали,
// отмечаем её опубликованной, иначе её дошлёт poller.
if pubErr := uc.bus.Publish(ctx, evt); pubErr != nil {
slog.WarnContext(ctx, "in-process publish failed, outbox poller will retry",
slog.String("event_id", evt.EventID),
slog.String("err", pubErr.Error()),
)
return nil
}
if err := uc.outbox.MarkPublishedByEventID(ctx, evt.EventID); err != nil {
// Не страшно: poller пришлёт событие ещё раз, подписчики идемпотентны
slog.WarnContext(ctx, "outbox mark failed",
slog.String("event_id", evt.EventID),
slog.String("err", err.Error()),
)
}
return nil
}
<?php
// src/Application/UseCase/CompleteLessonUseCase.php
declare(strict_types=1);
namespace App\Application\UseCase;
use App\Application\Port\EventBus;
use App\Application\Port\OutboxRepository;
use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Throwable;
final readonly class CompleteLessonRequest
{
public function __construct(
public int $userId,
public int $lessonId,
public string $trackSlug,
public string $lessonSlug,
public string $correlationId,
) {}
}
final class CompleteLessonUseCase
{
public function __construct(
private readonly Connection $connection,
private readonly OutboxRepository $outbox,
private readonly EventBus $bus,
private readonly LoggerInterface $logger,
) {}
public function execute(CompleteLessonRequest $req): void
{
$event = LessonCompleted::create(
correlationId: $req->correlationId,
userId: $req->userId,
lessonId: $req->lessonId,
trackSlug: $req->trackSlug,
lessonSlug: $req->lessonSlug,
);
// Транзакция: progress + outbox. completed = false в условии: повторный
// запрос (двойной клик, ретрай клиента) не должен порождать новый факт.
$created = $this->connection->transactional(function (Connection $tx) use ($req, $event): bool {
$affected = $tx->executeStatement(
'UPDATE lesson_progress SET completed = true, completed_at = now()
WHERE user_id = :user_id AND lesson_id = :lesson_id AND completed = false',
['user_id' => $req->userId, 'lesson_id' => $req->lessonId],
);
if ($affected === 0) {
return false; // урок уже завершён (или прогресса нет): события нет
}
$this->outbox->saveInTx($tx, $event);
return true;
});
if (!$created) {
return;
}
// После коммита: пробуем сразу опубликовать в in-process bus.
// Путь доставки один - строка outbox: если все подписчики отработали,
// отмечаем её опубликованной, иначе её дошлёт poller.
try {
$this->bus->publish($event);
} catch (Throwable $e) {
$this->logger->warning('in-process publish failed, outbox poller will retry', [
'event_id' => $event->eventId,
'err' => $e->getMessage(),
]);
return;
}
// Если отметка упадёт, poller пришлёт событие ещё раз - подписчики идемпотентны
$this->outbox->markPublishedByEventId($event->eventId);
}
}
# usecase/complete_lesson.py
from __future__ import annotations
import logging
from dataclasses import dataclass
from psycopg.types.json import Jsonb
from psycopg_pool import ConnectionPool
from backend.domain.events import new_lesson_completed
from backend.eventbus.bus import EventBus
from backend.middleware.correlation import correlation_from_ctx
from backend.outbox.repository import Repository
logger = logging.getLogger(__name__)
@dataclass(frozen=True, slots=True)
class CompleteLessonRequest:
user_id: int
lesson_id: int
track_slug: str
lesson_slug: str
class CompleteLessonUseCase:
"""Завершение урока с публикацией события.
ConnectionPool - аналог *sql.DB: пул соединений, безопасен для потоков.
"""
def __init__(self, pool: ConnectionPool, outbox: Repository, bus: EventBus) -> None:
self._pool = pool
self._outbox = outbox
self._bus = bus
def execute(self, req: CompleteLessonRequest) -> None:
"""Завершает урок для пользователя.
Ошибки БД не оборачиваются в error, а летят исключениями psycopg.
"""
# Создаём доменное событие; correlation_id - из contextvar,
# который заполнил HTTP-middleware (аналог ctx.Value в Go)
evt = new_lesson_completed(
correlation_from_ctx(),
req.user_id, req.lesson_id,
req.track_slug, req.lesson_slug,
)
# Сериализуем payload для outbox (Jsonb - адаптер для колонки JSONB)
payload = Jsonb(evt.to_dict())
# Транзакция: прогресс + outbox.
# conn.transaction() - commit на выходе, rollback при исключении
with self._pool.connection() as conn, conn.transaction():
# 1. Обновляем прогресс. completed = false в условии: повторный запрос
# (двойной клик, ретрай клиента) не должен порождать новый факт.
cur = conn.execute(
"""UPDATE lesson_progress
SET completed = true, completed_at = now()
WHERE user_id = %s AND lesson_id = %s AND completed = false""",
(req.user_id, req.lesson_id),
)
if cur.rowcount == 0:
return # урок уже завершён (или прогресса нет): события нет
# 2. Записываем событие в outbox (в той же транзакции)
conn.execute(
"""INSERT INTO outbox (event_id, event_type, payload)
VALUES (%s, %s, %s)""",
(evt.event_id, evt.event_type, payload),
)
# После коммита: публикуем в in-process bus для немедленной обработки.
# Путь доставки один - строка outbox: если все подписчики отработали,
# отмечаем её опубликованной, иначе её дошлёт poller.
try:
self._bus.publish(evt)
except Exception as exc:
logger.warning(
"in-process publish failed, outbox poller will retry",
extra={"event_id": evt.event_id, "err": str(exc)},
)
return
# Если отметка упадёт, poller пришлёт событие ещё раз - подписчики идемпотентны
self._outbox.mark_published_by_event_id(evt.event_id)
Обратите внимание: ошибка bus.Publish не приводит к ошибке use-case. Данные уже закоммичены, а событие лежит в outbox неотмеченным - значит есть что дослать. Это работает только потому, что Publish возвращает ошибки подписчиков, а не глотает их: иначе use-case и poller отмечали бы событие опубликованным даже после сбоя подписчика. Доставка остаётся at-least-once: poller может успеть взять строку до отметки, а при повторе событие снова получат все подписчики, в том числе уже отработавшие. Поэтому каждый подписчик обязан быть идемпотентным (дедупликация по event_id и имени обработчика, урок 6).
Подписчик 1: AchievementChecker
Проверяет, заработал ли пользователь бейдж после завершения урока. Подписчик обязан выдержать повторную доставку того же события, поэтому запись идёт через UPSERT, а не INSERT - остальные приёмы в уроке про идемпотентность:
// subscribers/achievement_checker.go
// AchievementChecker проверяет условия ачивок при завершении урока.
type AchievementChecker struct {
db *sql.DB
}
func NewAchievementChecker(db *sql.DB) *AchievementChecker {
return &AchievementChecker{db: db}
}
// Handle обрабатывает событие lesson.completed.
func (a *AchievementChecker) Handle(ctx context.Context, event eventbus.Event) error {
evt, ok := event.(domain.LessonCompleted)
if !ok {
return fmt.Errorf("unexpected event type: %T", event)
}
slog.InfoContext(ctx, "checking achievements",
slog.Int64("user_id", evt.UserID),
slog.String("track_slug", evt.TrackSlug),
slog.String("correlation_id", evt.CorrelationID),
)
// Подсчитываем завершённые уроки в треке
var completedCount int
err := a.db.QueryRowContext(ctx,
`SELECT COUNT(*) FROM lesson_progress
WHERE user_id = $1 AND track_slug = $2 AND completed = true`,
evt.UserID, evt.TrackSlug,
).Scan(&completedCount)
if err != nil {
return fmt.Errorf("count completed: %w", err)
}
// Проверяем условия ачивок
achievements := checkAchievementRules(evt.TrackSlug, completedCount)
for _, achievement := range achievements {
// UPSERT - идемпотентно: повторный вызов не создаёт дубль
_, err := a.db.ExecContext(ctx,
`INSERT INTO user_achievements (user_id, achievement_slug, earned_at)
VALUES ($1, $2, now())
ON CONFLICT (user_id, achievement_slug) DO NOTHING`,
evt.UserID, achievement,
)
if err != nil {
slog.ErrorContext(ctx, "grant achievement failed",
slog.String("achievement", achievement),
slog.String("err", err.Error()),
)
}
}
return nil
}
// checkAchievementRules возвращает список заслуженных ачивок.
func checkAchievementRules(trackSlug string, completedCount int) []string {
var result []string
if completedCount >= 1 {
result = append(result, "first_lesson")
}
if completedCount >= 5 {
result = append(result, "five_lessons")
}
if completedCount >= 10 {
result = append(result, fmt.Sprintf("track_%s_master", trackSlug))
}
return result
}
<?php
// src/Application/Subscriber/AchievementChecker.php
declare(strict_types=1);
namespace App\Application\Subscriber;
use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;
#[AsMessageHandler]
final class AchievementChecker
{
public function __construct(
private readonly Connection $connection,
private readonly LoggerInterface $logger,
) {}
public function __invoke(LessonCompleted $event): void
{
$this->logger->info('checking achievements', [
'user_id' => $event->userId,
'track_slug' => $event->trackSlug,
'correlation_id' => $event->correlationId,
]);
$completedCount = (int) $this->connection->fetchOne(
'SELECT COUNT(*) FROM lesson_progress
WHERE user_id = :uid AND track_slug = :slug AND completed = true',
['uid' => $event->userId, 'slug' => $event->trackSlug],
);
foreach ($this->checkAchievementRules($event->trackSlug, $completedCount) as $achievement) {
// UPSERT - идемпотентно: повторный вызов не создаёт дубль
$this->connection->executeStatement(
'INSERT INTO user_achievements (user_id, achievement_slug, earned_at)
VALUES (:uid, :slug, now())
ON CONFLICT (user_id, achievement_slug) DO NOTHING',
['uid' => $event->userId, 'slug' => $achievement],
);
}
}
/** @return list<string> */
private function checkAchievementRules(string $trackSlug, int $completedCount): array
{
$result = [];
if ($completedCount >= 1) {
$result[] = 'first_lesson';
}
if ($completedCount >= 5) {
$result[] = 'five_lessons';
}
if ($completedCount >= 10) {
$result[] = sprintf('track_%s_master', $trackSlug);
}
return $result;
}
}
# subscribers/achievement_checker.py
from __future__ import annotations
import logging
import psycopg
from psycopg_pool import ConnectionPool
from backend.domain.events import LessonCompleted
from backend.eventbus.bus import Event
logger = logging.getLogger(__name__)
class AchievementChecker:
"""Проверяет условия ачивок при завершении урока."""
def __init__(self, pool: ConnectionPool) -> None:
self._pool = pool
def handle(self, event: Event) -> None:
"""Обрабатывает событие lesson.completed."""
if not isinstance(event, LessonCompleted):
raise TypeError(f"unexpected event type: {type(event).__name__}")
evt = event
logger.info(
"checking achievements",
extra={
"user_id": evt.user_id,
"track_slug": evt.track_slug,
"correlation_id": evt.correlation_id,
},
)
# pool.connection() - commit на выходе из with, rollback при исключении
with self._pool.connection() as conn:
# Подсчитываем завершённые уроки в треке
row = conn.execute(
"""SELECT COUNT(*) FROM lesson_progress
WHERE user_id = %s AND track_slug = %s AND completed = true""",
(evt.user_id, evt.track_slug),
).fetchone()
completed_count = int(row[0]) if row else 0
# Проверяем условия ачивок
for achievement in check_achievement_rules(evt.track_slug, completed_count):
# UPSERT - идемпотентно: повторный вызов не создаёт дубль
try:
conn.execute(
"""INSERT INTO user_achievements (user_id, achievement_slug, earned_at)
VALUES (%s, %s, now())
ON CONFLICT (user_id, achievement_slug) DO NOTHING""",
(evt.user_id, achievement),
)
except psycopg.Error as exc:
logger.error(
"grant achievement failed",
extra={"achievement": achievement, "err": str(exc)},
)
def check_achievement_rules(track_slug: str, completed_count: int) -> list[str]:
"""Возвращает список заслуженных ачивок."""
result: list[str] = []
if completed_count >= 1:
result.append("first_lesson")
if completed_count >= 5:
result.append("five_lessons")
if completed_count >= 10:
result.append(f"track_{track_slug}_master")
return result
Подписчик 2: AnalyticsRecorder
Записывает факт завершения урока для статистики:
// subscribers/analytics_recorder.go
// AnalyticsRecorder записывает метрику завершения урока.
type AnalyticsRecorder struct {
db *sql.DB
}
func NewAnalyticsRecorder(db *sql.DB) *AnalyticsRecorder {
return &AnalyticsRecorder{db: db}
}
// Handle записывает событие в таблицу аналитики.
func (a *AnalyticsRecorder) Handle(ctx context.Context, event eventbus.Event) error {
evt, ok := event.(domain.LessonCompleted)
if !ok {
return fmt.Errorf("unexpected event type: %T", event)
}
// UPSERT: идемпотентно - повторный вызов обновляет timestamp
_, err := a.db.ExecContext(ctx,
`INSERT INTO analytics_events (event_id, event_type, user_id, track_slug, lesson_slug, occurred_at)
VALUES ($1, $2, $3, $4, $5, $6)
ON CONFLICT (event_id) DO NOTHING`,
evt.EventID, evt.Type, evt.UserID,
evt.TrackSlug, evt.LessonSlug, evt.OccurredAt,
)
if err != nil {
return fmt.Errorf("insert analytics: %w", err)
}
slog.InfoContext(ctx, "analytics event recorded",
slog.String("event_id", evt.EventID),
slog.Int64("user_id", evt.UserID),
slog.String("correlation_id", evt.CorrelationID),
)
return nil
}
<?php
// src/Application/Subscriber/AnalyticsRecorder.php
declare(strict_types=1);
namespace App\Application\Subscriber;
use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;
#[AsMessageHandler]
final class AnalyticsRecorder
{
public function __construct(
private readonly Connection $connection,
private readonly LoggerInterface $logger,
) {}
public function __invoke(LessonCompleted $event): void
{
// ON CONFLICT DO NOTHING - идемпотентно по event_id
$this->connection->executeStatement(
'INSERT INTO analytics_events (event_id, event_type, user_id, track_slug, lesson_slug, occurred_at)
VALUES (:eid, :etype, :uid, :track, :lesson, :occurred)
ON CONFLICT (event_id) DO NOTHING',
[
'eid' => $event->eventId,
'etype' => $event->eventType(),
'uid' => $event->userId,
'track' => $event->trackSlug,
'lesson' => $event->lessonSlug,
'occurred' => $event->occurredAt->format('Y-m-d H:i:s'),
],
);
$this->logger->info('analytics event recorded', [
'event_id' => $event->eventId,
'user_id' => $event->userId,
'correlation_id' => $event->correlationId,
]);
}
}
# subscribers/analytics_recorder.py
from __future__ import annotations
import logging
from psycopg_pool import ConnectionPool
from backend.domain.events import LessonCompleted
from backend.eventbus.bus import Event
logger = logging.getLogger(__name__)
class AnalyticsRecorder:
"""Записывает метрику завершения урока."""
def __init__(self, pool: ConnectionPool) -> None:
self._pool = pool
def handle(self, event: Event) -> None:
"""Записывает событие в таблицу аналитики.
Ошибка INSERT летит исключением psycopg - bus залогирует "subscriber failed".
"""
if not isinstance(event, LessonCompleted):
raise TypeError(f"unexpected event type: {type(event).__name__}")
evt = event
# UPSERT: идемпотентно - повторный вызов не создаёт дубль
with self._pool.connection() as conn:
conn.execute(
"""INSERT INTO analytics_events (event_id, event_type, user_id, track_slug, lesson_slug, occurred_at)
VALUES (%s, %s, %s, %s, %s, %s)
ON CONFLICT (event_id) DO NOTHING""",
(
evt.event_id, evt.event_type, evt.user_id,
evt.track_slug, evt.lesson_slug, evt.occurred_at,
),
)
logger.info(
"analytics event recorded",
extra={
"event_id": evt.event_id,
"user_id": evt.user_id,
"correlation_id": evt.correlation_id,
},
)
Подписчик 3: NotificationSender
Отправляет поздравление пользователю (заглушка - в реальности это может быть email, push или in-app уведомление):
// subscribers/notification_sender.go
// NotificationSender отправляет уведомление при завершении урока.
type NotificationSender struct {
notifier Notifier
}
// Notifier - порт для отправки уведомлений.
type Notifier interface {
Send(ctx context.Context, userID int64, message string) error
}
func NewNotificationSender(notifier Notifier) *NotificationSender {
return &NotificationSender{notifier: notifier}
}
// Handle отправляет поздравление.
func (n *NotificationSender) Handle(ctx context.Context, event eventbus.Event) error {
evt, ok := event.(domain.LessonCompleted)
if !ok {
return fmt.Errorf("unexpected event type: %T", event)
}
message := fmt.Sprintf("Отлично! Вы завершили урок %q в треке %q.",
evt.LessonSlug, evt.TrackSlug)
if err := n.notifier.Send(ctx, evt.UserID, message); err != nil {
return fmt.Errorf("send notification: %w", err)
}
slog.InfoContext(ctx, "notification sent",
slog.Int64("user_id", evt.UserID),
slog.String("correlation_id", evt.CorrelationID),
)
return nil
}
<?php
// src/Application/Subscriber/NotificationSender.php
declare(strict_types=1);
namespace App\Application\Subscriber;
use App\Application\Port\NotifierPort;
use App\Domain\Event\LessonCompleted;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;
#[AsMessageHandler]
final class NotificationSender
{
public function __construct(
private readonly NotifierPort $notifier,
private readonly LoggerInterface $logger,
) {}
public function __invoke(LessonCompleted $event): void
{
$message = sprintf(
"Отлично! Вы завершили урок '%s' в треке '%s'.",
$event->lessonSlug,
$event->trackSlug,
);
$this->notifier->send($event->userId, $message);
$this->logger->info('notification sent', [
'user_id' => $event->userId,
'correlation_id' => $event->correlationId,
]);
}
}
# subscribers/notification_sender.py
from __future__ import annotations
import logging
from typing import Protocol
from backend.domain.events import LessonCompleted
from backend.eventbus.bus import Event
logger = logging.getLogger(__name__)
class Notifier(Protocol):
"""Порт для отправки уведомлений."""
def send(self, user_id: int, message: str) -> None: ...
class NotificationSender:
"""Отправляет уведомление при завершении урока."""
def __init__(self, notifier: Notifier) -> None:
self._notifier = notifier
def handle(self, event: Event) -> None:
"""Отправляет поздравление."""
if not isinstance(event, LessonCompleted):
raise TypeError(f"unexpected event type: {type(event).__name__}")
evt = event
message = f'Отлично! Вы завершили урок "{evt.lesson_slug}" в треке "{evt.track_slug}".'
# Ошибка отправки летит исключением наверх - bus залогирует её
self._notifier.send(evt.user_id, message)
logger.info(
"notification sent",
extra={"user_id": evt.user_id, "correlation_id": evt.correlation_id},
)
⚠️ NotificationSender пока не идемпотентен
AchievementChecker защищён UPSERT-ом, AnalyticsRecorder - дедупликацией по
event_id, а уведомление при повторной доставке уйдёт второй раз. Повтор случается: poller может успеть взять строку outbox до отметки из use-case, а при сбое одного подписчика событие заново получат все. Для настоящей отправки добавь дедупликацию по(event_id, handler)через таблицуprocessed_events, как в уроке про идемпотентность, или передавайevent_idпровайдеру как ключ идемпотентности.
Outbox: DDL и Repository
CREATE TABLE outbox (
id BIGSERIAL PRIMARY KEY,
event_id VARCHAR(64) NOT NULL UNIQUE,
event_type VARCHAR(128) NOT NULL,
payload JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
published_at TIMESTAMPTZ,
attempts INT NOT NULL DEFAULT 0
);
CREATE INDEX idx_outbox_unpublished
ON outbox (created_at)
WHERE published_at IS NULL;
// outbox/repository.go
// Repository предоставляет доступ к outbox-таблице.
type Repository struct {
db *sql.DB
}
func NewRepository(db *sql.DB) *Repository {
return &Repository{db: db}
}
// FetchUnpublished возвращает пачку неотправленных событий без блокировки.
// Для тестов и отладки; poller берёт строки через claimBatch.
func (r *Repository) FetchUnpublished(ctx context.Context, limit int) ([]OutboxEntry, error) {
rows, err := r.db.QueryContext(ctx,
`SELECT id, event_id, event_type, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY created_at
LIMIT $1`,
limit,
)
if err != nil {
return nil, fmt.Errorf("query outbox: %w", err)
}
defer rows.Close()
var entries []OutboxEntry
for rows.Next() {
var e OutboxEntry
if err := rows.Scan(&e.ID, &e.EventID, &e.EventType, &e.Payload); err != nil {
return nil, fmt.Errorf("scan: %w", err)
}
entries = append(entries, e)
}
return entries, rows.Err()
}
// claimBatch забирает пачку неопубликованных событий, блокируя строки
// от других экземпляров поллера до конца транзакции tx (как в уроке 7).
// Пачка считывается целиком и rows закрывается до публикаций.
func (r *Repository) claimBatch(ctx context.Context, tx *sql.Tx, limit int) ([]OutboxEntry, error) {
rows, err := tx.QueryContext(ctx,
`SELECT id, event_id, event_type, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY created_at
LIMIT $1
FOR UPDATE SKIP LOCKED`,
limit,
)
if err != nil {
return nil, fmt.Errorf("query outbox: %w", err)
}
defer rows.Close()
var entries []OutboxEntry
for rows.Next() {
var e OutboxEntry
if err := rows.Scan(&e.ID, &e.EventID, &e.EventType, &e.Payload); err != nil {
return nil, fmt.Errorf("scan: %w", err)
}
entries = append(entries, e)
}
return entries, rows.Err()
}
// MarkPublishedByEventID отмечает событие отправленным после немедленной
// публикации из use-case. Если строку уже отметил poller - ничего не меняет.
func (r *Repository) MarkPublishedByEventID(ctx context.Context, eventID string) error {
_, err := r.db.ExecContext(ctx,
`UPDATE outbox SET published_at = now()
WHERE event_id = $1 AND published_at IS NULL`, eventID)
return err
}
<?php
// src/Infrastructure/Outbox/OutboxRepository.php
declare(strict_types=1);
namespace App\Infrastructure\Outbox;
use App\Application\Port\OutboxRepository as OutboxRepositoryPort;
use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use DateTimeInterface;
final readonly class OutboxEntry
{
public function __construct(
public int $id,
public string $eventId,
public string $eventType,
public string $payload,
) {}
}
final class OutboxRepository implements OutboxRepositoryPort
{
public function __construct(
private readonly Connection $connection,
) {}
public function saveInTx(Connection $tx, LessonCompleted $event): void
{
$tx->insert('outbox', [
'event_id' => $event->eventId,
'event_type' => $event->eventType(),
'payload' => json_encode([
'event_id' => $event->eventId,
'correlation_id' => $event->correlationId,
'occurred_at' => $event->occurredAt->format(DateTimeInterface::RFC3339),
'user_id' => $event->userId,
'lesson_id' => $event->lessonId,
'track_slug' => $event->trackSlug,
'lesson_slug' => $event->lessonSlug,
], JSON_THROW_ON_ERROR),
]);
}
/**
* Неотправленные события без блокировки - для тестов и отладки.
*
* @return list<OutboxEntry>
*/
public function fetchUnpublished(int $limit): array
{
return $this->toEntries($this->connection->fetchAllAssociative(
'SELECT id, event_id, event_type, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY created_at
LIMIT :lim',
['lim' => $limit],
));
}
/**
* Забирает пачку для poller-а, блокируя строки до конца транзакции $tx.
* SKIP LOCKED работает только внутри транзакции: в autocommit блокировка
* снялась бы сразу после SELECT.
*
* @return list<OutboxEntry>
*/
public function claimBatch(Connection $tx, int $limit): array
{
return $this->toEntries($tx->fetchAllAssociative(
'SELECT id, event_id, event_type, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY created_at
LIMIT :lim
FOR UPDATE SKIP LOCKED',
['lim' => $limit],
));
}
/**
* @param list<array<string, mixed>> $rows
* @return list<OutboxEntry>
*/
private function toEntries(array $rows): array
{
return array_map(
static fn(array $r) => new OutboxEntry(
id: (int) $r['id'],
eventId: $r['event_id'],
eventType: $r['event_type'],
payload: (string) $r['payload'],
),
$rows,
);
}
public function markPublished(Connection $tx, int $id): void
{
$tx->executeStatement(
'UPDATE outbox SET published_at = now() WHERE id = :id',
['id' => $id],
);
}
public function bumpAttempts(Connection $tx, int $id): void
{
$tx->executeStatement(
'UPDATE outbox SET attempts = attempts + 1 WHERE id = :id',
['id' => $id],
);
}
// Отметка после немедленной публикации из use-case. Если строку уже
// отметил poller - ничего не меняет.
public function markPublishedByEventId(string $eventId): void
{
$this->connection->executeStatement(
'UPDATE outbox SET published_at = now()
WHERE event_id = :event_id AND published_at IS NULL',
['event_id' => $eventId],
);
}
}
# outbox/repository.py
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from psycopg import Connection
from psycopg_pool import ConnectionPool
@dataclass(frozen=True, slots=True)
class OutboxEntry:
id: int
event_id: str
event_type: str
payload: dict[str, Any] # JSONB psycopg отдаёт уже распарсенным dict
class Repository:
"""Предоставляет доступ к outbox-таблице."""
def __init__(self, pool: ConnectionPool) -> None:
self._pool = pool
def fetch_unpublished(self, limit: int) -> list[OutboxEntry]:
"""Возвращает пачку неотправленных событий без блокировки (для тестов и отладки)."""
with self._pool.connection() as conn:
rows = conn.execute(
"""SELECT id, event_id, event_type, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY created_at
LIMIT %s""",
(limit,),
).fetchall()
return [
OutboxEntry(id=row[0], event_id=row[1], event_type=row[2], payload=row[3])
for row in rows
]
def claim_batch(self, conn: Connection, limit: int) -> list[OutboxEntry]:
"""Забирает пачку для poller-а, блокируя строки до конца транзакции conn."""
rows = conn.execute(
"""SELECT id, event_id, event_type, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY created_at
LIMIT %s
FOR UPDATE SKIP LOCKED""",
(limit,),
).fetchall()
return [
OutboxEntry(id=row[0], event_id=row[1], event_type=row[2], payload=row[3])
for row in rows
]
def mark_published_by_event_id(self, event_id: str) -> None:
"""Отметка после немедленной публикации из use-case.
Если строку уже отметил poller - ничего не меняет.
"""
with self._pool.connection() as conn:
conn.execute(
"""UPDATE outbox SET published_at = now()
WHERE event_id = %s AND published_at IS NULL""",
(event_id,),
)
Outbox Poller
// outbox/poller.go
// Poller периодически читает outbox и публикует события в EventBus.
type Poller struct {
repo *Repository
bus eventbus.EventBus
interval time.Duration
batch int
}
func NewPoller(repo *Repository, bus eventbus.EventBus, interval time.Duration, batch int) *Poller {
return &Poller{repo: repo, bus: bus, interval: interval, batch: batch}
}
// Run запускает polling. Останавливается по отмене контекста.
func (p *Poller) Run(ctx context.Context) {
ticker := time.NewTicker(p.interval)
defer ticker.Stop()
slog.Info("outbox poller started",
slog.Duration("interval", p.interval),
slog.Int("batch_size", p.batch),
)
for {
select {
case <-ctx.Done():
slog.Info("outbox poller stopped")
return
case <-ticker.C:
if err := p.pollBatch(ctx); err != nil {
slog.ErrorContext(ctx, "outbox poll failed",
slog.String("err", err.Error()),
)
}
}
}
}
// pollBatch публикует одну пачку - так же, как PollBatch из урока 7: одна
// транзакция, SELECT ... FOR UPDATE SKIP LOCKED, публикация и отметки внутри
// неё, затем COMMIT. Блокировка держит строки до COMMIT, поэтому второй
// экземпляр поллера их не возьмёт. Упали между Publish и COMMIT - событие
// уйдёт ещё раз (at-least-once), поэтому подписчики идемпотентны.
func (p *Poller) pollBatch(ctx context.Context) error {
tx, err := p.repo.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
defer tx.Rollback()
entries, err := p.repo.claimBatch(ctx, tx, p.batch)
if err != nil {
return err
}
for _, entry := range entries {
// Десериализуем событие по типу и публикуем. Publish возвращает
// ошибки подписчиков, поэтому сбой подписчика не отметит событие.
evt, err := deserializeEvent(entry.EventType, entry.Payload)
if err == nil {
err = p.bus.Publish(ctx, evt)
}
if err != nil {
slog.ErrorContext(ctx, "outbox publish failed",
slog.String("event_id", entry.EventID),
slog.String("err", err.Error()),
)
if _, uErr := tx.ExecContext(ctx,
`UPDATE outbox SET attempts = attempts + 1 WHERE id = $1`, entry.ID,
); uErr != nil {
return fmt.Errorf("bump attempts %s: %w", entry.EventID, uErr)
}
continue
}
if _, err := tx.ExecContext(ctx,
`UPDATE outbox SET published_at = now() WHERE id = $1`, entry.ID,
); err != nil {
return fmt.Errorf("mark published %s: %w", entry.EventID, err)
}
}
return tx.Commit()
}
// deserializeEvent восстанавливает событие из JSON по типу.
func deserializeEvent(eventType string, payload []byte) (eventbus.Event, error) {
switch eventType {
case "lesson.completed":
var evt domain.LessonCompleted
if err := json.Unmarshal(payload, &evt); err != nil {
return nil, err
}
return evt, nil
default:
return nil, fmt.Errorf("unknown event type: %s", eventType)
}
}
<?php
// src/Application/Cron/OutboxPollCommand.php
declare(strict_types=1);
namespace App\Application\Cron;
use App\Application\Port\EventBus;
use App\Domain\Event\LessonCompleted;
use App\Infrastructure\Outbox\OutboxRepository;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use DateTimeImmutable;
use LogicException;
use Throwable;
// Альтернатива - Symfony Messenger worker (`messenger:consume outbox-transport`).
// Здесь - однопроходная команда из cron, проще в развёртывании.
#[AsCommand(name: 'app:outbox-poll')]
final class OutboxPollCommand extends Command
{
private const BATCH_SIZE = 10;
public function __construct(
private readonly Connection $connection,
private readonly OutboxRepository $repo,
private readonly EventBus $bus,
private readonly LoggerInterface $logger,
) {
parent::__construct();
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
// Как PollBatch из урока 7: одна транзакция, SELECT ... FOR UPDATE SKIP LOCKED,
// публикация и отметки внутри неё, затем COMMIT. Два запуска cron внахлёст
// не возьмут одни и те же строки.
$this->connection->transactional(function (Connection $tx): void {
foreach ($this->repo->claimBatch($tx, self::BATCH_SIZE) as $entry) {
try {
$event = $this->deserializeEvent($entry->eventType, $entry->payload);
// publish бросает исключение, если упал хоть один подписчик
$this->bus->publish($event);
} catch (Throwable $e) {
$this->logger->error('outbox publish failed', [
'event_id' => $entry->eventId,
'err' => $e->getMessage(),
]);
$this->repo->bumpAttempts($tx, $entry->id);
continue;
}
$this->repo->markPublished($tx, $entry->id);
}
});
return Command::SUCCESS;
}
private function deserializeEvent(string $eventType, string $payload): LessonCompleted
{
$data = json_decode($payload, true, 512, JSON_THROW_ON_ERROR);
return match ($eventType) {
'lesson.completed' => new LessonCompleted(
eventId: $data['event_id'],
correlationId: $data['correlation_id'],
occurredAt: new DateTimeImmutable($data['occurred_at']),
userId: $data['user_id'],
lessonId: $data['lesson_id'],
trackSlug: $data['track_slug'],
lessonSlug: $data['lesson_slug'],
),
default => throw new LogicException(sprintf('unknown event type: %s', $eventType)),
};
}
}
# outbox/poller.py
from __future__ import annotations
import logging
import threading
from typing import Any
from psycopg_pool import ConnectionPool
from backend.domain.events import LessonCompleted
from backend.eventbus.bus import Event, EventBus
from backend.outbox.repository import Repository
logger = logging.getLogger(__name__)
class Poller:
"""Периодически читает outbox и публикует события в EventBus."""
def __init__(
self, pool: ConnectionPool, repo: Repository, bus: EventBus, interval: float, batch: int,
) -> None:
self._pool = pool
self._repo = repo
self._bus = bus
self._interval = interval # секунды
self._batch = batch
def run(self, stop: threading.Event) -> None:
"""Запускает polling в текущем потоке (main стартует его в threading.Thread).
Останавливается по stop-флагу - аналог отмены контекста в Go.
"""
logger.info(
"outbox poller started",
extra={"interval": self._interval, "batch_size": self._batch},
)
# stop.wait(interval) - это и ticker, и проверка ctx.Done() в одном вызове
while not stop.wait(self._interval):
try:
self.poll_batch()
except Exception as exc:
logger.error("outbox poll failed", extra={"err": str(exc)})
logger.info("outbox poller stopped")
def poll_batch(self) -> None:
"""Публикует одну пачку - как poll_batch из урока 7.
Одна транзакция, SELECT ... FOR UPDATE SKIP LOCKED, публикация и отметки
внутри неё, затем COMMIT при выходе из with. Второй экземпляр поллера
эти строки не возьмёт.
"""
with self._pool.connection() as conn, conn.transaction():
for entry in self._repo.claim_batch(conn, self._batch):
try:
evt = deserialize_event(entry.event_type, entry.payload)
# publish пробрасывает ошибки подписчиков (ExceptionGroup)
self._bus.publish(evt)
except Exception as exc:
logger.error(
"outbox publish failed",
extra={"event_id": entry.event_id, "err": str(exc)},
)
conn.execute(
"UPDATE outbox SET attempts = attempts + 1 WHERE id = %s", (entry.id,)
)
continue
conn.execute(
"UPDATE outbox SET published_at = now() WHERE id = %s", (entry.id,)
)
def deserialize_event(event_type: str, payload: dict[str, Any]) -> Event:
"""Восстанавливает событие из JSON по типу."""
match event_type:
case "lesson.completed":
return LessonCompleted.from_dict(payload)
case _:
raise ValueError(f"unknown event type: {event_type}")
Wiring в main.go
Всё собирается в main.go - создаём bus, регистрируем подписчиков, передаём bus в use-case:
// cmd/server/main.go (фрагмент)
func main() {
// ... DB, router, middleware setup ...
// 1. Создаём EventBus
bus := eventbus.NewInProcessBus()
// 2. Создаём подписчиков
achievementChecker := subscribers.NewAchievementChecker(db)
analyticsRecorder := subscribers.NewAnalyticsRecorder(db)
notificationSender := subscribers.NewNotificationSender(stubNotifier{})
// 3. Регистрируем подписчиков (одна строка на подписчика!)
bus.Subscribe("lesson.completed", achievementChecker.Handle)
bus.Subscribe("lesson.completed", analyticsRecorder.Handle)
bus.Subscribe("lesson.completed", notificationSender.Handle)
// 4. Создаём outbox и use-case
outboxRepo := outbox.NewRepository(db)
completeLessonUC := usecase.NewCompleteLessonUseCase(db, outboxRepo, bus)
// 5. Запускаём outbox poller в фоне
pollerCtx, pollerCancel := context.WithCancel(context.Background())
defer pollerCancel()
poller := outbox.NewPoller(outboxRepo, bus, 500*time.Millisecond, 10)
go poller.Run(pollerCtx)
// 6. Регистрируем handler
router.Put("/progress/lessons/{id}/complete", handler.CompleteLesson(completeLessonUC))
// ... server start, graceful shutdown ...
}
<?php
// config/services.yaml - autoconfigure через #[AsMessageHandler].
// Контроллер просто инжектит MessageBusInterface и dispatches DomainEvent.
// src/Controller/ProgressController.php
declare(strict_types=1);
namespace App\Controller;
use App\Application\UseCase\CompleteLessonRequest;
use App\Application\UseCase\CompleteLessonUseCase;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;
final class ProgressController extends AbstractController
{
public function __construct(
private readonly CompleteLessonUseCase $completeLesson,
) {}
#[Route('/api/progress/lessons/{id}/complete', methods: ['PUT'])]
public function complete(int $id, Request $request): JsonResponse
{
$payload = json_decode($request->getContent(), true, 512, JSON_THROW_ON_ERROR);
$this->completeLesson->execute(new CompleteLessonRequest(
userId: $this->getUser()->getId(),
lessonId: $id,
trackSlug: $payload['track_slug'],
lessonSlug: $payload['lesson_slug'],
correlationId: $request->headers->get('X-Correlation-Id', 'unknown'),
));
return new JsonResponse(['status' => 'ok']);
}
}
// Подписчики (AchievementChecker, AnalyticsRecorder, NotificationSender)
// с #[AsMessageHandler] - Symfony автоматически подвязывает их к типу события.
// Outbox poller: `bin/console app:outbox-poll` через systemd-timer или
// `bin/console messenger:consume outbox` для async-транспорта.
# cmd/server/main.py (фрагмент)
import os
import threading
from psycopg_pool import ConnectionPool
from backend.eventbus.bus import InProcessBus
from backend.outbox.poller import Poller
from backend.outbox.repository import Repository
from backend.subscribers.achievement_checker import AchievementChecker
from backend.subscribers.analytics_recorder import AnalyticsRecorder
from backend.subscribers.notification_sender import NotificationSender
from backend.usecase.complete_lesson import CompleteLessonUseCase
def main() -> None:
# ... DB, router, middleware setup ...
pool = ConnectionPool(os.environ["DATABASE_URL"]) # аналог *sql.DB
# 1. Создаём EventBus
bus = InProcessBus()
# 2. Создаём подписчиков
achievement_checker = AchievementChecker(pool)
analytics_recorder = AnalyticsRecorder(pool)
notification_sender = NotificationSender(StubNotifier())
# 3. Регистрируем подписчиков (одна строка на подписчика!)
bus.subscribe("lesson.completed", achievement_checker.handle)
bus.subscribe("lesson.completed", analytics_recorder.handle)
bus.subscribe("lesson.completed", notification_sender.handle)
# 4. Создаём outbox и use-case
outbox_repo = Repository(pool)
complete_lesson_uc = CompleteLessonUseCase(pool, outbox_repo, bus)
# 5. Запускаем outbox poller в фоновом потоке
poller_stop = threading.Event()
poller = Poller(pool, outbox_repo, bus, interval=0.5, batch=10)
threading.Thread(
target=poller.run, args=(poller_stop,), name="outbox-poller", daemon=True
).start()
# 6. Регистрируем handler. Роутинг фреймворк-независим: в FastAPI это
# @app.put("/progress/lessons/{id}/complete"), в Django - path() в urls.py
router.put("/progress/lessons/{id}/complete", complete_lesson_handler(complete_lesson_uc))
# ... server start, graceful shutdown: poller_stop.set() перед выходом ...
Добавить нового подписчика = один файл с реализацией + одна строка bus.Subscribe(...). Ни один существующий файл не меняется (Open-Closed Principle).
Тестирование: FakeEventBus
Для unit-тестов use-case не нужен реальный bus. Создаём FakeEventBus - подставную реализацию того же интерфейса, которая никому ничего не доставляет, а просто записывает опубликованные события в срез. Что это даёт:
- тестам use-case не нужен брокер и сеть: шина живёт в памяти процесса;
- видно, какие именно события опубликованы - тип, поля, количество;
- можно проверить обратное: если use-case вернул ошибку,
fake.Eventsдолжен остаться пустым, иначе подписчики отреагируют на факт, которого не было.
Подписчиков FakeEventBus не вызывает (Subscribe - пустышка), поэтому их тестируют отдельно, передавая событие прямо в обработчик (ниже).
// eventbus/bus_test.go
// FakeEventBus записывает все опубликованные события для проверки в тестах.
type FakeEventBus struct {
mu sync.Mutex
Events []Event
}
func NewFakeEventBus() *FakeEventBus {
return &FakeEventBus{}
}
func (f *FakeEventBus) Publish(_ context.Context, event Event) error {
f.mu.Lock()
defer f.mu.Unlock()
f.Events = append(f.Events, event)
return nil
}
func (f *FakeEventBus) Subscribe(_ string, _ Handler) {
// No-op для тестов
}
// Published возвращает все опубликованные события данного типа.
func (f *FakeEventBus) Published(eventType string) []Event {
f.mu.Lock()
defer f.mu.Unlock()
var result []Event
for _, e := range f.Events {
if e.EventType() == eventType {
result = append(result, e)
}
}
return result
}
<?php
// tests/Fake/FakeEventBus.php
declare(strict_types=1);
namespace App\Tests\Fake;
use App\Application\Port\EventBus;
use App\Domain\Event\DomainEvent;
// Каждый t.Run в PHPUnit/Pest создаёт новый bus - класс stateful, не singleton.
final class FakeEventBus implements EventBus
{
/** @var list<DomainEvent> */
public array $events = [];
public function subscribe(string $eventClass, callable $handler): void
{
// No-op для тестов
}
public function publish(DomainEvent $event): void
{
$this->events[] = $event;
}
/** @return list<DomainEvent> */
public function published(string $eventType): array
{
return array_values(array_filter(
$this->events,
static fn(DomainEvent $e) => $e->eventType() === $eventType,
));
}
}
# eventbus/test_bus.py
import threading
from backend.eventbus.bus import Event, Handler
class FakeEventBus:
"""Записывает все опубликованные события для проверки в тестах.
Каждый тест создаёт свой экземпляр - класс stateful, не singleton.
"""
def __init__(self) -> None:
self._lock = threading.Lock()
self.events: list[Event] = []
def publish(self, event: Event) -> None:
with self._lock:
self.events.append(event)
def subscribe(self, event_type: str, handler: Handler) -> None:
pass # No-op для тестов
def published(self, event_type: str) -> list[Event]:
"""Возвращает все опубликованные события данного типа."""
with self._lock:
return [e for e in self.events if e.event_type == event_type]
Тест use-case:
func TestCompleteLesson_PublishesEvent(t *testing.T) {
db := setupTestDB(t) // in-memory или testcontainers
fakeBus := eventbus.NewFakeEventBus()
outboxRepo := outbox.NewRepository(db)
uc := usecase.NewCompleteLessonUseCase(db, outboxRepo, fakeBus)
err := uc.Execute(context.Background(), usecase.CompleteLessonRequest{
UserID: 1,
LessonID: 42,
TrackSlug: "go",
LessonSlug: "goroutines",
})
require.NoError(t, err)
// Проверяем, что событие опубликовано
events := fakeBus.Published("lesson.completed")
require.Len(t, events, 1)
evt := events[0].(domain.LessonCompleted)
assert.Equal(t, int64(1), evt.UserID)
assert.Equal(t, int64(42), evt.LessonID)
assert.Equal(t, "go", evt.TrackSlug)
assert.Equal(t, "lesson.completed", evt.Type)
assert.NotEmpty(t, evt.EventID)
}
func TestCompleteLesson_WritesToOutbox(t *testing.T) {
db := setupTestDB(t)
fakeBus := eventbus.NewFakeEventBus()
outboxRepo := outbox.NewRepository(db)
uc := usecase.NewCompleteLessonUseCase(db, outboxRepo, fakeBus)
err := uc.Execute(context.Background(), usecase.CompleteLessonRequest{
UserID: 1,
LessonID: 42,
TrackSlug: "go",
LessonSlug: "goroutines",
})
require.NoError(t, err)
// Проверяем, что запись появилась в outbox. FakeEventBus принял событие,
// поэтому use-case уже отметил её опубликованной: ищем без фильтра по published_at.
var count int
err = db.QueryRow(`SELECT COUNT(*) FROM outbox
WHERE event_type = 'lesson.completed' AND published_at IS NOT NULL`).Scan(&count)
require.NoError(t, err)
assert.Equal(t, 1, count)
}
<?php
// tests/Application/UseCase/CompleteLessonUseCaseTest.php
declare(strict_types=1);
namespace App\Tests\Application\UseCase;
use App\Application\UseCase\CompleteLessonRequest;
use App\Application\UseCase\CompleteLessonUseCase;
use App\Domain\Event\LessonCompleted;
use App\Tests\Fake\FakeEventBus;
use PHPUnit\Framework\TestCase;
use Psr\Log\LoggerInterface;
final class CompleteLessonUseCaseTest extends TestCase
{
public function testPublishesEvent(): void
{
$db = $this->setUpTestDB();
$fakeBus = new FakeEventBus();
$outboxRepo = new OutboxRepository($db);
$uc = new CompleteLessonUseCase($db, $outboxRepo, $fakeBus, $this->createMock(LoggerInterface::class));
$uc->execute(new CompleteLessonRequest(
userId: 1,
lessonId: 42,
trackSlug: 'go',
lessonSlug: 'goroutines',
correlationId: 'test-corr',
));
// Проверяем, что событие опубликовано
$events = $fakeBus->published('lesson.completed');
self::assertCount(1, $events);
/** @var LessonCompleted $evt */
$evt = $events[0];
self::assertSame(1, $evt->userId);
self::assertSame(42, $evt->lessonId);
self::assertSame('go', $evt->trackSlug);
self::assertSame('lesson.completed', $evt->eventType());
self::assertNotEmpty($evt->eventId);
}
public function testWritesToOutbox(): void
{
$db = $this->setUpTestDB();
$fakeBus = new FakeEventBus();
$outboxRepo = new OutboxRepository($db);
$uc = new CompleteLessonUseCase($db, $outboxRepo, $fakeBus, $this->createMock(LoggerInterface::class));
$uc->execute(new CompleteLessonRequest(
userId: 1,
lessonId: 42,
trackSlug: 'go',
lessonSlug: 'goroutines',
correlationId: 'test-corr',
));
// FakeEventBus принял событие, поэтому use-case уже отметил строку
// опубликованной: ищем без фильтра по published_at IS NULL.
$count = $db->fetchOne(
"SELECT COUNT(*) FROM outbox WHERE event_type = 'lesson.completed' AND published_at IS NOT NULL",
);
self::assertSame(1, (int) $count);
}
}
# usecase/test_complete_lesson.py
import pytest
from backend.domain.events import LessonCompleted
from backend.eventbus.test_bus import FakeEventBus
from backend.outbox.repository import Repository
from backend.usecase.complete_lesson import CompleteLessonRequest, CompleteLessonUseCase
@pytest.fixture
def test_pool():
# testcontainers-python или локальный Postgres из docker-compose
pool = setup_test_db()
yield pool
pool.close()
def test_complete_lesson_publishes_event(test_pool) -> None:
fake_bus = FakeEventBus()
outbox_repo = Repository(test_pool)
uc = CompleteLessonUseCase(test_pool, outbox_repo, fake_bus)
uc.execute(CompleteLessonRequest(
user_id=1,
lesson_id=42,
track_slug="go",
lesson_slug="goroutines",
))
# Проверяем, что событие опубликовано
events = fake_bus.published("lesson.completed")
assert len(events) == 1
evt = events[0]
assert isinstance(evt, LessonCompleted)
assert evt.user_id == 1
assert evt.lesson_id == 42
assert evt.track_slug == "go"
assert evt.event_type == "lesson.completed"
assert evt.event_id
def test_complete_lesson_writes_to_outbox(test_pool) -> None:
fake_bus = FakeEventBus()
outbox_repo = Repository(test_pool)
uc = CompleteLessonUseCase(test_pool, outbox_repo, fake_bus)
uc.execute(CompleteLessonRequest(
user_id=1,
lesson_id=42,
track_slug="go",
lesson_slug="goroutines",
))
# Проверяем, что запись появилась в outbox. FakeEventBus принял событие,
# поэтому use-case уже отметил её опубликованной: ищем без фильтра по published_at.
with test_pool.connection() as conn:
(count,) = conn.execute(
"""SELECT COUNT(*) FROM outbox
WHERE event_type = 'lesson.completed' AND published_at IS NOT NULL"""
).fetchone()
assert count == 1
Тест подписчика:
func TestAchievementChecker_GrantsFirstLesson(t *testing.T) {
db := setupTestDB(t)
checker := subscribers.NewAchievementChecker(db)
// Подготовка: один завершённый урок
insertLessonProgress(t, db, 1, "go", true)
evt := domain.LessonCompleted{
EventID: "test-event-1",
Type: "lesson.completed",
UserID: 1,
TrackSlug: "go",
}
err := checker.Handle(context.Background(), evt)
require.NoError(t, err)
// Проверяем ачивку
var count int
db.QueryRow(`SELECT COUNT(*) FROM user_achievements
WHERE user_id = 1 AND achievement_slug = 'first_lesson'`).Scan(&count)
assert.Equal(t, 1, count)
// Повторный вызов - идемпотентно, ачивка не дублируется
err = checker.Handle(context.Background(), evt)
require.NoError(t, err)
db.QueryRow(`SELECT COUNT(*) FROM user_achievements
WHERE user_id = 1 AND achievement_slug = 'first_lesson'`).Scan(&count)
assert.Equal(t, 1, count) // по-прежнему 1
}
<?php
// tests/Application/Subscriber/AchievementCheckerTest.php
declare(strict_types=1);
namespace App\Tests\Application\Subscriber;
use App\Application\Subscriber\AchievementChecker;
use App\Domain\Event\LessonCompleted;
use PHPUnit\Framework\TestCase;
use DateTimeImmutable;
use Psr\Log\LoggerInterface;
final class AchievementCheckerTest extends TestCase
{
public function testGrantsFirstLesson(): void
{
$db = $this->setUpTestDB();
$checker = new AchievementChecker($db, $this->createMock(LoggerInterface::class));
// Подготовка: один завершённый урок
$this->insertLessonProgress($db, 1, 'go', true);
$event = new LessonCompleted(
eventId: 'test-event-1',
correlationId: 'test-corr',
occurredAt: new DateTimeImmutable(),
userId: 1,
lessonId: 1,
trackSlug: 'go',
lessonSlug: 'goroutines',
);
$checker($event);
// Проверяем ачивку
$count = (int) $db->fetchOne(
'SELECT COUNT(*) FROM user_achievements
WHERE user_id = 1 AND achievement_slug = :slug',
['slug' => 'first_lesson'],
);
self::assertSame(1, $count);
// Повторный вызов - идемпотентно, ачивка не дублируется
$checker($event);
$count = (int) $db->fetchOne(
'SELECT COUNT(*) FROM user_achievements
WHERE user_id = 1 AND achievement_slug = :slug',
['slug' => 'first_lesson'],
);
self::assertSame(1, $count); // по-прежнему 1
}
}
# subscribers/test_achievement_checker.py
from datetime import datetime, timezone
from backend.domain.events import LessonCompleted
from backend.subscribers.achievement_checker import AchievementChecker
def count_achievements(pool, user_id: int, slug: str) -> int:
with pool.connection() as conn:
row = conn.execute(
"""SELECT COUNT(*) FROM user_achievements
WHERE user_id = %s AND achievement_slug = %s""",
(user_id, slug),
).fetchone()
return int(row[0])
def test_achievement_checker_grants_first_lesson(test_pool) -> None:
checker = AchievementChecker(test_pool)
# Подготовка: один завершённый урок
insert_lesson_progress(test_pool, 1, "go", True)
# frozen dataclass требует все поля - в Go незаполненные были бы zero value
evt = LessonCompleted(
event_id="test-event-1",
event_type="lesson.completed",
correlation_id="test-corr",
occurred_at=datetime.now(timezone.utc),
user_id=1,
lesson_id=1,
track_slug="go",
lesson_slug="goroutines",
)
checker.handle(evt)
# Проверяем ачивку
assert count_achievements(test_pool, 1, "first_lesson") == 1
# Повторный вызов - идемпотентно, ачивка не дублируется
checker.handle(evt)
assert count_achievements(test_pool, 1, "first_lesson") == 1 # по-прежнему 1
ℹ️ Добавить нового подписчика = один файл + одна строка регистрации. Ни один существующий код не меняется.
Это главное преимущество event-driven архитектуры. Завтра понадобится отправлять данные в рекомендательную систему? Создайте
RecommendationUpdater, реализуйтеHandle, добавьтеbus.Subscribe("lesson.completed", recommender.Handle)в main.go. Use-case, другие подписчики, outbox - всё остаётся нетронутым.
Чеклист проекта
Убедитесь, что реализовано:
- Доменное событие
LessonCompletedс полямиevent_id,type,correlation_id,occurred_at,user_id,lesson_id,track_slug,lesson_slug - Интерфейс
EventBusс методамиPublishиSubscribe -
InProcessBus- реализация через горутины с логированием ошибок подписчиков - Таблица
outboxс DDL (id, event_id, event_type, payload, created_at, published_at, attempts) - Use-case
CompleteLessonUseCase, который сохраняет прогресс и outbox в одной транзакции - Подписчик
AchievementCheckerс идемпотентным UPSERT - Подписчик
AnalyticsRecorderс дедупликацией по event_id - Подписчик
NotificationSenderс интерфейсом Notifier (заглушка) -
OutboxPoller- горутина с интервалом; пачка в одной транзакции сFOR UPDATE SKIP LOCKED, публикация и mark published до COMMIT - Wiring в main.go: bus -> subscribers -> use-case -> poller
-
FakeEventBusдля unit-тестов - Тест:
CompleteLessonпубликует событие и записывает в outbox - Тест:
AchievementCheckerидемпотентен при повторном вызове
Типичные ошибки в этом проекте
bus.Publishнапрямую из use-case вместо outbox - публикация в брокер до commit транзакции. Откат БД → событие уже ушло. Use-case пишет только в outbox-таблицу в той же транзакции, что и progress; брокеру отправляет poller.- OutboxPoller - два инстанса без leader election - оба читают одну запись, дубли × N. Либо
FOR UPDATE SKIP LOCKED, либо один инстанс с k8sRecreatestrategy. AchievementCheckerчерезINSERTвместоUPSERT- повторное событие → unique violation, retry, DLQ. Идемпотентность черезINSERT ... ON CONFLICT DO NOTHINGилиON CONFLICT (event_id) DO NOTHING- фундамент проекта.AnalyticsRecorderпишет в Redis без AOF - событие записано, Redis перезагрузился, аналитика потеряна. Для аналитики достаточно at-least-once; для критики - PostgreSQL/долговечное хранилище.NotificationSenderотправляет email синхронно - SMTP отвечает за 5 секунд, subscriber обрабатывает 1 событие в 5с, очередь растёт. Notifier с deadline + retry + DLQ, либо отдельный сервис отправки.FakeEventBusдля теста разделён между параллельнымиt.Run- события одного теста ловит handler другого. Создавай новый bus в каждом setup.- Outbox-таблица без индекса на
(published_at, created_at)- poller-запросWHERE published_at IS NULLпод нагрузкой делает seqscan на миллионе строк. Индекс - обязательно с первого дня. correlation_idне пробрасывается в горутину subscriber-а - лог HTTP-запроса и лог subscriber-а не сопоставить. Subscriber извлекаетcorrelation_idиз envelope и добавляет вslog-контекст; как настроить это один раз через middleware и handler логгера - в уроке про наблюдаемость.
Мини-задание
- Реализуй полный pipeline: use-case -> outbox -> poller -> bus -> subscribers
- Напиши unit-тест с FakeEventBus, проверяющий публикацию LessonCompleted
- Убедись, что каждый подписчик идемпотентен (вызови Handle дважды - результат не меняется)
- Добавь четвёртого подписчика (например, RecommendationUpdater), не меняя ни одного существующего файла
- Запусти
go test ./...и убедись, что все тесты проходят