8.4 KiB
Архитектура лабораторной 2
Статус: реализовано, проверено локально и развёрнуто в Kubernetes dev / highload-applications. Требования: SPEC, фактический статус: PLAN.
Сохраняются Fiber v2, Fx, Zap и транспортный реестр fielderr. Composition root связывает интерфейсы с реализациями. Controller декодирует HTTP и преобразует DTO, service валидирует значения и доступ, PostgreSQL store исполняет SQL и транзакции. Парольная криптография и кеширование имеют собственные интерфейсы потребителей.
Схема и транзакции
users: UUID PK, username UNIQUE, display_name, password_hash, created_at. chats: UUID PK, title, created_at. chat_members: составной PK(chat_id,user_id), FK на users/chats. messages: UUID PK, chat_id/sender_id FK, text, created_at; индекс (chat_id,created_at,id). sessions: hash токена PK, user_id FK, expires_at. Создание чата и всех участников — одна транзакция; ограничение username обеспечивается БД, включая гонки. Вставки сообщений сериализуются на строке чата для монотонного времени в пределах чата. Чтение истории использует keyset и LIMIT, без OFFSET.
PostgreSQL хранит источник истины. Кэш неизменяемых профилей пользователей допускает безопасное восстановление из БД; сессия проверяется по PostgreSQL при каждом запросе, поэтому logout не зависит от успешной инвалидации кэша. TTL ограничивает срок хранения профиля. История не кэшируется.
Admission и шарды
Клиентское кольцо consistent hashing с виртуальными узлами распределяет пользовательские ключи и кэш между 2–3 самостоятельными Valkey. Это не Redis Cluster с его 16384 hash slots. Глобальный координатор лимитов имеет стабильный адрес и не перемещается при расширении кольца. Группы auth/read/write имеют независимые бюджеты. Слоты ограничивают одновременную работу, rate ограничивает частоту; lease освобождается при завершении и истекает после аварии. Недоступность limiter закрывает admission с ограниченной ошибкой.
Topology изменяется через остановку admission и drain активных lease; после выдержки полного окна rate новое кольцо безопасно включается. Кэш прогревается по требованию: обязательные данные не перемещаются и не теряются. Это демонстрация шардирования, не высокая доступность: отказ единственного PostgreSQL или глобального координатора останавливает обязательный путь.
Go и зависимости
Указатели на данные конфигурации, nullable значения и конкретные внутренние объекты инфраструктурного адаптера допустимы. Интерфейсы вводятся на границах поведения, прежде всего service/store/admission, а не для каждого поля. Все функции многострочные и документированы; HTTP-коды принадлежат transport.
Результат аудита зависимостей
Controller получает service.Service, service.Authentication, admission.Distributed и собственный интерфейс Readiness. Прямая зависимость от *admission.Limiter заменена. Business service получает store.Interface, service.CursorCodec и service.ProfileCache; authentication получает service.Accounts и service.Passwords. PostgreSQL/Valkey связываются только в cmd/server.
Конкретные указатели *fiber.App, *zap.Logger, *fielderr.Registry, *pgxpool.Pool, *redis.Client остаются внутри соответствующих инфраструктурных адаптеров. Они не пересекают business service boundary. Nullable cursor и указатели на секции конфигурации являются представлением данных, интерфейсы им не требуются.
Memory store и локальный limiter сохранены для независимых тестовых fixtures. Production Fx graph использует только PostgreSQL и Valkey. Публичная регистрация проходит через authentication и KDF. UsersCreate базового service остаётся операцией профильных fixtures; HTTP route не вызывает её напрямую.
Основные SQL-запросы используют pgx.StrictNamedArgs; статические migration DDL не содержат значений пользователя и выполняются без параметров. Миграция embedded, не зависит от рабочего каталога контейнера. Все чтения rows закрываются и проверяют rows.Err().
Фактические проверки и эксплуатационные ограничения, включая process-local cursor key, приведены в REPORT. Указанные Go conventions проверяются formatter/lint и AST-тестом направления импортов; они не заменяют анализ ответственности компонентов.
Классификация ошибок
PostgreSQL нормализует сетевые ошибки, разрыв соединения, deadline и SQLSTATE недоступности в store.ErrUnavailable, сохраняя исходную причину для errors.Is. service.ErrUnavailable — alias этой общей категории интерфейса хранилища; controller не импортирует драйвер или store. Это сохраняет классификацию и на пути проверки сессии, и в бизнес-операциях. HTTP-слой возвращает фиксированный 503/unavailable без деталей. Неизвестные ошибки SQL остаются 500; ограничения уникальности и отсутствие записи сохраняют прежнее отображение.
Развёртывание
Helm chart — единственный источник ресурсов стенда. Values задают образ, API-конфигурацию, ресурсы и число шардов. Изменение конфигурации меняет checksum pod template и вызывает rollout API. Namespace изолирует лабораторную; имена StatefulSet и PVC стабильны. Credentials создаются отдельно и передаются по именам Secret, без записи паролей в Helm values.
Смена кольца выполняется командой make reshard через Helm upgrade с остановленным API и ожиданием 31 секунды. Runtime topology guard защищает от несовпадающих колец; chart дополнительно запрещает изменение topology при работающем API. Подробности и порядок переноса существующих ресурсов: ADR-0002.