Асбоби API ва таҳлили статикӣ

1) Чаро пайванди API

• Пешгирии тағироти номувофиқ ва номуайян
• муттаҳид кардани статусҳо, хатогиҳо, бутпарастӣ, амният;
• мушаххасоти мошинро тафтиш кунед ва релизҳоро пешгӯишаванда созед;
• арзиши баррасӣ ва вақти боркуниро кам кунед.

Принсип: "шартномаҳо ба таври худкор тафтиш карда мешаванд; PR бидуни линтинги сабз нигоҳ надорад"

2) Иншооти линтинг

1. Шартномаҳо: Open

2. Амалисозӣ: Қаламҳои REST/GRPC, миёнаравӣ, рамзҳои ҳолат/сарлавҳаҳо.
3. Инфрасохтор: сарлавҳаҳои амният, маҳдудиятҳо, сиёсати кэш.
4. Артефактҳои марбута: намунаҳо, маҷмӯаҳои почтачиён, схемаҳои хатогӣ.

3) Қоидаҳои асосӣ барои HTTP API (профили тавсияшуда)

3. 1 Notation ва URL

snake_case дар мақомоти JSON, ҳолати кабоб дар роҳҳо, ё кебаб-ҳолати ягона/'/v1/... '.
Захираҳо - ҷамъ: '/v1/пардохтҳо ', лона - '/v1/ҳамён/{ id }/транзаксияҳо'.
Идентификаторҳо ҳамчун path-params: '/v1/payments/{ pay _ id} '(намуд: сатр, формат: uuid).

3. 2 Усулҳо ва статусҳо

'ГЕТ' - 200/206; ' POST '- 201 (+' Ҷойгиршавӣ '), муноқишаҳо - 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"}] }

Талаб карда мешавад: 'рамз', 'паём', 'trace _ id'; locale - тавассути 'Мазмун-Забон'.

3. 4 Пагинатсия/филтрҳо

Курсор дар асоси: 'page _ size', 'page _ token', otvet: 'next _ page _ token'.
Филтрҳо ва навъбандӣ - сафедпӯстон дар 'параметрҳо' ҳуҷҷатгузорӣ шудаанд.

3. 5 бехатарӣ

Схемаи ягонаи бехатарӣ: OAuth2/OIDC миқёс ё MTLS; рад 'http' (танҳо 'https').
Сарлавҳаҳои ҳассосро барнагардонед, нишонаҳои ниқобро дар мисолҳо.

3. 6 Маҳдудиятҳо ва андозаҳо

Маҳдудиятҳои унвон/бадан: 413/414/431; Қиматҳои ҳадди аксарро ҳуҷҷатгузорӣ кунед.

4) Воситаҳо ва экосистема

4. 1 Кушодани API

Спектрал (JSON/YAML lint), linter Redocly, oas-diff/openapi-diff (diff семантикӣ), схематез/дредд (санҷишҳо идома доранд).

4. 2 Protobuf/GRPC

буф (линт + шикастани чек), протолинт, генераторҳои SDK; гностикӣ барои таҳлил.

4. 3 Диаграммаи QL

graphql-schema-linter, graphql-инспектор (шикастан).

4. 4 Linters Code ва SAST

ESL mint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (бӯи API ва қолабҳои амниятӣ).

5) Намунаҳои қоида: Спектралӣ/Redocly

5. 1 Спектралӣ (мисол 'спектралӣ. 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 'буф. ямл '

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

• Рақамҳои майдонро аз нав истифода набаред; нест карда шуд - дар 'захирашуда'.
• Майдонҳои нав - 'ихтиёрӣ' ё бо пешфарз; намудҳо/семантикаро тағир надиҳед.

7) Тағйироти семантикӣ ва "шикастан"

7. 1 HTTP

• Дигаргун кардани намуди майдон/ҳатмӣ
• Нест кардани ҳолат/масир/параметр
• тангии enum/диапазон;
• тағир додани формати id (uuid → string).

• Илова кардани майдонҳои иловагӣ
• Статусҳои нав, ки ба роҳи хушбахт таъсир намерасонанд (масалан, ҳуҷҷатгузории '422')
• тамдиди enum.

7. 2 GRPC/Протобуф

Нест кардани майдон бе 'захирашуда '/азнавсозӣ - шикастан.
Тағйири намуд (int32 → сатр) - шикастан.
Илова кардани теги нав ҳамчун ихтиёрӣ одатан бехатар аст.

8) Робита бо шартнома ва кодекс

1. Шартнома → рамз: тавлиди стубҳои SDK/сервер, намунаҳои манфӣ дар озмоишҳо.

2. Шартнома → рамз: санҷишҳои мушаххас, санҷиши автоматии статусҳо/сарлавҳаҳо.

• манъ кардани 'return 200' when 'error! = нил';
• '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

• шикаста-фарқ вуҷуд дорад;
• Қоидаҳои асосӣ вайрон карда шуданд (статусҳо/амният/хатогиҳо)
• намунаҳо/тавсифи параметрҳо вуҷуд надоранд.

10) Феҳристи қоидаҳо (қолаб барои ташкили шумо)

Идентификаторҳо ва намудҳо

'_ id' - 'сатр', 'формат: uuid'.
Майдонҳои пулӣ - 'сатр '/' даҳӣ' бо миқёс; асъор - ISO-4217.

Хатогиҳо

Схемаи ягона (ниг. § 3. 3), рамзҳо: '400/401/403/404/409/422/429/5xx'.
Ҳамеша 'пайгирӣ _ id'; ' Retry-After 'for 429/503.

Пагинатсия

Танҳо курсор; max 'page _ size' ҳуҷҷатгузорӣ шудааст.

Бехатарӣ

Ҳама амалиётҳо - блоки 'амният'; 'соҳаҳо' тавсиф карда мешаванд.
Истиноди 'http:' нест; TLS 1. 2+.

Кэш/idempotency

Для ГЕТ - 'ET jag/Last-Modified'; барои навиштан - 'Idempotency-Key' (агар лозим бошад).

Ҳуҷҷатгузорӣ

'summary', 'тавсиф', намунаҳои дархостҳо/ҷавобҳо (эътибор).

11) Намунаҳои чекҳои автоматӣ

11. 1 Санҷиши сарлавҳаҳои амнияти ҳатмӣ (Спектралӣ)

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 --against '.git#branch=main'

12) Риояи сифати шартномаҳо

Нишондиҳандаҳо: ҳиссаи PR-ҳо бо хатогиҳои алоқаманд, ислоҳи вақт, шумораи кӯшиши шикастан, "қарзҳо" тибқи қоидаҳо.
Панели панелҳо: пешрафти муҳоҷират ба нақшаи ягонаи хатогӣ, фарогирӣ бо мисолҳо, устувории версия.

13) Антипаттернҳо

"Док" аз рамзи → desynchronization алоҳида зиндагӣ мекунад. Шартномаро ба хидмат наздик нигоҳ доред ва артефакти боэътимодро раҳо кунед.
Линтер танҳо бо дасти. Ба дарвозаи сахт PR лозим аст.
Мисолҳои тасодуфӣ (ғайримуқаррарӣ) - зарбаҳо дар чекҳо.
Ягон намунаҳои манфӣ ва рамзҳои хато нестанд.
Бозсозии нақшаи хатогӣ барои ҳар як хидмат.
Нодида гирифтани чекҳои шикастани Protobuf (иваз кардани барчасбҳо "бо чашм").

14) Хусусиятҳои IGaming/Finance

Майдонҳои асъор - миқёси собит/яклухткунӣ; манъи шино.
Сарлавҳаҳои ҳатмии 'X-иҷорагир', 'X-Region' ва пайгирӣ 'пайгирӣ'.
Дастурҳои хаттии пардохт: санҷиши 'Idempotency-Key', 'Retry-After' ва семантикаи 409/201 дуруст.
Webhooks PSP/KYC: HMAC/m зидди такрорӣ ('X-Timestamp', тиреза).
Маҳдудиятҳои минтақавӣ ва маҳаллисозии хатогиҳо ('Мундариҷа-забон').

15) Рӯйхати санҷиши омодагии Prod

• Профилҳои спектралӣ/Redocly дар пеш аз ӯҳдадорӣ ва PR-дарвоза тарҳрезӣ ва пайваст карда шудаанд.
• Намунаи хатогӣ ва ҳолати ягона - содир ва тафтиш карда мешавад.
• openapi-diff/Инспектор/GraphQL - тағиротҳои шикастани блок.
• Намунаҳои дархостҳо/ҷавобҳо дурустанд; пагинатсия/филтрҳо ҳуҷҷатгузорӣ шудаанд.
• Схемаҳо ва миқёсҳо пур карда мешаванд; Ягон пайванди http вуҷуд надорад.
• Барои Protobuf: дар барчасбҳои ҳазфшуда 'захира карда шудааст'; майдонҳои нав - ихтиёрӣ.
• linters Semgrep/code фаъол аст; ниқоб кардани асрори гузоришҳо.
• CI артефактҳои шартномавӣ ва ҳисоботҳои линтингро нашр мекунад.
• Китоби бозӣ: ҳангоми шикастани диффа чӣ гуна бояд амал кард (бозгашт, hotfix, огоҳиҳо ба интеграторҳо).

16) TL; ДР

Иҷрои линтинги автоматии шартномавӣ (Spectral/Redocly, buf/нозири графикӣ) ва diff семантикӣ, як хатогӣ/ҳолат/пагинатсия/амниятро ислоҳ кунед, PR-дарвозаро пайваст кунед ва шартномаҳоро ҳамчун артефакт нашр кунед. Ҳар гуна фарқияти шикаста нури тормоз аст. Барои пул/пардохтҳо - қоидаҳои махсус (idempotency, 'Retry-After', HMAC/MTLS).