پرش به محتوای اصلی
یک شروع رایگان برای شما

۳ روز رایگان،
پنل تحلیلگر را تجربه کنید

ثبت‌نام کنید و با تأیید شماره موبایل، دسترسی آزمایشی سه‌روزه‌تان را فعال کنید.

✓ بدون نیاز به پرداخت✓ فعال‌سازی پس از تأیید موبایل
شروع رایگان ۳ روزه

ویژه کاربران جدید · یک دوره برای هر حساب

چک‌لیست استفاده Production از API خبر؛ امنیت، پایداری و کنترل مصرف

پیش از استقرار سرویس مبتنی بر API خبر، این چک‌لیست امنیت، Timeout، Retry، کش، صفحه‌بندی، مانیتورینگ و سهمیه را مرور کنید.

تیم khapi · ۲۸ مرداد ۱۴۰۵ · ۱۰ دقیقه مطالعه
چک‌لیست استفاده Production از API خبر؛ امنیت، پایداری و کنترل مصرف

چرا کدی که روی لپ‌تاپ کار می‌کند کافی نیست؟

در محیط واقعی، شبکه کند می‌شود، پاسخ خالی می‌آید، سهمیه محدود است و کلید ممکن است نیاز به چرخش داشته باشد. سرویس Production باید خطا را پیش‌بینی کند و بدون ایجاد فشار اضافه، بازیابی شود.

چک‌لیست معماری امن و پایدار برای API خبر در Production

۱. کلید و دسترسی

  • برای Production کلید جدا بسازید.
  • کلید را در Secret Manager یا متغیر محیطی نگه دارید.
  • مقدار کامل را در لاگ، داشبورد خطا و پاسخ API چاپ نکنید.
  • فرایند چرخش و ابطال اضطراری را مستند کنید.
  • درخواست را از Backend بفرستید؛ کلید در JavaScript مرورگر قرار نگیرد.

راهنمای مدیریت چند API Key جزئیات این بخش را پوشش می‌دهد.

۲. Timeout اجباری

هیچ درخواست شبکه‌ای نباید بدون Timeout باشد. زمان اتصال و دریافت را متناسب با تجربه کاربر تعیین کنید. برای Job پس‌زمینه می‌توان زمان بیشتری در نظر گرفت، اما درخواست وب باید سریع Fail شود.

response = requests.get(
    "https://khapi.ir/api/v1/news",
    headers={"x-api-key": API_KEY},
    params={"q": "اقتصاد", "page": 1, "page_size": 20},
    timeout=(3, 15),
)
response.raise_for_status()

۳. Retry فقط برای خطای قابل تکرار

برای Timeout، خطای اتصال و پاسخ‌های موقت سرور Retry با تأخیر افزایشی اجرا کنید. خطای احراز هویت یا پارامتر نامعتبر با تکرار حل نمی‌شود. به `Retry-After` احترام بگذارید و Jitter اضافه کنید تا چند Worker هم‌زمان دوباره حمله نکنند.

تعداد تلاش باید محدود باشد. بعد از پایان تلاش‌ها، خطا را ثبت و مسیر جایگزین مثل کش آخرین پاسخ معتبر را فعال کنید.

۴. صفحه‌بندی و فیلتر دقیق

همیشه `page_size` متناسب با نیاز تنظیم کنید. برای همگام‌سازی دوره‌ای، بازه تاریخ و آخرین زمان پردازش‌شده را بفرستید. دریافت مکرر صدها خبر و حذف آن‌ها در کلاینت، هم کند و هم پرمصرف است.

از فیلترهای `q`، `q_in_title`، `sources`، `categories`، `entities`، `from_date` و `to_date` استفاده کنید. راهنمای فیلتر API خبر نمونه‌های بیشتری دارد.

۵. Idempotency در پردازش

خبر دریافت‌شده ممکن است در اجرای بعدی دوباره ظاهر شود. شناسه، URL نرمال‌شده یا هش محتوا را ذخیره کنید و پردازش را Idempotent بنویسید. ارسال ایمیل یا ایجاد رکورد مالی نباید با دیدن دوباره همان خبر تکرار شود.

Checkpoint آخرین زمان موفق را فقط پس از ذخیره کامل Batch جلو ببرید. در شکست نیمه‌راه، اجرای بعدی باید بتواند بدون از دست رفتن داده ادامه دهد.

۶. کش و تازگی

جست‌وجوهای پرتکرار را کوتاه‌مدت کش کنید. کلید کش باید همه پارامترهای مؤثر را شامل شود. زمان انقضا را بر اساس کاربرد تعیین کنید: داشبورد زنده به کش کوتاه و گزارش تاریخی به کش بلندتر نیاز دارد.

در رابط کاربری زمان آخرین به‌روزرسانی را نشان دهید تا کاربر پاسخ کش‌شده را با داده لحظه‌ای اشتباه نگیرد.

۷. قرارداد پاسخ را اعتبارسنجی کنید

پیش از استفاده از فیلدها، نوع و وجود آن‌ها را بررسی کنید. کلاینت را نسبت به اضافه‌شدن فیلد تازه مقاوم بنویسید. اگر فیلد اختیاری مثل تصویر یا خلاصه خالی بود، نمایش جایگزین داشته باشید.

تست قرارداد با چند پاسخ واقعی، پاسخ بدون نتیجه، خطای ۴۰۱، خطای ۴۲۲ و خطای موقت بنویسید.

۸. مانیتورینگ کاربردی

این شاخص‌ها را ثبت کنید:

  • نرخ موفقیت و خطا بر اساس Status Code؛
  • زمان پاسخ صدک ۵۰ و ۹۵؛
  • تعداد Retry؛
  • حجم درخواست و مصرف سهمیه؛
  • تعداد خبر تازه در هر اجرا؛
  • سن آخرین همگام‌سازی موفق.

هشدار را روی نشانه‌های اثرگذار بگذارید؛ مثلاً نبود همگام‌سازی موفق برای ۳۰ دقیقه، نه صرفاً یک خطای منفرد.

۹. بودجه و سهمیه

مصرف را در سطح حساب ببینید. چند API Key سهمیه مستقل ایجاد نمی‌کند. تعداد اجرای Job، اندازه صفحه و تعداد کاربران را در یک بودجه ماهانه تخمین بزنید. کش، Webhook داخلی و اشتراک داده بین سرویس‌ها از درخواست تکراری جلوگیری می‌کند.

۱۰. Runbook رخداد

برای این سناریوها دستورالعمل کوتاه داشته باشید: کلید نامعتبر، پایان سهمیه، افزایش خطا، کندی، داده قدیمی و افشای Secret. مسئول، روش تشخیص، اقدام موقت و مسیر Escalation را مشخص کنید.

جمع‌بندی

استقرار مطمئن API خبر فقط به یک درخواست موفق وابسته نیست. امنیت کلید، Timeout، Retry کنترل‌شده، فیلتر دقیق، پردازش Idempotent، کش، مانیتورینگ و Runbook اجزای یک کلاینت Production سالم‌اند.

اشتراک‌گذاری:

این مطلب چطور به کار شما بیاید؟

مفاهیم این مقاله را مستقیم در پنل khapi امتحان کنید:

آماده شروع هستید؟

۳ روز استفادهٔ رایگان از پنل تحلیلگر، مطابق محدودیت‌های دورهٔ آزمایشی و بدون نیاز به کارت بانکی.