Làm thế nào để định nghĩa các route (path operation)?

Question

Accepted Answer

Trong FastAPI, một **path operation** là một route — một function được trang trí bằng decorator HTTP method (`@app.get`, `@app.post`, v.v.) để xử lý request đến một path. Giá trị trả về của function được tự động serialize thành JSON.

## Định nghĩa route cho từng HTTP method

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → tự động serialize thành JSON

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint chuyển "5" → int (và validate)
    return {"id": item_id}

@app.post("/items")               # POST /items
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE hoạt động tương tự
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

Mỗi decorator ánh xạ một HTTP method + path tới một handler. Tên function là tùy bạn; decorator định nghĩa route. Các dict/list/Pydantic model được trả về sẽ tự động được serialize thành JSON — không cần `json.dumps` thủ công.

## Thứ tự quan trọng với các path chồng lấn

```python
@app.get("/users/me")            # ✅ route cụ thể ĐẶT TRƯỚC
def read_me(): ...
@app.get("/users/{user_id}")     # route động ĐẶT SAU — nếu không "me" sẽ khớp {user_id}
def read_user(user_id: int): ...
```

FastAPI khớp route theo thứ tự khai báo, vì vậy hãy đặt các path tĩnh trước các path động.

## Metadata của operation (điều khiển tài liệu)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

Các tham số decorator (`tags`, `summary`, `status_code`, `response_model`) cấu hình hành vi và làm phong phú tài liệu được sinh tự động.

## Tại sao điều này quan trọng

Path operations là nền tảng của mọi ứng dụng FastAPI — chúng định nghĩa các endpoint của API và cách xử lý request.

Hiểu pattern một-decorator-cho-mỗi-HTTP-method, rằng giá trị trả về tự động được serialize thành JSON (không boilerplate), rằng type hints trên tham số điều khiển việc chuyển đổi và validation, và rằng thứ tự route quan trọng với các path chồng lấn là kiến thức thiết yếu hằng ngày để xây dựng bất kỳ endpoint nào.

Metadata của decorator cũng nuôi dưỡng tài liệu tự động của FastAPI, gắn các route trực tiếp với tài liệu.

Đây là điều đầu tiên và cơ bản nhất cần thành thạo trong FastAPI.