بتل کد Battle Codeدارد باز می‌شود…

جلسه‌ی 3: کدهای وضعیت Status Codes

کد وضعیت در یک عدد می‌گوید کار چطور پیش رفت. خانواده‌ی 2xx یعنی «درست شد»، 4xx یعنی «مشتری اشتباه کرد» و 5xx یعنی «سرور خراب شد»؛ کدهای مهم 200، 201، 400، 401، 403، 404، 405 و 500. یاد می‌گیری با return "...", 404 یا abort(404, "...") کد را خودت انتخاب کنی، با r.ok جواب را بسنجی، و فرق GET (خواندن) و POST (فرستادن) را ببینی.

در این جلسه یاد می‌گیری

درس

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

یادت هست؟ در جلسه‌ی ۲ با @app.get("/...") مسیر ساختیم و دیدیم آدرسی که مسیر ندارد خودبه‌خود 404 می‌گیرد. آن 200 و 404 کد وضعیت بودند. امروز همه‌ی خانواده‌شان را می‌شناسی و یاد می‌گیری خودت انتخابشان کنی.

from server import app, ask

@app.get("/")
def home():
    return "Hi!"

ask("GET /")
ask("GET /nothing-here")

🚦 خانواده‌های کد وضعیت. رقم اول همه‌چیز را می‌گوید:
- 2xx همه‌چیز خوب است. 200 OK: «بفرما». 201 Created: «چیز تازه‌ای که خواستی ساخته شد».
- 4xx مشتری اشتباه کرده. 400 Bad Request: «درخواستت ناقص یا خراب است». 401 Unauthorized: «نمی‌دانم کی هستی؛ اول وارد شو». 403 Forbidden: «می‌دانم کی هستی، ولی اجازه نداری». 404 Not Found: «چنین چیزی ندارم». 405 Method Not Allowed: «این آدرس هست، ولی این کار را رویش نمی‌شود کرد».
- 5xx سرور خراب شده. 500 Internal Server Error: «تقصیر ما بود، کد سرور به مشکل خورد».
در رستوران: 400 یعنی سفارشت خوانا نیست، 404 یعنی این غذا در منو نیست، 500 یعنی آشپزخانه آتش گرفت!

from server import ask

ask("https://game.test/players/nima")
ask("https://game.test/players/kian")
ask("https://weather.test/today")

✋ کد را خودت انتخاب کن. تا حالا هر مسیری که متن برمی‌گرداند 200 می‌گرفت. اگر بعد از متن یک , و یک عدد بگذاری، آن عدد کد وضعیت می‌شود: return "Teachers only, sorry!", 403. اول بدنه، بعد کد. این‌طوری مشتری فقط از روی عدد هم می‌فهمد چه شد، حتی اگر متن را نخواند.

from server import app, ask

@app.get("/staff-room")
def staff_room():
    return "Teachers only, sorry!", 403

@app.get("/old-games")
def old_games():
    return "That page is gone", 404

ask("GET /staff-room")
ask("GET /old-games")

🛑 abort: همین‌جا بایست. abort(404, "no lunch menu yet") تابع را همان لحظه متوقف می‌کند؛ خط‌های بعدی اجرا نمی‌شوند. پاسخ کد 404 و بدنه‌ی {"error": "no lunch menu yet"} دارد، شکلی که برنامه‌ها راحت می‌خوانند. abort را باید مثل app از server وارد کنی. معمولاً داخل یک if می‌آید: «اگر چیزی درست نیست، بایست؛ وگرنه ادامه بده». در این مثال بعد از اولین درخواست، ناهار آماده می‌شود و درخواست دوم جواب دیگری می‌گیرد.

from server import app, ask, abort

lunch_ready = False

@app.get("/lunch")
def lunch():
    if not lunch_ready:
        abort(404, "no lunch menu yet")
    return "Today: rice and chicken"

ask("GET /lunch")
lunch_ready = True
ask("GET /lunch")

✅ r.ok برای مشتری. وقتی با quiet=True می‌پرسی، r.status عدد کد است، r.reason اسمش (مثل Not Found) و r.text بدنه به شکل متن. r.ok وقتی کد از خانواده‌ی 2xx باشد True است و وگرنه False. این‌طوری مشتری بدون حفظ کردن همه‌ی کدها می‌فهمد کار درست شد یا نه.

from server import app, ask

@app.get("/")
def home():
    return "Hi!"

r = ask("GET /", quiet=True)
print(r.status, r.reason, r.ok, r.text)
r = ask("GET /nothing", quiet=True)
print(r.status, r.reason, r.ok)

📮 GET می‌خواند، POST می‌فرستد. روش درخواست می‌گوید مشتری چه کاری می‌خواهد: GET یعنی «چیزی را به من نشان بده» و POST یعنی «این را از من بگیر و نگه دار» (مثل فرستادن یک امتیاز تازه). یک آدرس می‌تواند برای هر روش تابع خودش را داشته باشد: @app.get("/scores") و @app.post("/scores"). اگر روشی بیاید که برایش تابعی نیست، سرور 405 می‌دهد و می‌گوید چه روش‌هایی مجازند. فرستادن داده با POST را در فاز ۴ کامل یاد می‌گیری؛ فعلاً فقط روش را عوض می‌کنیم.

from server import app, ask

@app.get("/scores")
def read_scores():
    return "Best score: 2100"

@app.post("/scores")
def save_score():
    return "Score saved", 201

ask("GET /scores")
ask("POST /scores")
ask("DELETE /scores")

اشتباه‌های رایج:
- ترتیب برعکس: return 404, "Not here" خطا می‌دهد؛ اول بدنه، بعد کد: return "Not here", 404.
- کد داخل کوتیشن: return "Not here", "404" هم خطاست؛ کد یک عدد است.
- خطا با 200: return "error: no such player" به مشتری می‌گوید همه‌چیز خوب است (r.ok می‌شود True)؛ برای خطا کد خطا بفرست.
- کد بعد از abort: هر چه بعد از abort(...) بنویسی، اجرا نمی‌شود.
- 401 و 403 را قاطی نکن: 401 یعنی «اول بگو کی هستی»، 403 یعنی «تو را می‌شناسم ولی اجازه نداری».

مثال‌های این جلسه

چالش‌ها

  1. The Right Label (آسان)
  2. Sort the Codes (آسان)
  3. Teachers Only (متوسط)
  4. The Wrong Method (متوسط)
  5. Is the Quiz Ready? (سخت)
  6. The Guestbook (سخت)

بیشتر بخوان

← جلسه‌ی 2: اولین سرور تو جلسه‌ی 4: پروژه: سرور اطلاعات کلاس →