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

جلسه‌ی 16: پروژه: API کارهای من Project: My Tasks API

پایان فاز ۴. همه‌ی کارهای CRUD را یک بار دیگر در یک نگاه می‌بینی: ساختن با POST و 201، عوض کردن با PUT/PATCH، پاک کردن با DELETE و 204، و بررسی ورودی با isinstance، 400 و 409، با یک یادآوری از JSON و طراحی API در فاز ۳. بعد پروژه: یک API کامل کارهای روزانه (/tasks) در سه قدم.

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

درس

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

📌 جلسه‌ی ۱۳ در یک نگاه: ساختن با POST. کلاینت: ask("POST /notes", {"text": "..."}). سرور: @app.post("/notes") و data = request.json. لیست بیرون از تابع، چیز تازه با id بعدی، notes.append(note) و return note, 201. یک آدرس، دو روش: GET /notes می‌خواند و POST /notes می‌سازد.

📌 جلسه‌ی ۱۴ در یک نگاه: CRUD. Create = POST، Read = GET، Update = PUT (همه‌چیز را جایگزین کن) یا PATCH (فقط کلیدهای آمده)، Delete = DELETE با notes.remove(note) و return "", 204. یک تابع کمکی مثل find_note چیز را پیدا می‌کند یا با abort(404, ...) همه‌چیز را متوقف می‌کند. شماره را از یک شمارنده (counter = {"next": 1}) بگیر، نه از len(...) + 1، تا بعد از پاک کردن تکراری نشود.

📌 جلسه‌ی ۱۵ در یک نگاه: بررسی ورودی. isinstance(data, dict) (بدنه‌ای آمد؟)، isinstance(data.get("name"), str) (آمد و متن است؟)، بعد len و بازه (1 <= stars <= 5). داده‌ی بد: 400 با پیامی که بگوید چه قبول است. تکراری: 409. برای چند اشکال یک‌جا: problems = []، append و آخر {"error": ..., "problems": problems}, 400. برای true/false نوع bool را بپرس.

⚠️ اشتباه‌های رایج این فاز:
- لیست یا شمارنده داخل تابع (با هر درخواست از صفر).
- request.args به‌جای request.json برای بدنه.
- جا انداختن 201، یا return "Deleted", 204 (بدنه‌ی 204 فرستاده نمی‌شود).
- PUT با یک کلید (برای یک تکه PATCH).
- <id> بدون int:، یا notes[id - 1] به‌جای گشتن دنبال id.
- len پیش از isinstance، و data["x"] وقتی شاید نیامده.
- عوض کردن پیش از بررسی کامل: اگر بررسی دوم شکست بخورد، نیمی از کار انجام شده است.

🔁 از فاز ۳: JSON و طراحی API. dict و لیست پایتون به JSON تبدیل می‌شوند: True → true، None → null. منبع‌ها اسم جمع دارند (/tasks، /tasks/3) و فعل در روش است، نه در آدرس (نه /getTasks، نه /deleteTask?id=3). خطا همیشه یک شکل دارد: {"error": ...}، و لیست‌ها {"count": n, "items": [...]}. سمت کلاینت quiet=True و r.json.

from server import app, ask

tasks = [{"id": 1, "title": "Math homework", "done": False, "note": None}]

@app.get("/tasks")
def all_tasks():
    return {"count": len(tasks), "items": tasks}

ask("GET /tasks")
r = ask("GET /tasks", quiet=True)
print(r.json["items"][0]["done"], r.json["items"][0]["note"])

📋 پروژه: API کارهای من. یک سرور فهرست کارهای روزانه، با این نقشه:

| روش | آدرس | کار | جواب خوب | خطاها |
|---|---|---|---|---|
| GET | /tasks | همه‌ی کارها | 200 | |
| POST | /tasks | کار تازه | 201 | 400، 409 |
| PATCH | /tasks/<id> | عوض کردن عنوان یا تیک | 200 | 400، 404 |
| DELETE | /tasks/<id> | پاک کردن | 204 | 404 |

هر کار این شکل است: {"id": 1, "title": "Math homework", "done": false}. سه قدم:
1. GET و POST با بررسی عنوان.
2. PATCH با بررسی، و 404.
3. DELETE و 409 برای عنوان تکراری.
هر قدم روی کد قدم قبل ساخته می‌شود؛ دکمه‌ی «ادامه از کد مرحله‌ی قبلم» کدت را می‌آورد.

یک بررسی، دو جا. عنوان هم در POST بررسی می‌شود هم در PATCH. پس آن را در یک تابع check_title بنویس که اگر عنوان ایراد داشت پیام را برگرداند، و اگر درست بود None (یعنی «هیچ»). بعد در مسیر: problem = check_title(...) و if problem is not None: abort(400, problem). is not None یعنی «چیزی برگشته». این‌طوری قانون عنوان فقط یک جا نوشته می‌شود و اگر روزی عوضش کنی، هر دو مسیر با هم عوض می‌شوند.

def check_title(title):
    if not isinstance(title, str):
        return "title must be text"
    if len(title) < 1 or len(title) > 30:
        return "title must be 1 to 30 characters"
    return None

print(check_title("Math homework"))
print(check_title(""))
print(check_title(42))

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

چالش‌ها

  1. Good Addresses (آسان)
  2. After a Delete (آسان)
  3. A Careful POST (متوسط)
  4. Step 1: Add and List (متوسط)
  5. Step 2: Tick It Off (سخت)
  6. Step 3: Delete and No Twins (سخت)

بیشتر بخوان

← جلسه‌ی 15: بررسی ورودی جلسه‌ی 17: حافظه فراموش می‌کند: پایگاه داده →