Referans uygulaması

1) Hedefler, sınırlar ve ilkeler

1. Protokolün/özelliklerin açık bir yorumunu verin.

2. Bağımsız uyumluluk kontrolü sağlayın.

3. İstemci/sunucu/webhook'ların çalışma örneklerini sağlayın.

4. Entegrasyon ve uygulama maliyetlerini azaltın.

• RI, performansı en üst düzeye çıkarmak yerine davranışsal doğruluğa odaklanır.
• Minimum bir dizi üretim ayarı içerir (TLS, günlük kaydı, metrikler, izleme, sınırlayıcılar).
• Ticari/ürün satışlarının yerini almaz, ancak'daha düşük kalite çubuğunu "ayarlar.

• Spec-first: true - teknik özelliklerde (OpenAPI/AsyncAPI/Proto/JSON-Schema/IDL).
• Deterministik ve Test Edilebilir: Tekrarlanabilir Yanıtlar ve Kurgular.
• Docs-as-Code: Hepsi VCS'de, kod ve uygunluk testleri ile bir sürüm.
• Taşınabilirlik: konteynerler, Helm/compose, hazır manifestolar.

2) Referans uygulama türleri

RI-Server: spesifikasyon başına sunucu referansı (REST/gRPC/GraphQL/Streaming).
RI-Client/SDK: müşteri referansı (bir veya iki popüler platform) + örnekler.
RI-Webhook Alıcı: imzalı webhook işleyicisi (imza doğrulama, retrays).
RI-Adaptörler: mesaj aracılarına/olay veri yollarına (Avro/Proto/JSON, Schema Registry) adaptörler.
RI-Data: referans veri setleri, gizlilik profilleri, altın anlık görüntüler.

3) RI Depo Mimarisi

ri/
specs/        # OpenAPI/AsyncAPI/Proto/JSON-Schema server/       # эталонный сервер src/
config/
docker/
helm/
client/       # эталонный клиент/SDK + примеры js/ python/ go/
conformance/     # конформанс-раннер, тест-кейсы, золотые файлы cases/
fixtures/
golden/
samples/       # end-to-end сценарии, Postman/k6/Locust security/      # ключи тестовые, политики, пример подписи docs/        # руководство, ADR, runbook, FAQ ci/         # пайплайны, конфиги, матрица совместимости tools/        # генераторы, линтеры, проверяльщики схем

• Her sürümün bir 'vX' etiketi vardır. Y.Z've eserler (resimler, grafikler, SDK).
• Her bir nokta için - miktar ve imza (tedarik zinciri).
• CHANGELOG değişiklikleri "kırma'olarak işaretledi.

4) Özellikler, sözleşmeler ve planlar

Taşıma: OpenAPI/REST, gRPC/Proto, GraphQL SDL, AsyncAPI.
Anlambilim: hata kodları, idempotency, imleçler/sayfalama, retrai, veri tekilleştirme.
Olaylar: type/version,'id ',' occurred _ at _ utc ',' partition _ key ', order invariants.
İmzalar/güvenlik: OIDC/JWT damgaları, webhook imzası (HMAC/EdDSA), anahtar rotasyonu.

5) Uygunluk testi

• Lekelere uygunluk (şemaların doğrulanması),
• Davranışsal değişmezler (idempotency, sorting, cursors, TTL, retry policies),
• (güvenlik imzaları, son tarihler, nonce/replay koruması),
• Zamansal yönler (UTC, RFC3339, DST),
• olumsuz durumlar ve sınır koşulları.

Altın dosyalar: Sonuçların karşılaştırıldığı kararlı referans yanıtları/olayları.

python def run_conformance(target_url, cases, golden_dir):
for case in cases:
req = build_request(case.input)
res = http_call(target_url, req)
assert match_status(res.status, case.expect.status)
assert match_headers(res.headers, case.expect.headers)
assert match_body(res.json, golden_dir / case.id, allow_extra_fields=True)
for invariant in case.invariants:
assert invariant.holds(res, case.context)

consumer/sdk-js 1.4server 1.6, 1.7server 2.0 consumer/sdk-go 0.9server 1.5–1.7   –
webhook-receiver 1.1events v1events v2 (deprecated fields removed)

6) Üretim minimum (fırfırlar yok)

Güvenlik: Varsayılan olarak TLS, güvenlik başlıkları, CORS sınırlaması, sınırlayıcılar, anti-yeniden oynatma.
Gözlemlenebilirlik: günlükler (yapısal + PD maskeleme), metrikler (p50/p95/p99, hata oranı), izleme (korelasyon 'request _ id').
Yapılandırma: tüm ortam değişkenleri ve dosyaları aracılığıyla, yapılandırma şeması doğrulanır.
Perf-basline: ortak havuz ayarları, zincir zaman aşımı bütçesi, birleştirmeli önbellek.
Kararlılık: jitter ile retrai, devre kesici, geri basınç.

7) CI/CD ve eserler

1. Lint/montaj/ünite testleri.

2. Spec doğrulama (OpenAPI/AsyncAPI/Proto-lint).

3. Teknik özelliklerden SDK/bıçak üretimi.

4. Uyumluluk çalışması: 'ri-server', 'cases've' golds'a karşı.

5. Görüntüleri oluşturun (SBOM, imza), kayıt defterine yayınlayın.

6. E2E komut dosyaları (docker-compose/kind/Helm).

7. Docksite yayınlama ve örnekler.

• Konteyner resimleri'ri-server ','ri-webhook',
• SDK paketleri (npm/pypi/go),
• Helm chart/compose dosyaları,
• "Altın dosyalar've uygun bir koşucu ile zip.

8) Örnekler, SDK ve nasıl yapılır

İki popüler yığın üzerinde mini uygulama (örn. Düğüm noktası. Js/Go) aşağıdaki adımlarla: kimlik doğrulama> API çağrısı - hata işleme - geri çekme - webhook.
Nasıl yapılır: idempotent POST, el yazısı sayfalama, webhook imzası, işleme 429/503.
"Duman perf" için k6/JMeter profiller (yük değil, temel sağlık).

9) Sürüm ve evrim

SemVer: breaking changes - MAJOR; Kırılamayan MINOR - PATCH ekleyin.
Reddetme planı: özelliklerde bildirimler, özellik bayrakları, "gölge" uygunluk modu süresi, ardından zorlama.
Olay uyumluluğu: Tüketicilerin bilinmeyen alanları göz ardı etmesi gerekir.

10) RI'da güvenlik ve gizlilik

Test anahtarları ve sırları - sadece stand için; rıhtımda - değiştirme talimatları.
PD günlüklerde maskeleme; Ficesture anonimleştirme profilleri (PII - sentetik).
Demo ortamı eser ömrü politikası (TTL, otomatik temizleme).

11) Gözlemlenebilirlik ve RI için SLO

SLI/SLO RI: p95 <250 ms referans bankında, hata oranı <0. %5, bağımlılık hatası altında doğru bozulma (örnekte).
Panolar: gecikme/Verim/Hatalar + uygunluk sonuçları.
Webhooks/token kontrollerini imzalamak için karar günlükleri (izlenen başarısızlık nedenleri).

12) Performans: "Yeterli" taban çizgisi

Sıcak ve soğuk pistlerdeki 'wrk/hey/k6' profilleri.
Açık pozisyon: RI, maksimum RPS'de rekabet etmez, ancak tipik bir hedefe dayanmalıdır (örneğin, t3'te 500 RPS. p95 <200ms ile orta) - entegratörler için bir kılavuz olarak.

13) Kullanım kılavuzu (runbook)

Yerel başlatma: compose/' make up '.
K8s-deploy: Dümen değerleri, sırlar, giriş, HPA.
Webhook imzalama anahtarlarının döndürülmesi (çift anahtar dönemi).
Trableshooting: sık hatalar ve nedenleri (401, 403, 429, 503), günlükleri/izleri okumak için nasıl.

14) Yönetim ve mülkiyet

Sahipler: lekelerin ürün sahibi + platform (ekipman) + güvenlik.
Yayın takvimi ve mola değişikliği onay penceresi.
Anlamlı protokol değişiklikleri üzerine RFC/ADR.

15) Diller/platformlar için uyarlama

Önerilen minimum bir üst düzey (JS/TS) ve bir sistemdir (Go/Java).
Tür eşleme: tarihler/para biçimleri/ondalık/bayt kümeleri nasıl temsil edilir.
Her SDK'da geri çekilmeler/zaman aşımları/havuz ayarları için öneriler.

16) Anti-desenler

RI = "sandbox without tests": uygunluk yok, fayda yok.
Speka koddan ve testlerden "ayrı yaşıyor" - tutarsızlık.
"Altın dosyalar've değişmezlerin eksikliği - davranış hakkında pullar ve anlaşmazlıklar.
Bağımlılık çerçevesi: Kapsayıcı olmadan bir kütüphaneye/buluta katı bağlanma.
PD maskeleme olmadan günlükler, arşivdeki anahtarlar.
Perf, davranış yerine karışır: "kimin haklı" yerine "kimin daha hızlı" olduğunu ölçmeye çalışır.
Modülerlik ve eserler olmadan bir dev ikili/görüntü (SDK/grafikler/özellikler).

17) Mimar kontrol listesi

1. Speka - kanonik ve doğrulanmış? (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. Tam örneklerle bir RI sunucusu ve en az bir RI istemcisi/SDK var mı?
3. Uyumluluk koşucusu, vakalar, "altın dosyalar", negatifler ve değişmezler hazır mı?
4. CI/CD görüntüleri toplar, SDK, site, uygunluk ve e2e çalışır?
5. Varsayılan güvenlik: TLS, imzalar, sınırlar, PD maskeleme?
6. Gözlemlenebilirlik: RI için günlükler/metrikler/yollar, panolar ve SLO'lar?
7. Perf-basline belgelenmiş ve tekrarlanabilir?
8. SemVer sürümü, uyumluluk matrisi, reddetme prosedürü?
9. Runbook ve yerel/küme başlatma - tek tıklamayla?
10. Sahipler, yayın takvimi, RFC/ADR akışı tanımlandı mı?

18) Mini-örnek: referans webhook (pseudocode)

python def verify_webhook(request, keys):
sig = request.headers["X-Signature"]
ts = int(request.headers["X-Timestamp"])
if abs(now_utc().epoch - ts) > 300: return 401 # replay window body = request.raw_body if not any(hmac_ok(body, ts, k, sig) for k in keys.active_and_previous()):
return 401 event = json.loads(body)
if seen(event["id"]): return 200 # idempotency handle(event)
mark_seen(event["id"])
return 200

Test durumu kontrol eder: zaman penceresi, imzanın doğruluğu (geçerli ve önceki anahtar), olayın idempotensi. id ', negatifler (bozuk imza, süresi dolmuş' ts ').

Sonuç

Referans uygulaması, sistem davranışının kanonudur: kod, testler ve eserler tarafından onaylanan tek bir özellik. İyi RI entegrasyonu hızlandırır, protokol belirsizliğini ortadan kaldırır, doğrulanabilir uyumluluk sağlar ve güvenlik, gözlemlenebilirlik ve performans için minimum standartları belirler. Mühendislik "iskeletinizin'bir parçası haline getirin - ürünleriniz, ortaklarınız ve ekosisteminiz daha hızlı ve daha güvenilir bir şekilde hareket edecektir.