Версия документа: 1.4.2 | Дата последнего обновления: | Статус: Активно применяется в продакшн-среде

Часть 64365 определяет стандартизированный протокол взаимодействия между микросервисами в высоконагруженных распределенных системах. Данная спецификация разработана для решения проблем согласованности данных, отказоустойчивости и наблюдаемости (observability) при масштабировании горизонтальных кластеров.

Документ является обязательным к реализации для всех внутренних сервисов, обрабатывающих финансовые транзакции, персональные данные пользователей и телеметрию IoT-устройств.

Ключевые цели спецификации

• Гарантия exactly-once семантики доставки сообщений без блокирующих координаторов.
• Унификация формата логов и метрик для автоматической индексации в Elasticsearch/OpenSearch.
• Минимизация задержки (latency) на 99-м перцентиле до < 50 мс в междатацентровом взаимодействии.
• Встроенная поддержка схем данных (Schema Registry) с обратной и прямой совместимостью (Backward/Forward Compatibility).

Нормативные ссылки

1. RFC 7540 (HTTP/2) — транспортный уровень по умолчанию.
2. RFC 8259 (JSON) — базовый формат полезной нагрузки (Payload).
3. Apache Avro Specification 1.11 — для бинарной сериализации в высокопроизводительных топиках Kafka.
4. OpenTelemetry Specification 1.20 — для трассировки и метрик.

Архитектурные принципы

Модель взаимодействия: Smart Endpoints, Dumb Pipes

Согласно Части 64365, вся бизнес-логика валидации, трансформации и маршрутизации инкапсулируется в клиентских библиотеках (SDK) и сервисах-консьюмерах. Мессенджинговая инфраструктура (Kafka, NATS, RabbitMQ) рассматривается как «глупая труба», обеспечивающая только доставку и порядок сообщений внутри партиции.

Идемпотентность как обязательное требование

Каждая операция, изменяющая состояние (Command), обязана обладать свойством идемпотентности. Для этого в заголовке каждого сообщения должен присутствовать уникальный идентификатор операции X-Operation-Id (UUID v7).

// Пример заголовков сообщения (Headers)
X-Operation-Id: 018f3a2b-4c5d-7e8f-9a0b-c1d2e3f4a5b6
X-Schema-Version: 3
X-Correlation-Id: 018f3a2b-4c5d-7e8f-9a0b-c1d2e3f4a5b6
X-Causation-Id: 018f3a2b-4c5d-7e8f-9a0b-c1d2e3f4a5b5
Content-Type: application/avro+binary

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

Правила версионирования (Schema Evolution)

Спецификация Часть 64365 строго регламентирует изменения схем данных. Нарушение этих правил блокируется на этапе CI/CD пайплайна линтером schema-registry-cli.

Обработка «грязных» данных и кодировка

В контексте миграции легаси-систем (см. раздел 7), Часть 64365 предписывает использование UTF-8 как единственной кодировки. Любые байтовые последовательности, не проходящие валидацию UTF-8, должны быть заменены на символ замещения U+FFFD (�) при входе в систему (Ingress) с генерацией метрики encoding_errors_total.

Это критически важно при интеграции с внешними API, возвращающими данные в кодировках windows-1251 или koi8-r, а также при парсинге пользовательского ввода, содержащего смешанные скрипты (кириллица/латиница/эмодзи).

Транспортный уровень и Сетевая политика

mTLS и Service Mesh

Взаимодействие разрешено только через mTLS (mutual TLS) внутри Service Mesh (Istio / Linkerd). Текстовый HTTP/1.1 запрещен для межсервисного обмена, за исключением health-check эндпоинтов (/healthz, /ready).

Таймауты и Ретраи (Retries)

Стандартные значения, заданные в Части 64365 (переопределяются через ConfigMap):

• Connect Timeout: 200 ms
• Request Timeout (P99): 5000 ms
• Retry Policy: Макс. 3 попытки с экспоненциальным бэкоффом (base 50ms, max 1s) + jitter (±10%);
• Retryable Status Codes: 429, 500, 502, 503, 504.
• Non-Retryable: 4xx (кроме 429), 501.

Circuit Breaker (Автоматический выключатель)

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

1. Error Threshold: > 5% ошибок за 10 секунд.
2. Minimum Request Volume: 20 запросов за окно.
3. Sleep Window: 30 секунд (после открытия цепи).
4. Half-Open Probes: 5 тестовых запросов перед закрытием.

Наблюдаемость (Observability) — «Три столпа»

Реализация Части 64365 не считается завершенной без полной инструментации.

Логирование (Structured Logging)

Формат: JSON Lines. Поля timestamp (RFC3339Nano), level, message, trace_id, span_id, service.name — обязательны.

{
 "timestamp": "2026-07-25T02:50:45.123456789Z",
 "level": "WARN",
 "logger": "payment.gateway",
 "message": "Upstream latency exceeded threshold",
 "trace_id": "018f3a2b4c5d7e8f9a0bc1d2e3f4a5b6",
 "span_id": "c1d2e3f4a5b6c7d8",
 "service.name": "payment-api",
 "latency_ms": 4850,
 "threshold_ms": 4000
}

Метрики (Prometheus Exposition Format)

Именование следует соглашению <subsystem>_<action>_<unit> (например, http_requests_total, db_query_duration_seconds). Обязательные лейблы: job, instance, env (prod/staging), version (semver).

Распределенная трассировка (Distributed Tracing)

Контекст трассировки (W3C TraceContext) передается через заголовки traceparent и tracestate. Сэмплинг: Head-based (100% для ошибок 5xx, 10% для успешных, 100% для финансовых операций).

Работа с поисковыми подсистемами (Elasticsearch / OpenSearch)

Данный раздел регламентирует взаимодействие сервисов с кластерами поиска, что актуально для задач полнотекстового поиска, аналитики логов и автодополнения.

Индексация и Маппинги

• Использование dynamic: strict во всех маппингах. Новые поля требуют ревью и деплоя через миграции.
• Для текстов на русском языке обязательно использование анализатора russian_morphology (на базе morphology плагина) или кастомного анализатора с фильтром russian_stemmer и стоп-словами.
• Поля keyword для точного совпадения (ID, статусы, теги) и text с fields.keyword для гибридного поиска.

Оптимизация запросов

Запрещены запросы wildcard и regexp на горячих данных (hot tier). Для префиксного поиска используйте search_as_you_type или n-gram токенизаторы на индексе. При необходимости поиска по фразам с пунктуацией (например, "Что за бред!") используйте match_phrase с кастомным анализатором, сохраняющим знаки препинания, или shingle фильтр.

Экспорт в CSV / Отчеты

Для выгрузки больших выборок (>10k документов) в CSV формат нельзя использовать Scroll API или size=10000. Необходимо использовать Point In Time (PIT) + search_after с сортировкой по _shard_doc или детерминированному полю (timestamp + id). Это предотвращает OOM ошибки на координирующих нодах.

Стратегия миграции и Legacy-интеграция

Внедрение Части 64365 в существующую экосистему производится по паттерну Strangler Fig.

Адаптеры (Anti-Corruption Layer)

Для систем, не поддерживающих Avro/Protobuf и mTLS, разворачиваются сайдкар-адаптеры (Sidecar Proxies), выполняющие:

1. Терминацию mTLS.
2. Транскодирование JSON <-> Avro.
3. Валидацию схемы перед публикацией в Kafka.
4. Обогащение заголовков (добавление X-Operation-Id, если легаси его не генерирует).

Dual Write / CDC

При миграции БД используется Change Data Capture (Debezium) для репликации изменений в Kafka топики, соответствующие контрактам Части 64365. Прямая запись в новую и старую БД (Dual Write) запрещена из-за риска расхождения данных.

Безопасность и Соответствие (Compliance)

• Шифрование в покое: AES-256-GCM для всех топиков Kafka (конфиг message.format.version=3.0), дисков БД и бэкапов S3.
• Управление секретами: Только через Vault / SealedSecrets. В коде и конфигмапах секретов быть не должно.
• Аудит: Все административные действия (создание топиков, изменение ACL, деплой схем) логируются в immutable audit log ( кластер Kafka/ClickHouse).
• PII Handling: Поля, помеченные аннотацией @PII в схеме, автоматически маскируются в логах и недоступны для выборки в Grafana/Кибане без роли pii-viewer.

Чек-лист готовности к продакшену (Production Readiness Review)

Перед релизом любого сервиса, реализующего Часть 64365, команда должна пройти PRR и подтвердить:

1. [ ] Контракты (Avro/Proto) зарегистрированы в Schema Registry, прошли линтинг.
2. [ ] Настроены SLO/SLI (Latency, Availability, Error Rate) в мониторинге.
3. [ ] Реализованы Health Checks (liveness, readiness, startup).
4. [ ] Проведено нагрузочное тестирование (k6 / JMeter) с профилем production traffic.
5. [ ] Настроены алерты на Burn Rate (Multi-window, Multi-burn-alerting).
6. [ ] Документирован Runbook для инцидентов (On-call guide).
7. [ ] Пройден Chaos Engineering эксперимент (Pod Kill, Network Partition, Dependency Latency).
8. [ ] Соответствие GDPR / 152-ФЗ верифицировано DPO.

Часть 64365 является живым документом. Любые предложения по изменениям (RFC) оформляются через внутренний портал архитектурного комитета (Arch Review Board). Обратная совместимость протокола гарантируется в рамках мажорной версии (v1.x). Переход на v2.0 будет инициирован не ранее Q4 2026 года с 12-месячным периодом поддержки v1.

Последнее ревью: Архитектор платформы, Lead SRE, Security Officer. Подписи в системе управления документами (Confluence/GitOps).