Мини-проект: CQRS-система с Command → Read Model

Мини-проект: CQRS-система на Go

Соберём полный CQRS-поток: Command → запись → Read Model. Никаких брокеров - чистое разделение команд и запросов с оптимизированными read-проекциями.

Если нужны брокеры - это трек Message Brokers: там RabbitMQ + Kafka + Outbox паттерн.

Архитектура

HTTP POST /api/tracks/{trackID}/lessons/{lessonID}/complete
    │
    ▼
CompleteLesson (Command Handler)
    │
    ├─ INSERT completions (write model)
    └─ UPSERT user_progress (read model - в той же транзакции)

HTTP GET /api/me/progress   (пользователь - из аутентификации)
    │
    ▼
GetUserProgress (Query Handler)
    │
    └─ SELECT user_progress (read model - денормализован, без JOIN)

Ключевое: write model - таблица completions (иммутабельный журнал). Read model - user_progress (денормализованный, быстрый SELECT).

Структура проекта

cmd/
  api/main.go
internal/
  domain/
    lesson.go        -- LessonCompletion struct, интерфейсы
  usecase/
    complete_lesson.go
    get_progress.go
  repository/
    completion_repo.go
    progress_repo.go
  handler/
    lesson_handler.go
  config/
    wire.go          -- сборка зависимостей (вручную в main или Wire; Wire известный, но архивный)

Доменные типы

// internal/domain/lesson.go

type LessonCompletion struct {
    ID        uuid.UUID
    UserID    uuid.UUID
    LessonID  string
    TrackID   string
    CompletedAt time.Time
}

type UserProgress struct {
    UserID           uuid.UUID
    CompletedLessons int
    LastActivityAt   time.Time
    ProgressByTrack  map[string]int
}

// ErrProgressNotFound - доменная ошибка «прогресса нет».
//
// Нужна, чтобы handler мог отличить «такого пользователя нет» от «база
// недоступна»: без неё обе ситуации выглядят как `err != nil` и получают
// один код ответа.
var ErrProgressNotFound = errors.New("progress not found")

// Записывающие методы принимают транзакцию: две записи должны попасть
// в одну команду COMMIT, а транзакцией управляет use case.
type CompletionRepository interface {
    SaveTx(ctx context.Context, tx *sql.Tx, c *LessonCompletion) error
    FindByUser(ctx context.Context, userID uuid.UUID) ([]*LessonCompletion, error)
}

type ProgressRepository interface {
    UpdateTx(ctx context.Context, tx *sql.Tx, userID uuid.UUID, trackID string) error
    // Get возвращает ErrProgressNotFound, если строки нет.
    Get(ctx context.Context, userID uuid.UUID) (*UserProgress, error)
}

⚠️ \*sql.Tx в контракте порта - осознанное упрощение

Транзакция в сигнатуре означает, что порт знает про database/sql. Строго говоря это протечка инфраструктуры в контракт: заменить PostgreSQL на что-то другое, не меняя порт, уже нельзя.

Здесь так сделано намеренно - чтобы в одном примере было видно, где именно начинается и заканчивается транзакция. Способ спрятать её от портов показан в уроке Репозитории и Unit of Work: uow.Do(ctx, func(repos) error { ... }), где границу держит адаптер, а use case о *sql.Tx не знает.

Выбор между двумя вариантами - не вопрос «правильности». Прямая передача проще и честно показывает механику; Unit of Work чище по зависимостям и оправдан, когда репозиториев больше двух или когда СУБД реально может поменяться.

Command: CompleteLesson

// internal/usecase/complete_lesson.go

type CompleteLessonUseCase struct {
    completions CompletionRepository
    progress    ProgressRepository
    db          *sql.DB
}

type CompleteLessonInput struct {
    UserID   uuid.UUID
    LessonID string
    TrackID  string
}

func (uc *CompleteLessonUseCase) Execute(ctx context.Context, in CompleteLessonInput) error {
    tx, err := uc.db.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    completion := &domain.LessonCompletion{
        ID:          uuid.New(),
        UserID:      in.UserID,
        LessonID:    in.LessonID,
        TrackID:     in.TrackID,
        CompletedAt: time.Now(),
    }

    // Write model: записать факт прохождения
    if err := uc.completions.SaveTx(ctx, tx, completion); err != nil {
        return fmt.Errorf("save completion: %w", err)
    }

    // Read model: обновить денормализованную проекцию
    if err := uc.progress.UpdateTx(ctx, tx, in.UserID, in.TrackID); err != nil {
        return fmt.Errorf("update progress: %w", err)
    }

    return tx.Commit()
}

INSERT в write model и upsert read model идут одной транзакцией, поэтому проекция не может разъехаться с журналом: либо обе записи применились, либо ни одна.

Обычный UPDATE для read model не подойдёт: у нового пользователя строки в user_progress ещё нет, UPDATE изменит 0 строк, и проекция так и не появится. Поэтому UpdateTx делает upsert - INSERT ... ON CONFLICT. Он же спасает от гонки, когда два первых прохождения одного пользователя приходят одновременно:

INSERT INTO user_progress (user_id, completed_lessons, last_activity_at, progress_by_track)
VALUES ($1, 1, now(), jsonb_build_object($2::text, 1))
ON CONFLICT (user_id) DO UPDATE SET
    completed_lessons = user_progress.completed_lessons + 1,
    last_activity_at  = now(),
    progress_by_track = jsonb_set(
        user_progress.progress_by_track,
        ARRAY[$2::text],
        to_jsonb(COALESCE((user_progress.progress_by_track ->> $2::text)::int, 0) + 1)
    );

Query: GetUserProgress

// internal/usecase/get_progress.go

type GetProgressUseCase struct {
    progress ProgressRepository
}

func (uc *GetProgressUseCase) Execute(ctx context.Context, userID uuid.UUID) (*domain.UserProgress, error) {
    p, err := uc.progress.Get(ctx, userID)
    if err != nil {
        // %w сохраняет цепочку, поэтому errors.Is в handler увидит
        // domain.ErrProgressNotFound сквозь эту обёртку.
        return nil, fmt.Errorf("get progress: %w", err)
    }
    return p, nil
}

Query не трогает completions - читает только из денормализованного user_progress. Никаких JOIN, никаких агрегаций в реальном времени.

Схема БД

-- Write model: иммутабельный журнал
CREATE TABLE completions (
    id           UUID PRIMARY KEY,
    user_id      UUID NOT NULL,
    lesson_id    TEXT NOT NULL,
    track_id     TEXT NOT NULL,
    completed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (user_id, lesson_id)
);

-- Read model: денормализованная проекция
CREATE TABLE user_progress (
    user_id            UUID PRIMARY KEY,
    completed_lessons  INT NOT NULL DEFAULT 0,
    last_activity_at   TIMESTAMPTZ,
    progress_by_track  JSONB NOT NULL DEFAULT '{}'
);

UNIQUE (user_id, lesson_id) в completions - встроенная защита от повторного прохождения.

ℹ️ Почему здесь нет ни одного отдельного индекса

Первая версия схемы содержала CREATE INDEX ON completions (user_id) и CREATE INDEX ON user_progress (user_id). Оба лишние, и по разным причинам.

  • user_progress.user_id - первичный ключ, а PostgreSQL создаёт под PK уникальный индекс автоматически. Второй индекс на тот же столбец - точная копия, которая только замедляет запись.
  • completions.user_id - ведущий столбец составного UNIQUE (user_id, lesson_id). Запросы вида WHERE user_id = $1 этот индекс используют, как разобрано в уроке Индексы: составной индекс работает по префиксу столбцов.

Единственный сценарий, в котором отдельный узкий индекс оправдан, - когда запросов по user_id очень много, а составной индекс заметно шире, поэтому хуже помещается в кэш. Это решается замером EXPLAIN (ANALYZE, BUFFERS) на реальных данных, а не добавлением индекса на всякий случай: каждый индекс - это цена на каждом INSERT в completions, а пишем мы туда в той же транзакции, что и в read model.

HTTP Handler

// internal/handler/lesson_handler.go

// Маршрут: r.Post("/api/tracks/{trackID}/lessons/{lessonID}/complete", h.CompleteLesson)
func (h *LessonHandler) CompleteLesson(w http.ResponseWriter, r *http.Request) {
    userID := middleware.UserIDFromContext(r.Context())
    lessonID := chi.URLParam(r, "lessonID")
    trackID := chi.URLParam(r, "trackID")
    // chi.URLParam для отсутствующего параметра вернёт "" - не пишем мусор в БД
    if lessonID == "" || trackID == "" {
        http.Error(w, "trackID and lessonID are required", http.StatusBadRequest)
        return
    }

    err := h.completeLesson.Execute(r.Context(), usecase.CompleteLessonInput{
        UserID:   userID,
        LessonID: lessonID,
        TrackID:  trackID,
    })
    if err != nil {
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }

    w.WriteHeader(http.StatusNoContent)
}

// Маршрут: r.Get("/api/me/progress", h.GetProgress) - только свой прогресс
func (h *LessonHandler) GetProgress(w http.ResponseWriter, r *http.Request) {
    userID := middleware.UserIDFromContext(r.Context())

    progress, err := h.getProgress.Execute(r.Context(), userID)
    // Разные причины - разные коды. Одна ветка `if err != nil` с 404
    // превратила бы недоступную базу в «нет такого пользователя»:
    // клиент перестал бы повторять запрос, а мониторинг увидел бы 404
    // вместо ошибки сервера.
    switch {
    case errors.Is(err, domain.ErrProgressNotFound):
        http.Error(w, "not found", http.StatusNotFound)
        return
    case err != nil:
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    // Наружу - DTO под клиента, а не доменная структура (см. урок про Query)
    _ = json.NewEncoder(w).Encode(toProgressResponse(progress))
}

type progressResponse struct {
    UserID           string         `json:"user_id"`
    CompletedLessons int            `json:"completed_lessons"`
    LastActivityAt   time.Time      `json:"last_activity_at"`
    ProgressByTrack  map[string]int `json:"progress_by_track"`
}

func toProgressResponse(p *domain.UserProgress) progressResponse {
    return progressResponse{
        UserID:           p.UserID.String(),
        CompletedLessons: p.CompletedLessons,
        LastActivityAt:   p.LastActivityAt,
        ProgressByTrack:  p.ProgressByTrack,
    }
}

Docker Compose для разработки

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: cqrs_demo
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"
    healthcheck:
      test: pg_isready -U app
      interval: 5s
      retries: 5

  api:
    build: .
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://app:secret@postgres:5432/cqrs_demo
    ports:
      - "8080:8080"

Только postgres и api - никаких брокеров. Это и есть чистый CQRS без event-driven.

Тест use case

func TestCompleteLessonUseCase(t *testing.T) {
    db := testdb.Open(t) // тестовая БД из testcontainers
    repo := repository.NewCompletionRepo(db)
    progressRepo := repository.NewProgressRepo(db)
    uc := usecase.NewCompleteLessonUseCase(repo, progressRepo, db)

    userID := uuid.New()
    err := uc.Execute(context.Background(), usecase.CompleteLessonInput{
        UserID:   userID,
        LessonID: "go-01",
        TrackID:  "go",
    })
    require.NoError(t, err)

    // Проверяем write model
    completions, err := repo.FindByUser(context.Background(), userID)
    require.NoError(t, err)
    assert.Len(t, completions, 1)

    // Проверяем read model: при ошибке тест падает с диагнозом, а не паникой на nil
    progress, err := progressRepo.Get(context.Background(), userID)
    require.NoError(t, err)
    assert.Equal(t, 1, progress.CompletedLessons)
}

Типичная ошибка

Обновлять read model асинхронно (через фоновую горутину или брокер), когда в этом нет необходимости. Если read model обновляется в той же транзакции - он всегда консистентен, нет eventual consistency, нет задержек. Брокер нужен, когда событие должны обработать несколько систем - тогда смотри Message Brokers.

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

  • Реализуй CompletionRepository.SaveTx и ProgressRepository.UpdateTx принимающие *sql.Tx
  • Добавь UNIQUE constraint и проверь что повторный вызов возвращает специфичную ошибку (не 500)
  • Напиши интеграционный тест с testcontainers: PostgreSQL без моков
  • Добавь endpoint GET /api/me/completions возвращающий полный список пройденных уроков из write model

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