API astarı ve statik analiz

1) Neden link API

• Uyumsuz ve örtülü değişiklikleri önlemek
• Durumları, hataları, sayfalamayı, güvenliği birleştirin;
• Spesifikasyonları makine tarafından doğrulanabilir ve bültenleri öngörülebilir hale getirin;
• İnceleme maliyetini ve onboarding süresini azaltın.

İlke: "Sözleşmeler otomatik olarak kontrol edilir; Yeşil linting olmadan PR tutmaz"

2) Linting tesisleri

1. Sözleşmeler: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Avro/JSON Schema.
2. Uygulama: REST/gRPC kalemleri, ara katman yazılımı, durum kodları/başlıkları.
3. Altyapı: güvenlik başlıkları, sınırlar, önbellek ilkeleri.
4. İlgili eserler: örnekler, Postacı koleksiyonları, hata şemaları.

3) HTTP API için temel kurallar (önerilen profil)

3. 1 Gösterim ve URL

JSON gövdelerinde snake_case, yollarda kebap kılıfı veya tek tip kebap kılıfı/'/v1/... '.
Kaynaklar - çoğul:'/v1/payments ', iç içe -'/v1/wallets/{ id }/transactions'.
Yol-paramları olarak tanımlayıcılar:'/v1/payments/{ payment _ id} '(type: string, format: uuid).

3. 2 Yöntemler ve durumlar

'GET' - 200/206; ' POST '- 201 (+' Konum '), çakışmalar - 409; Doğrulama - 422; Limitler - 429 (+ 'Retry-After').
Hatalar için 200 döndürmeyin. Koşullu Sorgular - 304 'If-None-Match'tarafından.

3. 3 Hatalar (tek format)

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

Gerekli: 'kod', 'mesaj', 'trace _ id'; yerel - 'Content-Language' aracılığıyla.

3. 4 Sayfalama/filtreler

İmleç tabanlı: 'page _ size', 'page _ token', ответ: 'next _ page _ token'.
Filtreler ve sıralama - beyaz listeler 'parametrelerde' belgelenmiştir.

3. 5 Güvenlik

Tek tip güvenlik şeması: OAuth2/OIDC kapsamları veya mTLS; Deny 'http' (sadece 'https').
Hassas başlıkları döndürmeyin, örneklerde belirteçleri maskeleyin.

3. 6 Sınırlamalar ve boyutlar

Başlık/vücut sınırları: 413/414/431; İzin verilen maksimum değerleri belgeleyin.

4) Araçlar ve ekosistem

4. 1 OpenAPI

Spektral (JSON/YAML tiftik), Redocly linter, oas-diff/openapi-diff (anlamsal diff), şematez/dredd (devam eden kontroller).

4. 2 Protobuf/gRPC

Buf (tiftik + kesme kontrolü), protolint, SDK jeneratörleri; Analiz için gnostik.

4. 3 GraphQL

graphql-schema-linter, graphql-inspector (kırma).

4. 4 Kod Linters ve SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API kokusu ve güvenlik şablonları).

5) Kural örnekleri: Spectral/Redocly

5. 1 Spektral (örnek 'spektral. 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 Yeniden odaklama (fragment '.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 profili

6. 1 'buf. Yaml '

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

• Alan numaralarını tekrar kullanmayın; silindi - 'korunmuş'da.
• Yeni alanlar - 'isteğe bağlı' veya varsayılanlarla; Türleri/anlambilimleri değiştirmeyin.

7) Semantik diff ve "kırılma" değişiklikleri

7. 1 HTTP

• Alan türünü değiştirme/zorunlu
• Durumu/rotayı/parametreyi sil
• Enum/aralık daraltma;
• Kimlik değişikliği (uuid - string) formatı.

• İsteğe bağlı alanlar ekleme
• Mutlu yolu etkilemeyen yeni durumlar (örneğin, belgelenmiş '422')
• enum uzantısı.

7. 2 gRPC/Protobuf

'Korunmuş'/yeniden numaralandırma içermeyen bir alanı silme - kırma.
Tür değişikliği (int32 - string) - kırma.
İsteğe bağlı olarak yeni bir etiket eklemek genellikle güvenlidir.

8) Sözleşme ve Kod Bağlama

1. Contract kodu: SDK/sunucu taslaklarının oluşturulması, testlerde olumsuz örnekler.

2. Sözleşme - kod: şartname testleri, durumların/başlıkların otomatik kontrolü.

• 'Hata! = nil' olduğunda 'geri dönüş 200'e izin vermemek;
• Yazılı ödeme yollarında zorunlu 'Idempotency-Key';
• Günlüklerde belirteçleri maskelemek.

9) CI/CD boru hattı (referans)

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

• kırma-diff var;
• Temel kurallar ihlal edildi (durumlar/güvenlik/hatalar)
• Parametrelerin örnekleri/tanımları yoktur.

10) Kurallar kataloğu (kuruluşunuz için şablon)

Tanımlayıcılar ve türleri

'_ id' - 'string', 'format: uuid'.
Para alanları - 'string'/' decimal' ölçekli; Para birimi - ISO-4217.

Hatalar

Birleşik şema (bkz § 3. 3), kodları: '400/401/403/404/409/422/429/5xx'.
Her zaman 'trace _ id'; ' 429/503 için Retry-After '.

Pagination

Yalnızca imleç; max 'page _ size' belgelenmiştir.

Güvenlik

Tüm işlemler - 'güvenlik' bloğu; 'kapsamlar' tanımlanmıştır.
'http:' Bağlantısı yok; TLS 1. 2+.

Önbellek/idempotency

Для GET - 'ETag/Last-Modified'; Yazmak için - 'Idempotency-Key' (varsa).

Belgeler

'summary', 'description', istek/yanıt örnekleri (geçerli).

11) Otomatik kontrol örnekleri

11. 1 Zorunlu güvenlik başlıklarının doğrulanması (Spektral)

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

11. 2 openapi-diff (sözde CI adımı)

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

11. 3 buf kırma kontrolü

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

12) Sözleşmelerin kalitesinin gözlemlenebilirliği

Metrikler: PR'ların bağlantı hatalarıyla paylaşılması, düzeltme süresi, kırılma girişimlerinin sayısı, kurallara göre "borçlar".
Panolar: birleşik hata şemasına geçiş, örneklerle kapsama, sürüm kararlılığı.

13) Antipatterns

"Doc" koddan ayrı yaşar - eşzamansızlık. Sözleşmeyi hizmete yakın tutun ve sürümlü bir eser bırakın.
Linter sadece elle. Sağlam bir PR-gate lazım.
Rastgele örnekler (deterministik olmayan) - kontrollerde pullar.
Olumsuz örnek ve hata kodu yok.
Her hizmet için hata şemasının yeniden oluşturulması.
Protobuf kırma kontrollerini göz ardı etme (etiketleri "göze göre" değiştirme).

14) iGaming/Finansın Özellikleri

Para birimi alanları - sabit ölçek/yuvarlama; yüzdürme yasağı.
Zorunlu başlıklar 'X-Tenant', 'X-Region've trace' traceparent '.
Ödeme yazma kolları: 'Idempotency-Key', 'Retry-After've doğru 409/201 semantiğini kontrol etme.
Webhooks PSP/KYC: HMAC/mTLS 'securitySchemes' içinde açıklanmıştır; Anti-replay ('X-Timestamp', pencere).
Bölgesel kısıtlamalar ve hata yerelleştirme ('Content-Language').

15) Prod Hazırlık Kontrol Listesi

• Spektral/Redocly profiller tasarlanmış ve ön-commit ve PR-kapı bağlı.
• Tek hata deseni ve durumları - taahhüt ve kontrol.
• openapi-diff/GraphQL Inspector/buf - blok kırma değişiklikleri.
• İstek/yanıt örnekleri geçerlidir; sayfalama/filtreler belgelenmiştir.
• SecuritySchemes ve kapsamları doldurulur; HTTP bağlantısı yoktur.
• Protobuf için: silinen etiketlerde 'ayrılmış'; Yeni alanlar - isteğe bağlı.
• Semgrep/code linters etkin; Günlüklerdeki sırları maskelemek.
• CI sözleşme eserler ve linting raporları yayınlar.
• Playbook: breaking-diffa sırasında nasıl hareket edilir (geri alma, düzeltme, entegratörlere bildirimler).

16) TL; DR

Otomatik sözleşme linting (Spectral/Redocly, buf/GraphQL Inspector) ve anlamsal diff uygulayın, tek bir hata/durum/sayfalama/güvenlik şemasını düzeltin, PR-gate'i bağlayın ve sözleşmeleri eser olarak yayınlayın. Herhangi bir kırılma farkı bir fren lambasıdır. Para/ödemeler için - özel kurallar (idempotency, 'Retry-After', HMAC/mTLS).