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

جلسه‌ی 12: پروژه: API آمار بازی و کلاینتش Project: Game Stats API and Its Client

پایان فاز سوم. JSON، طراحی API خوب و سمت مشتری را یک بار دیگر در یک نگاه می‌بینی، با یک یادآوری از فاز دوم (پارامتر در آدرس، پرسش در آدرس، 400 و 404). بعد پروژه: یک API آمار بازی برای کلاس که آمار هر بازیکن و جدول امتیاز هر بازی را می‌دهد، و یک کلاینت که با همین API جدول امتیاز قشنگی چاپ می‌کند.

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

درس

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

📌 جلسه‌ی ۹ در یک نگاه: JSON. وقتی route دیکشنری یا لیست برمی‌گرداند، سرور آن را به متن JSON تبدیل می‌کند. json.dumps(data) دیکشنری → متن، json.loads(text) متن → دیکشنری. در JSON: true/false، null، فقط کوتیشن دوتایی، و کلیدها همیشه متن‌اند ({1: ...} می‌شود {"1": ...}). JSON می‌تواند تودرتو باشد: r.json["teacher"]["name"]. r.text متن است و r.json دیکشنری یا لیست آماده.

📌 جلسه‌ی ۱۰ در یک نگاه: طراحی خوب. آدرس اسم جمع یک چیز است (/books، /books/3، /books/3/reviews) و کار را متد می‌گوید، نه آدرس (/getBooks نه). همه‌ی خطاها یک شکل دارند: {"error": "..."} با کد درست (abort(404, "...") یا return {"error": ...}, 400). فهرست‌ها در پاکت: {"count": n, "items": [...]}. app.show_routes() منوی API را چاپ می‌کند.

📌 جلسه‌ی ۱۱ در یک نگاه: سمت مشتری. مشتری (فرانت‌اند) درخواست را بی‌صدا می‌فرستد (r = ask(..., quiet=True))، اول r.status یا r.ok را نگاه می‌کند، بعد r.json را می‌خواند، روی لیستش حلقه می‌زند و یک گزارش قشنگ چاپ می‌کند. گاهی از جواب یک درخواست، آدرس درخواست بعدی را می‌سازد: f"https://game.test/players/{name}".

⚠️ اشتباه‌های رایج این بخش:
- data[1] روی JSONی که کلیدش "1" است (KeyError).
- true یا null در کد پایتون به‌جای True و None.
- خطا با 200 (return {"error": ...} بدون کد)، یا هر بار یک شکل خطای دیگر.
- فعل در آدرس (/getPlayers).
- جا انداختن quiet=True در مشتری.
- خواندن r.json["temp"] پیش از نگاه کردن به r.status.

🔁 از فاز دوم: مسیر و پارامتر. <name> یک تکه از آدرس را به شکل متن به تابع می‌دهد و <int:id> یک عدد کامل (برای abc خودش 404 می‌دهد). request.args.get("n", "3") پرسش آدرس (?n=5) را می‌خواند و جوابش همیشه متن است؛ int() با try/except ValueError و 400 برای ورودی خراب. چیزی که در لیست نیست: 404.

from server import app, ask, abort, request

words = {"api": "a menu of things a server can do", "json": "text that carries data"}

@app.get("/words/<word>")
def one_word(word):
    if word not in words:
        abort(404, f"no word {word}")
    return {"word": word, "meaning": words[word]}

@app.get("/top")
def top():
    try:
        n = int(request.args.get("n", "3"))
    except ValueError:
        abort(400, "n must be a whole number")
    return {"n": n}

ask("GET /words/json")
ask("GET /words/cat")
ask("GET /top?n=abc")

🎮 پروژه: API آمار بازی و کلاینتش. کلاس ما مسابقه‌ی Snake و Pong گذاشته و نتیجه‌ی هر بازی در لیست matches است (هر عضو: player، game، score). تو هم بک‌اند را می‌سازی و هم کلاینت را، در سه قدم:
1. GET /players/<name>: آمار یک بازیکن (چند بازی، بهترین، جمع)؛ 404 اگر بازی نکرده.
2. GET /leaderboard?game=Snake: بهترین امتیاز هر بازیکن در آن بازی، از بیشترین، در پاکت؛ 400 اگر game نیامده.
3. کلاینت: جدول امتیاز هر بازی و قهرمان Snake را چاپ می‌کند.
برای «بهترین امتیاز هر بازیکن» یک دیکشنری بساز: اگر اسم هنوز در آن نیست یا امتیاز تازه بیشتر است، عوضش کن. هر قدم روی کد قدم قبل ساخته می‌شود؛ دکمه‌ی «ادامه از کد مرحله‌ی قبلم» کدت را می‌آورد.

matches = [
    {"player": "Sara", "score": 30},
    {"player": "Reza", "score": 42},
    {"player": "Sara", "score": 55},
]

best = {}
for m in matches:
    name = m["player"]
    if name not in best or m["score"] > best[name]:
        best[name] = m["score"]

for name in best:
    print(name, best[name])
print("biggest:", max([30, 42, 55]), "sum:", sum([30, 42, 55]))

مرتب کردن با sorted. sorted(list) یک لیست تازه‌ی مرتب‌شده می‌دهد و reverse=True آن را از بزرگ به کوچک می‌کند. ولی وقتی عضوها دیکشنری‌اند، پایتون نمی‌داند با کدام کلید مقایسه کند. پس با key= یک تابع به آن می‌دهی که یک عضو را می‌گیرد و عددی را برمی‌گرداند که باید با آن مرتب شود. بعد از اسم تابع پرانتز نگذار (key=by_best، نه key=by_best()): خودِ تابع را می‌دهی و sorted برای هر عضو صدایش می‌زند.

rows = [
    {"player": "Ali", "best": 95},
    {"player": "Sara", "best": 150},
    {"player": "Mina", "best": 140},
]

def by_best(row):
    return row["best"]

board = sorted(rows, key=by_best, reverse=True)
for row in board:
    print(row["player"], row["best"])

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

چالش‌ها

  1. Back From JSON (آسان)
  2. Which Status Code? (آسان)
  3. A Client in Order (متوسط)
  4. Step 1: A Player's Stats (متوسط)
  5. Step 2: The Leaderboard (سخت)
  6. Step 3: The Leaderboard Client (سخت)

بیشتر بخوان

← جلسه‌ی 11: سمت مشتری: استفاده از API جلسه‌ی 13: POST: ساختن چیز تازه →