ЧистаяВайбАрхитектура (CVA) — Полное руководство

2025-10-16

Оглавление

1. Введение и TL;DR
2. Глоссарий и терминология
3. Архитектурная карта и слои
4. Принципы и правила
5. Паттерны
6. Схема данных и контракты
7. Наблюдаемость
8. Безопасность
9. DevEx и продуктивность
10. Референс-скелет (Go)
11. Референс-скелет (Symfony/PHP)
12. Политики эволюции
13. Feature Toggles
14. Визуализация
15. Чек-листы внедрения
16. Лицензирование и вклад

Часть 1: Введение и TL;DR

1.1 Что такое ЧистаяВайбАрхитектура (CVA)

ЧистаяВайбАрхитектура (ClearVibeArchitecture, CVA) — архитектурный стиль для бэкенд-систем, сочетающий:

• Hexagonal (Ports & Adapters) как основу изоляции домена
• Событийность по умолчанию (Domain Events + Outbox/Inbox, идемпотентность)
• Наблюдаемость by default (трассировки, метрики, структурные логи, timeline)
• Обязательные Feature Toggles как сквозной паттерн для любого нового функционала
• Визуализацию потока (web/VR) как продуктовый артефакт, а не «приятную опцию»

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

1.2 Какую проблему решает

CVA решает следующие ключевые проблемы:

1. Сложно безопасно менять систему → фичефлаги + canary/blue-green

2. Не видно, «что происходит внутри» → otel-трейсинг + бизнес-метрики + timeline

3. Надёжная интеграция между сервисами → Outbox/Inbox + идемпотентность

4. Разработчики тонут в инфраструктуре → чистый домен и контракты на границах

5. Сложно объяснить бизнесу поведение системы → визуализатор потока запросов/событий

1.3 Цели (Design Goals)

Архитектура CVA преследует следующие цели:

• Прозрачность: любой запрос и событие трассируется сквозь все слои

• Изоляция домена: доменная модель независима от инфраструктуры

• Надёжная доставка: события публикуются транзакционно (Outbox)

• Управляемая эволюция: все новые ветки — за фичефлагами, с версионированием контрактов

• Developer Experience: шаблоны модулей, единые практики CI/CD, тесты как стандарт

1.4 Нефункциональные требования (NFR)

• Надёжность: идемпотентные обработчики, ретраи, дедупликация
• Наблюдаемость: p95-латентность, error rate, saturation — обязательные метрики
• Безопасность: Zero-Trust границы; подпись сообщений; аудит изменений флагов/контрактов
• Производительность: in-proc кэш решений флагов, back-pressure, батчинг I/O
• Совместимость: SemVer контрактов API/событий, поддержка n-1

1.5 TL;DR принципов

• Domain First: домен не знает об ORM/HTTP/broker
• Ports & Adapters: весь I/O — через интерфейсы (in/out-порты)
• Events First: доменные события — первоклассные; публикация через Outbox
• Observability First: trace_id везде; бизнес-метрики на доменных событиях
• Feature-Toggles Everywhere: новый функционал не живёт без флага и kill-switch
• Contracts First: схемы API/событий версионированы, проверяемы, совместимы
• Visualize the Flow: обязательная визуализация пути запроса/событий

1.6 Область применения

CVA лучше всего подходит для:

• Микросервисы и крупные монолиты с перспективой декомпозиции
• Высокая интеграционная нагрузка, частые релизы, A/B-эксперименты
• Команды, которым важны прозрачность и воспроизводимость инцидентов

Важно: CVA не лучший выбор, если система крайне проста, почти не меняется и не требует телеметрии/событийности.

1.7 Критерии «готовности по CVA»

Система считается готовой к CVA, если:

• Все новые фичи замкнуты на feature flags с canary и kill-switch

• Есть Outbox/Inbox и идемпотентные обработчики

• Включён OpenTelemetry (трейсинг), структурные логи и ключевые бизнес-метрики

• Контракты API/событий описаны схемами, проходят CI-валидацию, ведётся SemVer

• Есть веб/VR-визуализатор потока (минимум — веб-граф + timeline)

• Шаблоны/генераторы модулей, линтеры, PR-чек-листы, базовые e2e-тесты

1.8 Артефакты на выходе

• Архкарта слоёв и портов (in/out), модель домена и границы контекстов
• Каталог контрактов (OpenAPI/Proto/JSON-Schema/Avro) с SemVer и проверками
• Outbox/Inbox библиотека/модуль, FeatureGate SDK, otel-интеграция
• Дашборды SLO и визуализатор потока (минимально — веб)
• Шаблоны кода (Go, Symfony/PHP), Makefile/Compose, CI-пайплайн

Часть 2: Глоссарий и терминология

2.1 Базовые сущности

• Домен (Domain) — предметная область, описывающая бизнес-правила и инварианты

• Агрегат (Aggregate) — корневая сущность, инкапсулирующая состояние и поведение связанных объектов

• Событие (Domain Event) — неизменяемый факт, зафиксированный в домене

• Команда (Command) — намерение изменить состояние (создать, обновить, удалить)

• Запрос (Query) — намерение получить данные без побочных эффектов

• Use Case (Юзкейс) — прикладная логика, связывающая команду/запрос и домен

2.2 Порты и адаптеры

• InPort — интерфейс входа в систему (API, UI, CLI, тест)

• OutPort — интерфейс выхода из системы (база данных, брокер сообщений, сторонние API)

• Adapter — реализация порта для конкретной инфраструктуры

2.3 Событийные компоненты

• Outbox — таблица/хранилище для надёжной публикации событий вместе с транзакцией

• Inbox — таблица/хранилище для приёма и дедупликации входящих событий

• Saga/Process Manager — координирует длинные процессы через последовательность событий

2.4 Observability

• Trace ID — уникальный идентификатор запроса, прокидывается через все слои
• Span — часть трейса, отражающая шаг (например: SQL-запрос, вызов API)
• Metric — измерение (latency, error rate, business metric)
• Structured Log — лог в формате JSON с обязательными полями (timestamp, trace_id, level, message)

2.5 Feature Toggles

• Feature Flag (Фичефлаг) — бинарный переключатель или вариативный параметр, управляющий доступностью функционала
• Variant — значение вариативного флага (A/B/n-тест)
• Kill-Switch — флаг для мгновенного отключения проблемной функции
• Exposure Event — событие факта показа функционала пользователю

2.6 Контракты

• API Contract — формальное описание API (OpenAPI, gRPC proto)
• Event Contract — описание структуры события (JSON Schema, Avro)
• Backward Compatibility — новое описание не ломает клиентов предыдущих версий
• SemVer — версионирование контрактов по правилам Semantic Versioning

2.7 Политики

• Access Policy — правила авторизации и прав доступа на уровне use case
• Validation Policy — проверка данных до входа в домен
• Rollout Policy — стратегия включения флага (percentage, segment, variant)

2.8 Визуализация

• Timeline — хронологический поток событий/запросов с задержками и статусами
• Flow Graph — граф узлов (сервисы, агрегаты) и рёбер (события, вызовы)
• Heatmap — визуализация узких мест по latency/error rate

2.9 DevEx

• Scaffold — генератор шаблонов модулей и портов
• CI/CD Pipeline — сборка, тестирование и деплой системы
• PR Checklist — набор обязательных пунктов для ревью (фичефлаг, метрики, тесты)

Часть 3: Архитектурная карта и слои

3.1 Общая схема

┌─────────────────────────────────────────────────────┐
│           Interface Layer                           │
│   (REST, gRPC, GraphQL, CLI, VR/AR)                 │
└────────────────┬────────────────────────────────────┘
                 │ InPorts
┌────────────────▼────────────────────────────────────┐
│           Application Layer                         │
│   (Commands, Queries, Handlers, Policies)           │
└────────────────┬────────────────────────────────────┘
                 │ Domain Services
┌────────────────▼────────────────────────────────────┐
│           Domain Layer                              │
│   (Entities, Aggregates, Events, Value Objects)     │
└─────────────────────────────────────────────────────┘
                 ▲
                 │ OutPorts
┌────────────────┴────────────────────────────────────┐
│           Infrastructure Layer                      │
│   (DB, Brokers, Outbox/Inbox, Observability)        │
└─────────────────────────────────────────────────────┘

3.2 Interface Layer

Вход: REST, gRPC, GraphQL, CLI, VR/AR-визуализатор

Задачи: принимать команды/запросы, конвертировать в DTO, передавать в Application

Особенности: логирование, трассировка, authN/authZ

3.3 Application Layer

Сердце прикладной логики, включающее:

• Команды, запросы, хендлеры, политики
• Координация: orchestrators, saga, process managers
• Валидация и маппинг DTO
• Гарантия транзакционных границ: один use case = одна транзакция
• Все побочные эффекты — через Outbox

Важно: Application Layer обеспечивает транзакционную целостность всех операций.

3.4 Domain Layer

Чистое доменное ядро системы:

• Entities, Aggregates, Value Objects
• Инварианты, бизнес-правила, ubiquitous language
• Domain Events как первоклассные объекты
• Domain Services — чистые функции без инфраструктуры

Принцип: Domain не знает об ORM, HTTP, брокерах и любой инфраструктуре.

3.5 Infrastructure Layer

• Реализация портов: репозитории, адаптеры брокеров, клиентов внешних API
• Outbox/Inbox — обязательные компоненты для публикации/приёма событий
• Observability stack: otel-интеграция, логирование, метрики
• Кэширование, файловые хранилища, интеграции с внешними сервисами

3.6 Взаимодействие слоёв

• Зависимости всегда направлены внутрь (Infrastructure → Application → Domain)
• Interface вызывает Application через InPorts
• Application использует OutPorts, которые реализуются в Infrastructure
• Domain общается только с Application через события и инварианты

3.7 «Вайб» слоя

У каждого слоя свои обязательные артефакты:

• Interface: трассировки, authN/authZ
• Application: команды, события, фичефлаги
• Domain: инварианты, события
• Infrastructure: outbox/inbox, observability

Всё вместе создаёт живой поток, который можно проследить и визуализировать.

Часть 4: Принципы и правила

4.1 Чистое ядро (Domain First)

Ключевые правила:

• Домен изолирован от инфраструктуры
• Запрещено использовать ORM-аннотации, SQL или SDK внешних сервисов внутри домена
• Инварианты проверяются только в домене

Принцип: Доменный слой должен оставаться чистым и не зависеть от технических деталей реализации.

4.2 Порты и адаптеры

• Все внешние взаимодействия — через интерфейсы (Ports)
• Реализации интерфейсов — только в Infrastructure (Adapters)
• Application вызывает OutPorts, Domain ничего не знает о них

4.3 Событийность по умолчанию

Обязательные требования:

• Каждое значимое изменение фиксируется как Domain Event
• События публикуются через Outbox вместе с транзакцией
• Для входящих событий используется Inbox с идемпотентностью

Важно: Событийность — не опциональная возможность, а обязательный элемент архитектуры CVA.

4.4 Транзакционные границы

• Один use case = одна транзакция
• Побочные эффекты (отправка в брокер, интеграции) фиксируются в Outbox
• Обработка Outbox асинхронна и ретраибельна

4.5 Наблюдаемость по умолчанию

• Каждый запрос и событие сопровождается trace_id
• Все хендлеры и адаптеры обязаны логировать и метриковать свою работу
• Бизнес-события становятся частью метрик (например: order.created.count)

4.6 Договоры на границах

• API и события описываются контрактами (OpenAPI/Proto/Avro/JSON Schema)
• Контракты версионируются (SemVer)
• Backward Compatibility — обязательное требование (поддержка n-1 версий)

4.7 Feature Toggles Everywhere

Обязательные требования:

• Любой новый функционал внедряется только за флагом
• Фичефлаг обязателен, даже если функционал будет всегда включён позже
• У каждого флага есть владелец, sunset-дата и kill-switch

Принцип: Feature flags — это не опция, а обязательный паттерн для любого нового кода в CVA.

4.8 Визуализация потока

• Таймлайн запроса и событий должен быть воспроизводим в визуализаторе (web/VR)
• Узкие места подсвечиваются автоматически (heatmap)
• Визуализация — часть продукта, а не «доп. тул»

4.9 Эволюционность

• Все изменения проходят через feature flags и canary/blue-green
• Миграции БД выполняются с обратимостью
• Shadow-write/read при раскатке новых моделей данных

4.10 Безопасность

• Zero Trust между сервисами: mTLS, подпись сообщений
• RBAC для админки и управления фичефлагами
• Audit trail для всех событий и изменений

4.11 Качество

• Unit и property-based тесты на инварианты
• E2E тесты сквозного сценария (создать → опубликовать событие → обработать)
• Линтеры и статический анализ как часть CI

Часть 5: Паттерны

5.1 Hexagonal / Ports & Adapters

Базовый паттерн CVA:

• Домен изолирован, входные и выходные зависимости оформлены как InPorts/OutPorts
• Взаимодействие с внешним миром происходит через адаптеры

Основа CVA: Hexagonal Architecture обеспечивает изоляцию доменной логики от технических деталей.

5.2 CQRS (опционально)

• Разделение команд (изменения состояния) и запросов (чтение данных)
• Используется там, где чтение сильно отличается от записи
• Позволяет масштабировать чтения и писать оптимизированные проекции

5.3 Outbox / Inbox

Ключевые компоненты событийной архитектуры:

• Outbox: транзакционная запись событий вместе с изменением в БД
• Inbox: регистрация и дедупликация входящих сообщений

Гарантия: Паттерн Outbox/Inbox обеспечивает exactly-once delivery на прикладном уровне.

5.4 Saga / Process Manager

• Управление долгоживущими процессами
• Saga: цепочка шагов с компенсациями
• Process Manager: реагирует на события, координирует действия нескольких агрегатов/сервисов

5.5 Policy / Rule Engine

• Декларативные правила для бизнес-логики (например, скидки, тарифы, доступ)
• Реализуется в Application Layer
• Может подключаться к внешнему движку правил

5.6 Event Sourcing (опционально)

• Хранение истории изменений как последовательности событий
• Позволяет «переиграть» состояние
• Подходит, когда важна аудитируемость и полная история

5.7 Feature Toggles (обязательный)

• Сквозной паттерн: любой новый функционал внедряется за флагом
• Флаги имеют владельца, sunset-даты и kill-switch
• Поддерживается процентный rollout, сегменты пользователей, A/B/n-тесты
• Логируется каждое exposure event (факт использования флага)

5.8 Observability Patterns

• Distributed Tracing: trace_id сквозь все слои
• Structured Logging: JSON-логи с ключевыми полями
• Metrics & SLOs: бизнес и технические метрики; авто-алерты
• Timeline Visualization: поток событий и запросов отображается в веб/VR

5.9 Database Patterns

• Shadow Write/Read: временный дубль данных при миграции схемы
• Blue/Green Schema Migration: параллельное ведение старой и новой версии таблицы
• Transactional Outbox: публикация событий вместе с транзакцией в БД

5.10 Deployment Patterns

• Feature Flags + Canary Release: новый функционал включается постепенно
• Blue/Green Deployment: два параллельных окружения, быстрое переключение
• Rollback по метрикам: автоматическое отключение фичи/версии при деградации

Часть 6: Схема данных и контракты

6.1 Контракты API

Обязательные требования:

• Все публичные API описываются в OpenAPI или gRPC Proto
• Контракты проходят автоматическую проверку в CI
• Версионирование строгое: SemVer (1.2.3)
• Backward compatibility: поддержка n-1 версии клиента
• Контракты публикуются в артефакт-репозиторий

Важно: Контракты — это формальное соглашение между командами и сервисами.

6.2 Контракты событий

• События описываются в JSON Schema, Avro или Protobuf
• Каждое событие имеет: event_name, version, timestamp, trace_id, payload
• Обязательные поля: id, trace_id, source
• События проходят проверку схемы до публикации

6.3 Версионирование

• Контракты версионируются независимо от сервисов
• Поддержка нескольких версий событий: потребители могут читать v1 и v2 параллельно
• При переходе: producer начинает публиковать оба формата (dual write)

6.4 Схемы БД

• Миграции управляются инструментами: Liquibase/Flyway/golang-migrate/DoctrineMigrations
• Каждое изменение в БД сопровождается скриптом миграции
• Поддерживается shadow-write/read при сложных изменениях схемы
• Все миграции проходят через CI и тестовую базу

6.5 Контракты для Feature Flags

• Фичефлаг — тоже контракт
• Поля: key, type, rules, default, owner, ttl, version
• Хранятся в Postgres (истина) + Redis (кэш)
• Версионируются так же, как API и события

6.6 CI-проверки контрактов

• Проверка схем API и событий на валидность
• Проверка совместимости (n-1)
• Автогенерация SDK (Go, PHP, TS)
• Сравнение изменений с предыдущими версиями

6.7 Документация контрактов

• Сервис-каталог: документация доступна в Swagger UI или gRPC UI
• События документируются в Event Catalog
• Все изменения фиксируются changelog’ом

6.8 «Вайб» в контрактах

• Контракты не только для машин — но и для людей
• Каждое событие описывается в терминах бизнеса, а не техники
• Визуализатор использует схемы для отображения структуры данных в потоке

Часть 7: Наблюдаемость

7.1 Принцип «Observability by Default»

Ключевой принцип CVA:

• Любой новый сервис или модуль в CVA обязан иметь встроенные средства наблюдаемости
• Метрики, логи и трассировки не добавляются «потом» — они часть архитектуры
• Наблюдаемость охватывает и технические, и бизнес-процессы

Принцип: Наблюдаемость — не надстройка, а встроенная часть архитектуры с первого дня.

7.2 Трассировки (Distributed Tracing)

Обязательные требования:

• Используется OpenTelemetry или совместимый стандарт
• Каждый запрос имеет уникальный trace_id
• Каждая операция (SQL, RPC, внешнее API) фиксируется как span
• Все события (Domain Events) также несут trace_id
• Визуализатор (web/VR) строит таймлайн на основе trace_id

Совет: Единый trace_id позволяет проследить весь путь запроса через все сервисы и слои.

7.3 Логи (Structured Logging)

Формат логов:

• Формат: JSON
• Обязательные поля: timestamp, level, trace_id, service, message
• Логи пишутся в stdout → централизованное хранилище (ELK, Loki)
• Ошибки и бизнес-события фиксируются одинаково структурировано

Принцип: Структурированные логи позволяют легко фильтровать и анализировать события.

7.4 Метрики

• Технические: latency (p95/p99), error_rate, saturation, throughput
• Бизнес: количество заказов, конверсия, количество отказов по правилам
• Feature Flags: метрики exposure (сколько пользователей видит фичу), enable_rate
• Метрики доступны в Prometheus/Grafana или аналогах

7.5 Алерты и SLO

• Каждая критичная метрика имеет SLO (Service Level Objective)
• Нарушения → алерты (PagerDuty, Slack, Email)
• Алерты должны быть actionable (понятно, что делать при срабатывании)
• Для фичефлагов есть авто-откат по SLO

7.6 Timeline и Flow Visualization

• Timeline: шаги запроса (API → Application → Domain → Outbox → Consumer)
• Flow Graph: узлы = сервисы/агрегаты, рёбра = события/вызовы
• Heatmap: подсветка узких мест по latency/error_rate
• Поддержка VR: разработчик/аналитик может «увидеть» поток данных в 3D

7.7 Наблюдаемость в CI/CD

• Unit-тесты проверяют наличие базовых метрик и логов
• E2E-тесты фиксируют trace_id и проверяют, что он проходит сквозь систему
• В CI проверяется схема логов и наличие trace_id в событиях

7.8 «Вайб» наблюдаемости

• Система «светится изнутри» — любой запрос или событие видны
• Бизнес может видеть живые дашборды
• Разработчики могут отследить ошибку до конкретного шага
• Наблюдаемость — не надстройка, а часть архитектурного стандарта

Часть 8: Безопасность

8.1 Принцип Zero Trust

Ключевые положения:

• Каждый сервис и компонент взаимодействует с другими только через проверенные каналы
• По умолчанию нет доверия даже внутри одной сети
• Авторизация и аутентификация применяются на каждом уровне

Принцип: Zero Trust означает, что доверие нужно заслужить на каждом шаге, а не предоставлять по умолчанию.

8.2 Аутентификация (AuthN)

• Внешние вызовы: OAuth2 / OpenID Connect / mTLS
• Внутренние вызовы: сервисные аккаунты + mTLS
• Все запросы обязаны содержать корреляционный trace_id и токен авторизации

8.3 Авторизация (AuthZ)

• RBAC (Role-Based Access Control) или ABAC (Attribute-Based Access Control)
• Проверки прав выполняются в Application Layer (policies)
• Feature Flags могут ограничиваться по ролям/сегментам

8.4 Шифрование

• В транзите: TLS 1.3 (API, брокеры, БД)
• В покое: шифрование дисков/таблиц/объектов (AES-256)
• Конфиденциальные данные (PII) — всегда зашифрованы

8.5 Управление секретами

• Секреты не хранятся в коде или переменных окружения
• Используется Vault/KMS (HashiCorp Vault, AWS KMS, GCP Secret Manager)
• Доступ к секретам — строго по принципу минимальных прав

8.6 Аудит и логирование

• Все действия фиксируются в audit log
• Audit log immutable, хранится отдельно
• Для критичных операций фиксируются IP, userId, trace_id, действие, результат

8.7 Feature Flags и безопасность

• Каждый флаг имеет владельца и sunset-дату
• Изменение флагов возможно только с авторизацией
• Все изменения логируются в audit trail
• Kill-switch можно дернуть только авторизованной ролью

8.8 Политики безопасности

• Least Privilege: сервисы и пользователи имеют только минимально необходимые права
• Defense in Depth: защита на каждом уровне (API, App, DB, Infra)
• Fail Secure: при ошибке доступ запрещён, а не открыт

8.9 Соответствие (Compliance)

• CVA ориентируется на стандарты: GDPR, HIPAA, PCI DSS
• Логи и метрики должны учитывать защиту персональных данных
• PII в событиях хэшируется/псевдонимизируется

8.10 «Вайб» безопасности

• Безопасность встроена «по умолчанию», а не как «опция»
• DevOps/разработчик не тратит время на изобретение решений
• Бизнес видит прозрачность: кто, когда и почему сделал изменение

Часть 9: DevEx и продуктивность

9.1 Принцип DevEx-first

Философия CVA:

• Архитектура должна быть удобной для разработчика
• Шаблоны, инструменты и процессы встроены в CVA
• Разработчик тратит минимум времени на рутину и инфраструктуру

Совет: Хороший DevEx повышает скорость разработки и снижает вероятность ошибок.

9.2 Scaffold и генераторы

Автоматизация создания кода:

Генераторы кода для сущностей, команд, событий, портов и адаптеров.

Пример использования:

1

make scaffold module=Order

Создаётся структура:

• Domain: entity, events, value objects
• Application: commands, handlers, policies
• Infrastructure: repository, adapters

Совет: Генераторы обеспечивают единообразие структуры во всех модулях проекта.

9.3 Кодстайл и линтеры

• Единый кодстайл (Go, PHP, JS/TS)
• Pre-commit hooks: линтеры, тесты, security scans
• Обязательная проверка trace_id, логов, фичефлагов

9.4 CI/CD пайплайн

CI проверяет:

• Компиляцию/сборку
• Тесты (unit, integration, e2e)
• Схемы контрактов (API, события)
• Миграции БД
• Security scan

CD поддерживает:

• Blue/green deployment
• Canary deployment

Важно: Автоматизация CI/CD — обязательное требование для безопасной эволюции системы.

9.5 Тестирование

• Unit: инварианты домена
• Property-based: проверка правил и моделей
• Integration: взаимодействие с адаптерами (DB, broker)
• E2E: полный сценарий (запрос → событие → consumer → проекция)
• Smoke-тесты для rollout под feature flags

9.6 Productivity Tools

• Makefile/Taskfile для стандартных задач (build, test, run, migrate)
• Docker Compose/Dev Containers для локальной разработки
• Автогенерация документации (Swagger, AsyncAPI)
• Hot reload / watch mode для dev-окружения

9.7 PR Checklist

Обязательные пункты для каждого PR:

• Есть feature flag
• Добавлены метрики и trace_id
• Контракт обновлён и проверен
• Миграции БД задокументированы
• Тесты: unit + integration + e2e
• Логи структурированы

Важно: Чек-лист обеспечивает качество каждого изменения и соответствие стандартам CVA.

9.8 Обратная связь

• DevEx метрики: время на ревью, время на деплой, MTTR
• Система должна быть «приятной» для работы
• Любое улучшение, которое повышает скорость и снижает стресс разработчиков — часть CVA

9.9 «Вайб» DevEx

• Разработчик чувствует поток: scaffold → код → тесты → визуализация
• Инструменты не мешают, а помогают
• «Сначала скучно, потом приятно» → стандарты дают предсказуемость и уверенность

Часть 10: Референс-скелет (Go)

10.1 Общая структура проекта

/clearvibe
  /cmd
    /app
      main.go             // точка входа
  /internal
    /domain
      /order
        entity.go         // Aggregate, инварианты
        events.go         // Domain Events
        service.go        // Domain Services
    /app
      /order
        commands.go       // команды: CreateOrder, PayOrder
        handler.go        // CommandHandlers
        policies.go       // правила доступа и валидации
        ports.go          // InPorts, OutPorts (Repo, Broker, Flags)
    /infra
      /db
        order_repo_pg.go  // реализация OrderRepo через Postgres
      /broker
        outbox.go         // Outbox publisher
        inbox.go          // Inbox consumer (идемпотентность)
      /http
        server.go         // HTTP API → InPorts
      /obs
        tracing.go        // OpenTelemetry
        metrics.go        // Prometheus
        logging.go        // slog / structured logging
      /flags
        feature_gate.go   // SDK фичефлагов

10.2 Интерфейсы портов

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// internal/app/order/ports.go
package order

type OrderRepo interface {
    Save(*Order) error
    FindByID(id string) (*Order, error)
}

type EventPublisher interface {
    Publish(topic string, key string, payload any) error
}

type FeatureGate interface {
    Enabled(ctx FeatureContext, key string) bool
    Variant(ctx FeatureContext, key string, variants ...string) Variant
}

type FeatureContext struct {
    UserID     string
    OrgID      string
    Attributes map[string]any
}

10.3 Команда и хендлер

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// internal/app/order/commands.go
type CreateOrderCmd struct {
    CustomerID string
    Items      []Item
}

// internal/app/order/handler.go
func (h *createOrderHandler) Handle(cmd CreateOrderCmd) (string, error) {
    if h.flags.Enabled(order.FeatureContext{UserID: cmd.CustomerID}, "orders.dynamic_pricing") {
        // новая ветка логики
    }
    ord, err := domain.NewOrder(cmd.CustomerID, cmd.Items)
    if err != nil {
        return "", err
    }
    if err := h.repo.Save(ord); err != nil {
        return "", err
    }
    evt := domain.OrderCreated{ID: ord.ID, Total: ord.Total}
    if err := h.outbox.Add("order.created", ord.ID, evt); err != nil {
        return "", err
    }
    return ord.ID, nil
}

10.4 Реализация репозитория

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// internal/infra/db/order_repo_pg.go
type PgOrderRepo struct { db *sql.DB }

func (r *PgOrderRepo) Save(o *domain.Order) error {
    _, err := r.db.Exec("INSERT INTO orders(id, customer_id, total) VALUES($1,$2,$3)",
        o.ID, o.CustomerID, o.Total)
    return err
}

func (r *PgOrderRepo) FindByID(id string) (*domain.Order, error) {
    row := r.db.QueryRow("SELECT id, customer_id, total FROM orders WHERE id=$1", id)
    var ord domain.Order
    if err := row.Scan(&ord.ID, &ord.CustomerID, &ord.Total); err != nil {
        return nil, err
    }
    return &ord, nil
}

10.5 Outbox Publisher

1
2
3
4
5
6
7
8
9

// internal/infra/broker/outbox.go
type Outbox struct { db *sql.DB }

func (o *Outbox) Add(topic, key string, payload any) error {
    data, _ := json.Marshal(payload)
    _, err := o.db.Exec("INSERT INTO outbox(topic, key, payload, created_at) VALUES($1,$2,$3,now())",
        topic, key, data)
    return err
}

10.6 Feature Flags SDK

1
2
3
4
5
6
7
8

// internal/infra/flags/feature_gate.go
type RedisFeatureGate struct { cache *redis.Client }

func (g *RedisFeatureGate) Enabled(ctx order.FeatureContext, key string) bool {
    val, err := g.cache.Get(context.Background(), "flag:"+key).Result()
    if err != nil { return false }
    return val == "true"
}

10.7 Observability интеграция

• tracing.go: инициализация OpenTelemetry, экспорт трейсов
• metrics.go: регистрация бизнес-метрик (order_created_total)
• logging.go: slog с JSON-форматом и trace_id

10.8 «Вайб» Go-скелета

• Чёткое разделение слоёв
• Feature flags встроены сквозь Application
• Outbox обеспечивает надёжную доставку событий
• Observability встроена в каждый слой
• Код легко тестируется (моки портов)

Часть 11: Референс-скелет (Symfony/PHP)

11.1 Общая структура проекта

src/
  Domain/Order/
    Entity/Order.php
    Event/OrderCreated.php
    ValueObject/Item.php
    Service/PricingService.php
    Repository/OrderRepositoryInterface.php
  Application/Order/
    Command/CreateOrder.php
    Handler/CreateOrderHandler.php
    Policy/OrderPolicy.php
    Port/In/CreateOrderHandlerInterface.php
    Port/Out/OrderRepository.php
    Port/Out/OutboxBus.php
    Port/Out/FeatureGate.php
  Infrastructure/
    Persistence/Doctrine/OrderRepository.php
    Messaging/OutboxPublisher.php
    FeatureFlags/RedisFeatureGate.php
    Http/Controller/OrderController.php
    Observability/TracingMiddleware.php
    Observability/Logger.php
    Observability/Metrics.php

11.2 Сущность и событие

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// src/Domain/Order/Entity/Order.php
final class Order {
    private string $id;
    private string $customerId;
    private array $items;
    private float $total;

    private function __construct(string $customerId, array $items) {
        $this->id = Uuid::uuid4()->toString();
        $this->customerId = $customerId;
        $this->items = $items;
        $this->total = array_sum(array_map(fn($i) => $i->price(), $items));
    }

    public static function create(string $customerId, array $items): self {
        return new self($customerId, $items);
    }

    public function id(): string { return $this->id; }
    public function total(): float { return $this->total; }
}

// src/Domain/Order/Event/OrderCreated.php
final class OrderCreated {
    public function __construct(
        public readonly string $id,
        public readonly float $total,
    ) {}
}

11.3 Команда и обработчик

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// src/Application/Order/Command/CreateOrder.php
final class CreateOrder {
    public function __construct(
        public readonly string $customerId,
        public readonly array $items,
    ) {}

    public static function fromRequest(Request $r): self {
        return new self(
            $r->get('customerId'),
            $r->get('items', [])
        );
    }
}

// src/Application/Order/Handler/CreateOrderHandler.php
final class CreateOrderHandler {
    public function __construct(
        private OrderRepositoryInterface $repo,
        private OutboxBus $outbox,
        private FeatureGate $flags,
    ) {}

    public function __invoke(CreateOrder $cmd): string {
        if ($this->flags->enabled(new Context(userId: $cmd->customerId), 'orders.dynamic_pricing')) {
            // новая логика ценообразования
        }
        $order = Order::create($cmd->customerId, $cmd->items);
        $this->repo->save($order);
        $this->outbox->add('order.created', $order->id(), new OrderCreated($order->id(), $order->total()));
        return $order->id();
    }
}

11.4 Репозиторий

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// src/Infrastructure/Persistence/Doctrine/OrderRepository.php
final class OrderRepository implements OrderRepositoryInterface {
    public function __construct(private EntityManagerInterface $em) {}

    public function save(Order $order): void {
        $this->em->persist($order);
        $this->em->flush();
    }

    public function findById(string $id): ?Order {
        return $this->em->find(Order::class, $id);
    }
}

11.5 Outbox Publisher

1
2
3
4
5
6
7
8
9

// src/Infrastructure/Messaging/OutboxPublisher.php
final class OutboxPublisher implements OutboxBus {
    public function __construct(private EntityManagerInterface $em) {}

    public function add(string $topic, string $key, object $event): void {
        $this->em->persist(new OutboxMessage($topic, $key, $event));
        $this->em->flush();
    }
}

11.6 Feature Flags

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// src/Infrastructure/FeatureFlags/RedisFeatureGate.php
final class RedisFeatureGate implements FeatureGate {
    public function __construct(private Redis $redis) {}

    public function enabled(Context $ctx, string $key): bool {
        return $this->redis->get("flag:$key") === 'true';
    }

    public function variant(Context $ctx, string $key, array $variants): string {
        $hash = crc32($ctx->userId . $key);
        return $variants[$hash % count($variants)];
    }
}

11.7 Контроллер

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// src/Infrastructure/Http/Controller/OrderController.php
#[Route('/orders', methods: ['POST'])]
final class OrderController extends AbstractController {
    public function __construct(private MessageBusInterface $bus) {}

    public function create(Request $r): JsonResponse {
        $dto = CreateOrder::fromRequest($r);
        $envelope = $this->bus->dispatch($dto);
        return $this->json([
            'status' => 'accepted',
            'trace' => $r->headers->get('X-Trace-Id'),
        ]);
    }
}

11.8 Observability

• TracingMiddleware: добавляет trace_id в каждый запрос и передаёт его в шину сообщений
• Logger: структурированный JSON-лог через Monolog
• Metrics: счётчики (order_created_total), latency, error_rate

11.9 «Вайб» Symfony-скелета

• DDD-структура: Domain/Application/Infrastructure
• Feature flags интегрированы прямо в Handler
• Outbox обеспечивает надёжность доставки событий
• Observability встроена в middleware, логику и метрики
• Код легко тестируется и масштабируется

Часть 12: Политики эволюции

12.1 Общий принцип

Ключевой принцип эволюции:

Эволюция — управляемая и наблюдаемая.

Любое изменение:

• Проходит через фичефлаги, контракты и миграции
• Имеет владельца и риск-план
• Имеет пути отката

Принцип: Безопасная эволюция требует планирования и возможности отката на каждом этапе.

12.2 Версионирование контрактов (API/Events)

• SemVer: MAJOR.MINOR.PATCH
• Совместимость n-1: минимум одна предыдущая версия поддерживается
• Dual write/read: при миграции событий производитель публикует vN и vN+1
• CI-валидаторы совместимости: запрещают breaking-changes без MAJOR

12.3 Жизненный цикл фичи (Feature Lifecycle)

Этапы жизненного цикла:

1. Draft: флаг создан (disabled), владелец, цель, метрики успеха, sunset-дата

2. Internal: включено для dev/stage/own team

3. Canary: 1% → 5% → 25% → 50% → 100% (детерминированный бакетинг)

4. General Availability: флаг по умолчанию on

5. Sunset: флаг и мёртвый код удалены, контракты стабилизированы

Совет: Постепенный rollout позволяет выявить проблемы на ранних этапах.

12.4 Стратегии релиза

• Blue/Green: два окружения, переключение трафика
• Canary: инкрементальный rollout с авто-стражами по SLO
• Dark Launch: код задеплоен, фича выключена флагом до активации

12.5 Откат (Rollback) и Kill-Switch

• Kill-Switch: мгновенно отключает фичу на всём трафике
• Auto-rollback: триггер по SLO (error_rate/latency/conversion)
• Чек-лист отката: кто дергает, что откатываем, как верифицируем

12.6 Эволюция данных и схем

• Миграции с обратимостью: up/down
• Shadow Write/Read: временно пишем в новую схему, читаем из старой
• Backfill/Replay: безопасная догрузка исторических данных
• Контроль последовательности: миграции данных не идут вперёд без зелёных метрик

12.7 Политики изменения домена

• Изменение инвариантов — только через фичефлаг и миграции
• Новые атрибуты — совместимые (nullable/optional) до полного включения
• Удаление полей — после sunset и MAJOR

12.8 Governance изменений

• RFC/ADR: каждое значимое изменение оформляется решением
• Owner & DRI: владелец, сроки, метрики успеха, риск-план
• Gate в PR: наличие флага, метрик, миграций, тестов — обязательно

12.9 Наблюдаемость эволюции

• Метрики миграций: скорость backfill, доля трафика на новой ветке
• События эволюции: flag.exposed, flag.variant, migration.started/completed
• Дашборды перехода: сравнение p95/error_rate/бизнес-метрик по старой/новой ветке

12.10 Безопасность и соответствие

• Изменение флагов/контрактов — только с RBAC и аудитом
• PII-безопасность при миграциях (псевдонимизация/шифрование)
• Хранение ADR/RFC и журналов аудита — неизменяемое

Часть 13: Feature Toggles

13.1 Принцип

Feature Toggles — обязательный и сквозной паттерн CVA.

Любой новый функционал внедряется только за флагом:

• Флаг есть всегда
• У каждого флага есть владелец, версия, sunset-дата и kill-switch
• Решения по флагу наблюдаемы и логируются

Принцип: Feature flags — не опциональный инструмент, а обязательный механизм управления изменениями.

13.2 Типы флагов

Основные типы feature flags:

• Boolean: включен/выключен
• Percentage: процент трафика (canary rollout)
• Segment: включение по атрибутам (страна, тариф, роль)
• Multivariant: несколько вариантов для A/B/n-тестов

Совет: Выбирайте тип флага в зависимости от стратегии раскатки функционала.

13.3 Архитектура слоя фичефлагов

Interface/UI ─┐  reads → FeatureGate SDK (in-proc cache) ─┐
API/gRPC ─────┤                                           │
Application ──┤  policies/deciders → uses FeatureGate ────┼→ Telemetry
Domain ───────┘                                           │
Infrastructure: Provider (PG/Redis), Syncers, Warmers, Auditor ─┘

13.4 Контракты и хранение

• Хранилище: Postgres (источник истины) + Redis (кэш, pub/sub)
• Схема: flags(id, key, type, rules, default, owner, version, ttl, updated_at)
• Правила: JSON Schema для сегментов/процентов/вариантов
• Версионирование: SemVer для контрактов флагов, поддержка n-1

13.5 SDK API (Go)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

type FeatureContext struct {
    UserID, OrgID string
    Attributes    map[string]any
}

type Variant struct { Key string; Payload any }

type FeatureGate interface {
    Enabled(ctx FeatureContext, key string) bool
    Variant(ctx FeatureContext, key string, variants ...string) Variant
}

Использование:

1
2
3

if flags.Enabled(FeatureContext{UserID: cmd.CustomerID}, "orders.dynamic_pricing") {
    // новая логика
}

13.6 SDK API (Symfony/PHP)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

interface FeatureGate {
    public function enabled(Context $ctx, string $key): bool;
    public function variant(Context $ctx, string $key, array $variants): string;
}

final class Context {
    public function __construct(
        public readonly ?string $userId=null,
        public readonly ?string $orgId=null,
        public readonly array $attributes=[]
    ) {}
}

13.7 Метрики и наблюдаемость

• Exposure events: flag.exposed, flag.variant
• Метрики: exposure_count, enable_rate, error_rate, stale_cache_count
• Дашборды: сравнение вариантов (A/B), корреляция с бизнес-метриками
• Trace_id: всегда прокидывается в события экспозиции

13.8 Rollout & Sunset процесс

1. Флаг создаётся с default=off
2. Включается для команды (internal)
3. Canary rollout: 1% → 5% → 25% → 50% → 100%
4. General Availability: включен для всех
5. Sunset: мёртвый код и сам флаг удалены

13.9 Безопасность

• Управление флагами доступно только авторизованным ролям (RBAC)
• Все изменения фиксируются в audit log
• PII-атрибуты для сегментации хэшируются
• Подпись снапшотов правил для защиты от подмены

13.10 Чек-лист для PR

• Добавлен флаг (с ключом, владельцем, sunset)
• Есть kill-switch
• Метрики и события exposure подключены
• Есть тесты (unit + e2e)
• Флаг документирован

13.11 «Вайб» фичефлагов

• Безопасные изменения без страха
• Возможность быстро экспериментировать (A/B)
• Прозрачность: все знают, какие фичи включены
• Визуализация: на таймлайне видно, где запрос свернул по фичефлагу

Часть 14: Визуализация

14.1 Принцип

Ключевое положение CVA:

В CVA визуализация — это не «приятная опция», а обязательный слой.

Система должна уметь показать поток данных и событий.

Важно: Визуализация делает систему понятной не только для разработчиков, но и для бизнеса.

14.2 Timeline

Хронологическое отображение запроса:

• Отображает шаги запроса в хронологическом порядке
• Примеры шагов: HTTP-запрос принят, Handler выполнен, Событие записано в Outbox
• Каждому шагу соответствует span (trace)
• Timeline доступен в web-интерфейсе и экспортируется в VR

Совет: Timeline помогает визуально увидеть узкие места и последовательность операций.

14.3 Flow Graph

• Узлы: сервисы, агрегаты, адаптеры
• Рёбра: вызовы и события
• Поддержка фильтров: по trace_id, по типу событий, по ошибкам/latency
• Можно проследить путь любого запроса

14.4 Heatmap

• Подсветка узких мест
• Метрики latency/error_rate визуализируются в цвете
• Красный = проблема, зелёный = норма
• Используется для анализа производительности и деградаций

14.5 VR-визуализация

• Поток данных можно «увидеть» в 3D (VR/AR)
• Узлы-сервисы в пространстве, линии-события движутся в реальном времени
• Полезно для обучения новых членов команды и анализа инцидентов
• Интерактивное включение/выключение фичефлагов в VR

14.6 Интеграция с Observability

• Визуализация строится на основе данных OpenTelemetry
• Метрики Prometheus/Grafana агрегируются и отображаются в графах
• Exposure событий фичефлагов отображаются как точки ветвления

14.7 Сценарии использования

• Dev: отладка бизнес-логики → видно, как событие «идёт» по сервисам
• Ops: поиск bottleneck при инцидентах
• Biz: наглядная демонстрация работы продукта

14.8 «Вайб» визуализации

• Система становится «живой» и «светящейся»
• Любой член команды может увидеть поведение, а не только читать логи
• Визуализация формирует доверие между разработкой и бизнесом

Часть 15: Чек-листы внедрения

15.1 Общий чек-лист проекта

• Определены Bounded Contexts и Ubiquitous Language
• Сформирована архитектурная карта слоёв
• Назначен владелец архитектуры (Architecture Owner / Tech Lead)

15.2 Domain Layer

• Все сущности описаны как Entity/ValueObject
• Инварианты зафиксированы и покрыты тестами
• Domain Events определены и документированы
• Нет зависимостей на ORM/HTTP/брокеры

15.3 Application Layer

• Каждое действие оформлено как Command/Query
• Для каждой команды есть Handler
• Политики (Policy) валидируют доступ и правила
• Транзакционные границы определены
• Feature Flags встроены в use cases

15.4 Infrastructure Layer

• Реализованы репозитории через OutPorts
• Подключен Outbox (обязательный)
• Подключен Inbox для входящих событий
• Настроены адаптеры для API/брокеров/БД
• Подключены observability-компоненты

15.5 Interface Layer

• API оформлено в OpenAPI/gRPC
• Добавлен middleware для trace_id и логирования
• Авторизация/аутентификация включены
• Контракты проверяются в CI

15.6 Feature Toggles

• У каждого нового кода есть фичефлаг
• Флаги имеют владельца, sunset-даты, kill-switch
• Exposure событий логируются
• Rollout сценарии задокументированы
• Тесты включают on/off сценарии

15.7 Observability

• Все запросы/события имеют trace_id
• Логи структурированы (JSON)
• Метрики: технические + бизнес
• Дашборды и алерты настроены
• Визуализатор подключен (timeline/flow graph/VR)

15.8 Data & Contracts

• API и события имеют схемы
• Контракты версионированы (SemVer)
• Проверка backward-compatibility в CI
• Миграции БД описаны и протестированы
• Shadow-write/read используется при сложных изменениях

15.9 Security

• Все вызовы аутентифицированы
• RBAC/ABAC политики определены
• Секреты в Vault/KMS
• Audit log immutable и централизован
• PII обрабатываются безопасно

15.10 Delivery & Deployment

• CI: сборка, тесты, линтеры, security scan
• CD: canary/blue-green deployment
• Rollback план задокументирован
• Auto-rollback по SLO включён
• Canary метрики мониторятся

15.11 People & Process

• PR checklist в каждом репозитории
• ADR для значимых изменений
• Регулярный архитектурный review
• Метрики DevEx измеряются
• Обучение команды по CVA

15.12 «Вайб» чек-листов

• Чек-листы делают внедрение архитектуры предсказуемым
• Разработчики уверены, что ничего не упустили
• Бизнес получает стабильную эволюцию без сюрпризов

Часть 16: Лицензирование и вклад

16.1 Лицензия

• Open Source (MIT/Apache 2.0): архитектурные принципы, чек-листы и шаблоны доступны свободно
• Можно использовать в коммерческих и некоммерческих проектах без ограничений
• Единственное требование — сохранять упоминание авторства и лицензии

16.2 Contribution Guide

Pull Request принимается только если:

• Прописан ADR для изменений
• Пройден CI (контракты, тесты, миграции)
• Обновлены чек-листы и документация
• Добавлены примеры (Go/PHP SDK, миграции, метрики)

16.3 Governance

• Maintainers: ответственны за review и выпуск новых версий CVA-манифеста
• Contributors: вносят идеи, багфиксы, дополнения к чек-листам и паттернам
• Решения принимаются через RFC/ADR

16.4 Версионирование манифеста

• Манифест CVA также следует SemVer
• MINOR — добавление паттернов/чек-листов
• MAJOR — изменения в обязательных принципах

16.5 Community

• Slack/Discord/Matrix-группа для обсуждений
• Wiki с best practices и шаблонами
• Showcase: список компаний/проектов, внедривших CVA

16.6 «Вайб» вклада

• CVA — это живая архитектура, которая развивается вместе с сообществом
• Вклад — не только код, но и: документация, схемы, визуализации, примеры
• Каждый коммит делает систему прозрачнее, надёжнее и «вайбовее»

Ключевые отличия CVA

От классической Hexagonal/Clean Architecture

База та же (DDD + Hexagonal), но CVA делает обязательными вещи, которые обычно «допиливают потом»:

• Событийность (Domain Events + Outbox/Inbox)
• Наблюдаемость (трейсинг/метрики/структурные логи)
• Фичефлаги со сквозной интеграцией
• Управляемая эволюция (canary/blue-green, контрактное версионирование)
• Визуализация потока (веб/VR)

Идея: система изначально «живая, прозрачная и безопасно эволюционирующая».

Где CVA лучше

1. Прозрачность и отладка — встроенный OpenTelemetry, бизнес-метрики, timeline
2. Надёжная интеграция — Outbox/Inbox, идемпотентность, ретраи по умолчанию
3. Безопасные релизы — feature flags, canary rollout, kill-switch, авто-откат
4. Управляемая эволюция — SemVer, dual write/read, shadow write/read
5. Developer Experience — шаблоны, чек-листы, стандарты
6. Понимание для бизнеса — визуализация потока, бизнес-метрики из коробки
7. Безопасность по умолчанию — RBAC, аудит, zero-trust

Где классический Hexagonal проще

1. Маленькие проекты и редкие релизы
2. Команда без опыта событийности и телеметрии
3. Жёсткие ограничения по инфраструктуре

Когда выбирать CVA

• Микросервисы и интеграционно насыщенные системы
• Частые релизы и эксперименты (growth/продуктовые команды)
• Высокие требования к надёжности доставки событий
• Нужно «прозрачно» объяснять технологию бизнесу
• Планируется масштабирование команды и проекта

Когда лучше остаться на классическом Hexagonal

• Простой сервис/монолит без активной эволюции
• Команда маленькая, нет ресурсов на телеметрию и фичефлаги
• Внешних интеграций почти нет, SLA мягкие

Заключение

ЧистаяВайбАрхитектура — это не просто набор паттернов, а целостный подход к построению современных бэкенд-систем.

CVA делает систему:

• Прозрачной — каждый запрос видим от начала до конца

• Надёжной — события доставляются гарантированно

• Безопасной — изменения контролируемы и откатываемы

• Понятной — визуализация помогает всем: от разработчиков до бизнеса

Резюме: Это «Hexagonal на стероидах» — дороже на старте, но многократно окупается на средних и больших системах.