قرارداد¶
وضعیت: تصمیم گرفته شده. هر شکلی که از سرور بیرون میرود، هر کد خطا، و هر تنظیم. کد از این سند پیروی میکند؛ هر تغییری در آنچه به کلاینت میرسد، اول اینجا تغییر میکند. سؤالهایی که بر اساسشان تصمیم گرفته شد، و تصمیم هر کدام، در انتها آمدهاند.
English:
contract.md.
پیامهای نمونهی زیر به انگلیسی نوشته شدهاند؛ در عمل هر پیام به زبان
درخواست (Accept-Language) گفته میشود.
۱. قالب پاسخ¶
همهی پاسخها - موفق و ناموفق - یک سطح بالای یکسان دارند، تا کلاینت فقط یک شکل را بخواند و هیچ پاسخی را جداگانه مدیریت نکند.
| کلید | نوع | کِی هست | معنی |
|---|---|---|---|
success |
بولی | همیشه | آیا درخواست کاری را که خواسته بود انجام داد |
status_code |
عدد | همیشه | کد HTTP، تکرار شده در بدنه |
message |
متن | همیشه | یک جمله برای انسان، به زبان درخواست |
data |
شیء یا آرایه | همیشه | جواب: یک شیء، یک لیست، یا {} |
pagination |
شیء | فقط در لیست صفحهبندیشده | چطور صفحهی بعد را بخواهیم |
error_code |
متن | فقط در خطا | چیزی که کد کلاینت بر اساسش تصمیم میگیرد |
قانونها:
- یک کلید یا همیشه هست، یا به دلیلی هست.
paginationروی لیستی که صفحهبندی ندارد قولی توخالی است؛error_codeروی پاسخ موفق کدی برای هیچ چیز. هیچکدام هرگز خالی فرستاده نمیشوند. dataهیچوقتnullنیست. چیزی برای گفتن نبودن یعنی{}.messageبرای انسان است،error_codeبرای کد. پیام ترجمه میشود و عوض خواهد شد؛ کلاینتی که آن را مقایسه کند، روزی که جملهای بازنویسی شود خراب میشود.status_codeهمیشه با کد HTTP همان پاسخ برابر است.
پیامی که پاسخ موفق میگوید¶
وقتی کسی پیامی ننوشته، از روی خود درخواست تعیین میشود - پس ViewSet،
APIView ساده و @action سفارشی همه چیز معقولی میگویند، و هیچکدام لازم
نیست چیزی یادشان بماند:
| درخواست | پیام | کلیدش در MESSAGES |
|---|---|---|
پاسخ 201 |
«Created.» - ساخته شد. | created |
PUT یا PATCH |
«Saved.» - ذخیره شد. | saved |
DELETE |
«Deleted.» - حذف شد. | deleted |
| هر چیز دیگر | «Done.» - انجام شد. | done |
کلاینت بیشتر پیام نوشتن را نشان میدهد - یک toast که میگوید «ذخیره شد» - و بهندرت پیام خواندن را. هر کدام در سه سطح عوض میشود، و نزدیکترین برنده است:
return success_response(data=order, message=_('The order was paid.')) # one answer
class ProductViewSet(EnvelopeMixin, ModelViewSet): # one view
envelope_messages = {'create': _('The product was added.')}
DRF_PARCEL = {'MESSAGES': {'created': _('Saved successfully.')}} # the project
یک شیء¶
ساخته شد¶
{
"success": true,
"status_code": 201,
"message": "Created.",
"data": {"id": 8, "name": "Necklace"}
}
حذف شد¶
پاسخ 204 No Content طبق تعریف بدنه ندارد، پس قالب دور ریخته میشد. حذف
به جای آن 200 همراه با قالب برمیگرداند - و همینطور هر 204ی که
کتابخانه جواب میدهد، چه 204 بدون قالب یک view و چه
success_response(status_code=204):
لیستی که صفحهبندی ندارد¶
چیزهایی که هرگز قالببندی نمیشوند¶
- پاسخی که JSON نیست - فایل، PDF، استریم، ریدایرکت؛
- viewی که خودش بیرون میماند (
parcel_wrap = False)، برای webhook یا health check که فراخوانندهاش شکل خودش را انتظار دارد - صفحههایش هم، که همانcount،next،previousوresultsخود DRF هستند؛ - پاسخی که از قبل در قالب است -
success_responseیکی برمیگرداند، و دو بار قالببندی نمیشود؛ - پاسخ
205 Reset Content- به کلاینت میگوید فرمش را خالی کند، و طبق تعریف بدنه ندارد، پس همانطور که view داده میماند.success_response(status_code=205)رد میشود: بدنهای نیست که قالب در آن گذاشته شود.
پاسخ OPTIONS - توصیفی که DRF از view میدهد - مثل هر پاسخ موفق دیگری است، و
در قالب است.
۲. صفحهبندی¶
دو نوع، و هر view خودش انتخاب میکند - در یکی لیست شمارهدار، در دیگری
فید بیپایان. pagination.type میگوید کدام است، تا یک کامپوننت در کلاینت
هر دو را بدون حدس زدن بخواند.
با شمارهی صفحه¶
GET /products/?page=2&page_size=20
{
"success": true,
"status_code": 200,
"message": "Done.",
"data": [{"id": 21}, {"id": 22}],
"pagination": {
"type": "page",
"count": 45,
"page": 2,
"pages": 3,
"page_size": 20,
"has_next": true,
"has_previous": true
}
}
| کلید | معنی |
|---|---|
count |
تعداد ردیفهای کل لیست |
page |
این صفحه، از ۱ |
pages |
تعداد صفحهها |
page_size |
اندازهای که واقعاً اعمال شد - بعد از سقف، بخش ۲.۳ |
has_next، has_previous |
آیا صفحهی بعد و قبل وجود دارد |
لینک next و previous نداریم: کلاینت روی دامنهی دیگری است و ?page=3
را خودش میسازد، و سرور پشت پروکسی لینکها را با پروتکل یا دامنهی اشتباه
میسازد.
صفحهای بعد از آخرین صفحه 404 (not_found) است، همانطور که DRF میکند.
با cursor¶
GET /notifications/?cursor=cD0yMDI2LTExLTE0&page_size=20
{
"success": true,
"status_code": 200,
"message": "Done.",
"data": [{"id": 90}, {"id": 89}],
"pagination": {
"type": "cursor",
"next_cursor": "cD0yMDI2LTExLTEz",
"previous_cursor": "cj0xJnA9MjAyNi0xMS0xNA",
"page_size": 20,
"has_next": true,
"has_previous": true
}
}
کلاینت همان چیزی را که گرفته پس میفرستد و هرگز خودش یکی نمیسازد. count
و page ندارد - نشمردن، روی جدولی که بزرگتر از آن است که در هر درخواست
شمرده شود، کل فایدهی cursor است. has_next در هر دو نوع هست، پس دکمهی
«بیشتر» با هر دو کار میکند.
cursor امضا شده است، با SECRET_KEY پروژه، و ترتیبی را که برایش ساخته
شده با خودش دارد. cursorی که دستی عوض شده، cursorی که برای ترتیب دیگری ساخته
شده - لیستی که با ?ordering= دوباره مرتب شده - یا cursorی که با کلید دیگری
امضا شده، پیش از اینکه از دیتابیس چیزی پرسیده شود رد میشود: 400
(invalid_cursor). cursorی هم که سرور اصلاً نتواند بخواند همینطور. عوض کردن
کلید با SECRET_KEY_FALLBACKS خود Django، cursorهایی را که داده شدهاند نگه
میدارد.
cursor امضا شده است، نه محرمانه. میشود آن را رمزگشایی کرد، و مقدار ستونی را که فید بر اساسش مرتب شده، برای ردیفی که صفحه با آن تمام میشود، در خود دارد. فید را فقط بر اساس مقداری مرتب کنید که خوانندههایش اجازهی دیدنش را دارند - زمان ساخت، یک id.
۲.۳ انتخاب تعداد هر صفحه توسط کلاینت¶
بهطور پیشفرض خاموش. وقتی view اجازه بدهد، کلاینت ?page_size= میفرستد،
و سرور همیشه سقف اعمال میکند - بدون سقف، ?page_size=1000000 یعنی
خواندن کل جدول، که برای هر کسی باز است.
| کلاینت میفرستد | سرور اعمال میکند |
|---|---|
| هیچ | page_size خود view |
24، زیر سقف |
۲۴ |
500، بالای سقف |
سقف - بدون خطا: صفحهبندی جای سختگیری نیست |
0، -3، abc |
page_size خود view |
| هر چیزی، وقتی view اجازه نمیدهد | page_size خود view؛ پارامتر نادیده گرفته میشود و در اسکیما نیست |
pagination.page_size همیشه اندازهی اعمالشده را میگوید، پس کلاینتی که
۵۰۰ خواسته میبیند که ۱۰۰ گرفته.
۳. خطاها¶
همان قالب، با success: false و یک error_code.
{
"success": false,
"status_code": 409,
"error_code": "province_in_use",
"message": "This province has branches and cannot be deleted.",
"data": {"branches": 3}
}
data چیزی را دارد که کلاینت میتواند بر اساسش کاری بکند - کدام رکورد سر
راه است، چقدر باید صبر کند. وقتی چیزی نیست {} است.
۳.۱ اعتبارسنجی¶
اولین مشکل در message، همهی مشکلها در data.fields:
{
"success": false,
"status_code": 400,
"error_code": "validation_error",
"message": "Enter a valid phone number.",
"data": {
"fields": {
"phone": [{"code": "invalid", "message": "Enter a valid phone number."}],
"items.0.quantity": [{"code": "min_value", "message": "Ensure this value is greater than or equal to 1."}],
"non_field_errors": [{"code": "invalid", "message": "The dates are the wrong way round."}]
}
}
}
- صفحهای که یک جمله نشان میدهد
messageرا میخواند؛ فرمی که زیر هر فیلد خطا میگذاردfieldsرا - و کلاینتی که برای شکل قدیمی (فقط یک پیام) نوشته شده همچنان کار میکند. - هر مشکل
codeخودش را دارد (required،max_length،unique،invalidو ...) تا کلاینت «خالی» را از «تکراری» تشخیص بدهد بدون اینکه متن ترجمهشده را بخواند. - فیلد تودرتو یک مسیر تخت است که با
.به هم وصل میشود:items.0.quantityیعنی تعداد اولین آیتم. - خطاهایی که مال هیچ فیلدی نیستند زیر کلید خود DRF هستند،
non_field_errors(تنظیمNON_FIELD_ERRORS_KEYآن). ValidationErrorخود Django -clean()یک مدل، یک سرویس - دقیقاً به همین شکل برمیگردد.
۳.۲ کدهای خطای استاندارد¶
| وضعیت | error_code |
از کجا | data |
|---|---|---|---|
| 400 | validation_error |
serializer، یا ValidationError خود Django |
fields |
| 400 | parse_error |
بدنهای که JSON معتبر نیست | {} |
| 400 | invalid_cursor |
cursorی که سرور نمیتواند بخواند | {} |
| 401 | not_authenticated |
اطلاعات ورود فرستاده نشده - و 403، همانطور که DRF جواب میدهد، وقتی اولین کلاس احراز هویت view هدر WWW-Authenticate نمیفرستد (احراز هویت با session) |
{} |
| 401 | authentication_failed |
اطلاعات ورود اشتباه یا منقضی | {} |
| 403 | permission_denied |
PermissionDenied در DRF یا Django - با جملهای که با آن raise شده، اگر داشته باشد |
{} |
| 404 | not_found |
NotFound، یا Http404 خود Django |
{} |
| 405 | method_not_allowed |
متدی که view ندارد | {} |
| 406 | not_acceptable |
Acceptی که کسی جوابش را ندارد |
{} |
| 409 | already_exists |
IntegrityError از نوع unique، وقتی روشن باشد (۳.۵) |
{} |
| 409 | conflict |
IntegrityError از نوع foreign key، وقتی روشن باشد (۳.۵) |
{} |
| 415 | unsupported_media_type |
نوع بدنهای که view نمیخواند | {} |
| 429 | rate_limited |
محدودیت تعداد درخواست | retry_after، به ثانیه |
| 500 | internal_error |
هر چیزی که کسی طراحیاش نکرده | {} |
| 503 | service_unavailable |
ServiceUnavailableError |
{} |
اسم هر کد در تنظیمات (ERROR_CODES) قابل تغییر است، برای پروژهای که
کلاینتهایش از قبل بر اساس کلمههای دیگری تصمیم میگیرند.
هدرها حفظ میشوند. DRF روی 429 هدر Retry-After، روی 405 هدر Allow
و روی 401 هدر WWW-Authenticate میگذارد؛ همه روی پاسخ میمانند.
۳.۳ خطاهای خود پروژه¶
from drf_parcel.exceptions import DomainError
class ProvinceInUse(DomainError):
status_code = 409
default_code = 'province_in_use'
default_detail = _('This province has branches and cannot be deleted.')
raise ProvinceInUse(data={'branches': 3})
raise ProvinceInUse(_('Move its 3 branches first.'), data={'branches': 3})
DomainError همان APIException خود DRF است، با یک چیز اضافه: data.
اسمهایش اسمهای خود DRF هستند - status_code، default_code (که بهعنوان
error_code فرستاده میشود)، default_detail (که بهعنوان message
فرستاده میشود) - پس چیز تازهای برای یاد گرفتن نیست، و یک نوع خطا داریم، نه
دو نوع.
class DomainError(APIException):
status_code = 400
default_code = 'error'
default_detail = _('The request could not be completed.')
def __init__(self, detail=None, code=None, *, data=None):
super().__init__(detail, code)
self.data = data or {}
- بدون handler این کتابخانه هم کار میکند. پروژهای که mixin را نصب
کرده و handler خود DRF را نگه داشته، باز هم کد وضعیت درست،
set_rollbackو یک جواب معقول میگیرد - نه 500. - یک exception معمولی هم هست. سرویس آن را raise میکند، و تسک Celery یا management command آن را مثل هر exception دیگری catch میکند.
- rollback کار handler است، نه کار کلاس. handler خود DRF تابع
set_rollbackرا صدا میزند؛ این کتابخانه آن handler را جایگزین میکند، پس handler خودش آن را صدا میزند، در همهی مسیرها (۳.۶). - پیام همان لحظهی raise شدن به متن تبدیل میشود، همانطور که DRF میکند - داخل یک درخواست، به زبان همان درخواست. خطایی که بیرون از درخواست raise شود به زبان پیشفرض است.
کتابخانه خطاهای رایج را همراه خودش دارد - InvalidInputError،
InvalidCursorError، AuthenticationFailedError، PermissionDeniedError، NotFoundError،
ConflictError، RateLimitedError، ServiceUnavailableError.
خطاهای فعلی پروژه همچنان کار میکنند. هر زیرکلاس APIException در DRF،
چه از DomainError باشد چه نه، بدون هیچ تغییری در قالب جواب میدهد:
status_code خودش، default_code خودش بهعنوان error_code، detail خودش
بهعنوان message، و data اگر داشته باشد.
۳.۴ چیزی که هرگز گفته نمیشود¶
خطای پیشبینینشده با 500 و یک جملهی عمومی جواب داده میشود. متن آن هرگز از سرور بیرون نمیرود - ممکن است یک کوئری، مسیر یک فایل یا اسم یک نفر در آن باشد. یک 404 یا یک شمارهی تلفن اشتباه اصلاً بهعنوان error لاگ نمیشود.
هر 5xxی که جواب داده میشود بهعنوان error لاگ و گزارش میشود - خطای
پیشبینینشده، و خطای طراحیشده هم: APIExceptionی که با وضعیت 500 یا
بالاتر raise شده، ServiceUnavailableError. یک 5xx طراحیشده پیامی را میگوید
که با آن raise شده، پس آن پیام هرگز نباید متن یک exception باشد.
- با
DEBUG = Trueبه جای جواب، خطا بالا میرود تا صفحهی خطای Django traceback را نشان بدهد (RAISE_UNHANDLED_IN_DEBUG). REPORTERتابعی است که با هر 5xx صدا زده میشود - برای Sentry یا هر ابزار مشابه.
۳.۵ یکپارچگی دیتابیس¶
بهطور پیشفرض خاموش. قیدی که دیتابیس رد میکند معمولاً زودتر، در serializer
یا سرویس، گرفته شده است؛ این یک تور ایمنی است که با HANDLE_INTEGRITY_ERRORS
روشن میشود.
نوع قید از کدی خوانده میشود که درایور دیتابیس گزارش میدهد - هرگز از متن خطا، که با دیتابیس، نسخه و زبانش عوض میشود:
| قید | PostgreSQL sqlstate |
SQLite sqlite_errorcode |
MySQL errno |
|---|---|---|---|
| unique | 23505 |
2067، 1555 |
1062 |
| foreign key | 23503 |
787 |
1451، 1452 |
| not null | 23502 |
1299 |
1048 |
| check | 23514 |
275 |
3819 |
| قید | جواب | چرا |
|---|---|---|
| unique | 409 already_exists |
دو درخواست همزمان: ورودی درست بود، و بین بررسی و نوشتن، ردیف گرفته شد |
| foreign key | 409 conflict |
ردیفی که به آن اشاره شده در همین فاصله حذف یا عوض شده |
| not null | 500 internal_error |
قانونی که serializer باید میگفت جا افتاده - باگ است، و کاربر نمیتواند درستش کند |
| check | 500 internal_error |
همان |
| کدی که شناخته نیست | 500 internal_error |
ناشناخته یعنی رد |
500 اینجا مثل هر 500 دیگری است (۳.۴): با traceback لاگ میشود، گزارش میشود،
و در DEBUG بالا میرود - باگی پیدا شده است. پیام همیشه یک جملهی عمومی و
ترجمهشده است: نه متن دیتابیس، نه اسم قید و نه اسم ستون از سرور بیرون
نمیرود. اینکه کدام فیلد تکراری است را serializer باید بگوید.
۳.۶ تراکنش¶
هر خطایی که جواب داده میشود، تراکنش درخواست را برای rollback علامت میزند
(set_rollback)، تا پروژهای که ATOMIC_REQUESTS دارد هرگز نیمی از یک
نوشتن را پشت یک خطا نگه ندارد.
۳.۷ بیرون از DRF¶
کتابخانه به پاسخی که DRF میدهد شکل میدهد، و نه به چیز دیگری. درخواستی که
هیچوقت به یک view در DRF نمیرسد - آدرسی که با هیچ URLی جور نیست، خطایی در
یک middleware پیش از view - را Django جواب میدهد، با handler404 و
handler500 خود پروژه، و بیرون از این کتابخانه است.
این عمدی است: آن handlerها مال کل پروژهاند - پنل ادمین و صفحههای وب هم - نه مال API، و کتابخانهای برای DRF به آنها دست نمیزند.
۴. استفاده¶
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'drf_parcel.handlers.exception_handler',
'DEFAULT_PAGINATION_CLASS': 'drf_parcel.pagination.PageNumberPagination',
'DEFAULT_SCHEMA_CLASS': 'drf_parcel.schema.ParcelAutoSchema', # the schema extra
}
هر خط مستقل است: handler بهتنهایی فقط قالب خطا را میدهد و نه چیز دیگری.
from drf_parcel.pagination import CursorPagination
from drf_parcel.responses import EnvelopeMixin, success_response
class ProductViewSet(EnvelopeMixin, ModelViewSet):
page_size = 12
client_page_size = True
max_page_size = 48
envelope_messages = {'create': _('The product was added.')}
class NotificationViewSet(EnvelopeMixin, ModelViewSet):
pagination_class = CursorPagination
ordering = '-created_at'
class TotalsView(EnvelopeMixin, APIView):
def get(self, request):
return success_response(data={'total': 12}, message=_('Totals.'))
EnvelopeMixin پاسخ را یک بار، در finalize_response، قالببندی میکند،
پس هیچ اکشنی - list، create، یک @action سفارشی - لازم نیست یادش بماند.
۵. تنظیمات¶
یک دیکشنری. کلیدی که کتابخانه نمیشناسد هنگام start رد میشود، نه نادیده
گرفته - PAGE_SZIE اشتباهی که بیصدا نادیده گرفته شود، اندازهی صفحهای
است که هیچوقت عوض نمیشود و کسی نمیفهمد چرا.
DRF_PARCEL = {
'PAGE_SIZE': 20,
'MAX_PAGE_SIZE': 100,
'CLIENT_PAGE_SIZE': False,
'PAGE_SIZE_QUERY_PARAM': 'page_size',
'FIELD_ERRORS': 'detailed',
'FIELD_PATH_SEPARATOR': '.',
'ERROR_CODES': {},
'HANDLE_INTEGRITY_ERRORS': False,
'RAISE_UNHANDLED_IN_DEBUG': True,
'REPORTER': None,
'MESSAGES': {},
}
| کلید | پیشفرض | چه چیزی را تعیین میکند |
|---|---|---|
PAGE_SIZE |
20 |
اندازهی صفحه وقتی view چیزی نگفته. اگر نوشته نشده باشد، REST_FRAMEWORK['PAGE_SIZE'] خود DRF خوانده میشود اگر تنظیم شده باشد - پروژهای که آن را آنجا گذاشته اندازهاش را نگه میدارد - و فقط بعد از آن 20 |
MAX_PAGE_SIZE |
100 |
سقف اندازهای که کلاینت انتخاب میکند |
CLIENT_PAGE_SIZE |
False |
آیا کلاینت میتواند اندازه را انتخاب کند |
PAGE_SIZE_QUERY_PARAM |
'page_size' |
اسم پارامتری که با آن انتخاب میکند |
FIELD_ERRORS |
'detailed' |
'detailed': برای هر مشکل {code, message}؛ 'messages': فقط متن، شکل خود DRF |
FIELD_PATH_SEPARATOR |
'.' |
مسیر فیلد تودرتو با چه چیزی وصل شود |
ERROR_CODES |
{} |
تغییر اسم یک کد استاندارد: {'validation_error': 'validation_failed'} |
HANDLE_INTEGRITY_ERRORS |
False |
بخش ۳.۵ |
RAISE_UNHANDLED_IN_DEBUG |
True |
بخش ۳.۴ |
REPORTER |
None |
مسیر تابعی که با هر 500 صدا زده میشود |
MESSAGES |
{} |
عوض کردن پیام پیشفرض موفقیت، با کلیدش: created، saved، deleted، done (۱) |
هر view تنظیمات صفحهبندی را با attributeهایی به همان اسم و با حروف کوچک
عوض میکند: page_size، max_page_size، client_page_size.
هنگام start بررسی میشود: MAX_PAGE_SIZE کمتر از PAGE_SIZE، REPORTERی
که import نمیشود، کدی در ERROR_CODES که کتابخانه ندارد.
۶. اسکیما¶
با بخش اختیاری schema (pip install 'drf-parcel[schema]')، سند OpenAPI
ساختهشده همان چیزی را میگوید که واقعاً منتقل میشود:
- هر پاسخ 2xx یک view با
EnvelopeMixinداخل قالب -dataهمان serializer است، و حذف همان 200ی است که واقعاً جواب میدهد؛ - لیست صفحهبندیشده بهعنوان قالب خودش، با
paginationاز همان نوعی که view استفاده میکند، با اسمی که نوعش را میگوید -ItemPage،ItemCursorPage- تا هیچوقت باPaginatedItemListخود DRF اشتباه گرفته نشود؛ page_sizeفقط روی viewی مستند میشود که به کلاینت اجازهی انتخاب بدهد، با سقفش بهعنوان maximum؛- قالب خطا بهعنوان یک component مشترک،
ErrorEnvelope، که پاسخdefaultهمهی عملیاتهاست، وValidationErrorEnvelope، باdata.fields، که پاسخ 400 هر عملیاتی است که بدنه میگیرد - خطایی که خود view مستند کرده حفظ میشود. فقط تا وقتی کهEXCEPTION_HANDLERپروژه مال این کتابخانه است - یا handler خود پروژه که آن را صدا میزند و باfunctools.wraps(exception_handler)این را میگوید: در غیر این صورت خطاها شکل خود DRF را دارند، و اسکیما شکل دیگری را قول نمیدهد.
viewی که mixin ندارد همانطور که جواب میدهد مستند میشود - پاسخهای موفقش
بدون قالب، و صفحههایش در قالب، همانطور که paginatorها جواب میدهند. viewی که
دستی با success_response جواب میدهد در عمل در قالب است و در اسکیما نیست:
به آن mixin بدهید.
نصب با 'DEFAULT_SCHEMA_CLASS': 'drf_parcel.schema.ParcelAutoSchema'، یا با
افزودن ParcelSchemaMixin به AutoSchema خود پروژه.
فرانتی که تایپهایش را از اسکیما میسازد آن وقت response.data.id
مینویسد، که همان چیزی است که میرسد.
۷. ترجمه¶
هر پیامی که کتابخانه میگوید برای ترجمه علامت خورده و به زبان درخواست گفته میشود. کتابخانه فارسی را همراه خودش دارد؛ پروژه زبان دیگر را در کاتالوگ خودش اضافه میکند.
۸. تصمیمها¶
آنچه پیش از مرحلهی ۱ پرسیده شد، و تصمیم مالک پروژه.
- ~~یک کد برای خطای ورود یا دو کد؟~~ تصمیم: دو کد، همان کدهای خود
DRF -
not_authenticated(فرستاده نشده) وauthentication_failed(اشتباه یا منقضی). کلاینت روی دومی نشست را تمدید میکند و فقط روی اولی کاربر را به صفحهی ورود میبرد. - ~~
validation_failedیاvalidation_error؟~~ تصمیم:validation_error- همان چیزی که کلاینت سه پروژه از چهار پروژه همین الان میخواند، و کتابخانههای مشابه هم همین را میگویند. کد خود DRF،invalid، کد فیلدها هم هست، پس استفاده نمیشود. اسم کلاس کتابخانهInvalidInputErrorاست. - ~~
IntegrityError: 409 یا 400؟~~ تصمیم: بر اساس نوع قید، که از کد درایور خوانده میشود (۳.۵). - ~~پیام پیشفرض موفقیت؟~~ تصمیم: از روی خود درخواست - «Created.» روی
201، «Saved.» روی
PUTوPATCH، «Deleted.» رویDELETE، و «Done.» در بقیه - که برای یک پاسخ، یک view، یا کل پروژه باMESSAGESعوض میشود (۱). - ~~
handler404وhandler500: در اولین نسخه، یا بعداً؟~~ تصمیم: هیچکدام. چیزی که هیچوقت به DRF نمیرسد کار این کتابخانه نیست (۳.۷).
تصمیمهایی که بعد از 0.1.0، بر اساس یافتههای یک بررسی امنیتی، گرفته شد:
- cursor امضا میشود (۲): cursorی که دستکاری شده، یا برای ترتیب دیگری ساخته شده، پیش از اینکه از دیتابیس چیزی پرسیده شود رد میشود، پس یک باگ واقعی حین خواندن فید همچنان باگ میماند - لاگ و گزارش میشود. امضا، نه رمزگذاری: گفته شده که cursor قابل رمزگشایی است.
- هر 5xx لاگ و گزارش میشود، خطای طراحیشده هم (۳.۴).
- پاسخ 205 همانطور که view داده میماند (۱): بدنهای ندارد که در قالب برود.
OPTIONSدر قالب است (۱)، مثل هر پاسخ موفق دیگری.page_sizeخود view سقف ندارد: سقف روی چیزی است که کلاینت میخواهد، و تعداد خود view را برنامهنویسش تعیین میکند. کلید یکDictFieldکه جداکنندهی مسیر را در خود دارد، مسیر مبهمی درdata.fieldsمیسازد؛FIELD_PATH_SEPARATORجداکننده را عوض میکند.