مدیریت خطا و پیام‌ها

تو هر پروژه‌ای خطا اجتناب‌ناپذیره، مهم اینه چطور باهاش برخورد کنیم. اگه پیام‌ها درست مدیریت نشن، هم کاربر گیج میشه، هم فرانت سخت‌تر می‌تونه هندل کنه.

چند تا نکته به عنوان best practice:

- برای خطاها یه ساختار مشخص داشته باش تا فرانت بتونه راحت تشخیص بده با چه شرایطی طرفه.
- پیام برای کاربر باید ساده و قابل فهم باشه، نه پر از اصطلاحات فنی.
- جزئیات فنی و لاگ‌ها رو نگه دار برای بک‌اند و تیم فنی، نه برای کاربر.
- همیشه از پیام‌های عمومی برای خطاهای پیش‌بینی‌نشده استفاده کن (مثل "مشکلی پیش اومده، دوباره امتحان کن").
- خطاها رو دسته‌بندی کن (مثلاً خطای کاربر، خطای سرور، خطای دسترسی) تا بتونی راحت‌تر مدیریت کنی.

از مهمترین شرایطی که باید یک توسعه دهنده بک اند در API لحاظ کنه Custom Exception Handler هستش تا بتونه خطا ها رو با یک فرمت مناسب و یک دست پاسخ بده و این موضوع بر اساس کمپانی های مختلف متفاوت هستش ولی می تونین الگوی مناسبی رو از درونشون پیدا کنین.

مثلا داشتن کلید error در پیام و همچنین در ادامه status کد خطای اتفاق افتاده و همچنین جدا سازی detail و message که در یکی خطای توسعه و دیگری پیام قابل نمایش به کاربر قرار میگیره. در بعضی شرایط ممکنه حتی timestamp و اطلاعات بیشتری هم درج بشه مثلا code یا type که ممکنه شماره خطای خاص و یا کلید واژه مربوطه برای ردگیری خطای سریعتر باشه.

دیده میشه گاهی وقتا آدرس و یا حتی ورودی ها رو هم در بعضی سرویس ها نشون میدن که به نظرم جاش توی ریسپانس نیست و باید توی لاگ ها باشه و با این حال بعضی سرویس ها ارائه میدن.


نمونه Response مناسب برای خطا ها

{
  "error": {
    "status": 404,
    "code": "OBJECT_NOT_FOUND",
    "message": "آبجکت مورد نظر یافت نشد",
    "detail": "Object matching query does not exist.",
    "timestamp": "2025-10-03T12:30:45Z"
  }
}

رفرنس ها:
- https://zuplo.com/learning-center/best-practices-for-api-error-handling
- https://api7.ai/learning-center/api-101/error-handling-apis
- https://nordicapis.com/5-real-world-examples-of-great-api-error-messages/
- https://www.baeldung.com/rest-api-error-handling-best-practices


📢 @thealibigdeli_channel

#api_design
#api

این پستو دیدم تقریبا هر Rest standard ای بود توش رعایت نشده :))

در خصوص ارور و integration داشتن خوب با فرانت اند؛

۱. همیشه سعی کنید از HTTP STATUS استفاده کنید. اگه ۲۰۰ میدین یعنی ریسپانس موفقیت آمیز بوده، حالا هرچی که اسمشو موفقیت آمیز میذارید. چون تقریبا تمام ابزار های telemetry (چه بک اند چه فرانت) بر مبنا همین کار میکنه. اینکه شما http status code رو بذارید تو بادی کار بسیار اشتباه و غلطی هست. استاندارد های http رو دور زدید.

۲. فرانتی که نمیدونه کی به سرور درخواست داده، دولوپر نیست. صرفا یک LLM ای هست با دسترسی به git. یک تایمی ارسال میشه از سمت سرور به کلاینت. حالا اگه این تایم استمپ زمان اتمام درخواسته بازم برای کلاینت مهم نیست که شما بخوای رو سرور بذاری. برای کلاینت مهم اینه که درخواست رو کی دریافت کرده که میدونه.

۳. اینکه شما پیام ترجمه شده رو سمت سرور نگه دارید یک اشتباه دیگست. code کافیه. داکیومنت شما باید تو OpenAPI برای ارور ها باید schema داشته باشه که فرانت بدونه چه ارور هایی ممکنه بیاد. اینطوری اگه فرانت از ابزار های code auto generate استفاده کنه (که مثلا schema openapi رو میگیرن و کلاینت میسازن خودشون) اون ارور هارو هم میبینه و تو تایپ سیستمش میاد. میتونه اونا رو حالا به هر زبونی که کاربر هست بهش نشون بده. میتونه هرجوری بخواد ترجمه کنه. OBJECT_NOT_FOUND هم به شدت کلید اشتباهیه. چون معلوم نیست کدوم آبجکت not found عه. درستش اینه مثلا BookNotFound.‌که فرانت بتونه ترجمه کنه.

اگه خیلی فرانت بخوای قشنگ کارو در بیاره (تو سورس کد خودم اینکارو کردم) یک هوک نوشتم useError. این هوک اگه ریسپانس ۲۰۰نباشه ریسپانس رو میگیره. و کدش رو مپ میکنه به زبون یوزر و ترجمه میکنه و بهش نمایش میده. اگه کدی هم وجود نداشت (مثلا اروری که واقعا catch نشده بود) اون موقع فال بک میشه به اینکه خطایی در سرور رخ داده و نمیدونم این خطا چیه :)‌. این هوک من, به شما هم ErrorMessage رو میده. هم یک کال بکی میده که از react-toastify استفاده کرده و ارور رو toast میکنه برای شما.

پس هم میتونی بنویسی

const { errorMessage } = useError()
errorMessage(response)

و هم

const { toastError} = useError()
toastError(response)

@PyBackendHub

و به این شکل یوزر هر زبونی که هست براش ترجمه میکنید.

چرا بهتره ترجمه رو سمت کلاینت نگه داریم؟

۱. از رو مرورگر میتونید متوجه بشید زبون کاربر چیه. ولی بخواین اینو رو سرور متوجه شید باید فرانت اول یک کدی بفرسته که اینو براتون تو سرور بفرسته.

۲. اینکه کاربر چه زبونی داره در درجه اول state frontend هست. نه بک اند.

۳. اگه یوزر زبونش رو تغییر داد, اگه فرانت state management رو درست انجام داده باشه بدون اینکه درخواست http ای بزنه کل محتوا صفحه رو میتونه آپدیت کنه. و این تجربه کاربری رو بهتر میکنه.

۴. اکوسیستم مدیریت زبان در فرانت بسیار قوی تره.

ولی خب در نهایت یک جاهایی مجبور میشیم ترجمه سمت سرورم داشته باشیم. مثلا ارسال نوتفیکیشن.

@PyBackendHub

آقا دیس لایک میذارید دلیلشم بنویسید.
به قول مهدی تو گروه همه چیز را همگان دانند و همگان هنوز از مادر نزاده اند.
چهار تا چیزم ما یاد میگیریم از کامنت هاتون.
ولی این ری اکشنا چیزی یاد کسی نمیده.

کامنت و ری اکشن برای همین بازه که شما نظرتونو بگید و مخالفت کنید :)

@PyBackendHub

مرسی که دلیل های بیشتری گذاشتین :))

فکت :))
@PyBackendHub

دوستان خواهشا پیوی من سوال برنامه نویسی و جنرال نپرسید.

https://t.iss.one/PythonFellow
عضو گروه بشین، من همیشه معمولا پاسخ میدم. بقیه هم میدن، سوال ممکنه برای شما باشه ولی بقیه هم میتونن استفاده کنند جواب بدن و نظره من ممکنه bias باشه. بحث بهتره جمعی باشه تا دو نفره.


پیوی زمانی بپرسید که سوالتون رو نمیخواین تو جمع مطرح کنید به دلایل خیلی شخصی.

@PyBackendHub

گیتهاب یک فیچر خوب داشت که میدیدی تو چه PR و ایشو هایی اخیرا چه فعالیت هایی بود (اونایی که سابسکرایب کرده بودی) و اینم برداشتن :))

@PyBackendHub

سلام به همه همراهان
من اکانت گیت هابم بسته شده, بدون اینکه دلیل رو بهم ایمیل کنند یا بگن. و این واقعا برام عجیب بود. تیکت ساختم که پییگری بشه ولی برام خیلی مهمه که بتونم اکانتمو برگردونم چون پروژه اوپن سورس داشتم روش که روزانه هزار دانلود میخورد و داکیومنتش رو گیت هاب هاست میشد :(‌

خیلی خوشحال میشم اگه این پست لینکدین رو repost کنید تا بیشتر دیده بشه 🙏


@PyBackendHub

ظاهرا پست لینکدین جواب داد. تو ردیت همه نوشته بودن ۲-۳ هفته طول میکشه جواب بدن بررسی کنند. جالبه تیکتی که باز کردم هنوز جوابی نگرفته. تازه sponsorship گیتهابو فعال کردن برام که بتونم پروژه هام اسپانسر بگیرن و پول بگیرم از این طریق. :))
@PyBackendHub

یک ترد جالب تو ردیت
از اینجور آدما فراری باشید :)
کامنت خیلی خوب بود.. resume driven development 😂

@PyBackendHub

وضعیت وایب کدر ها:

@PyBackendHub

لایو تجربه مهاجرت کاری مانی مظفر به آلمان 🚀🇩🇪

Software Engineer | Noah Labs | Berlin

📅 زمان: چهارشنبه ۷ آبان (29th Oct)
🕔ساعت: 10 شب به وقت ایران | ۷:۳۰ بعدازظهر به وقت اروپای مرکزی
🎙 میزبان: بابی
📆 اضافه کردن ایونت به کلندر:لینک

https://www.youtube.com/watch?v=7alVm0lwytg

اگه لایو رو از دست دادین سیو شده. کامنت یا سوالی داشتین بپرسید این زیر حتما که تو لایو نتونستیم بهش بپردازیم.