Middleware — קוד שרץ על כל בקשה

מה נלמד?#

• איזו בעיה יש כשרוצים לעשות משהו בכל בקשה.
• מה זה Middleware, ואיך הוא קשור ל-Decorator שכבר מכירים.
• @app.middleware("http"), call_next, async ו-await.
• לוג ומדידת זמן לכל בקשה ב-API הסטודנטים, ו-Header שמתווסף לכל תשובה.

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

ה-API הסטודנטים מהשיעור הקודם עובד. עכשיו רוצים לדעת מה קורה בו: איזו בקשה הגיעה, איזה קוד חזר, וכמה זמן היא לקחה. הדרך הראשונה שעולה לראש — להוסיף שורת לוג לכל Route:

@app.get("/students")
def list_students():
    logging.info("GET /students")
    return students


@app.get("/students/{student_id}")
def get_student(student_id: int):
    logging.info("GET /students/" + str(student_id))
    ...

שלוש בעיות:

1. אותה שורה מועתקת לכל Route — חמש, עשר, חמישים פעמים.
2. Route חדש שבו שכחו את השורה — פשוט לא נרשם.
3. אין דרך לדעת כך את קוד התשובה — 404 ו-400 נוצרים ב-raise HTTPException, אחרי שורת הלוג, ו-422 נוצר עוד לפני שה-Route רץ. וגם לא כמה זמן הבקשה לקחה.

הסבר מהבסיס#

הרעיון — Middleware#

Middleware (תוכנת ביניים) = קוד שעוטף כל בקשה שמגיעה לשרת: הוא רץ לפני ה-Route, מעביר את הבקשה הלאה, ורץ שוב אחרי — כשהתשובה כבר ביד.

Client --request--> Middleware --------> Route (your function)
                    before: start the timer
Client <-response-- Middleware <-------- Route
                    after: status code, duration, log

כמו Decorator — לכל השרת#

בשיעור על דקורטורים כתבנו Decorator שמודד זמן: הוא עוטף פונקציה אחת, רץ לפניה ואחריה, וקורא לה באמצע. Middleware הוא בדיוק אותו רעיון — רק שהוא עוטף את כל הבקשות לשרת, בלי לגעת באף Route.

למה צריך לחכות נכון?#

ה-Middleware מעביר את הבקשה ל-Route, ואז מחכה לתשובה. אבל שרת מקבל הרבה בקשות בבת אחת. אם הוא “נתקע” ומחכה לכל בקשה עד הסוף, כל השאר עומדות בתור.

async ו-await#

בדיוק בשביל זה יש await. בתוך ה-Middleware מופיעה השורה:

response = await call_next(request)

• call_next(request) — מעביר את הבקשה הלאה: ל-Route המתאים (או ל-404 אם אין כזה), ומחזיר את התשובה. זו ההזמנה למטבח.
• await — “תודיעו לי כשהמנה מוכנה”: מחכים לתשובה של ה-Route, ובינתיים השרת פנוי לטפל בבקשות אחרות. כשהתשובה מוכנה, הקוד ממשיך מהשורה הבאה.
• async def — את await מותר לכתוב רק בתוך פונקציה שמוגדרת עם async def. לכן ה-Middleware מוגדר כך.

request ו-response#

תחביר#

from fastapi import FastAPI, Request

app = FastAPI()


@app.middleware("http")
async def my_middleware(request: Request, call_next):
    # ... before the route
    response = await call_next(request)     # wait for the route's response
    # ... after the route
    return response                         # always pass the response on

• @app.middleware("http") — רושם את הפונקציה כ-Middleware לכל בקשת HTTP.
• request: Request — Request מיובא מ-fastapi.
• return response — חובה. בלעדיו הלקוח לא מקבל תשובה.

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

לוג ומדידת זמן לכל בקשה ב-API הסטודנטים. בראש students_memory.py (מהשיעור הקודם) — רק מוסיפים, אף Route לא משתנה:

import logging
import time

from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel

logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")

app = FastAPI(title="Students API")


@app.middleware("http")
async def log_requests(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    ms = round((time.time() - start) * 1000, 1)
    logging.info(request.method + " " + request.url.path + " -> "
                 + str(response.status_code) + " (" + str(ms) + " ms)")
    return response

# ... students, StudentIn and all the routes stay exactly the same

מריצים (uvicorn students_memory:app --reload), ושולחים בקשות מ-Swagger (/docs). הלוג ב-Terminal:

INFO GET /students -> 200 (0.7 ms)
INFO GET /students/99 -> 404 (0.5 ms)
INFO POST /students -> 201 (1.3 ms)
INFO POST /students -> 400 (0.6 ms)
INFO GET /students/abc -> 422 (0.5 ms)

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

שימו לב: הזמנים קצרים מאוד — הנתונים ברשימה בזיכרון. כשנחבר את השרת למסד נתונים, נראה את הזמנים עולים — ומדידה כזו היא בדיוק הדרך לגלות איפה השרת “מבזבז” זמן.

דוגמה נוספת#

Header לכל תשובה#

Middleware יכול גם לשנות את התשובה. כאן מוסיפים לכל תשובה Header בשם X-Process-Time, עם הזמן שלקח לטפל בה:

@app.middleware("http")
async def add_process_time(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    ms = round((time.time() - start) * 1000, 1)
    response.headers["X-Process-Time"] = str(ms)
    return response

ב-Swagger, תחת Response headers, מופיע עכשיו:

x-process-time: 0.7

• response.headers[...] = ... — כמו הוספת מפתח למילון.
• X- בתחילת השם — מוסכמה ל-Header שלנו, שאינו חלק מהתקן של HTTP.
• אפשר כמה Middlewares באותו שרת — כל בקשה עוברת דרך כולם.

מתי לא Middleware?#

Middleware מתאים לדברים שכל בקשה צריכה — לוג, מדידת זמן, Headers. כלל של Route אחד — למשל “גיל מינימלי 16” ב-POST /students — שייך ל-Route עצמו, ולא לקוד שרץ על כל השרת.

טעות נפוצה#

הטעות 1: לשכוח return response.

@app.middleware("http")
async def log_requests(request: Request, call_next):
    response = await call_next(request)
    logging.info(request.url.path)

ה-Middleware מחזיר None, והלקוח מקבל 500 — על כל בקשה, כי Middleware רץ על כולן.

הטעות 2: לשכוח await.

response = call_next(request)

בלי await, לא מחכים ל-Route — ו-response הוא לא תשובה. השרת נכשל בכל בקשה. await לפני call_next, תמיד.

הטעות 3: def במקום async def. בלי async, אי אפשר להשתמש ב-await בתוך הפונקציה: SyntaxError: 'await' outside async function.

הטעות 4: לוגיקה של Route בתוך Middleware. if request.url.path == "/students" and ... — Middleware שבודק נתיבים ספציפיים הוא בדרך כלל סימן שהקוד שייך ל-Route.

תרגול#

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

תרגיל 1: מה רץ קודם?#

@app.middleware("http")
async def trace(request: Request, call_next):
    print("before", request.method, request.url.path)
    response = await call_next(request)
    print("after", response.status_code)
    return response


@app.get("/hello")
def hello():
    print("inside the route")
    return {"message": "hi"}

שולחים GET /hello. מה יודפס, ובאיזה סדר? ומה יודפס עבור GET /nothing, נתיב שלא קיים?

from fastapi import FastAPI, Request
from fastapi.testclient import TestClient

app = FastAPI()


@app.middleware("http")
async def trace(request: Request, call_next):
    print("before", request.method, request.url.path)
    response = await call_next(request)
    print("after", response.status_code)
    return response


@app.get("/hello")
def hello():
    print("inside the route")
    return {"message": "hi"}


client = TestClient(app)
client.get("/hello")
client.get("/nothing")

before GET /hello
inside the route
after 200
before GET /nothing
after 404

תרגיל 2: לוג לכל בקשה#

כתבו Middleware בשם log_requests שרושם ללוג, ברמת INFO, שורה לכל בקשה: ה-Method, הנתיב וקוד התשובה — בפורמט שבפלט הצפוי.

השתמשו באפליקציה הקטנה הזו: רשימה עם סטודנט אחד, GET /students ו-GET /students/{student_id} (שמחזיר 404 לסטודנט שלא קיים). את הלוג מגדירים כך שהשורות יודפסו למסך:

logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s", stream=sys.stdout)
logging.getLogger("httpx").setLevel(logging.WARNING)   # hide the test client's own log lines

students = [{"id": 1, "name": "Dana"}]

כדי לבדוק בלי להריץ שרת, שולחים את שלוש הבקשות עם TestClient של FastAPI — כלי ששולח בקשות ישר לאפליקציה מתוך קוד Python:

from fastapi.testclient import TestClient

client = TestClient(app)
client.get("/students")
client.get("/students/1")
client.get("/students/99")

פלט צפוי:

INFO GET /students -> 200
INFO GET /students/1 -> 200
INFO GET /students/99 -> 404

import logging
import sys

from fastapi import FastAPI, HTTPException, Request
from fastapi.testclient import TestClient

logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s", stream=sys.stdout)
logging.getLogger("httpx").setLevel(logging.WARNING)   # hide the test client's own log lines

app = FastAPI()
students = [{"id": 1, "name": "Dana"}]


@app.middleware("http")
async def log_requests(request: Request, call_next):
    response = await call_next(request)
    logging.info(request.method + " " + request.url.path + " -> " + str(response.status_code))
    return response


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


@app.get("/students/{student_id}")
def get_student(student_id: int):
    for student in students:
        if student["id"] == student_id:
            return student
    raise HTTPException(status_code=404, detail="student not found")


client = TestClient(app)
client.get("/students")
client.get("/students/1")
client.get("/students/99")

INFO GET /students -> 200
INFO GET /students/1 -> 200
INFO GET /students/99 -> 404

תרגיל 3: Header עם זמן הטיפול#

כתבו Middleware שמודד כמה זמן לקח לטפל בבקשה, ומוסיף לתשובה Header בשם X-Process-Time עם הזמן במילישניות. באפליקציה יש Route אחד, GET / שמחזיר {"message": "hello"}.

בדקו שה-Header מגיע — שולחים בקשה עם TestClient (כלי ששולח בקשות ישר לאפליקציה מתוך קוד Python) ובודקים את ה-Headers של התשובה:

from fastapi.testclient import TestClient

client = TestClient(app)
response = client.get("/")
print(response.status_code)
print("Has X-Process-Time:", "x-process-time" in response.headers)

פלט צפוי:

200
Has X-Process-Time: True

import time

from fastapi import FastAPI, Request
from fastapi.testclient import TestClient

app = FastAPI()


@app.middleware("http")
async def add_process_time(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    ms = round((time.time() - start) * 1000, 1)
    response.headers["X-Process-Time"] = str(ms)
    return response


@app.get("/")
def home():
    return {"message": "hello"}


client = TestClient(app)
response = client.get("/")
print(response.status_code)
print("Has X-Process-Time:", "x-process-time" in response.headers)

200
Has X-Process-Time: True

תרגיל 4: async ו-await#

@app.middleware("http")
async def log_requests(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    ms = round((time.time() - start) * 1000, 1)
    logging.info(request.url.path + " (" + str(ms) + " ms)")
    return response

1. מה עושה השורה response = await call_next(request)? הסבירו עם אנלוגיית המלצר והמטבח.
2. מה השרת עושה בזמן ש-await מחכה?
3. למה הפונקציה מוגדרת עם async def ולא עם def?
4. האם גם ה-Routes שלנו (list_students, get_student) צריכים להיות async def?

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

@app.middleware("http")
def log_requests(request: Request, call_next):
    response = call_next(request)
    logging.info(request.url.path)

מצאו שלוש בעיות. ומתי לא נכון להשתמש ב-Middleware?

סיכום#

• Middleware = קוד שעוטף כל בקשה: לפני ה-Route, ואחריו. כמו Decorator — לכל השרת.
• @app.middleware("http") + async def + await call_next(request) + return response.
• לפני call_next — מה שצריך לפני הבקשה (למשל, להתחיל למדוד). אחרי — יש תשובה ביד: קוד, Headers, זמן.
• שימושים: לוג לכל בקשה, מדידת זמן, Headers לכל תשובה.
• כללים של Route אחד — ב-Route, לא ב-Middleware.

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

• FastAPI — Middleware — @app.middleware(“http”) ו-call_next
• FastAPI — Concurrency and async / await — למה async ו-await