API сызуу жана статикалык талдоо

1) Эмне үчүн API линт

• шайкеш келбеген жана көрүнбөгөн өзгөрүүлөрдү болтурбоого;
• статустарды, каталарды, пагинацияны, коопсуздукту бириктирүү;
• спецификацияларды машина менен текшерилүүчү жана релиздерди алдын ала айтууга болот;
• бааны жана онбординг убактысын кыскартат.

Принцип: "контракттар автоматтык түрдө текшерилет; Жашыл линтингсиз PR кармалбайт".

2) Линтинг объекттери

1. Келишимдер: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Euro/JSON схемасы.
2. ишке ашыруу: REST/gRPC туткалары, орто, статус коддору/аталыштары.
3. Инфраструктура: коопсуздук аталыштары, лимиттер, кэш саясаты.
4. Тиешелүү экспонаттар: мисалдар (examples), Postman-чогултуу, ката схемалар.

3) HTTP API үчүн негизги эрежелер (сунушталган кароо)

3. 1 Нотация жана URL

JSON денелеринде snake_case, жолдордо kebab-case же бир түрдөгү kebab-case/'/v1/... '.
Ресурстар - көп сан: '/v1/payments ', салынган - '/v1/wallets/{ id }/transactions'.
path-params катары ID: '/v1/payments/{ payment _ id} '(түрү: string, формат: uuid).

3. 2 ыкмалары жана статусу

'GET' - 200/206; 'POST' - 201 (+ 'Location'), чыр-чатактар - 409; валидация - 422; лимиттери - 429 (+ 'Retry-After').
каталар үчүн 200 кайтарып жок. Шарттуу суроолор - 304 'If-None-Match'.

3. 3 Каталар (бирдиктүү формат)

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"...", "details":[{"field":"amount","reason":"min:1"}] }

Милдеттүү: 'code', 'message', 'trace _ id'; жергиликтүү - 'Content-Language' аркылуу.

3. 4 Пагинация/чыпкалар

Cursor-based: `page_size`, `page_token`, ответ: `next_page_token`.
Фильтрлер жана сорттоо - whitelists, документтештирилген 'parameters'.

3. 5 Коопсуздук

Бирдиктүү security схемасы: OAuth2/OIDC scopes же mTLS; тыюу салуу 'http' (гана 'https').
Сезгич аталыштарды кайтарбоо, үлгү катары белгилерди жашыруу.

3. 6 Чектөөлөр жана өлчөмдөрү

Аталыштардын/дененин лимиттери: 413/414/431; максималдуу жол берилген маанилерди документтештириңиз.

4) Аспаптар жана экосистема

4. 1 OpenAPI

Spectral (JSON/YAML lint), Redocly linter, oas-diff/openapi-diff (semantic diff), schemathesis/dredd (аткарылган текшерүү).

4. 2 Protobuf/gRPC

buf (lint + breaking check), protolint, SDK генераторлор; gnostic талдоо үчүн.

4. 3 GraphQL

graphql-schema-linter, graphql-inspector (breaking).

4. 4 Code Linters жана SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API-жыт жана коопсуздук үлгүлөрү).

5) Эрежелердин мисалдары: Spectral/Redocly

5. 1 Spectral (мисал 'spectral. yaml`)

yaml extends: ["spectral:oas", "spectral:asyncapi"]
rules:
openapi-tags: off info-contact: error no-http: error path-kebab-case:
description: "Paths must be kebab-case"
given: "$.paths[]~"
severity: error then:
function: pattern functionOptions: { match: "^/(?:[a-z0-9]+(?--[a-z0-9]+)/?)+$" }
response-error-schema:
description: "Error responses must use standard schema"
given: "$.paths[][].responses[?(@property >= '400')]"
then:
field: "content.application/json.schema.$ref"
function: truthy id-as-uuid:
given: "$..parameters[?(@.name =~ /.id$/i)]"
then:
field: schema.format function: enumeration functionOptions: { values: ["uuid"] }

5. 2 Redocly (фрагмент '.redocly. yaml`)

yaml apis:
main: openapi.yaml lint:
extends:
- recommended rules:
no-ambiguous-paths: error operation-2xx-only: off operation-success-response:
severity: error where:
subject: response filterInParentKeys: ["200","201","204"]
operation-security-defined: error no-plain-http: error

6) Protobuf/gRPC: buf-кароо

6. 1 `buf. yaml`

yaml version: v2 modules:
- path: proto lint:
use:
- DEFAULT except:
- PACKAGE_VERSION_SUFFIX # используем v1 в package breaking:
use:
- WIRE_JSON deps: []

• Талаа номерлерин кайра колдонбоңуз; өчүрүлгөндөр - 'reserved'.
• Жаңы талаалар - 'optional' же дефолттор менен; түрлөрүн/семантикасын өзгөртпөйт.

7) Семантикалык diff жана "сындыруу" өзгөрүүлөр

7. 1 HTTP

• талаанын түрүн/милдеттүүлүгүн өзгөртүү;
• статус/маршрут/параметр алып салуу;
• enum/диапазону тарышы;
• id форматын өзгөртүү (uuid → string).

• кошумча талааларды кошуу;
• happy-path таасир этпеген жаңы статустар (мисалы, документтештирилген '422');
• enum кеңейтүү.

7. 2 gRPC/Protobuf

'reserved' жок талааны алып салуу/номерин өзгөртүү - breaking.
түрүн өзгөртүү (int32 → string) - breaking.
optional катары жаңы тег кошуу - адатта safe.

8) Байланыш линтинг келишимдер жана код

1. Контракт → код: SDK/Server капкактарынын генерациясы, тесттердеги терс мисалдар.

2. Code → келишим: спецификациялык тесттер, статустарды/аталыштарды автоматтык түрдө текшерүү.

• тыюу салуу 'return 200' учурда 'error! = nil';
• write-маршруттарында милдеттүү 'idempotency-Key';
• логдордо токендерди жашыруу.

9) CI/CD Pipeline (шилтеме)

pre-commit: spectral lint, redocly lint
PR gate:  openapi-diff (base..PR), buf breaking-check, graphql-inspector build:   schemathesis smoke, unit/integration linters (ESLint/golangci-lint)
release:  publish contracts (artifact/broker), sign & tag

• breaking-diff бар;
• негизги эрежелер бузулган (статустар/коопсуздук/каталар);
• параметрлердин мисалдары/сүрөттөөлөрү жок.

10) эрежелер каталогу (сиздин уюм үчүн үлгү)

Идентификаторлор жана түрлөрү

`_id` — `string`, `format: uuid`.
Акча талаалары - 'string '/' decimal' менен scale; валюта - ISO-4217.

Каталар

Бирдиктүү схема (§ 3 караңыз. 3), коддору: '400/401/403/404/409/422/429/5xx'.
Ар дайым 'trace _ id'; 'Retry-After' үчүн 429/503.

Пагинация

Гана cursor; max 'page _ size' документтештирилген.

Коопсуздук

Бардык операциялар - 'security' блок; сүрөттөлгөн 'scopes'.
Жок 'http:' шилтемелер; TLS 1. 2+.

Кэш/демпотенттүүлүк

Для GET — `ETag/Last-Modified`; write үчүн - 'Idempotency-Key' (колдонулуучу жерде).

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

'summary', 'description', суроо/жооп мисалдары (valid).

11) Автоматташтырылган текшерүүлөрдүн мисалдары

11. 1 Милдеттүү коопсуздук аталыштарын текшерүү (Spectral)

yaml security-headers:
given: "$.paths[][].responses['200'].headers"
then:
function: truthy

11. 2 openapi-diff (psevdo CI-кадам)

openapi-diff --fail-on-incompatible base.yaml pr.yaml

11. 3 buf breaking-check

buf breaking --against '.git#branch=main'

12) Контракттардын сапатын байкоо

Метриктер: линтинг каталары менен PR үлүшү, фикс убактысы, breaking-аракеттердин саны, эрежелер боюнча "карыздар".
Дашборддор: бирдиктүү ката схемасы боюнча миграциянын прогресси, мисалдарды камтыган, версиялардын туруктуулугу.

13) Антипаттерндер

"Doc" коддон өзүнчө жашайт → синхрондоштуруу. Келишимди кызматтын жанында кармап, версияланган артефактты чыгарыңыз.
Линтер кол менен гана. Катуу PR-gate керек.
Кокус мисалдар (non-deterministic) - текшерүү flakes.
Терс мисалдардын жана ката коддорунун жоктугу.
Ар бир кызмат үчүн ката схемасын кайра алуу.
Protobuf breaking-текшерүүлөрдү четке кагуу (тегтерди "көзгө" өзгөртүү).

14) iGaming/каржы өзгөчөлүктөрү

Акча талаалары - белгиленген масштаб/тегеректөө; float тыюу салуу.
Милдеттүү аталыштар 'X-Tenant', 'X-Region' жана 'traceparent'.
Төлөм write туткалары: 'Idempotency-Key', 'Retry-After' жана туура 409/201 семантикаларды текшерүү.
PSP/KYC: HMAC/mTLS 'securitySchemes' менен сүрөттөлгөн; anti-replay ('X-Timestamp', терезе).
Аймактык чектөөлөр жана каталарды локалдаштыруу ('Content-Language').

15) Prod-даярдык чек тизмеси

• Spectral/Redocly профилдери иштелип чыккан жана pre-commit жана PR-дарбазасына туташтырылган.
• Каталардын бирдиктүү схемасы жана статустары - жазылган жана текшерилет.
• openapi-diff/GraphQL Inspector/buf - бөгөттөлгөн breaking-өзгөрүүлөр.
• Суроо-талаптардын/жооптордун үлгүлөрү валидна; pagination/чыпкалар документтештирилген.
• SecuritySchemes жана scopes толтурулган; HTTP шилтемелер жок.
• Protobuf үчүн: 'reserved' алыскы тегдерде; жаңы талаалар - optional.
• Semgrep/код линтерлери камтылган; жашыруу.
• CI контракттардын артефакттарын жана линтинг отчетторун жарыялайт.
• Playbook: breaking-диффа (rollback, hotfix, интеграторлорго билдирүүлөр) менен иш-аракет кылууга.

16) TL; DR

Контракттарды автоматтык линтингди (Spectral/Redocly, buf/GraphQL Inspector) жана семантикалык diff киргизүү, каталардын/статустардын/pagination/коопсуздуктун бирдиктүү схемасын бекитүү, PR-дарбазаны туташтыруу жана контракттарды экспонаттар катары жарыялоо. Ар кандай breaking-дифф - токтоо сигналы. Акча/төлөмдөр үчүн - өзгөчө эрежелер (демпотенттик, 'Retry-After', HMAC/mTLS).