חיבור Routes לפעולות Database — הארכיטקטורה

מה נלמד?#

היום מחברים הכול: השרת מנושא Backend ו-FastAPI, המסד מימים 2–4. השיעור הזה מתמקד בארכיטקטורה, כלומר איך החלקים מתחברים, וממש את שני ה-Endpoints הראשונים (קריאה). בשיעור הבא, את השאר.

למה צריך את זה?#

בנושא Backend ו-FastAPI השרת שמר סטודנטים ב-RAM, והם נעלמו בכל הפעלה מחדש. עכשיו השרת ישמור במסד: נתונים שנשארים, עם אילוצים ו-Transactions. זו הארכיטקטורה הבסיסית של כמעט כל Backend בעולם: Client → API → Database.

הסבר מהבסיס#

שני קבצים, שתי אחריויות#

students-api/
├── main.py     ← the API layer: routes, HTTP, validation, status codes
└── db.py       ← the data layer: SQL, connections, commit (from the databases topic)

MySQL in Docker (kodkod-mysql)  ← where the data lives

זו “הפרדת קוד בסיסית בין Route לבין קוד הגישה למסד” שהסילבוס מבקש. ולמה זה טוב?

• כל קובץ קטן וממוקד (SRP, נושא Python–3).
• בודקים כל שכבה לבד: את db.py כבר בדקנו אתמול, בלי שרת.
• מחליפים שכבה בלי לגעת בשנייה: מעבר ל-PostgreSQL ישנה רק את db.py. ממשק אחר (אפליקציית שורת פקודה) ישתמש באותו db.py.

טבלת המיפוי#

כל Route עושה שלושה דברים: (1) מקבל ומוודא קלט (FastAPI + ולידציה), (2) קורא לפונקציה אחת ב-db.py, (3) מתרגם את התוצאה ל-HTTP.

בקשה אחת, מקצה לקצה#

GET /students/2
   │
   ▼  Uvicorn receives the HTTP request (port 8000)
   ▼  FastAPI finds the route, converts "2" → 2 (int), calls get_student(2)
   ▼  main.get_student  →  db.get_student(2)
   ▼  db: open connection → SELECT ... WHERE id = %s (2) → fetchone → dict → close
   ▼  main: dict is not None → return it
   ▼  FastAPI: dict → JSON, status 200
   ▼  Uvicorn sends the HTTP response
{"id": 2, "name": "Avi", "age": 31, "email": "avi@mail.com"}

כל השבועות במסלול אחד: HTTP ו-Port (נושא מחשב, מערכת הפעלה ורשת), פונקציות ו-dict ו-JSON (נושא Python), Classes ו-Pydantic (נושא OOP), SQL (נושא Backend ומסדי נתונים).

מתי נוצרת הטבלה?#

db.init_db() נקראת פעם אחת, כשהשרת עולה (ברמה הראשית של main.py). בגלל IF NOT EXISTS, זה בטוח בכל הפעלה: בפעם הראשונה הטבלה נוצרת, ובשאר הפעמים לא קורה כלום.

תחביר#

from fastapi import FastAPI, HTTPException

import db                                   # our data layer (same folder)

app = FastAPI(title="Students API")
db.init_db()                                # create the table once, on startup


@app.get("/students/{student_id}")
def get_student(student_id: int):
    student = db.get_student(student_id)    # 1 call to the data layer
    if student is None:                     # translate "not found" to HTTP
        raise HTTPException(status_code=404, detail="student not found")
    return student                          # dict → JSON (200)

שמות זהים בשתי שכבות: הפונקציה ב-main.py נקראת get_student, וגם זו ב-db.py. אין התנגשות, כי קוראים לזו של המסד דרך שם המודול: db.get_student(...) (נושא Python!).

דוגמת קוד ראשונה#

הקמת הפרויקט (הקונטיינר של MySQL צריך לרוץ — docker start kodkod-mysql):

mkdir ~\dev\kodkod6\week-4\students-api
cd ~\dev\kodkod6\week-4\students-api
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install "fastapi[standard]" mysql-connector-python
git init

.gitignore:

.venv/
__pycache__/
.env

העתיקו את db.py מנושא מסדי הנתונים (CRUD מלא) לתיקייה. ו-main.py, בשלב הזה רק שני Endpoints:

from fastapi import FastAPI, HTTPException

import db

app = FastAPI(title="Students API")
db.init_db()


@app.get("/students")
def list_students():
    return db.get_all_students()


@app.get("/students/{student_id}")
def get_student(student_id: int):
    student = db.get_student(student_id)
    if student is None:
        raise HTTPException(status_code=404, detail="student not found")
    return student

הוספת נתונים לבדיקה (המסד ריק! עוד אין POST). seed.py:

import db

db.init_db()
for name, age, email in [("Dana", 24, "dana@mail.com"), ("Avi", 31, "avi@mail.com")]:
    try:
        print(db.create_student(name, age, email))
    except ValueError as error:
        print("Skipped:", error)

python seed.py
uvicorn main:app --reload

בדפדפן:

• http://127.0.0.1:8000/students
• http://127.0.0.1:8000/students/2
• http://127.0.0.1:8000/students/99

תשובות:

[{"id":1,"name":"Dana","age":24,"email":"dana@mail.com"},{"id":2,"name":"Avi","age":31,"email":"avi@mail.com"}]

{"id":2,"name":"Avi","age":31,"email":"avi@mail.com"}

{"detail":"student not found"}

פירוק הקוד שורה אחר שורה#

ועכשיו הניסוי החשוב: עצרו את השרת (Ctrl + C), והפעילו שוב. רעננו את /students. הנתונים שם! בניגוד לנושא Backend ו-FastAPI, הם במסד — בשרת ה-MySQL שבקונטיינר, שכותב אותם ל-Storage (נושא מחשב, מערכת הפעלה ורשת!). אפשר גם לראות אותם ב-Database Client.

דוגמה נוספת#

Endpoint נוסף, שמשתמש ב-db.py עם Query Parameter: חיפוש. הוסיפו ל-db.py את search_students מתרגול אתמול, ול-main.py:

@app.get("/students/search")
def search_students(name: str):
    if len(name.strip()) < 2:
        raise HTTPException(status_code=400, detail="search text must have at least 2 characters")
    return db.search_students(name)

איפה בקובץ? /students/search הוא נתיב קבוע, ולכן הוא חייב להיות לפני /students/{student_id} (נושא Backend ו-FastAPI, טעות 3!). אחרת search ייתפס כ-student_id → 422.

GET /students/search?name=av   → 200 [{"id": 2, "name": "Avi", ...}]
GET /students/search?name=a    → 400 {"detail": "search text must have at least 2 characters"}
GET /students/search           → 422 (name is required)

שימו לב לחלוקת העבודה: הולידציה (לפחות 2 תווים) ב-main.py, כי זה כלל של ה-API. הSQL (LIKE, lower) ב-db.py.

טעות נפוצה#

הטעות 1: SQL בתוך ה-Route.

@app.get("/students/{student_id}")
def get_student(student_id: int):
    connection = mysql.connector.connect(
        host="localhost", user="root", password="kodkod", database="school")
    cursor = connection.cursor()
    cursor.execute("SELECT * FROM students WHERE id = %s", (student_id,))
    ...

“עובד”, אבל עכשיו יש SQL בשני מקומות, פרטי חיבור בשני מקומות, ו-Route שעושה הכול. Route = קלט + קריאה ל-db + תרגום.

הטעות 2: להחזיר None מה-Route.

@app.get("/students/{student_id}")
def get_student(student_id: int):
    return db.get_student(student_id)

לסטודנט שלא קיים מוחזר 200 עם null. ה-Client יחשוב שההצלחה. “לא נמצא” = 404.

הטעות 3: השרת לא עולה — הקונטיינר של MySQL לא רץ. db.init_db() רץ כש-Uvicorn טוען את main.py, ולכן השרת נופל כבר בהפעלה:

mysql.connector.errors.InterfaceError: 2003: Can't connect to MySQL server on 'localhost:3306' ...

בודקים עם docker ps, ומפעילים: docker start kodkod-mysql (נושא מסדי נתונים ו-MySQL!).

הטעות 4: ModuleNotFoundError: No module named 'db'. db.py לא באותה תיקייה כמו main.py, או שמריצים את uvicorn מתיקייה אחרת. מריצים מתיקיית הפרויקט.

תרגול#

התרגילים מבוססים רק על מה שנלמד בשיעור הזה ובשיעורים שלפניו. נסו לבד, ורק אז פתחו את הפתרון.

תרגיל 1: שתי שכבות#

לכל שורת קוד — האם היא שייכת ל-main.py (שכבת ה-HTTP) או ל-db.py (שכבת הנתונים)?

1. cursor.execute("SELECT * FROM students WHERE id = %s", (student_id,))
2. raise HTTPException(status_code=404, detail="student not found")
3. @app.get("/students/{student_id}")
4. mysql.connector.connect(host="localhost", user="root", ...)
5. return db.get_student(student_id)

תרגיל 2: Routes לקריאה#

יש לכם את db.py מהשיעור הקודם (עם init_db, get_all_students ו-get_student). כתבו main.py עם:

• db.init_db() בהפעלת השרת;
• GET /students — כל הסטודנטים;
• GET /students/{student_id} — סטודנט אחד, או 404 עם "student not found".

from fastapi import FastAPI, HTTPException

import db

app = FastAPI(title="Students API")
db.init_db()


@app.get("/students")
def list_students():
    return db.get_all_students()


@app.get("/students/{student_id}")
def get_student(student_id: int):
    student = db.get_student(student_id)
    if student is None:
        raise HTTPException(status_code=404, detail="student not found")
    return student

תרגיל 3: בקשה אחת — מקצה לקצה#

סדרו את מה שקורה בבקשה GET /students/2:

• (א) db.get_student(2) מריצה SELECT ... WHERE id = %s עם (2,)
• (ב) FastAPI ממיר את "2" מהנתיב ל-int
• (ג) התשובה חוזרת כ-JSON עם 200
• (ד) main.get_student(2) נקראת
• (ה) השורה חוזרת כמילון

GET /students/2
  -> FastAPI: student_id = 2 (int)
  -> main.get_student(2)
  -> db.get_student(2)
  -> SELECT ... WHERE id = %s   (2,)
  -> {'id': 2, 'name': 'Avi', ...}
  -> JSON, 200

תרגיל 4: Endpoint חיפוש#

הוסיפו ל-main.py את GET /students/search?name=..., שמשתמש ב-db.search_students. שם קצר מ-2 תווים ‏←‏ 400. איפה צריך להגדיר את ה-Route, ולמה?

@app.get("/students/search")
def search_students(name: str):
    if len(name.strip()) < 2:
        raise HTTPException(status_code=400, detail="too short")
    return db.search_students(name)

תרגיל 5: מה לא בסדר?#

@app.get("/students/{student_id}")
def get_student(student_id: int):
    connection = mysql.connector.connect(
        host="localhost", user="root", password="kodkod", database="school")
    cursor = connection.cursor()
    cursor.execute("SELECT * FROM students WHERE id = %s", (student_id,))
    return cursor.fetchone()

מצאו שלוש בעיות בקוד הזה.

סיכום#

• main.py = שכבת ה-API: Routes, ולידציה וקודי סטטוס. db.py = שכבת הנתונים: SQL, חיבורים ו-commit. אין SQL ב-Routes.
• מיפוי: GET→SELECT, POST→INSERT (201), PUT→UPDATE, DELETE→DELETE (204). None/False → 404. ValueError → 409.
• Route = קלט ‏←‏ קריאה אחת ל-db ‏←‏ תרגום ל-HTTP.
• db.init_db() פעם אחת בעליית השרת (IF NOT EXISTS).
• נתיבים קבועים (/students/search) לפני /students/{student_id}.
• הנתונים שורדים הפעלה מחדש של השרת, כי הם במסד.

דוקומנטציה רשמית#

• FastAPI — Bigger Applications — חלוקת הקוד לקבצים
• FastAPI — Handling Errors — HTTPException כשרשומה לא נמצאה