API linting және статикалық талдау

1) Неліктен API сызғыш

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

Қағидат: "келісімшарттар автоматты түрде тексеріледі; Жасыл линтингсіз PR ұстамайды".

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

1. Келісімшарттар: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Euro/JSON Schema.
2. Іске асыру: REST/gRPC-қаламдар, middleware, мәртебе кодтары/тақырыптар.
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 ретінде идентификаторлар: '/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`.
Сүзгілер және сұрыптау - 'parameters' бағдарламасында құжатталған whitelists.

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 Кодтық линтерлер және SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API-иістер мен security үлгілері).

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/серверлік тығындарды генерациялау, тесттердегі теріс мысалдар.

2. Код → келісімшарт: спецификациялық тесттер, мәртебелерді/тақырыптарды автоматты түрде тексеру.

• тыйым салу 'return 200' кезінде 'error! = nil';
• write-төлем бағыттарында міндетті 'Idempotency-Key';
• логтардағы токендерді бүркемелеу.

9) CI/CD пайплайн (референс)

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' c scale; валюта - ISO-4217.

Қателер

Бірыңғай схема (қараңыз § 3. 3), кодтары: '400/401/403/404/409/422/429/5хх'.
Әрқашан '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', сұрау/жауап мысалдары (валидті).

11) Автоматтандырылған тексеру үлгілері

11. 1 Міндетті қауіпсіздік тақырыптарын тексеру (Spectral)

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

11. 2 openapi-diff (псевдо 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) Антипаттерндер

«Док» кодтан бөлек тұрады → рассинхронизация. Келісімшартты сервистің жанында ұстаңыз және нұсқаланған артефактіні шығарыңыз.
Линтер тек қолмен. Қатты PR-gate қажет.
Кездейсоқ мысалдар (non-deterministic) - тексерулердегі флейкалар.
Теріс мысалдар мен қате кодтарының болмауы.
Әрбір сервис үшін қателер схемасын қайта алу.
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-gate бағдарламасына қосылған.
• Қателер мен мәртебелердің бірыңғай схемасы - тіркелген және тексеріледі.
• openapi-diff/GraphQL Inspector/buf - breaking-өзгерістерді бұғаттайды.
• Сұраулардың/жауаптардың мысалдары валидті; пагинация/сүзгілер құжатталған.
• SecuritySchemes және scopes толтырылған; http сілтемелері жоқ.
• Protobuf үшін: 'reserved' қашықтағы тегтерде; жаңа өрістер - optional.
• Semgrep/код линтерлері қосылған; логдарда құпияларды жасыру.
• CI келісімшарттар артефактілері мен линтинг есептерін жариялайды.
• Плейбук: breaking-диффе кезінде қалай әрекет ету керек (rollback, hotfix, интеграторларға хабарламалар).

16) TL; DR

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