พารามิเตอร์เส้นทางและพารามิเตอร์ query ทำงานอย่างไร

Question

Accepted Answer

FastAPI สกัด **พารามิเตอร์เส้นทาง** (ส่วนของเส้นทาง URL) และ **พารามิเตอร์ query** (หลัง `?`) จากอาร์กิวเมนต์ฟังก์ชัน โดยใช้ type hints สำหรับการแปลงและตรวจสอบความถูกต้องโดยอัตโนมัติ

## พารามิเตอร์เส้นทาง — ส่วนของ URL

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

พารามิเตอร์ฟังก์ชันที่มีชื่อตรงกับ `{placeholder}` ในเส้นทางจะกลายเป็น **พารามิเตอร์เส้นทาง** type hint (`int`) จะแปลง string จาก URL โดยอัตโนมัติและส่งกลับข้อผิดพลาด 422 ที่ชัดเจนหากไม่ตรงกัน

## พารามิเตอร์ query — ทุกอย่างอื่น

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

พารามิเตอร์ฟังก์ชันที่ **ไม่** อยู่ในเส้นทางจะกลายเป็น **พารามิเตอร์ query** ค่าเริ่มต้นทำให้เป็นตัวเลือก (`skip: int = 0`); `str | None = None` สร้างพารามิเตอร์ query ที่เป็นตัวเลือกและเป็น nullable ไม่มีค่าเริ่มต้นแล้วเป็นสิ่งจำเป็น

## บังคับเทียบกับตัวเลือก

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## รวมทั้งสอง

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## เหตุใดึ่งสำคัญ

พารามิเตอร์เส้นทางและ query คือวิธีที่ endpoints รับอินพุตจาก URL — เป็นพื้นฐานของเกือบทุก API route (ดึงทรัพยากรตาม id การกรอง pagination การค้นหา)

วิธีการของ FastAPI นั้นสวยงามและเป็นเหตุผลสำคัญที่ทำให้เป็นผลิตภาพ: การประกาศพารามิเตอร์ฟังก์ชันที่มี type hint อย่างง่าย ๆ ให้คุณได้รับการสกัดอัตโนมัติ **การแปลง type** **การตรวจสอบความถูกต้อง** (พร้อมข้อผิดพลาด 422 ที่ชัดเจนสำหรับอินพุตที่ไม่ดี) และ required-vs-optional semantics (ผ่านค่าเริ่มต้น) — ทั้งหมดมาจาก Python type hints มาตรฐาน โดยไม่ต้องแยกวิเคราะห์ด้วยตนเอง

การทำความเข้าใจความแตกต่าง (พารามิเตอร์เส้นทางมาจาก `{placeholder}` ทุกอย่างอื่นคือพารามิเตอร์ query) และวิธีที่ค่าเริ่มต้นควบคุมความเป็นตัวเลือก เป็นความรู้พื้นฐานในแต่ละวันที่จำเป็นสำหรับการสร้าง FastAPI endpoints