API-шлюз и маршрутизация

1) Роль API-шлюза в архитектуре

• Маршрутизирует запросы (по пути/хедерам/гео/весу/версии).
• Защищает периметр (TLS/mTLS, WAF, DDoS, rate limits, authN/Z).
• Управляет трафиком (canary/AB, shadow/mirror, circuit breaker, ретраи, таймауты).
• Стандартизирует протоколы (REST/gRPC/WebSocket), заголовки, коды.
• Наблюдает (логи, метрики, трассировки, кореляция).
• Трансформирует и валидирует (JSON/XML, нормализация, schema-validation).

Для iGaming это еще и гео-комплаенс (блокировки по странам/возрасту), платежный смарт-роутинг и политики ответственной игры на краю.

2) Варианты маршрутизации

Path-based: `/api/v1/payments/ → payments-svc`.
Host-based: `eu.api.example.com → eu-edge`, `psp.example.com → psp-proxy`.
Header-based: `X-Client: partner-A` → партнерский бэкенд; `Accept: application/grpc`.
Geo-routing: по IP/ASN/стране (GDPR/локальные запреты, latency).
Weighted/Canary: `90%` на старую, `10%` на новую версию; быстрое откатывание.
Claim-routing: по `JWT.claims.tier/role/region` (например, high-roller → premium-лимиты).
Failover: актив-актив/актив-пассив между ЦОД/облаками и PSP.

3) Безопасность периметра

TLS everywhere: TLS 1.2+ на внешке, mTLS внутри (шлюз↔сервисы).
OAuth2/JWT: проверка подписи, аудит `exp/nbf/aud/scope`, JWKS-ротация; кеш валидации с TTL.
HMAC: подпись тел для webhooks/платежей.
API-ключи: для системных клиентов; связываем с квотами/ролями.
WAF: базовые правила (injection, protocol anomalies), размер тела, deny-лист стран.
DDoS-защита: connection limiting, SYN cookies, rate-limit на IP/ключ/эндпойнт.
Zero-Trust: мандатные политики (SPIFFE/SPIRE, идентичности сервисов), принцип наименьших прав.
Приватность: редактирование PII в логах, маскирование PAN/IBAN, политика хранения.

4) Лимиты, квоты и защита от бурстов

Модели: token bucket, leaky bucket, fixed/sliding window.
Границы: per-IP, per-key, per-user, per-route.

• Burst + sustained (например, `50 rps burst`, `10 rps sustain`).
• Retry-Budget и Slow-Loris защита (таймауты чтения).
• Quota по суткам/месяцу для партнеров.

5) Трансформации и валидация

Normalize заголовков (trace-id, locale, client-id).
Request/Response-mapping (поля/коды, скрытие внутренних атрибутов).
Schema validation (OpenAPI/JSON Schema) до проксирования — ранний отказ 4xx.
Compression/`Accept-Encoding`, caching (см. ниже).

6) Кеширование и производительность

Edge-кеш для справочников, публичных метаданных, конфигов (TTL, `ETag`/`If-None-Match`).
Micro-кеш 1–5 с на горячие GET (снижает пиковую нагрузку).
Negative-cache краткий (на 404/empty) — осторожно.
Hedging-requests и конкурентные запросы к репликам при p95>порог.

7) Таймауты, ретраи, устойчивость

Таймауты: connect/read/write отдельно; разумные p95-ориентиры.
Ретраи: idempotent-методы (GET/PUT) c backoff+джиттер; retry-budget.
Идемпотентность POST: `Idempotency-Key` + дедупликация на стороне сервиса/шлюза.
Circuit-Breaker: по ошибкам/latency; half-open пробы.
Bulkhead/Pool-изоляция по апстримам.

8) Версионирование и совместимость

• URI: `/v1/...` (просто, но «шумит» маршруты).
• Header/Content-Negotiation: `Accept: application/vnd.app.v2+json`.
• Feature-флаги/серверные capability — для совместимости minor-изменений.

Политика: SemVer, окно поддержки (например, `v1` = 12–18 мес), график деприкаций, совместимые ответы при расширениях (добавление полей — не ломает).

9) Наблюдаемость и контроль качества

Корреляция: `traceparent`/`x-request-id` обязателен; прокидываем вниз.
OpenTelemetry: метрики RPS/p50/p95/p99/5xx/4xx, saturation, retry/circuit события.
Логи: структурные JSON; маскируем PII; уровни по кодам.
Сэмплирование трейсов: базовое 5–10% + целевое на ошибки/медленные.
SLO/алерты: по маршрутам/клиентам (аптайм, latency, ошибка).

10) Управление трафиком релизов

Blue-Green: переключение DNS/LB.
Canary: весовая доля/сегменты (регион, партнер, роль).
Shadow/Mirror: копия трафика на новую версию без ответа клиенту.
Kill-switch: флаг для быстрого отключения проблемного апстрима/фичи.

11) Смарт-маршрутизация платежей (iGaming)

Правила выбора PSP: гео, валюта, сумма, риск-скор, доступность, комиссия.
Failover PSP: автоматический переход при `5xx/timeout`.
Same-method rule: возвраты/выводы через исходный метод — проверка на краю.
Идемпотентность платежей: ключ на `userId+amount+currency+purpose`.
ETA-прозрачность: шлюз добавляет статусы и причины отказов (не коды PSP).

12) Политики кросс-регионов и комплаенс

Geo-фильтры: белые/черные списки стран, возрастные ограничения, IP-рейнджи.
Данные резидентов: маршрутизация в региональные кластеры (GDPR/локальные законы).
Логи и TTL: хранение по регионам, автоматическая анонимизация.

13) Примеры конфигураций

13.1 NGINX (маршрутизация + лимит + хедеры)

nginx http {
map $http_x_request_id $req_id { default $request_id; }
limit_req_zone $binary_remote_addr zone=per_ip:10m rate=20r/s;

server {
listen 443 ssl http2;
server_name api. example. com;

Security add_header Strict-Transport-Security "max-age = 31536000" always;
add_header X-Content-Type-Options nosniff;

Limit on IP location/api/v1/{
limit_req zone=per_ip burst=40 nodelay;
proxy_set_header X-Request-Id $req_id;
proxy_set_header X-Client-Ip $remote_addr;
proxy_read_timeout 5s;
proxy_connect_timeout 1s;
proxy_pass http://payments_v1;
}

Canary traffic by header location/api/v2/{
if ($http_x_canary = "1") { proxy_pass http://payments_v2; }
proxy_pass http://payments_v1;
}
}
}

13.2 Envoy (JWT, rate limit, retries, outlier)

yaml static_resources:
listeners:
- name: https address: { socket_address: { address: 0. 0. 0. 0, port_value: 443 } }
filter_chains:
- filters:
- name: envoy. filters. network. http_connection_manager typed_config:
"@type": type. googleapis. com/envoy. extensions. filters. network. http_connection_manager. v3. HttpConnectionManager route_config:
name: local_route virtual_hosts:
- name: payments domains: ["api. example. com"]
routes:
- match: { prefix: "/api/v1/payments" }
route:
cluster: payments_v1 timeout: 5s retry_policy:
retry_on: "connect-failure,refused-stream,5xx,retriable-status-codes"
num_retries: 2 per_try_timeout: 2s http_filters:
- name: envoy. filters. http. jwt_authn typed_config:
"@type": type. googleapis. com/envoy. extensions. filters. http. jwt_authn. v3. JwtAuthentication providers:
main:
issuer: "https://auth. example. com/"
remote_jwks: { http_uri: { uri: "https://auth. example. com/.well-known/jwks. json" } }
forward: true rules:
- match: { prefix: "/api/" }
requires: { provider_name: "main" }
- name: envoy. filters. http. ratelimit
- name: envoy. filters. http. router clusters:
- name: payments_v1 connect_timeout: 0. 5s type: STRICT_DNS lb_policy: ROUND_ROBIN load_assignment: { cluster_name: payments_v1, endpoints: [{ lb_endpoints: [{ endpoint: { address: { socket_address: { address: payments, port_value: 8080 }}}}]}] }
outlier_detection: { consecutive_5xx: 5, interval: 5s, base_ejection_time: 30s }

14) Чек-листы

Перед релизом маршрута

• Схема аутентификации (JWT/JWKS, ключи, TTL кэша).
• Таймауты/ретраи/идемпотентность настроены.
• Лимиты: per-IP, per-key, per-route; квоты партнеров.
• Валидация схемы запросов/ответов.
• Логи и трассировки с `trace-id`, маски PII.
• SLO/алерты и дашборд.
• Гео-правила/комплаенс/возраст проверены.

Операции и платежи

• Смарт-роутинг PSP: правила, приоритеты, фейловер.
• Same-method проверяется на краю.
• Прозрачные статусы и коды ошибок для клиента (без сырого кода PSP).

Релизы

• Canary/AB и kill-switch, план отката.
• Shadow-трафик на новую версию, сравнение метрик.
• Нагрузочное тестирование и p95 цели.

15) Метрики качества (минимум)

Availability/SLO по маршрутам; error rate 5xx/4xx.
Latency p50/p95/p99 (внешняя и внутренняя).
Retry/timeout/circuit события (уровень шума).
Cache hit-ratio и экономия RPS.
Rate-limit hits и отброшенные запросы.
PSP-routing KPIs: успехи, TtW, процент фейловера, комиссия.

16) Анти-паттерны

Один общий лимит «на все».
«Мгновенные» ретраи без джиттера (усиление шторма).
Доверие к `X-Forwarded-For` без нормализации и списка доверенных прокси.
Твердые таймауты без учета p95 (ложные срабатывания).
Жесткие трансформации, ломающие совместимость.
Логи с PII/PAN/секретами.
Смешение внутреннего и внешнего API под одним доменом/политикой.

17) Шаблоны ответов и ошибки (microcopy)

429 Too Many Requests: «Достигнут лимит запросов. Повторите через N секунд или увеличьте квоту в кабинете партнера.»

401/403: «Токен недействителен/истек. Выполните вход заново.»

408/504: «Сервис отвечает дольше ожидаемого. Запрос принят не был.»

Idempotency-conflict: «Запрос с таким Idempotency-Key уже обработан (статус: успех/отказ).»

18) Процесс внедрения (по шагам)

1. Модель маршрутов: карта доменов/путей/регионов.
2. Политики безопасности: TLS/mTLS, WAF, authN/Z, ключи/JWKS.
3. Надежность: таймауты, ретраи, idempotency, circuit-breaker.
4. Наблюдаемость: логи/метрики/трейсы, кореляция.
5. Кеш/перф: edge/micro-cache, компрессия, коннект-пулы.
6. Платежный роутинг: правила, тесты, мониторинг.
7. Релизы: canary/shadow, kill-switch, план отката.
8. Комплаенс/гео: фильтры стран, хранение данных, возраст.

Итоговая шпаргалка

Строгий периметр (TLS/mTLS, WAF, лимиты) + управляемый трафик (ретраи, circuit, canary).
Валидация и трансформации на краю → меньше дефектов «внутри».
Наблюдаемость с trace-id и масками PII — не опция, а стандарт.
Смарт-роутинг платежей и комплаенс-гео — критичны для iGaming.
Версионирование и политика деприкаций — предсказуемость для партнеров.