API linting եւ ստատիկ վերլուծություն

1) Ինչու՞ լինել API-ը

API-ը թիմերի և արտաքին ինտեգրատորների միջև պայմանագիր է։ Լինթինգը և ստատիկ վերլուծությունը

նվաստացնում են արձանները, սխալները, սագինացիան, անվտանգությունը։

ճշգրտումներ են անում ստուգվող և կանխատեսելի ալգորիթմներ։

կանխում են անհամատեղելի և աննշան փոփոխությունները.

կրճատում են ծախսերը և ժամանակը։

Սկզբունքը '"պայմանագրերը ինքնաբերաբար ստուգվում են. PR-ն առանց կանաչ ոսպնյակի չի մեռնվում"։

2) Լինթինգի օբյեկտները

1. Պայմանագրեր ՝ OpenAPI/AsyncAPI/GraphQL SDL, Drobuf/Avro/JSON Schema։

2. Տե՛ ս ՝ REST/gRPC գրիչներ, middleware, wwww.stus/վերնագրեր։

3. Ենթակառուցվածքը 'անվտանգության վերնագրեր, սահմաններ, քեշի քաղաքականություն։

4. Հարակից արտեֆակտները 'օրինակներ (examples), Postman հավաքածուներ, սխալների սխեմաներ։

3) HTTP API-ի հիմնական կանոնները (առաջարկվող պրոֆիլը)

3. 1 Նոտացիա և URL

wwww.ake _ cript JSON-ի մարմիններում, kebab-cast ճանապարհներում կամ միանձնյա kebab-case//v1/... "։

Ռեսուրսները բազմաթիվ թիվ են '«/v1/payments », ներդրված' «/v1/wallets/+ id +/transactions»։

Բաղադրիչները որպես path-params: '/v1/payments/+ payment _ id _ "(տիպը ՝ string, ձևաչափը ՝ uuid)։

3. 2 Մեթոդներ և արձաններ

«GET» - 200/206; «POST» - 201 (+ «Corporation»), հակամարտությունները ՝ 407; vailivation - 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», «code», «trace _ id»; Suble-ը '«Content-Language» -ի միջոցով։

3. 4 Պագինացիա/ֆիլտրեր

Cursor-based: `page_size`, `page_token`, ответ: `next_page_token`.

Ֆիլտրերը և տեսակավորումը whitelis.ru են, որոնք փաստաթղթավորված են «parameters» -ում։

3. 5 Անվտանգություն

Միատարր ֆայլային սխեմա ՝ OAuth2/OIDC scopes կամ mTSA; արգելել '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 dik), delolint, MSK գեներատորներ; gnostic վերլուծության համար։

4. 3 GraphQL

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

4. 4 Կոդային ոսպնյակներ և SFC

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) Delobuf/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) Սեմանտիկ դիֆը և «կոտրող» փոփոխությունները

7. 1 HTTP

Breaking-օրինակներ

դաշտային փոփոխությունը/պարտավորությունը;

հեռացում/105/105;

enum/տիրույթի նեղացումը;

ձևաչափի փոփոխությունը (uuid no string)։

Նեբրեյքինգը

էլեկտրամագնիսական դաշտերի ավելացում;

նոր արձաններ, որոնք չեն ազդում happy-path-ի վրա (օրինակ, փաստաթղթավորված '422');

ընդլայնումը enum.

7. 2 gRPC/Protobuf

Դաշտի հեռացումը առանց «reserved »/համարի փոփոխությունը breaking է։

Տիպի փոփոխությունը (int32 հազար string) - breaking։

Նոր թեգի ավելացումը որպես optional սովորաբար safe է։

8) Linting Linting-ի և կոդի կապը

Համաձայնությունը ապահովվում է երկու հոսքերով

1. Պայմանագիրը պաշտոնական կոդը 'SDK/սերվերային փակուղիների արտադրություն, թեստերի բացասական օրինակներ։

2. Կոդը կանխատեսում է պայմանագիրը 'հատուկ թեստեր, ստատուսի/վերնագրերի ավտոմատ ստուգում։

Semgrep գաղափարները

արգելքը 'return 200' irror! = nil ';

պարտադիր «Idempotency-Key» -ը վճարման կետերում;

հյուսվածքներում հյուսվածքները քողարկելը։

9) CI/CD pline (հանրաքվե)

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

PR պետք է ընկնի, եթե

կա breaking-diff;

խախտվել են հիմնական կանոնները (կարգավիճակներ/անվտանգություն/սխալներ);

օրինակներ/նկարագրություն չկան։

10) Կանոնների կատալոգ (ձևանմուշներ ձեր կազմակերպության համար)

Բաղադրիչները և տեսակները

`_id` — `string`, `format: uuid`.

Դրամական դաշտերը '«string '/» decimal' s scale; արժույթը RF-3517 է։

Սխալներ

Միասնական սխեմա (տե՛ ս 383։ 3), 07: 400/401/404/409/422/422/5xx "։

Միշտ 'trace _ id ";" Retry-After "429/503 համար։

Պագինացիա

Միայն cursor; max 'page _ size "փաստաթղթավորված է։

Անվտանգություն

Բոլոր վիրահատությունները '«07» բլոկը; նկարագրված է «scopes»։

Ոչ 'http:' հղումներ; TLS 1. 2+.

Քաշ/idempotention

Для 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) Որակ դիտելը

Metriks: PR մասնաբաժինը լինթինգի սխալներով, ֆիքսման ժամանակը, breaking-փորձերի քանակը, «պարտքերը» կանոններով։

Dashbords: առաջընթացը միացված սխալների սխեմայի վրա, օրինակների ծածկումը, ռուսական տարբերակները։

13) Անտիպատերնի

«Դոկ» -ը ապրում է կոորդինատիզացիայից առանձին։ Պայմանագիր պահեք ծառայության կողքին և թողեք տարբերակված արտեֆակտը։

Լինթերը միայն ձեռքով է։ Անհրաժեշտ է կոշտ PR-gate։

Պատահական օրինակները (non-deterministic) ֆլեյտներ են ստուգման մեջ։

Բացասական օրինակների և ձախողումների բացակայությունը։

Սխալների սխեմայի վերաթողարկումը յուրաքանչյուր քայլի համար։

Անտեսելով Delobuf breaking ստուգումները (փոխում են «աչքի վրա»)։

14) iGaming/ֆինանսական առանձնահատկությունները

Պարտադիր վերնագրերը «X-Tenault», «X-Region» և «traceparent» ուղին։

Դրամական դաշտերը ֆիքսված մասշտաբն են/կլորացումը; արգելք float.

Հիբրիդային write-բռնակները '«Idempotency-Key», «Retry-After» և ճիշտ 4.9/201 սեմանտիկ։

Webhuks PMS/KYC: HMAC/mTSA-ը նկարագրված է «www.Schemes» -ում։ anti-replay («X-Timestamp», պատուհան)։

Տարածաշրջանային սահմանափակումները և սխալների տեղայնացումը («Content-Language»)։

15) Չեկ-թուղթ պատրաստակամության համար

• Spectral/Redocly պրոֆիլները կազմված և միացված են pre-commit և PR-gate-ում։
• Սխալների և ստատուսների միասնական սխեման գրանցվում և ստուգվում է։
• openapi-diff/GraphQL Inspector/buf - արգելափակում են breaking-փոփոխությունները։
• Հարցումների/պատասխանների օրինակները վալիդային են. / ֆիլտրերը փաստագրված են։
• Peter Schemes և scopes լցված են; http-հղումներ չկան։
• Disobuf '«reserved» -ի համար հեռավոր թեստերում։ նոր դաշտերը optional են։
• Semgrep/կոդի ոսպնյակները ներառում են. գաղտնիքները լոգարաններում։
• CI-ն հրապարակում է արտեֆակտները և լինթինգի հաշվետվությունները։
• Պլեյբուկ 'ինչպես վարվել breaking-2019-ում (rollback, hotfix, ծանուցում ինտեգրատորներին)։

16) TL; DR

Ներդրեք ավտոմատ ոսպնյակներ (Spectral/Redocly, buf/GraphQL Inspector) և սեմանտիկ diff, ամրագրեք սխալների/կարգավիճակների/ապահովության/, միացրեք PR-gate-ը և հրապարակումը որպես արտեֆակտներ։ Ցանկացած breaking-ազդանշան է։ Փողի/վճարման համար հատուկ կանոններ են (idempotention, «Retry-After», HMAC/mTRK)։