پرش به محتویات

۳. خطاها

EXCEPTION_HANDLER مال کتابخانه است، پس هر خطایی در همان قالب جواب داده می‌شود، با success: false و یک error_code که کلاینت بر اساسش تصمیم می‌گیرد.

ورودی‌ای که اشتباه است

curl -X POST -H 'Content-Type: application/json' -d '{"quantity": 0}' \
     http://127.0.0.1:8000/api/orders/
{"success": false, "status_code": 400, "error_code": "validation_error",
 "message": "This field is required.",
 "data": {"fields": {
   "product": [{"code": "required", "message": "This field is required."}],
   "quantity": [{"code": "min_value", "message": "Ensure this value is greater than or equal to 1."}]}}}

اولین مشکل در message، برای صفحه‌ای که یک جمله نشان می‌دهد؛ همه‌ی مشکل‌ها در data.fields، برای فرمی که زیر هر فیلد خطا می‌گذارد - هر کدام با یک code، تا کلاینت «خالی» را از «خیلی کوچک» تشخیص بدهد بدون اینکه متن ترجمه‌شده را بخواند. فیلد تودرتو یک مسیر تخت است: items.0.quantity.

خطاهای خود فروشگاه

example/shop/errors.py
class OutOfStockError(DomainError):
    status_code = status.HTTP_409_CONFLICT
    default_code = 'out_of_stock'
    default_detail = _('There is not enough of this product in stock.')


class StillOrderedError(DomainError):
    status_code = status.HTTP_409_CONFLICT
    default_code = 'still_ordered'
    default_detail = _('This product has orders, and cannot be deleted.')

یک سرویس آن‌ها را raise می‌کند، با چیزی که کلاینت بر اساسش کاری می‌کند در data:

example/shop/services.py
def place_order(product: Product, quantity: int) -> Order:
    """An order, taken from the stock - or OutOfStockError, saying how many there are."""
    with transaction.atomic():
        locked = Product.objects.select_for_update().get(pk=product.pk)

        if locked.stock < quantity:
            raise OutOfStockError(data={'available': locked.stock})

        Product.objects.filter(pk=locked.pk).update(stock=F('stock') - quantity)
        return Order.objects.create(product=locked, quantity=quantity)
curl -X POST -H 'Content-Type: application/json' -d '{"product": 3, "quantity": 1}' \
     http://127.0.0.1:8000/api/orders/
{"success": false, "status_code": 409, "message": "There is not enough of this product in stock.",
 "data": {"available": 0}, "error_code": "out_of_stock"}

خطایی که پیش از کتابخانه نوشته شده

خطاهای پروژه از پیش از کتابخانه - APIException خود DRF، بدون data - بدون تغییر در قالب جواب می‌دهند:

example/shop/errors.py
class PaymentRequiredError(APIException):
    status_code = status.HTTP_402_PAYMENT_REQUIRED
    default_code = 'payment_required'
    default_detail = _('This order is not paid yet.')
{"success": false, "status_code": 402, "message": "This order is not paid yet.",
 "data": {}, "error_code": "payment_required"}

یک باگ

هر چیزی که کسی طراحی‌اش نکرده با یک 500 عمومی جواب داده می‌شود. متنش - که ممکن است یک کوئری، مسیر یک فایل یا اسم یک نفر را داشته باشد - هرگز از سرور بیرون نمی‌رود. با traceback لاگ می‌شود و به REPORTERی داده می‌شود که تنظیمات نام می‌برد:

example/config/settings.py
# drf-parcel: the library's own setting. Every key is optional.
DRF_PARCEL = {
    'PAGE_SIZE': 10,
    'MAX_PAGE_SIZE': 50,
    # Two orders at once for the last of a name: a 409, not a 500.
    'HANDLE_INTEGRITY_ERRORS': True,
    # Where a bug is reported - Sentry, in a real project.
    'REPORTER': 'shop.reporting.report',
}
{"success": false, "status_code": 500, "message": "Something went wrong. Please try again.",
 "data": {}, "error_code": "internal_error"}

در DEBUG به جای جواب، خطا بالا می‌رود تا صفحه‌ی خطای Django آن را نشان بدهد.

همه‌ی کدهایی که کتابخانه می‌فرستد در مرجع آمده‌اند.

قدم بعد

۴. اسکیما و زبان‌ها