مدیریت خطاها – Error handling

مقدمه ای بر Error Handling #

قبل از هر چیز لازم است بدانیم مدیریت خطا یا error handling به چه معناست. این اصطلاح به واکنش و مکانیسم‌های بازیابی نرم‌افزار در صورت بروز خطا اشاره می‌کند. به عبارت دیگر این کار فرآیندی است که شامل پیش‌بینی دقیق، شناسایی و رفع خطاها در برنامه‌ها است.

اجرای منظم یک برنامه از طریق مدیریت خطا آسان‌تر است. وقتی صحبت از رویکردهای خطا handling می‌شود، بسیاری از برنامه‌ها با مشکلات معماری نرم‌افزار مواجه می‌شوند.

توجه داشته باشید که API AirPlus کامل منطق بر اصول RESTful API نوشته شده است پس بنابراین پاسخ تمام درخواست ها با Status Code مورد نظر خود ارسال خواهد شد و مدیریت این Status Code ها یا هما کدهای وضعیتی در برنامه شما الزامیست.

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

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

نحوه نگارش خطاها #

پاسخ نادرست – Response False یا همان مشکل در ارسال اطلاعات #

{
    "status": false,
    "time": "Timestamp", // Timestamp
    "code": "Error Code"
}

Status Code – کدهای وضعیتی درخواست ها #

وضعیت 200 #

کد وضعیت 200 OK نشان می‌دهد که سرور درخواست ارسال‌شده را به‌درستی دریافت و پردازش کرده و پاسخ مورد انتظار را بدون هیچ‌گونه خطا بازگردانده است. به‌ عبارت‌ دیگر، زمانی که مرورگر با کد 200 مواجه می‌شود، یعنی صفحهٔ وب یا منبع درخواست‌شده به‌درستی بارگذاری شده است. شما با مواجه شدن با وضعیت 200 بدون هیچ مشکلی میتوانید دیتاهای مورد نظر خود را استخراج نمائید و به فرایند خود ادامه دهید.

وضعیت 201 #

کد 201 به معنای موفقیت در ایجاد یک منبع جدید در وب توسط وب‌سرور استفاده می‌شود. این کد وضعیت نشان‌دهنده این است که وب‌سرور با موفقیت درخواست POST (ایجاد منبع) یا PUT (به‌روزرسانی منبع) را پردازش کرده و یک منبع جدید ایجاد کرده است. این منبع معمولاً با یک URI (شناسه منابع یکتا) جدید معرفی می‌شود که به عنوان پاسخ به کلاینت ارسال می‌شود. این URI معمولاً به کلاینت امکان می‌دهد که به سرعت به منبع جدید دسترسی پیدا کند.

بطور مثال در زمان خرید بلیت در صورتی که خرید شما بدون هیچ مشکلی صورت بگیرد وضعیت 201یه معنای ایجاد این آیتم در وب سرور مرکزی دریافت خواهد شد.

وضعیت 204 #

کد 204 اعلام می‌کند که سرور درخواست کاربر را به خوبی برآورده کرده است اما محتوای جدیدی در پاسخ به درخواست در دسترس نیست.

بطور مثال شما زمانی که از API بازکردن قفل رزرو استفاده میکنید در صورت موفق بودن پاسخ برای شما با وضعیت 204 ارسال خواهد شد.

وضعیت 207 #

Status Code 207 Multi-Status یکی از کدهای وضعیت پروتکل HTTP است که معمولاً در پاسخ به درخواست‌های مربوط به WebDAV استفاده می‌شود. این کد نشان می‌دهد که سرور پاسخ‌های متعددی را برای یک درخواست واحد بازگردانده است.

در صورتی که شما مواردی را (بیشتر از یک آیتم) در درخواست خود جهت انجام عملیات ارسال فرمائید. پاسخ شما در صورتی که با خطا اولیه مواجه نشود اما به هر دلیلی مانند تکراری بودن و یا هر مورد دیگری ارسال شده باشد وضعیت کد 207 دریافت می شود و این به این معناست که قسمتی از درخواست انجام شده و قسمتی دیگر بنا به دلایل مشخص رد شده است.

کد وضعیت روشی برای اطلاع‌رسانی شما در مورد وضعیت درخواست است. این کد وضعیت معمولاً به دو صورت ارسال می‌شود. وضعیت 200 که نشان‌دهنده درست بودن همه مراحل درخواست و پاسخ سرور است و کد وضعیت 500 یا Error 500 که نشان‌دهنده بروز مشکل در پاسخ به درخواست است و یا کدهای دیگر که در زیر به جزئیات آن پرداخته ایم.

وضعیت 500 #

ارور 500 یک کد خطای HTTP status code است به این معنی که مشکلی در سرور وب‌سایت رخ داده، اما سرور نمی‌تواند بگوید مشکل دقیقاً چیست. کد وضعیت 500 (ارور داخلی سرور) نشان می‌دهد که سرور با شرایط غیرمنتظره‌ای مواجه شده که مانع از انجام درخواست شما می‌شود. هنگامی که از یک وب‌سایت بازدید می‌کنید، مرورگر شما درخواستی را به سروری که سایت در آن میزبانی می‌شود ارسال می‌کند. سرور این درخواست را دریافت کرده، آن را پردازش کرده و منابع درخواستی را به همراه یک هدر HTTP باز می‌فرستد. این هدر کد وضعیت HTTP (response code in the Hypertext Transfer Protocol) را نیز شامل می‌شود.

جهت حفظ ارتباط پایدار در صورتی که با این خطا مواجه شده اید، لطفا از طریق Base URL پشتیبان درخواست خود را ارسال نمائید. قابل ذکر است استفاده از سرور پشتیبان در شرایط معمولی توصیه نمیگردد.
سرور پشتیبان روشی جامع و کامل جهت ایجاد ارتباطی پایدار می باشد.

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

وضعیت 400 #

  ارور 400 که به  Bad Request 400  نیز معروف است به عنوان خطای کاربر یا کلاینت توسط سرور مرکزی شناخته می‌شود. زمانی که کاربران یک درخواست اشتباه را به سرور ارسال می‌کنند و سرور نمی‌تواند جوابی برای آن درخواست پیدا کند این خطا را به کاربر نشان می‌دهد. در واقع ارور 400 به کاربران نشان می‌دهد که درخواست آنها با موفقیت به سرور ارسال نشده است یا درخواست آنها نادرست بوده است. سرور نمی‌تواند درخواست کاربر را به دلیل وجود خطای کلاینت پردازش کند. به همین دلیل این موضوع را با ارسال پیام‌های مانند invalid request message framing یا deceptive request routing به کاربر نشان می‌دهد. دلایل مختلفی وجود دارد که باعث ایجاد خطا در ارسال درخواست کاربران به سرورها می‌شود.

وضعیت 404 #

ارور 404 خطای عدم یافتن مسیر و یا صفحه مورد نظر می باشد. در سرویس API ما در صورتی که شما آدرس URL مورد نظر را بصورت صحیح وارد ننمائید با این خطا مواجه میشوید.

در صورت بروز این خطا لطفا یکبار دیگر آدرس URL ارسالی خود را بررسی فرمائید.

در بعضی از شرایط امکان این وجود دارد که در مهلت تعیین شده جهت جابجایی آدرس Base شما اقدام نکرده باشید و سرور مورد نظر دیگر در آن ورژن پاسخگو درخواست های شما نباشد.

وضعیت 405 #

ارور 405 نشان دهنده این موضوع است که سرور مرکزی متد ارسالی مورد استفاده را نپذیرفته است و یکی از ارورهای سمت کلاینت به شمار می رود. به عبارتی این ارور نشان می دهد که درخواست به دسترسی ارسال شده است و وب سرور نیز این درخواست را تشخیص داده است اما متد به کار رفته را قبول نکرده است که در نتیجه کاربر قادر به مشاهده صفحه مورد نظر نخواهد بود و با ارور Method Not Allowed مواجه خواهد شد.

وضعیت 409 #

Status Code 409 Conflict یکی از کدهای وضعیت HTTP است که به معنای وجود تعارض یا مشکل در درخواست ارسالی توسط کلاینت است. این کد نشان‌دهنده‌ی این است که درخواست کلاینت نمی‌تواند به‌درستی اجرا شود زیرا با وضعیت جاری سرور یا منابع موجود تعارض دارد.

به طور مثال در صورتی که شما آیتمی تکراری جهت ثبت ارسال نمائید با وضعیت کد 409 مواجه می شود و این به معنی تکراری بودن آیتم می باشد.

وضعیت 422 #

Status Code 422 Unprocessable Entity یکی از کدهای وضعیت HTTP است که به معنای “موجودیتی که قابل پردازش نیست” است. این کد معمولاً زمانی استفاده می‌شود که درخواست ارسال‌شده از نظر ساختاری صحیح است (یعنی درخواست به درستی فرمت شده و اطلاعات ضروری را شامل می‌شود)، اما سرور قادر به پردازش آن نیست به دلیل اینکه داده‌های درخواست با مشکلات منطقی یا اعتبارسنجی مواجه هستند.

خطاهایی که در قالب Response دریافت میشود #

این خطا ها در قالب Response False بصورت کد دریافت میشوند که میتوانید در متن خطا ها و راه حل آنها را در جدول زیر مشاهده نمائید.

در ضمن میتوانید از طریق API زیر بصورت داینامیک این خطاها را دریافت و مدیریت نمائید.

دریافت جزئیات خطا از طریق API #

در این روش شما باید درخواست خود را از طریق لینک زیر ارسال فرمائید.

سربرگ – Header #

{{Api Url}}/error-handling

HEADER
GET /api/reservation/{{Api version}}/error-handling HTTP/1.1
Host: {{Your Host}}
Authorization: Bearer JWTToken
Content-Type: application/json
Domain: {{Your Domain}}

API Url از طریق پنل کاربری قابل مشاهده خواهد بود

مقادیر ارسالی – Request Data #

{
    "code": "Error Code"
}

پاسخ صحیح – Response True #

{
    "status": true,
    "time": "Timestamp", // Timestamp
    "data": [
        {
            "title": "Error title in Persian",
            "solution": "How to solve errors in Persian"
        },
        ...
    ]
}

پاسخ نادرست – Response False #

{
    "status": false,
    "time": "Timestamp", // Timestamp
    "code": "Error Code"
}