Event Sourcing (опционально): когда это реально нужно
Event Sourcing: когда это реально нужно
Event Sourcing - это когда источник правды - события, а текущее состояние - результат их проигрывания. Это мощно, но дорого по сложности. Перекликается с domain events и event-driven архитектурой.
Обычная БД 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 фиксирует состояние на определённой версии:
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?