Event Sourcing (опционально): когда это реально нужно

Event Sourcing: когда это реально нужно

Event Sourcing - это когда источник правды - события, а текущее состояние - результат их проигрывания. Это мощно, но дорого по сложности. Перекликается с domain events и event-driven архитектурой.

События в append-only логе и replay для получения текущего состояния

Обычная БД vs Event Sourcing

Обычная БД (state-based):            Event Sourcing:
──────────────────────────           ──────────────────────────
Хранит текущее состояние             Хранит ВСЕ события
UPDATE balance = 500                 BalanceCreated{amount: 0}
                                     MoneyDeposited{amount: 300}
                                     MoneyDeposited{amount: 400}
                                     MoneyWithdrawn{amount: 200}
                                     → replay → balance = 500

Потеряна история «почему 500»        Полная история: кто, когда, что

Event Store: хранилище событий

В Event Sourcing все события записываются в append-only хранилище:

// Событие - иммутабельный факт
type Event struct {
    ID            string    `json:"id"`
    AggregateID   string    `json:"aggregate_id"`
    AggregateType string    `json:"aggregate_type"`
    Type          string    `json:"type"`
    Version       int       `json:"version"`        // позиция события в потоке агрегата
    SchemaVersion int       `json:"schema_version"` // версия формата payload (для upcasting)
    Data          []byte    `json:"data"`
    CreatedAt     time.Time `json:"created_at"`
}

// Event Store - append-only
type EventStore interface {
    Append(ctx context.Context, aggregateID string, events []Event, expectedVersion int) error
    Load(ctx context.Context, aggregateID string) ([]Event, error)
    // LoadFrom - события начиная с версии fromVersion (нужно для snapshot-ов)
    LoadFrom(ctx context.Context, aggregateID string, fromVersion int) ([]Event, error)
}
<?php
declare(strict_types=1);

// Событие - иммутабельный факт
final readonly class StoredEvent
{
    public function __construct(
        public string $id,
        public string $aggregateId,
        public string $aggregateType,
        public string $type,
        public int $version,            // позиция события в потоке агрегата
        public int $schemaVersion,      // версия формата payload (для upcasting)
        public string $data,            // JSON-payload
        public DateTimeImmutable $createdAt,
    ) {}
}

// Event Store - append-only
interface EventStore
{
    /** @param StoredEvent[] $events */
    public function append(string $aggregateId, array $events, int $expectedVersion): void;

    /** @return StoredEvent[] */
    public function load(string $aggregateId): array;

    /** @return StoredEvent[] события начиная с версии $fromVersion (для snapshot-ов) */
    public function loadFrom(string $aggregateId, int $fromVersion): array;
}
from dataclasses import dataclass
from datetime import datetime
from typing import Protocol


# Событие - иммутабельный факт
# (поле event_type - единое имя по курсу; в JSON ключ "type")
@dataclass(frozen=True, slots=True)
class Event:
    id: str
    aggregate_id: str
    aggregate_type: str
    event_type: str
    version: int  # позиция события в потоке агрегата
    data: bytes  # JSON-payload
    created_at: datetime
    schema_version: int = 1  # версия формата payload (для upcasting)


# Event Store - append-only
class EventStore(Protocol):
    def append(self, aggregate_id: str, events: list[Event], expected_version: int) -> None: ...

    def load(self, aggregate_id: str) -> list[Event]: ...

    # события начиная с версии from_version (для snapshot-ов)
    def load_from(self, aggregate_id: str, from_version: int) -> list[Event]: ...

SQL-схема для Event Store:

CREATE TABLE events (
    id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    aggregate_id   TEXT NOT NULL,
    aggregate_type TEXT NOT NULL,
    event_type     TEXT NOT NULL,
    version        INT NOT NULL,                -- позиция события в потоке агрегата
    schema_version SMALLINT NOT NULL DEFAULT 1, -- версия формата payload
    data           JSONB NOT NULL,
    created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (aggregate_id, version) -- оптимистичная блокировка
);
-- Отдельный индекс на (aggregate_id, version) не нужен: UNIQUE уже создаёт
-- B-tree индекс, и чтение потока агрегата использует его.

Не путай две версии: version - порядковый номер события в потоке агрегата (по нему работает оптимистичная блокировка), schema_version - версия формата data, по ней работает upcasting (раздел Event Versioning ниже).

Оптимистичная блокировка - это когда агрегат при чтении не блокируют, а конфликт ловят при записи. Append получает expectedVersion - версию, на которой агрегат был загружен, и пишет новые события с версиями expectedVersion+1, +2... Если другой процесс успел записать событие с той же версией, UNIQUE (aggregate_id, version) отклонит INSERT: команда узнаёт, что агрегат уже изменили, перезагружает его и решает заново (retry). Так два конкурентных изменения не перезапишут друг друга.

Агрегат: восстановление из событий

type UserProgress struct {
    UserID          int64
    CompletedMap    map[int64]time.Time // lessonID → completedAt
    TotalCompleted  int
    Version         int
}

// Восстанавливаем состояние, проигрывая события
func (p *UserProgress) Apply(event Event) {
    switch event.Type {
    case "lesson.completed":
        var data LessonCompletedData
        json.Unmarshal(event.Data, &data)
        // Повторное событие для того же урока не должно увеличивать счётчик
        if _, done := p.CompletedMap[data.LessonID]; !done {
            p.TotalCompleted++
        }
        p.CompletedMap[data.LessonID] = data.CompletedAt
    case "progress.reset":
        p.CompletedMap = make(map[int64]time.Time)
        p.TotalCompleted = 0
    }
    p.Version = event.Version
}

// Загружаем агрегат из Event Store
func LoadProgress(ctx context.Context, store EventStore, userID int64) (*UserProgress, error) {
    events, err := store.Load(ctx, fmt.Sprintf("user-progress-%d", userID))
    if err != nil {
        return nil, err
    }
    progress := &UserProgress{
        UserID:       userID,
        CompletedMap: make(map[int64]time.Time),
    }
    for _, evt := range events {
        progress.Apply(evt)
    }
    return progress, nil
}
<?php
declare(strict_types=1);

final class UserProgress
{
    /** @var array<int, DateTimeImmutable> lessonId => completedAt */
    private array $completedMap = [];
    private int $totalCompleted = 0;
    private int $version = 0;

    public function __construct(
        public readonly int $userId,
    ) {}

    // Восстанавливаем состояние, проигрывая события
    public function apply(StoredEvent $event): void
    {
        $data = json_decode($event->data, true, flags: JSON_THROW_ON_ERROR);

        match ($event->type) {
            'lesson.completed' => $this->onLessonCompleted($data),
            'progress.reset'   => $this->onReset(),
            default            => null,
        };

        $this->version = $event->version;
    }

    private function onLessonCompleted(array $data): void
    {
        // Повторное событие для того же урока не должно увеличивать счётчик
        if (!isset($this->completedMap[$data['lesson_id']])) {
            $this->totalCompleted++;
        }
        $this->completedMap[$data['lesson_id']] = new DateTimeImmutable($data['completed_at']);
    }

    private function onReset(): void
    {
        $this->completedMap = [];
        $this->totalCompleted = 0;
    }
}

// Загружаем агрегат из Event Store
final class ProgressLoader
{
    public function __construct(
        private readonly EventStore $store,
    ) {}

    public function load(int $userId): UserProgress
    {
        $progress = new UserProgress($userId);
        foreach ($this->store->load("user-progress-$userId") as $evt) {
            $progress->apply($evt);
        }
        return $progress;
    }
}
import json
from dataclasses import dataclass, field
from datetime import datetime


@dataclass
class UserProgress:
    user_id: int
    completed_map: dict[int, datetime] = field(default_factory=dict)  # lesson_id -> completed_at
    total_completed: int = 0
    version: int = 0

    # Восстанавливаем состояние, проигрывая события
    def apply(self, event: Event) -> None:
        match event.event_type:
            case "lesson.completed":
                data = json.loads(event.data)
                # Повторное событие для того же урока не должно увеличивать счётчик
                if data["lesson_id"] not in self.completed_map:
                    self.total_completed += 1
                self.completed_map[data["lesson_id"]] = datetime.fromisoformat(data["completed_at"])
            case "progress.reset":
                self.completed_map = {}
                self.total_completed = 0
        self.version = event.version


# Загружаем агрегат из Event Store
def load_progress(store: EventStore, user_id: int) -> UserProgress:
    events = store.load(f"user-progress-{user_id}")  # ошибка хранилища - исключение из адаптера
    progress = UserProgress(user_id=user_id)
    for evt in events:
        progress.apply(evt)
    return progress

Snapshots: оптимизация загрузки

Если у агрегата тысячи событий, проигрывать их каждый раз дорого. Snapshot фиксирует состояние на определённой версии:

Snapshot фиксирует состояние, дальше Apply вызывается только для новых событий

Events: [1] [2] [3] ... [1000] [Snapshot v1000] [1001] [1002]
                                      ↑
                               Загружаем snapshot,
                               проигрываем только 1001 и 1002
type Snapshot struct {
    AggregateID string `json:"aggregate_id"`
    Version     int    `json:"version"`
    State       []byte `json:"state"`  // сериализованный агрегат
}

// userIDFromAggregate: "user-progress-42" -> 42
func userIDFromAggregate(id string) (int64, error) {
    return strconv.ParseInt(id[strings.LastIndex(id, "-")+1:], 10, 64)
}

func LoadWithSnapshot(ctx context.Context, store EventStore, snapshotRepo SnapshotRepo, id string) (*UserProgress, error) {
    userID, err := userIDFromAggregate(id)
    if err != nil {
        return nil, fmt.Errorf("bad aggregate id %q: %w", id, err)
    }
    // map создаём сразу: без snapshot-а первый Apply иначе упадёт на nil map
    progress := &UserProgress{UserID: userID, CompletedMap: make(map[int64]time.Time)}
    startVersion := 0

    snap, err := snapshotRepo.GetLatest(ctx, id) // (nil, nil), если snapshot-а нет
    if err != nil {
        return nil, err
    }
    if snap != nil {
        if err := json.Unmarshal(snap.State, progress); err != nil {
            return nil, fmt.Errorf("decode snapshot: %w", err)
        }
        startVersion = snap.Version
    }

    events, err := store.LoadFrom(ctx, id, startVersion+1)
    if err != nil {
        return nil, err
    }

    for _, evt := range events {
        progress.Apply(evt)
    }
    return progress, nil
}
<?php
declare(strict_types=1);

final readonly class Snapshot
{
    public function __construct(
        public string $aggregateId,
        public int $version,
        public string $state, // сериализованный агрегат (JSON)
    ) {}
}

final class ProgressLoaderWithSnapshot
{
    public function __construct(
        private readonly EventStore $store,
        private readonly SnapshotRepository $snapshots,
    ) {}

    public function load(string $aggregateId): UserProgress
    {
        $snap = $this->snapshots->getLatest($aggregateId);

        $progress = $snap !== null
            ? UserProgress::fromState($snap->state)
            : new UserProgress(userId: (int) substr($aggregateId, strrpos($aggregateId, '-') + 1));

        $startVersion = $snap?->version ?? 0;

        foreach ($this->store->loadFrom($aggregateId, $startVersion + 1) as $evt) {
            $progress->apply($evt);
        }
        return $progress;
    }
}
import json
from dataclasses import dataclass


@dataclass(frozen=True, slots=True)
class Snapshot:
    aggregate_id: str
    version: int
    state: bytes  # сериализованный агрегат (JSON)


def load_with_snapshot(store: EventStore, snapshot_repo: SnapshotRepo, aggregate_id: str) -> UserProgress:
    snap = snapshot_repo.get_latest(aggregate_id)  # Snapshot | None

    start_version = 0
    if snap is not None:
        progress = UserProgress.from_state(json.loads(snap.state))
        start_version = snap.version
    else:
        user_id = int(aggregate_id.rsplit("-", 1)[1])  # "user-progress-42" -> 42
        progress = UserProgress(user_id=user_id)

    events = store.load_from(aggregate_id, start_version + 1)
    for evt in events:
        progress.apply(evt)
    return progress

ℹ️ Когда делать snapshot

Простое правило: каждые N событий (например, 100). Или когда загрузка агрегата превышает допустимый порог по времени. Не нужно снапшотить каждый раз.

Event Versioning

Со временем формат событий меняется. Нельзя менять старые - они иммутабельны. Дешевле всего эволюцию переживают события, у которых с самого начала есть конверт с event_id, type и версией - как его собирать, разобрано в уроке про доменные события. Решение - версионирование:

// v1: начальная версия
type LessonCompletedV1 struct {
    LessonID int64 `json:"lesson_id"`
}

// v2: добавили поле
type LessonCompletedV2 struct {
    LessonID        int64 `json:"lesson_id"`
    DurationSeconds int   `json:"duration_seconds"`
    Score           int   `json:"score"`
}

// Upcaster: преобразует v1 → v2. Принимает schemaVersion (формат payload),
// а не Version (позицию события в потоке)
func UpcastLessonCompleted(data []byte, schemaVersion int) (LessonCompletedV2, error) {
    switch schemaVersion {
    case 1:
        var v1 LessonCompletedV1
        if err := json.Unmarshal(data, &v1); err != nil {
            return LessonCompletedV2{}, err
        }
        return LessonCompletedV2{LessonID: v1.LessonID, DurationSeconds: 0, Score: 0}, nil
    case 2:
        var v2 LessonCompletedV2
        if err := json.Unmarshal(data, &v2); err != nil {
            return LessonCompletedV2{}, err
        }
        return v2, nil
    default:
        return LessonCompletedV2{}, fmt.Errorf("unknown schema version: %d", schemaVersion)
    }
}
<?php
declare(strict_types=1);

// v1: начальная версия
final readonly class LessonCompletedV1
{
    public function __construct(
        public int $lessonId,
    ) {}
}

// v2: добавили поля
final readonly class LessonCompletedV2
{
    public function __construct(
        public int $lessonId,
        public int $durationSeconds,
        public int $score,
    ) {}
}

// Upcaster: преобразует v1 → v2
final class LessonCompletedUpcaster
{
    // $schemaVersion - версия формата payload, а не позиция события в потоке
    public function upcast(string $rawJson, int $schemaVersion): LessonCompletedV2
    {
        $data = json_decode($rawJson, true, flags: JSON_THROW_ON_ERROR);

        return match ($schemaVersion) {
            1 => new LessonCompletedV2(
                lessonId: $data['lesson_id'],
                durationSeconds: 0,
                score: 0,
            ),
            2 => new LessonCompletedV2(
                lessonId: $data['lesson_id'],
                durationSeconds: $data['duration_seconds'],
                score: $data['score'],
            ),
            default => throw new RuntimeException("unknown schema version: $schemaVersion"),
        };
    }
}
import json
from dataclasses import dataclass


# v1: начальная версия
@dataclass(frozen=True, slots=True)
class LessonCompletedV1:
    lesson_id: int


# v2: добавили поля
@dataclass(frozen=True, slots=True)
class LessonCompletedV2:
    lesson_id: int
    duration_seconds: int
    score: int


# Upcaster: преобразует v1 -> v2. schema_version - версия формата payload,
# а не позиция события в потоке
def upcast_lesson_completed(data: bytes, schema_version: int) -> LessonCompletedV2:
    payload = json.loads(data)
    match schema_version:
        case 1:
            v1 = LessonCompletedV1(**payload)
            return LessonCompletedV2(lesson_id=v1.lesson_id, duration_seconds=0, score=0)
        case 2:
            return LessonCompletedV2(**payload)
        case _:
            raise ValueError(f"unknown schema version: {schema_version}")

Projections: из событий в Read Model

Projection (проекция) подписывается на поток событий и строит read model. Для примера возьмём отдельную таблицу проекции с ключом под upsert (у track_lessons_view из прошлого урока ключ другой - (track_id, lesson_id, user_id)):

CREATE TABLE user_lesson_progress (
    user_id      BIGINT NOT NULL,
    lesson_id    BIGINT NOT NULL,
    completed    BOOLEAN NOT NULL,
    completed_at TIMESTAMPTZ,
    PRIMARY KEY (user_id, lesson_id)
);
type ProgressProjection struct {
    readDB *sql.DB
}

func (p *ProgressProjection) Handle(ctx context.Context, event Event) error {
    switch event.Type {
    case "lesson.completed":
        data, err := UpcastLessonCompleted(event.Data, event.SchemaVersion)
        if err != nil {
            return err
        }
        userID, err := userIDFromAggregate(event.AggregateID) // см. раздел Snapshots
        if err != nil {
            return err
        }
        _, err = p.readDB.ExecContext(ctx,
            `INSERT INTO user_lesson_progress (user_id, lesson_id, completed, completed_at)
             VALUES ($1, $2, true, $3)
             ON CONFLICT (user_id, lesson_id) DO UPDATE SET completed = true, completed_at = $3`,
            userID, data.LessonID, event.CreatedAt)
        return err
    }
    return nil
}
<?php
declare(strict_types=1);

final class ProgressProjection
{
    public function __construct(
        private readonly Connection $readDb,
        private readonly LessonCompletedUpcaster $upcaster,
    ) {}

    public function handle(StoredEvent $event): void
    {
        if ($event->type !== 'lesson.completed') {
            return;
        }

        $data = $this->upcaster->upcast($event->data, $event->schemaVersion);

        $this->readDb->executeStatement(
            'INSERT INTO user_lesson_progress (user_id, lesson_id, completed, completed_at)
             VALUES (:user_id, :lesson_id, TRUE, :completed_at)
             ON CONFLICT (user_id, lesson_id) DO UPDATE
                SET completed = TRUE, completed_at = EXCLUDED.completed_at',
            [
                // "user-progress-42" -> 42
                'user_id'      => (int) substr($event->aggregateId, strrpos($event->aggregateId, '-') + 1),
                'lesson_id'    => $data->lessonId,
                'completed_at' => $event->createdAt->format(DATE_ATOM),
            ],
        );
    }
}
import psycopg


class ProgressProjection:
    def __init__(self, read_conn: psycopg.Connection) -> None:
        self._read_conn = read_conn

    def handle(self, event: Event) -> None:
        match event.event_type:
            case "lesson.completed":
                data = upcast_lesson_completed(event.data, event.schema_version)
                user_id = int(event.aggregate_id.rsplit("-", 1)[1])  # "user-progress-42" -> 42
                # Запись - в transaction(): psycopg по умолчанию не коммитит
                # сам, без неё upsert откатится при закрытии соединения
                with self._read_conn.transaction():
                    self._read_conn.execute(
                        """
                        INSERT INTO user_lesson_progress (user_id, lesson_id, completed, completed_at)
                        VALUES (%s, %s, true, %s)
                        ON CONFLICT (user_id, lesson_id) DO UPDATE
                            SET completed = true, completed_at = EXCLUDED.completed_at
                        """,
                        (user_id, data.lesson_id, event.created_at),
                    )

Проекцию можно пересобрать: сбрасываем read model и проигрываем все события заново.

⚠️ Когда НЕ надо Event Sourcing

Если у тебя обычная платформа обучения, чаще всего хватит:

  • обычной БД как source of truth
  • outbox, чтобы событие и данные фиксировались одной транзакцией
  • read models для быстрого чтения

Event Sourcing оправдан, когда важна полная история изменений, аудит, replay или сложный биллинг.

Сравнение подходов

Критерий            State-based      Event Sourcing
──────────────      ──────────       ──────────────
Сложность           Низкая           Высокая
История изменений   Потеряна         Полная
Аудит               Нужен отдельно   Встроен
Запись              UPDATE строки    Append в журнал (дёшево)
Чтение              Прямо из таблиц  Через проекции или replay
Масштабирование     Как у обычной БД Чтение - отдельными проекциями
Отладка             Смотришь БД      Проигрываешь события
Миграции            ALTER TABLE      Event versioning

Мини-задание

  • Ответь: тебе нужна история «почему стало так» или достаточно текущего состояния?
  • Набросай 3-5 событий для одного агрегата в своём проекте (например, UserProgress)
  • Напиши функцию Apply(), которая восстанавливает состояние из этих событий
  • Подумай: при каком количестве событий понадобится snapshot?

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.