کتابخانه‌ی استاندارد · سیستم و ابزار

خطاها error

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

واردسازی خطاها

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

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

هر خطا یک نوع دارد، مثل نوع خطا.یافت نشد، برای تصمیم‌گیری در کد، و یک پیام برای خواندن انسان. تجزیه‌گرها جای مشکل را هم پر می‌کنند: جایگاه، خط و ستون، و مسیری مثل $.users[3].age. یک بسته می‌تواند کنار نوع کلی، کد دقیق خودش را هم بگذارد، مثل json.trailing_data. وقتی خطا از لایه‌ای می‌گذرد که چیز بیشتری می‌داند، بپیچ توضیح آن لایه را جلوی آن می‌گذارد و نوع خطا عوض نمی‌شود.

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

مرتبط: اختیاری در بسته‌ی هسته مقدار یا نبودنش را در یک جا نگه می‌دارد، برای وقتی که یک مقدار فقط ممکن است نباشد، نه این‌که چیزی خراب شده باشد؛ وقتی می‌خواهید نتیجه را نگه دارید و بعداً رسیدگی کنید، جداشمار موفق/خطا خودتان را بسازید، همان‌طور که درس جداشمارها نشان می‌دهد.

اشتباه‌های رایج:

  • فراخوانی تابع خطادار باید تلاش داشته باشد یا درون بلوک تلاش: باشد؛ وگرنه کامپایلر آن را نمی‌پذیرد (E155).
  • تلاش به‌تنهایی خطا را به فراخوان می‌فرستد، پس فقط در تابعی کار می‌کند که خودش خطادار است (E156). در تابع ریشه خطادار: بنویسید یا از بلوک تلاش: استفاده کنید.
  • در تلاش x گرفتن خطا جایگزین مقدار جایگزین هر بار و پیش از همه حساب می‌شود. آن را یک مقدار ساده نگه دارید.
  • بپیچ، با کد، با مسیر و با موقعیت خطای تازه‌ای برمی‌گردانند و خطای قبلی را دست نمی‌زنند.
  • بر اساس نوع یا است تصمیم بگیرید، نه با خواندن پیام: پیام برای انسان است و ممکن است عوض شود.

خطا در لایه‌های یک برنامه

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

error-guide-layers.salam
تابع بارگیری کاربر(شناسه: صحیح): رشته خطادار:
    اگر شناسه <= ۰:
        پرتاب خطا خطا.جدید(نوع خطا.آرگومان نامعتبر، "شناسه باید مثبت باشد")
    پایان
    اگر شناسه != ۷:
        پرتاب خطا خطا.جدید(نوع خطا.یافت نشد، "چنین کاربری نیست").با کد("user." + شناسه)
    پایان
    برگشت "لیلا"
پایان

تابع خوشامد(شناسه: صحیح): رشته خطادار:
    تلاش:
        برگشت "خوش برگشتی، " + بارگیری کاربر(شناسه)
    گرفتن خطا خ:
        پرتاب خطا خ.بپیچ("ساختن پیام خوشامد ممکن نشد")
    پایان
پایان

تابع وضعیت برای(خ: خطا): صحیح:
    اگر خ.است(نوع خطا.یافت نشد):
        برگشت ۴۰۴
    وگرنه خ.است(نوع خطا.آرگومان نامعتبر):
        برگشت ۴۰۰
    پایان
    برگشت ۵۰۰
پایان

تابع ریشه:
    هر شناسه در [7، 3، -1]:
        تلاش:
            سرچاپ ۲۰۰، خوشامد(شناسه)
        گرفتن خطا خ:
            سرچاپ وضعیت برای(خ)، خ.به رشته()
            اگر خ.کد != "":
                سرچاپ "    کد:"، خ.کد
            پایان
        پایان
    پایان
پایان
خروجی200 خوش برگشتی، لیلا 404 ساختن پیام خوشامد ممکن نشد: چنین کاربری نیست کد: user.3 400 ساختن پیام خوشامد ممکن نشد: شناسه باید مثبت باشد

پیچیدن نوع خطای اصلی را نگه می‌دارد، پس لایه‌ی بالا هنوز می‌بیند که علت اصلی «یافت نشد» بوده و پاسخ ۴۰۴ می‌دهد. کد جزئیاتی را می‌برد، این‌جا شناسه‌ی گم‌شده، که کد بدون تجزیه‌ی متن می‌خواندش.

حلقه‌ی تلاش دوباره

باید تکرار شود کل پرسش را با یک فراخوانی پاسخ می‌دهد: آیا خطا از نوعی است که ممکن است خودبه‌خود برطرف شود (ناموجود، اتمام زمان یا ورودی خروجی)، و آیا هنوز تلاشی مانده است؟ تاخیر برای دفعه مدت صبر پیش از تلاش بعدی را می‌دهد که هر بار دو برابر می‌شود تا به سقف برسد. وقتی تلاش‌ها تمام شوند، آخرین خطا پیچیده و برای فراخوان پرتاب می‌شود.

error-guide-retry.salam
واردسازی خطاها
واردسازی همگام سازی

ناپایا شمار := ۰

تابع قیمت بگیر(): صحیح خطادار:
    شمار++
    اگر شمار < ۳:
        پرتاب خطا خطا.جدید(نوع خطا.ناموجود، "سرویس قیمت شلوغ است")
    پایان
    برگشت ۴۲۰۰
پایان

تابع قیمت پایدار(): صحیح خطادار:
    ناپایا س := خطاها.سیاست تکرار جدید(۵، ۱۰، ۸۰)
    ناپایا دفعه := ۱
    تا درست:
        تلاش:
            برگشت قیمت بگیر()
        گرفتن خطا خ:
            اگر وارونه خطاها.باید تکرار شود(س، خ، دفعه):
                پرتاب خطا خ.بپیچ("پس از " + دفعه + " کوشش رها شد")
            پایان
            صبر := خطاها.تاخیر برای کوشش(س، دفعه)
            سرچاپ "کوشش"، دفعه، "ناموفق بود:"، خ.پیام، "| صبر"، صبر، "میلی‌ثانیه"
            همگام سازی.خواب میلی ثانیه(صبر)
        پایان
        دفعه++
    پایان
پایان

تابع ریشه:
    تلاش:
        سرچاپ "قیمت:"، قیمت پایدار()
    گرفتن خطا خ:
        سرچاپ خ.به رشته()
    پایان
    بد := خطا.جدید(نوع خطا.آرگومان نامعتبر، "کالای ناشناخته")
    ناپایا س := خطاها.سیاست تکرار جدید(۵، ۱۰، ۸۰)
    سرچاپ "درخواست بد دوباره امتحان شود؟"، خطاها.باید تکرار شود(س، بد، ۱)
پایان
خروجیکوشش 1 ناموفق بود: سرویس قیمت شلوغ است | صبر 10 میلی‌ثانیه کوشش 2 ناموفق بود: سرویس قیمت شلوغ است | صبر 20 میلی‌ثانیه قیمت: 4200 درخواست بد دوباره امتحان شود؟ false

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

همه‌ی مشکل‌ها را یک‌جا جمع کنید

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

error-guide-validate.salam
ساختار ثبت‌نام:
    همگانی رایانامه: رشته = ""
    همگانی سن: صحیح = ۰
    همگانی گذرواژه: رشته = ""
پایان

تابع بررسی(ث: ثبت‌نام): وکتور<خطا>:
    ناپایا مشکل‌ها := وکتور {} برگردان وکتور<خطا>
    اگر وارونه ث.رایانامه.دربردارد("@"):
        مشکل‌ها.بیفزا(خطا.جدید(نوع خطا.آرگومان نامعتبر، "رایانامه @ ندارد").با مسیر("رایانامه"))
    پایان
    اگر ث.سن < ۱۳:
        مشکل‌ها.بیفزا(خطا.جدید(نوع خطا.خارج از بازه، "دست‌کم باید ۱۳ سال داشته باشید").با مسیر("سن"))
    پایان
    اگر ث.گذرواژه.طول() < ۸:
        مشکل‌ها.بیفزا(خطا.جدید(نوع خطا.آرگومان نامعتبر، "گذرواژه خیلی کوتاه است").با مسیر("گذرواژه"))
    پایان
    برگشت مشکل‌ها
پایان

تابع ثبت(ث: ثبت‌نام): رشته خطادار:
    مشکل‌ها := بررسی(ث)
    اگر مشکل‌ها.طول() > ۰:
        پرتاب خطا خطا.جدید(نوع خطا.آرگومان نامعتبر، مشکل‌ها.طول() + " فیلد باید درست شود")
    پایان
    برگشت "خوش آمدی، " + ث.رایانامه
پایان

تابع ریشه:
    فرم := ثبت‌نام { رایانامه = "sara.example.com"، سن = ۱۱، گذرواژه = "abc" }
    مشکل‌ها := بررسی(فرم)
    سرچاپ مشکل‌ها.طول()، "مشکل:"
    هر م در مشکل‌ها:
        سرچاپ "  " + م.مسیر + ":"، م.پیام
    پایان
    تلاش:
        سرچاپ ثبت(فرم)
    گرفتن خطا خ:
        سرچاپ "ثبت نشد:"، خ.پیام
    پایان
    تلاش:
        سرچاپ ثبت(ثبت‌نام { رایانامه = "sara@example.com"، سن = ۳۰، گذرواژه = "به اندازه‌ی کافی بلند" })
    گرفتن خطا خ:
        سرچاپ "ثبت نشد:"، خ.پیام
    پایان
پایان
خروجی3 مشکل: رایانامه: رایانامه @ ندارد سن: دست‌کم باید ۱۳ سال داشته باشید گذرواژه: گذرواژه خیلی کوتاه است ثبت نشد: 3 فیلد باید درست شود خوش آمدی، sara@example.com

انتخاب نوع خطا

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

پیام‌ها را کوتاه و بدون نقطه‌ی پایانی بنویسید، چون به رشته زمینه و پیام را با «: » در یک جمله کنار هم می‌گذارد.

گونه‌ها

سیاست تکرار RetryPolicy

ساختار سیاست تکرار
سیاست تلاش دوباره.
نامانگلیسیگونهتوضیح
بیشترین کوششmax_attemptsصحیح = 3بیشترین تعداد تلاش؛ پیش‌فرض ۳.
تأخیر پایه میلی‌ثانیهbase_delay_msصحیح = 100تأخیر پس از نخستین تلاش ناموفق، بر حسب میلی‌ثانیه؛ پیش‌فرض ۱۰۰.
سقف تأخیر میلی‌ثانیهmax_delay_msصحیح = 5000سقف تأخیر، بر حسب میلی‌ثانیه؛ پیش‌فرض ۵۰۰۰.
error-RetryPolicy.salam
واردسازی خطاها

تابع ریشه:
    ناپایا س := خطاها.سیاست تکرار جدید(۴، ۱۰۰، ۱۰۰۰)
    سرچاپ س.بیشترین کوشش، س.تأخیر پایه میلی‌ثانیه، س.سقف تأخیر میلی‌ثانیه
    خ := خطا.جدید(نوع خطا.اتمام زمان، "سرور پاسخ نداد")
    سرچاپ خطاها.نام نوع(خ.نوع)، خطاها.قابل تکرار است(خ)
    ناپایا دفعه := ۱
    تا خطاها.باید تکرار شود(س، خ، دفعه):
        سرچاپ "کوشش"، دفعه، "پس از"، خطاها.تاخیر برای کوشش(س، دفعه)، "میلی‌ثانیه"
        دفعه++
    پایان
    سرچاپ خطاها.باید تکرار شود(س، خطا.جدید(نوع خطا.آرگومان نامعتبر، "ورودی بد")، ۱)
پایان
خروجی4 100 1000 timed out true کوشش 1 پس از 100 میلی‌ثانیه کوشش 2 پس از 200 میلی‌ثانیه کوشش 3 پس از 400 میلی‌ثانیه false

تابع‌ها

نام نوع KindName

تابع نام نوع(kind: ErrorKind): رشته
نام کوتاه انگلیسی یک نوع، مثل "not found"؛ وقتی پیام خالی باشد به رشته از آن استفاده می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: error-RetryPolicy.salam

قابل تکرار است IsRetryable

تابع قابل تکرار است(e: Error): منطقی
درست است اگر خطا گذرا و ارزش تلاش دوباره را داشته باشد: اتمام زمان، سرویس ناموجود یا خطای خواندن و نوشتن.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: error-RetryPolicy.salam

سیاست تکرار جدید NewRetryPolicy

تابع سیاست تکرار جدید(max_attempts: صحیح، base_delay_ms: صحیح، max_delay_ms: صحیح): سیاست تکرار
سیاستی با بیشترین تعداد تلاش و تأخیر پایه و بیشینه می‌سازد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: error-RetryPolicy.salam

تاخیر برای کوشش DelayForAttempt

تابع تاخیر برای کوشش(p &: سیاست تکرار، attempt: صحیح): صحیح
چند میلی‌ثانیه پس از شکست تلاش شماره‌ی attempt باید صبر کرد: پس از نخستین، تأخیر پایه، سپس هر بار دو برابر تا سقف. خودش صبر نمی‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: error-RetryPolicy.salam

باید تکرار شود ShouldRetry

تابع باید تکرار شود(p &: سیاست تکرار، e: Error، attempt: صحیح): منطقی
درست است اگر خطا قابل تکرار باشد و attempt هنوز کمتر از max_attempts باشد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: error-RetryPolicy.salam