API-шлюз және бағыттау

1) API-шлюздің архитектурадағы рөлі

• кіріс трафигін қабылдайды (HTTP/HTTP2/HTTP3, WebSocket, gRPC);
• ереже бойынша бағыттайды (host/path/headers/method/query/geo/салмағы/денсаулығы);
• толассыз саясатты қолданады: аутентификация/авторизация, rate limiting, WAF, CORS, кешіктіру;
• трансформацияларды орындайды (тақырыптарды/телефондарды қалыпқа келтіру, gRPC, JSON, GraphQL stitching);
• тұрақтылықты қамтамасыз етеді (timeouts, retries, circuit-breaker, outlier detection);
• бақылау мен биллинг (логи, метрика, трассировка, квота) жүргізеді;
• ішкі топологияны (service mesh, жеке сервистер) оқшаулайды.

Көбінесе жұпта пайдаланылады: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - біріншісі сыртқы саясатты шешеді, екіншісі - шығыс-батыс.

2) Типтік топологиялар

Бірыңғай жаһандық шлюз (CDN/edge POP → L7 gateway → сервистер) - қарапайым, орталықтандырылған саясаткерлер.
Өңірлік шлюздер (per-region) + гео/латенттілік бойынша ақылды бағыттау.
Multi-tenant: бөлінген маршруттар/кіші домендер/кілттер, жалға алушыға квоталар мен лимиттер.
Hybrid: on-prem + cloud, private link/peering, API-шлюздің артындағы жеке бэкендтер.

3) L7 маршруттау ережелері

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Method/Content-Type: JSON/Proto/GraphQL ажырату.
• Query/Fragment: сақтық - кэшке/нұсқаларға әсер етеді.
• Geo/Latency: ең жақын РОР/өңір, тозу кезінде failover.
• Weighted/Canary: трафикті бөлу 90/10, 50/50, sticky cookie.
• Session affinity: hash-based (масштабтау кезінде ұқыпты).

yaml nginx. ingress. kubernetes. io/canary: "true"
nginx. ingress. kubernetes. io/canary-weight: "10" # 10% traffic to new backend

yaml match: { prefix: "/orders", headers: [{name: "X-Experiment", exact_match: "new"}] }
route: { cluster: orders-v2 }

4) Хаттамалар және үйлесімділік

REST/JSON - дефолт, клиенттерді валидациялау/генерациялау үшін OpenAPI сипаттаңыз.
gRPC - HTTP/2 үстінен бинарлық Proto; сыртқы клиенттер үшін gRPC-JSON transcoding пайдаланыңыз.
GraphQL - сервистерді біріктіреді; периметрде сұраулардың complexity/тереңдігін бақылаңыз.
WebSocket/SSE - екі бағытты/іске қосу; sticky және timeouts.
HTTP/2/3 (QUIC) - мультиплексиялау/жылдам бастау; WAF/проксидің үйлесімділігін тексеріңіз.

5) Қауіпсіздік: аутентификация және авторизация

5. 1 Көлік

TLS 1. 2 + периметрде, HSTS, OCSP stapling, PFS.
В2В/ішкі API және машинаға арналған mTLS.
IP allowlist/denylist, гео-шектеулер.

5. 2 Қолданбалы деңгей

OAuth2/OIDC: JWT bearer-токендері, қолтаңбаны/экспирацияны/аудиторияны тексеру.
НМАС/қолтаңбалар: күні + канондалған жол + қолтаңба (AWS-ұқсас) - ауыстырудан, қайталаудан қорғау (nonce/тайм-терезе).
API кілттері: тек идентификатор ретінде; құқықтар - RBAC/ABAC/сатып алу арқылы.
CORS: айқын allow-origin, алдын ала флайт кэш.
WAF: сигнатуралар (OWASP API Top 10), анормалия, бот-қорғаныс, рекурсивті JSON-өрістер.
DDoS/Abuse: connection limiting, token-bucket/Leaky bucket, берст + орташа жылдамдық, динамикалық бан.

yaml plugins:
- name: oidc config: { issuer: "...", client_id: "...", client_secret: "...", scopes: ["orders. read"] }
- name: rate-limiting config: { minute: 600, policy: local }

6) Валидация, трансформация және үйлесімділік

Схемалар: OpenAPI/JSON-Schema/Protobuf бойынша денені/тақырыптарды/параметрлерді валидациялау.
Трансформациялар: өрістерді қалыпқа келтіру, PII бүркемелеу, корреляциялық тақырыптарды қосу ('traceparent', 'x-request-id').
Нұсқалау: 'Header: X-API-Version', префикстер '/v1 ', ресурс-нұсқалау; deprecation policy и Sunset.
Backward-compat: тек add өрісі; жаңа нұсқасыз «бұзатын» өзгерістерді болдырмаңыз.
Idempotency: `Idempotency-Key` для POST; gateway TTL бағдарламасында Redis кілттерін сақтайды.

7) Тұрақтылық: қосылу саясаты

Timeouts: connect/read/write; ақылға қонымды дефолттар (мысалы, 1s/5s/5s).
Retries: тек қауіпсіз және іспеттес үшін; джиттер, exponential backoff, максималды әрекеттер.
Circuit breaker: қателер/жасырындылық кезінде ашу; сынамалар үшін half-open.
Outlier detection: жаман әрекеттерді пулдан шығару.
Bulkhead/бәсекелестік: per-route бір мезгілде сұрау лимиттері.
Failover: белсенді/пассивті, аймақтық тозу.
Shadow traffic: салыстыру үшін V1 параллельді V2 «сұр» прогоны (жауапсыз).

yaml circuit_breakers:
thresholds:
- priority: DEFAULT max_connections: 1024 max_pending_requests: 2048 max_retries: 3

8) Кешіктіру және өнімділік

HTTP-кеш: `Cache-Control`, `ETag/If-None-Match`, `Vary`, `stale-while-revalidate`.
Edge-кештер/РОР: Статикаға арналған CDN және «кешіктірілетін» API (іспеттес GET).
Compression: 'gzip/br' (сығылған күйді қысмаңыз).
Request collapsing («coalescing»): ұқсас параллель сұрауларды біріктіру.
Response shaping: өрістер/сүзгілер, пагинация (cursor-based), өлшем лимиттері.

9) Бақылау және пайдалану

Метрики: `l7_req_total{route,method,code}`, `latency_ms{p50,p95,p99}`, `upstream_errors`, `retry_count`, `cb_state`, `429_rate`, `quota_usage{tenant}`.
Логтар: құрылымдық, 'trace _ id/span _ id', 'user _ id/tenant _ id', 'client _ ip'.
Traces: W3C Trace Context ('traceparent', 'tracestate'), апстримдерге насихаттаңыз.
Аудит: кім не, қандай құқықтармен шақырған; сезімтал API үшін өзгермейтін сақтау орындары.
SLO/SLA: мақсатты p99, қателер бюджеті; роут-деңгей жаһандық деңгейден жақсы.

10) Өткізу қабілеті жоспарын басқару

Quota per-tenant/кілт/клиенттер пулы, мин/сағ/тәулік.
Burst + sustained лимиттері; тегістеуге арналған leaky bucket.
Fairness: артық жүктеу кезінде - «бірінші кездескен» орнына fair queuing.
Басымдықтар: басымдығы және бөлiнген пулдары бар жүйелi/сындарлы бағыттар.

11) Өзгерістерді басқару және релиздер

Canary/Blue-Green: салмақтық бағыттау; SLO бойынша автоматты жылжыту (қателер/жасырындылық).
Feature gates/бэкенд жалаушалары: тақырып/токен бойынша қосу.
Shadowing/дифф-валидаторлар: тел/мәртебелерді салыстыру, дельта бойынша рұқсаттар.
Стейджингтер: бөлектелген домендер/жолдар ('staging. api... '), жеке кілттер мен квоталар.

12) Конфигурация мысалдары

12. 1 NGINX - лимиті мен кэші бар базалық gateway

nginx map $http_x_request_id $reqid { default $request_id; }

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

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

security add_header Strict-Transport-Security "max-age = 31536000" always;

location /v1/ {
limit_req zone=perip burst=30 nodelay;
proxy_set_header X-Request-ID $reqid;
proxy_set_header Authorization $http_authorization;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;

proxy_cache api_cache;
proxy_cache_valid 200 10s;
proxy_cache_use_stale error timeout updating;
proxy_pass http://orders-v1;
}
}

12. 2 Envoy - таразы және ретра бойынша маршруттау

yaml routes:
- match: { prefix: "/orders" }
route:
weighted_clusters:
clusters:
- name: orders-v1 weight: 90
- name: orders-v2 weight: 10 retry_policy:
retry_on: "5xx,reset,connect-failure"
num_retries: 2 per_try_timeout: 2s

12. 3 Traefik - мидлварилер мен хедерлер

yaml http:
middlewares:
secHeaders:
headers:
stsSeconds: 31536000 contentTypeNosniff: true routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: svc-orders middlewares: ["secHeaders"]

13) Қарсы үлгілер

Бір жаһандық шектеу - «жақсы көршілер» «шудан» зардап шегеді.
Идемпотенттілігі жоқ ретрайлер → дубль эффекттері (төлемдер, мәнін жасау).
'timeout '/' max body size' → тоқтап қалу/воркерлердің таусылуы.
edge-саясатты және бизнес-логиканы шлюзде араластыру (периметрді ауырлату).
Схемаларды валидациялаудың жоқтығы → клиенттердің осалдығы және «сындыратын» релиздер.
auth/лимиттер/idle-таймсыз жалаңаш WebSocket.
Ротациясыз тақырыптардағы құпиялар; ішкі B2B-де mTLS болмауы.

14) Тест-плейбуктер (Game Days)

Сұраулар дауылы: тексеру limiter/quota, 429-мінез-құлық, тозу.
Бір кластерді жоғалту: failover/салмақты қайта бөлу; SLO канарейка.
Ауыр жауаптар: max body/timeouts; қосылыстарды кесу.
Инъекциялар/аномалиялар: WAF ережелері, рекурсивті JSON тыйым салу, GraphQL үлкен тереңдігі.
Трассалау жаңылысы: 'traceparent' насихатын және тұқымдастыруды тексеру.
Құпиялар: кілттерді/JWKS ротациялау, токендердің аяқталуы, clock-skew рұқсаты.

15) Енгізу чек-парағы

• OpenAPI/Proto жарияланған домендер/жолдар/нұсқалар анықталған.
• TLS/mTLS, HSTS, құпия менеджмент және ротация теңшелген.
• Аутентификация (OIDC/HMAC), RBAC/сатып алулар, CORS қосылған.
• per-tenant лимиттері/квоталары, әділ кезектер, 429-UX.
• Таразылар/тақырыптар бойынша маршруттау, канарейка және rollback жоспары.
• timeout/retry/circuit-breaker/outlier саясаты.
• Схемаларды валидациялау, трансформациялау, PII бүркемелеу.
• Edge-кеш/ETag, coalescing, gzip/br.
• Бақылануы: метрика, логи, трассалар, дашбордтар және алерта.
• Runbooks: оқиғалар, кілттерді ротациялау, блок-парақтар, «қара жұма».

16) FAQ

Q: API-шлюз сервис-қаптан қалай ерекшеленеді?
A: Шлюз - north-south (сыртқы периметр, өтпелі саясат). Меш - east-west (кластер ішіндегі байланыстылық/MTLS/ретра). Жиі бірге пайдаланылады.

Q: auth қайда іске асыру керек: шлюзде немесе сервистерде?
A: Екі деңгей: шлюз - coarse-grained (аутентификация, базалық құқықтар/квоталар), сервис - fine-grained (домендік рөлдер/атрибуттар).

Q: gRPC-JSON transcoding қашан қажет?
A: ішкі gRPC және сыртқа REST/JSON және қарапайым клиенттер/браузерлер қажет болғанда.

Q: Нұсқалау стратегиясын қалай таңдауға болады?
A: Көпшілік API үшін - жол '/vN '+ депривация тақырыптары және ұзақ overlap. Ішкі үшін - capability-жалаулар/үйлесімділік схемасы.

17) Қорытынды

API-шлюз - жай ғана «проксик» емес, саясат пен тұрақтылықтың орталығы. Дұрыс бағыттау, қауіпсіздік, лимиттер, валидация және бақылау релиздердің болжамдылығы мен жылдамдығын береді. edge-шлюзді сервис-қапшықпен біріктіріңіз, канареялар мен квоталарды автоматтандырыңыз, ақаулықтарды тестілеңіз - және периметр бөтелке мойны емес, сіздің үдеткішіңіз болады.