هماهنگ سازی داده ها از طریق API

1) چرا هماهنگ سازی مورد نیاز است و اهداف چیست

سازگاری دامنه: مشخصات، کیف پول، دایرکتوری ها، محدودیت ها، KYC.
کاهش تاخیر: تقریبا در زمان واقعی برای فرآیندهای بحرانی (پرداخت، پاداش).
انعطاف پذیری: تجربه قطع برق شبکه/ارائه دهنده بدون از دست دادن حوادث.
اقتصاد: به حداقل رساندن خروج/CPU از طریق deltas و packetization.

معیارهای موفقیت: تاخیر (ها) بین منبع و مصرف کننده، طراوت، نسبت تکراری، درصد درگیری ها، هزینه GB/ساعت آبی.

2) مدل های همگام سازی

2. 1 کشیدن (رای گیری)

مشتری درخواست تغییرات در فواصل زمانی.

مزایا: سادگی، کنترل بار.
معایب: تاخیر، نظرسنجی «خالی»، خطر پرش در نرخ بالای تغییر.
بهبودها: If-Modified-Since, Etag/If-None-Match, change_token.

2. 2 فشار (webhooks/رویدادها)

منبع حوادث را به گیرنده تحمیل می کند.

مزایا: تقریبا در زمان واقعی، اقتصاد نظرسنجی.
معایب: نیاز به تحویل با retrays، deduplication، امنیت (امضا، mTLS).
الزامات: مصرف کنندگان بی نظیر، عقب نشینی نمایشی، پخش مجدد.

2. 3 CDC/جریان (تغییر ضبط داده ها)

تصویر لحظهای تغییرات از ثبت معامله/ثبت رویداد) کافکا، دبزیوم (.

مزایا: کامل بودن، نظم، مقیاس.
معایب: پیچیدگی، شما نیاز به کنترل انواع عملیات (درج/به روز رسانی/حذف/سنگ قبر).

2. 4 ترکیبی

Webhooks به عنوان یک «ماشه»، رای گیری به عنوان یک عقب نشینی و برای آشتی.

3) دلتاهای افزایشی

3. 1 علامت (نشانگر زمان)

مشتری «last _ seen _ ts» را ذخیره می کند و درخواست «updated _ at> watermark» را درخواست می کند.

خطرات: رانش ساعت - استفاده از UTC و NTP ؛ پنجره همپوشانی را برای 1-2 دقیقه و dedup با نسخه ID + بگیرید.

3. 2 تغییر نشانه/مکان نما

نشانه توالی پایدار: '؟ مکان نما = eyJvZmZzZXQiOjEwMDB9 '.

مزایا: انعطاف پذیری برای تغییر نظم، مقیاس.
مورد نیاز: نشانگر های غیر تخلیه شده، TTL و پخش ایمن.

3. 3 آفست شماره (افزایش خودکار)

«id» last_id'. ساده، اما زمانی که sharding و «سوراخ» در دنباله شکسته می شود.

4) صفحه بندی نمونه بزرگ

کیست/مکاننما) ارجح (: "؟ after = cursor & limit = 1000 '- با تغییرات پایدار است.
Offset/limit - ساده، اما گران و در معرض تغییر است.
همیشه یک کلید مرتب سازی پایدار را مشخص کنید (به عنوان مثال، (updated_at، id)).

json
{
"items": [ { "id": "u_1", "updated_at": "2025-11-03T16:59:10Z" } ],
"next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0xMS0wM1QxNjo1OToxMFoifQ==",
"has_more": true
}

5) تغییر معانی: upsert، ادغام، حذف

5. 1 Upsert/ادغام

«PUT/resource/{ id}» یک جایگزین کامل است.
'PATCH/resource/{ id}' - بهروزرسانی جزئی (وصلههای ادغام با اعتبارسنجی).
Idempotency توسط 'Idempotency-Key' برای همه نوشتن.

5. 2 حذف ها

Soft delete (فیلد 'deleted = true', 'deleted _ at') - تاریخچه را ذخیره کنید; سینک سنگ قبر می دهد.
حذف سخت - قبل از ناپدید شدن، رویداد را «deleted» کنید.

json
{ "id":"u_1", "event":"deleted", "deleted_at":"2025-11-03T17:00:00Z" }

6) کنترل نسخه و رقابت

6. 1 ETag/If-Match (قفل خوش بینانه)

دفعات بازدید: «ETag:» v123 «».
به روز رسانی از "If-Match:" v123 "- حفاظت در برابر" به روز رسانی از دست رفته ".
در صورت تعارض - 409 تعارض با «error _ code:» CONFLICT_VERSION"'.

6. 2 نسخه از سوابق

فیلد 'version '/' updated _ at' - در محاسبه دلتا و deduplication.

6. 3 درگیری ها

سیاستها: last-write-wins, server-wins, merge-strategy by fields (به عنوان مثال، مجموع → افزودنی، پرچم → اولویت منبع).

7) سفارش و تقسیم بندی

7. 1 روش تحویل

گارانتی: حداقل یک بار به علاوه idempotency → عملا استاندارد.
برای جریانهای نقدی بحرانی - اثرات دقیقا یک بار از طریق فروشگاه idemotency.

7. 2 کلید های idempotence

ترکیب فیلدهای دامنه: «source _ id» event _ type «sequence».
ذخیره سازی TTL 24-72 ساعت (یا بیشتر در SLA).

7. 3 تقسیم بندی

ذخیره آخرین نسخه/seq اعمال شده به گیرنده ؛ افراد مسن را رها کنید.

8) تکرار، وقفه، عقب نشینی

قابل بازیابی: 5xx/429/408/زمان بندی ؛ غیر قابل بازیابی: 400/401/403/404/ 409/422/410/412.

عقب نشینی نمایشی + jitter: 1s، 2s، 4s... تا 30-60

پس از احترام برای 429/503.
وقفه های مشتری: اتصال 3-5 ثانیه، درخواست عمومی 10-30 ثانیه ؛ محدودیت کلی تلاش 3-6.

9) تاخیر و کنترل SLA

9. 1 SLI/SLO

SLI تاخیر: متوسط/p95 تاخیر بین «رخ داده است _ در» و «اعمال شده در مصرف کننده».
SLO: به عنوان مثال، "p95 lag ≤ 60s (28d)"، "سهم رویدادهای از دست رفته = 0"، "سهم تکراری ≤ 0. 01%».
بودجه خطا: صرف انتشار/آزمایش.

9. 2 معیارها

«sync _ lag _ seconds»، «events _ received _ total»، «events _ applied _ total»، «duplicates _ total»، «conflicts _ total»، «retries _ total»، «backlog _ size»، «cursor _ advance _ rate».

10) آشتی و عقب نشینی

آشتی روز/ساعت: مجموع/هش پنجره.
API آشتی: GET/آشتی ؟ از =... & به =... چک سام ها و واریانس ها را برمی گرداند.
پر کردن مجدد: بارگیری مجدد داده های تاریخی در دسته ها با یک مکان نما، بدون منبع DDOS ؛ محدودیتها را مشاهده کنید.

11) طرح ها و مثال ها

11. 1 رویدادهای وبهوک (امضا شده)

json
{
"event": "user. updated",
"id": "evt_01HX",
"occurred_at": "2025-11-03T18:00:05Z",
"sequence": 123456,
"data": { "id": "u_1", "email": "a@b. com", "updated_at": "2025-11-03T18:00:02Z" }
}

• 'X-Signature: sha256 = '
• شناسه رویداد ایکس: evt_01HX'
• 'X-تلاش مجدد: 0.. N'

11. 2 نمونه گیری افزایشی (نظرسنجی)

GET/v1/کاربران ؟ updated_after=2025-11-03T17: 58:00Z&cursor=...&limit=1000'

11. 3 upsert idempotent

POST /v1/users
Idempotency-Key: upsert-u_1-20251103T1800Z
{ "id":"u_1","email":"a@b. com","version":124 }
→ 201/200 (stable)

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

Auth: حوزه های OAuth2/JWT ؛ برای کانال های لینک - mTLS در تقاضا.
زیرنویس ها: سرفصل های HMAC برای webhooks، اسرار چرخش.
به حداقل رساندن PII، ماسک در سیاهههای مربوط ؛ GDPR/DSAR آپلود/حذف.
RBAC/ABAC: دسترسی مستاجر/سازمان، سهمیه های سخت.

13) قابلیت مشاهده و سیاهههای مربوط

Лейблы: 'env'، 'service'، 'tenant'، 'source'، 'cursor'، 'seq'، 'event _ type'.
همبستگی: 'trace _ id' از ورودی → به سیاههها و ردپاها اعمال میشود.
داشبورد: تاخیر، عقب ماندگی، سرعت مکان نما، خطاهای نوع، 429/5xx، هزینه (خروج/دقیقه).

14) FinOps: هزینه هماهنگ سازی

دسته بندی (اندازه دسته 100-1000) + فشرده سازی (gzip/br).
ذخیره سازی و ETag برای صفحات بدون تغییر.
بارهای نازک: فقط فیلدهای تغییر یافته، پیوندی به یک منبع کامل در صورت تقاضا.
محدودیت های همزمانی و «پنجره های شب» برای پر کردن.

15) تست و کیفیت

15. 1 قراردادها و موارد منفی

اعتبارسنجی طرحهای JSON، فیلدهای مورد نیاز، پایداری 'error _ code'.
تست: خارج از ترتیب، تکراری، پرش حوادث، درگیری نسخه، 429/5xx.

15. 2 هرج و مرج/بازی

تزریق: تاخیر شبکه، کاهش 10-30٪ از حوادث، مرتب سازی مجدد.

معیارها: حفظ نظم/یکپارچگی ؟ بدون باخت ؟ تاخیر در SLO

16) چک لیست پیاده سازی

• مدل انتخاب شده (فشار/کشیدن/ترکیبی) و منبع حقیقت.
• دلتای افزایشی: علامت یا مکان نما/نشانه.
• صفحه بندی: مکان نما/keyset با درجه پایدار.
• Idempotency فروشگاه، کلید و TTL ؛ dedup by '(id, version/seq)'.
• ETag/If-Match و سیاست درگیری (LWW/server-wins/merge).
• تلاش مجدد/عقب نشینی/jitter، احترام 'تلاش مجدد-پس از'.
• معیارهای عقب ماندگی/backlog/تکراری/درگیری، داشبورد و هشدار.
• آشتی API + آشتی روزانه.
• امنیت: OAuth2/JWT، امضای وب، mTLS، سیاست های PII.
• FinOps: فشرده سازی دسته ای +، محدودیت همزمانی، خروج از سهمیه.
• مجموعه تست: مرتب سازی مجدد، تکراری، قطع، backfill.

17) برنامه پیاده سازی (3 تکرار)

1. MVP (1-2 هفته):

صفحه بندی مکان نما، دلتاهای علامت گذاری، uppert idemotent، تاخیر/عقب ماندگی اساسی، معیارهای مجدد + عقب نشینی.

2. مقیاس (2-3 هفته):

Webhooks به عنوان trigger + polling-fallback، امضای HMAC، آشتی، ETag/If-Match، داشبورد و هشدار سوختگی با تاخیر.

3. نرم افزار (3-4 هفته):

CDC/streaming (Kafka/Debezium) برای دامنه های داغ، پر کردن خودکار، اسکریپت های DR، بهینه سازی FinOps (دسته ای/بروتلی)، SLA برای تاخیر و گزارش.

18) مینی سوالات متداول

چه چیزی را انتخاب کنید: علامت یا مکان نما ؟

مکان نما/keyset در برابر مرتب سازی مجدد و مقیاس مقاوم تر است. علامت گذاری آسان تر برای شروع است، اما اضافه کردن همپوشانی و deadup.

آیا دقیقا یک بار لازم است ؟

به طور کلی، گران است. تمرین - حداقل یک بار + idempotency ؛ دقیقا یک بار - فقط برای اثرات پولی.

چگونه تعارضات را کاهش دهیم ؟

استفاده از ETag/If-Match، ادغام طراحی توسط زمینه ها، جلوگیری از «پنهان» عوارض جانبی.

مجموع

هماهنگ سازی قابل اعتماد دلتاهای افزایشی + صفحه بندی صحیح + idemotency و کنترل نسخه است, افزایش یافته توسط مشاهده, جرقه و حمل و نقل مقرون به صرفه. مدل مناسب را انتخاب کنید (فشار/کشش/CDC)، SLO را در تاخیر پین کنید، سیاست های درگیری و آزمایش های سناریوی کثیف را اجرا کنید - و تبادل اطلاعات شما قابل پیش بینی، پایدار و مقرون به صرفه می شود.