پیاده سازی مرجع

1) اهداف، مرزها و اصول

1. یک تفسیر واضح از پروتکل/مشخصات ارائه دهید.

2. اطمینان از بررسی سازگاری مستقل.

3. ارائه نمونه های کار از مشتری/سرور/webhooks.

4. کاهش هزینه های ادغام و پیاده سازی.

• RI به جای به حداکثر رساندن عملکرد، بر صحت رفتار تمرکز دارد.
• شامل حداقل مجموعه ای از تنظیمات تولید (TLS، ورود به سیستم، متریک، ردیابی، محدود کننده).
• فروش تجاری/محصول را جایگزین نمی کند، اما «نوار با کیفیت پایین» را تنظیم می کند.

• مشخصات اول: درست - در مشخصات (OpenAPI/AsyncAPI/Proto/JSON-Schema/IDL).
• قطعی و قابل آزمایش: پاسخ های تجدید پذیر و داستان
• Docs-as-Code: همه در VCS، یک نسخه با کد و تست انطباق.
• قابلیت حمل: ظروف، Helm/compose، مانیفست های آماده شده.

2) انواع پیاده سازی های مرجع

RI-Server: مرجع سرور در هر مشخصات (REST/gRPC/GraphQL/Streaming).
RI-Client/SDK: مرجع مشتری (یک یا دو سیستم عامل محبوب) + نمونه.
گیرنده RI-Webhook: دستگیره webhook امضا شده (تأیید امضا، بازپرداخت).
آداپتورهای RI: آداپتورها به کارگزاران پیام/اتوبوس رویداد (Avro/Proto/JSON، Schema Registry).
RI-Data: مجموعه داده های مرجع، پروفایل های حریم خصوصی، عکس های طلا.

3) معماری مخزن RI

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/        # генераторы, линтеры, проверяльщики схем

• هر نسخه دارای یک برچسب «vX» است. Y.Z 'و مصنوعات (تصاویر، نمودار، SDK).
• برای هر ذره - مقدار و امضا (زنجیره تامین).
• CHANGELOG تغییرات «شکستن» را مشخص کرد.

4) مشخصات، قراردادها و طرح ها

حمل و نقل: OpenAPI/REST، gRPC/Proto، GraphQL SDL، AsyncAPI.
معناشناسی: کدهای خطا، idemotency، نشانگر/صفحه بندی، retrai، deduplication.
رویدادها: نوع/نسخه، 'id'، 'رخ داده است _ at _ UTC'، 'partition _ key'، سفارش ناوردا.
امضا/امنیت: تمبرهای OIDC/JWT، امضای وب هوک (HMAC/EdDSA)، چرخش کلید.

5) تست انطباق

• انطباق با لکه ها (اعتبار سنجی طرح ها)،
• متغیرهای رفتاری (idempotency، مرتب سازی، نشانگر، TTL، سیاست های مجدد)،
• امنیت (امضا، مهلت، حفاظت از nonce/replay)،
• جنبه های زمانی (UTC، RFC3339، DST)،
• موارد منفی و شرایط مرزی.

فایل های طلایی: پاسخ های مرجع پایدار/رویدادهایی که نتایج با آنها مقایسه می شوند.

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) حداقل تولید (بدون زواید)

امنیت: TLS به طور پیش فرض، سرصفحه های امنیتی، محدودیت CORS، محدود کننده ها، ضد پخش.
قابلیت مشاهده: گزارش ها (پوشش ساختاری + PD)، معیارها (p50/p95/p99، میزان خطا)، ردیابی (همبستگی 'request _ id').
پیکربندی: از طریق متغیرهای محیطی و فایل ها، طرح پیکربندی معتبر است.
Perf-basline: تنظیمات استخر مشترک, بودجه timeout زنجیره ای, کش با coalescing.
پایداری: retrai با لرزش، قطع کننده مدار، فشار پشتی.

7) CI/CD و مصنوعات

1. تست های خطی/مونتاژ/واحد.

2. اعتبار سنجی تنظیمات (OpenAPI/AsyncAPI/Proto-lint).

3. تولید SDK/stabs از مشخصات.

4. انطباق اجرا: «ri-server» در مقابل «موارد» و «طلا».

5. ساخت تصاویر (SBOM، امضا)، انتشار به رجیستری.

6. اسکریپت های E2E (docker-compose/kind/Helm).

7. انتشار docksite و مثالها.

• تصاویر کانتینر «ری سرور»، «ری وب هوک»،
• بسته های SDK (npm/pypi/go)
• نمودار هلم/نوشتن فایل ها،
• زیپ با «فایل های طلا» و یک دونده مطابق.

8) نمونه ها، SDK و نحوه

مینی نرم افزار در دو پشته محبوب (به عنوان مثال،. گره ها js/Go) همراه با مراحل: authentication → API call → error handling → retray webhook.
چگونه به: POST idempotent، صفحه بندی شکسته، امضای webhook، پردازش 429/503.
پروفایل های k6/JMeter برای «smoke-perf» (نه بار، اما سلامت عمومی).

9) نسخه و تکامل

SemVer: شکستن تغییرات → MAJOR ؛ اضافه کردن جزئی غیر قابل شکستن → PATCH →

طرح رد: اعلامیه ها در مشخصات، پرچم های ویژگی، دوره «سایه» حالت انطباق، و سپس اجرای.
سازگاری رویداد: مصرف کنندگان باید زمینه های نا آشنا را نادیده بگیرند.

10) امنیت و حریم خصوصی در RI

تست کلید و اسرار - فقط برای پایه ؛ در اسکله - دستورالعمل جایگزینی.
PD ماسک در سیاهههای مربوط ؛ پروفایل های ناشناس سازی Ficesture (PII → مصنوعی).
محیط زیست نسخه ی نمایشی سیاست طول عمر مصنوعی (TTL، خودکار تمیز).

11) قابلیت مشاهده و SLO برای RI

SLI/SLO RI: p95 <250 ms در نیمکت مرجع، نرخ خطا <0. 5٪، تخریب صحیح تحت شکست وابستگی (در نمونه).
داشبورد: تاخیر/توان/خطاها + نتایج سازگاری.
سیاهههای مربوط به تصمیم برای امضای webhooks/token checks (ردیابی علل شکست).

12) عملکرد: پایه «کافی»

پروفایل های «wrk/hey/k6» در آهنگ های گرم و سرد.
موقعیت روشن: RI در حداکثر RPS رقابت نمی کند، اما باید یک هدف معمولی (به عنوان مثال، 500 RPS در T3) را تحمل کند. متوسط با p95 <200ms) - به عنوان یک راهنما برای انتگرال.

13) کتابچه راهنمای عملیات (runbook)

راه اندازی محلی: ترکیب/« را تشکیل می دهند ».
K8s-deploy: ارزش های هلم، اسرار، ورود، HPA.
چرخش کلید امضای webhook (دوره دو کلید).
Trableshooting: خطاهای مکرر و علل آنها (401، 403، 429، 503)، نحوه خواندن سیاهههای مربوط/مسیرهای پیاده روی.

14) مدیریت و مالکیت

صاحبان: صاحب محصول نقطه + پلت فرم (تجهیزات) + امنیت.
انتشار تقویم و شکستن پنجره تأیید تغییر.
RFC/ADR در مورد تغییرات معنی دار پروتکل.

15) سازگاری برای زبان/سیستم عامل

حداقل توصیه شده یک سطح بالا (JS/TS) و یک سیستم (Go/Java) است.
Type mapping: نحوه نمایش تاریخها/قالبهای ارز/مجموعههای دهدهی/بایت.
توصیه هایی برای تنظیمات retrays/timeouts/pool در هر SDK.

16) ضد الگوهای

RI = «sandbox without tests»: بدون انطباق، بدون سود.
اسپکا جدا از کد و تستها زندگی میکند.
فقدان «فایل های طلایی» و invariants → لکه ها و اختلافات در مورد رفتار.
چارچوب وابستگی: اتصال سفت و سخت به یک کتابخانه/ابر بدون containerization.
سیاهههای مربوط بدون PD پوشش، کلید در مخزن.
Perf به جای رفتار مخلوط می شود: تلاش برای اندازه گیری «چه کسی سریعتر است» به جای «چه کسی درست است».
یک باینری/تصویر غول پیکر بدون مدولار و مصنوعات (SDK/نمودار/مشخصات).

17) چک لیست معمار

1. اسپکا - متعارف و معتبر ؟ (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. آیا یک سرور RI و حداقل یک سرویس گیرنده/SDK با نمونه های کامل وجود دارد ؟

3. دونده انطباق, موارد, «فایل های طلایی», منفی و ناوردا آماده?

4. CI/CD تصاویر، SDK، سایت را جمع آوری می کند، سازگاری را اجرا می کند و e2e ؟

5. امنیت پیش فرض: TLS، امضا، محدودیت، پوشش PD ؟

6. قابلیت مشاهده: Logs/metrics/trails، داشبورد و SLO برای RI ؟

7. Perf-basline مستند و قابل تجدید است ؟

8. SemVer نسخه، ماتریس سازگاری، روش رد ؟

9. Runbook و راه اندازی محلی/خوشه - در یک کلیک ؟

10. صاحبان، تقویم انتشار، جریان RFC/ADR تعریف شده است ؟

18) مینی مثال: وب هوک مرجع (شبه کد)

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

مورد آزمون بررسی می کند: پنجره زمان، صحت امضا (کلید فعلی و قبلی)، idempointency رویداد ". id ', نگاتیو (امضای خراب، ts منقضی شده).

نتیجه گیری

پیاده سازی مرجع، کانون رفتار سیستم است: یک مشخصات واحد که توسط کد، تست ها و مصنوعات تایید شده است. RI خوب یکپارچه سازی را سرعت می بخشد، ابهام پروتکل را حذف می کند، سازگاری قابل تایید را فراهم می کند و حداقل استانداردهای امنیت، قابلیت مشاهده و عملکرد را تعیین می کند. آن را بخشی از «اسکلت» مهندسی خود قرار دهید - و محصولات، شرکا و اکوسیستم شما سریعتر و قابل اطمینان تر حرکت خواهند کرد.