ادغام HUB و API لینک

1) نقش HUB و حوزه مسئولیت

• پروتکل ها و فرمت ها را متحد کنید
• اطمینان از قابلیت اطمینان (retrays، صف، سیاست های timeout، قطع کننده مدار) ؛
• تضمین امنیت (mTLS، OAuth2، JWT، HMAC، IP-allowlist) ؛
• متمرکز کردن قابلیت مشاهده (سیاهههای مربوط، معیارها، ردیابی) ؛
• ساده کردن ارائه دهنده در حال تغییر (آداپتورها + نقشه برداری درست)
• قراردادهای پایدار برای تیم های محصول ارائه دهید.

2) اصول طراحی

قراردادهای سازگار: تک DTO/رویدادها، طرح دقیق و نسخه.
Idempotency - کلید درخواست، deduplication، تلاش مجدد امن است.
خرابی پیش فرض: اتمام وقت، برگشت، سیاست های قطع کننده مدار.
قابلیت مشاهده به عنوان یک تابع: همه چیز قابل اندازه گیری و ردیابی است.
جداسازی ادغام از دامنه: آداپتورها منطق کسب و کار هسته را «نمی دانند».
ارزش رویداد: انتشار/اشتراک برای فرآیندهای ناهمزمان.
نسخه بندی: قراردادهای SemVer و تخریب مدیریت شده.

3) معماری سطح بالا

API دروازه: احراز هویت، محدودیت نرخ، انتشار قناری، WAF.
Orchestrator/Router: مسیریابی توسط ارائه دهندگان، اولویت ها، شکست، مسیریابی هوشمند.
آداپتورهای ارائه دهنده: REST/gRPC/GraphQL/WebSocket، نقشه برداری زمینه، حافظه های محلی.
اتوبوس EDA (Kafka/RabbitMQ/NATS): رویدادهای «پرداخت ایجاد شده»، «KYC گذشت»، «جلسه بازی آغاز شد».
خدمات قرارداد/طرح: ثبت طرح برای JSON/Avro/Protobuf.
ذخیره سازی حالت ادغام: کلید های idempotence، همبستگی، وضعیت.
قابلیت مشاهده: داشبورد Prometheus/OTel + و هشدارها.
DevPortal: دایرکتوری های ادغام، OpenAPI/Protobuf، نمونه ها، سندباکس ها.

4) قراردادهای داده و طرح

طرح های سختگیرانه (JSON Schema/Avro/Protobuf)، اعتبار ورودی/خروجی اجباری.
رجیستری طرح با سیاست سازگار با عقب.
قراردادهای خطای پاک (فرمت کد/جزئیات یکنواخت).

5) پروتکل های پشتیبانی شده

REST (OpenAPI): همه کاره، آسان برای سند.
gRPC: عملکرد بالا برای ارتباطات داخلی.
GraphQL: هنگامی که نمونه های جمع آوری شده مورد نیاز است.
Webhooks: رویدادها به سیستم های خارجی ؛ HMAC امضا، تحویل مجدد.
SSE/WebSocket: جریان رویداد زنده (وضعیت های زنده، معاملات).

6) امنیت و دسترسی

mTLS بین خدمات داخلی.
OAuth2/OIDC برای مشتریان خارجی، نشانه های کوتاه مدت.

JWT برای فدراسیون خدمات هویت ؛ ادعاهای حسابرسی

امضای HMAC برای webhooks/collbacks بحرانی.
IP allowlist، WAF، RASP، فیلترهای ضد ربات.
مدیریت مخفی (KMS/HSM)، چرخش کلید، تقسیم دانش.
GDPR/PCI DSS: به حداقل رساندن داده های شخصی و کارت، نشانه گذاری.

7) مسیریابی و ارکستراسیون

مسیریابی مبتنی بر سیاست: توسط جغرافیایی، ارز، معیارهای شکست، ارائه دهنده SLA.
شکست: توالی PSP/ارائه دهنده، تخریب خودکار.
قطع کننده مدار: شاخه های سریع تحمل خطا برای خطاهای مکرر.
Bulkhead: جداسازی توسط ارائه دهنده/مستاجر/استخر موضوع.
حماسه/ارکستراسیون برای فرآیندهای طولانی (ثبت نام → KYC → سپرده).

8) Idempotence و دقیقا یک بار (به عنوان واقعی به عنوان آن می شود)

حافظه پنهان Idempotency-Key + وضعیت/پاسخ.
تفکیک رویداد گذرگاه) کلید همبستگی (.
ذخیره سازی «درخواست های دیده شده» با TTL.

http
POST /payments
Idempotency-Key: 3d8c1a4f-7f0e-4a2a-9e5a-2b8d3e7e2c11
Content-Type: application/json

json
{
"tenantId": "eu-casino-12",
"userId": "u-9812",
"currency": "EUR",
"amount": 50. 00,
"method": "card",
"metadata": {"orderId": "ORD-2025-1105-001"}
}

HUB نتیجه را ذخیره می کند و همان پاسخ را در تکرار باز می گرداند.

9) صف و اتوبوس رویداد

Kafka/NATS/RabbitMQ برای مراحل ناهمزمان: نتایج KYC، وضعیت پرداخت، تعادل ارائه دهنده بازی.
تم ها با کلید های عضویت عبارتند از «tenantId»، «userId» یا «providerId».
نگهداری و DLQ (نامه مرده) با ارسال مجدد خودکار پس از رفع.
الگوی Outbox در خدمات هسته برای انتشار رویداد تضمین شده.

10) نسخه و سازگاری

SemVer در قراردادها: "v1"، "v1. 1 "،" v2 ".
وجود موازی از دو نسخه جزئی، یک برنامه depriction روشن است.
آداپتورهای مهاجرت (نقشه های موقت زمینه) برای انتقال صاف.

11) قابلیت مشاهده و قابلیت اطمینان

معیارها: تأخیر p50/p95/p99، میزان خطا، توان عملیاتی، نسبت موفقیت توسط ارائه دهندگان، زمان تأیید رویداد، «زمان به کیف پول».
ردیابی (OTel): پایان دادن به پایان 'trace _ id '/' span _ id' از تماس API به پاسخ ارائه دهنده.
سیاهههای مربوط: ساختار یافته، با همبستگی 'request _ id'، PII/PAN پوشش.
SLO: به عنوان مثال، 99. میزان موفقیت 9٪ <1. 5S برای مسیرهای بحرانی.
هشدارها: با بودجه SLO خطا، رشد DLQ، ناهنجاری های retray/timeout.

12) Sandboxes و مدارهای تست

Sandbox برای هر ارائه دهنده: رفع, شبیه ساز پاسخ, نسخه داده ها.
تست قرارداد (Pact/Buf) و تولید خودکار SDK.
بارگذاری پروفایل با توجه به سناریوهای «اوج مسابقات»، «امواج پرداخت».

13) دسته بندی ادغام (به عنوان مثال برای iGaming)

پرداخت/برداشت: PSP, بانکداری A2A/Open, دروازه رمزنگاری.
KYC/AML/خطر: تأیید هویت/آدرس، لیست تحریم ها، امتیاز دهی رفتاری.
ارائه دهندگان بازی/Aggregators: راه اندازی جلسه، نشانه های بازی، Collecks بازگشت.
ارتباطات: ایمیل/اس ام اس/فشار/پیام رسان.
تجزیه و تحلیل ترافیک/BI: جریان رویداد و aggregates.
تقلب/شارژر: مراکز اختلاف، هشدارها.

14) چند اجاره ای و منطقه ای

جداسازی TenantId: کلید های رمزگذاری، سهمیه ها، محدودیت ها، استخر های اتصال.
Geo-sharding: مسیریابی به نزدیکترین RAP/منطقه، با توجه به قوانین محلی.
روش های محلی ارائه دهنده/پرداخت: لیست توسط صلاحیت و سطح KYC.

15) عملکرد و ذخیره سازی

حافظه پنهان توکن (PSP/KYC)، پاسخهای فراداده ارائه دهنده (TTL).
ادغام اتصال و استفاده مجدد از جلسات TLS.
Async I/O برای RPS بالا ؛ خم شدن در آداپتورها.
محدودیت های نرخ در محیط های مشتری و ارائه دهنده.

16) سناریوهای پایان به پایان (نمونه)

16. 1 سپرده (کارت)

1. پست/پرداخت → ارکستر → PSP شماره 1.
2. اتمام وقت 2 ؛ при '5xx/timeout' - سعی کنید с برگشت ؛ در طول تخریب - PSP # 2.
3. پرداخت مراسم. مجاز → هسته تعادل → BI/ضد تقلب.

16. 2 KYC

1. 'POST/kyc/submit' → آداپتور ارائه دهنده KYC.
2. async: webhook 'kyc. نتیجه توسط HMAC امضا شده است ؛ در صورت شکست - تحویل مکرر (تا N بار).
3. رویداد 'kyc. تایید شده است به اتوبوس منتشر شده است.

16. 3 جلسه بازی

1. 'POST/games/session' → آداپتور جمع کننده → نشانه جلسه.
2. Collbecks نتایج/شرط → HUB اعتبار امضا و idempotency.
3. رویداد "بازی. دور بزنید. حل و فصل می رود به محاسبه پرداخت و گزارش.

17) خطاها و فرمت پاسخ یکنواخت

Коды: 'INTEGRATION _ TIMEOUT', 'PROVIDER _ UNAVAILABLE', 'CONTRACT _ VALIDATION _ FAILED', 'SECURITY _ SIGNATURE _ INVALID'.

json
{
"code": "PROVIDER_UNAVAILABLE",
"message": "Primary PSP degraded, switched to fallback",
"correlationId": "9f8e1b6a-1c2d-4b4e-9d31-91c6bc31c1d4",
"provider": "psp-1",
"hint": "Retry allowed; idempotency key required"
}

18) وب سایت های امن: ثبت نام و تکرار

X-Signature: sha256=hex(hmac_sha256(secret, body + timestamp))
X-Timestamp: 1730812800

رانش زمان را بررسی کنید و فقط اطلاعیه های تازه را بپذیرید. تکرار - به صورت نمایی به N، سپس در DLQ.

19) تغییر مدیریت و انتشار

آداپتورهای قناری (1-5٪ از ترافیک)، دارای پرچم های هر مستاجر هستند.
نسخه های سازگار با عقب: ابتدا آداپتورها، سپس قراردادها.
CAB/CRQ برای ارائه دهندگان خارجی، پنجره های استقرار SLA سازگار است.

20) SLA/SLO/OLA

SLA ارائه دهنده: آپ تایم ≥ 99. 9٪، ack webhooks ≤ 3c، نهایی شدن پرداخت ≤ 30c (p95).
SLO HUB: p95 <1. 5c به نقاط پایانی بحرانی، نرخ خطا <0. 3%.
OLA در داخل: محدودیت صف، بودجه بازپرداخت، حداکثر زمان DLQ.

21) کاتالوگ یکپارچه سازی و DevPortal

صفحات ارائه دهنده: وضعیت، نسخه آداپتور، مورد نیاز درست، چک لیست.
SDK autogen (OpenAPI/gRPC)، نمونه ها، مجموعه های پستچی، سرورهای ساختگی.
دکمه «Test in Sandbox» و خطوط ادغام CI.

22) ایمنی و انطباق

نسخه PII در سیاههها، رمزگذاری فیلدهای در حالت استراحت، فیلدهای PAN فقط به صورت توکن شده.
RBAC/ABAC برای پانل های اپراتور، حداقل اصل امتیاز.
ثبت رضایت (GDPR)، حق حذف/پورت.
فروشنده ریسک و DPIA برای ادغام جدید.

23) برنامه پیاده سازی (MVP → مقیاس)

MVP (0-2 ماه): دروازه، 1-2 PSP، 1 KYC، 1 جمع کننده بازی، معیارهای پایه، idemotency، DLQ.
مرحله 2 (3-4 ماه): اتوبوس EDA، DevPortal، تست قرارداد، مسیریابی مجدد، امضای وب سایت.
مرحله 3 (5-6 ماه): خوشه هایی با چرخش جغرافیایی، مسیریابی هوشمند از طریق SLA، SLO/هشدارهای گسترده، اتوژن SDK، قناری.

24) چک لیست پیش فروش

قراردادها در رجیستری، آزمون سازگاری گذشت.
سیاست های Timeout/retray/breaker با آزمون های e2e تنظیم و پوشش داده می شوند.
IdempotencyKey در POST/PUT بحرانی گنجانده شده است.
امضاهای وب سایت تأیید می شوند، تکرار پیکربندی می شوند، DLQ نظارت می شود.
معیارهای p95/p99 و میزان خطا با SLO مطابقت دارد، هشدارها متصل می شوند.
اسرار در KMS، چرخش تست شده ؛ IP-allowlist/WAF فعال هستند.
Runbooks/playbooks حادثه منتشر شده، در تماس برنامه ریزی شده.
DevPortal و sandboxes برای شرکا در دسترس هستند، نسخه ها مستند شده اند.

خلاصه

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