FastAPI基礎教程：路由、請求與響應的基礎用法

1. 什麼是FastAPI？¶

FastAPI是一個基於Python的現代、快速（高性能）的Web框架，用於構建API。它有幾個突出的特點：

高性能：基於Starlette和Pydantic構建，性能接近Node.js和Go
自動生成API文檔：自動生成交互式的Swagger UI和ReDoc文檔
類型提示支持：利用Python的類型提示自動驗證數據和生成文檔
簡單易用：代碼簡潔，學習曲線平緩，適合初學者快速上手

2. 安裝FastAPI¶

要開始使用FastAPI，首先需要安裝它和一個ASGI服務器（如Uvicorn）：

pip install fastapi uvicorn

3. 基礎路由定義¶

路由是API中URL與處理函數的映射關係，FastAPI使用@app裝飾器定義路由。

3.1 最基本的路由¶

from fastapi import FastAPI

# 創建FastAPI應用實例
app = FastAPI()

# 定義一個GET請求路由，路徑爲"/"
@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI!"}

@app.get("/")：這是一個路徑操作裝飾器，表示處理根路徑/的GET請求
def read_root()：處理函數，返回一個字典（FastAPI會自動轉爲JSON響應）

3.2 帶路徑參數的路由¶

路徑參數是URL中動態變化的部分，例如/items/123中的123。

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id, "message": f"你請求的商品ID是: {item_id}"}

{item_id}：路徑參數，item_id是參數名
item_id: int：參數類型提示，FastAPI會自動驗證類型並轉換
當訪問/items/5時，會返回{"item_id": 5, "message": "你請求的商品ID是: 5"}

3.3 帶查詢參數的路由¶

查詢參數是URL中?後面的鍵值對，用於傳遞額外信息。

@app.get("/search")
def search_items(q: str = None, limit: int = 10):
    return {"query": q, "limit": limit}

q: str = None：查詢參數q，默認值爲None
limit: int = 10：查詢參數limit，默認值爲10
訪問/search?q=test&limit=5時，返回{"query": "test", "limit": 5}

4. 請求處理¶

當需要接收客戶端發送的數據（如POST請求的JSON數據）時，FastAPI使用請求體。

4.1 使用Pydantic模型定義請求體¶

Pydantic是一個數據驗證庫，FastAPI用它來定義請求數據結構：

from pydantic import BaseModel

# 定義數據模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None  # 可選字段，默認值爲None

@app.post("/items/")
def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

Item類繼承自BaseModel，定義了三個字段：name（字符串）、price（浮點數）、is_offer（布爾值，可選）
在create_item函數中，item: Item參數表示接收一個Item類型的請求體
FastAPI會自動解析請求體的JSON數據，並驗證數據類型是否匹配

4.2 發送請求體測試¶

使用curl發送POST請求：

curl -X POST "http://localhost:8000/items/" \
  -H "Content-Type: application/json" \
  -d '{"name": "iPhone", "price": 999.99, "is_offer": true}'

5. 響應處理¶

FastAPI會自動將函數返回值轉換爲JSON響應。

5.1 返回Pydantic模型¶

@app.get("/items/{item_id}", response_model=Item)
def get_item(item_id: int):
    # 模擬數據庫查詢
    return {"name": "Example Item", "price": 100.0, "is_offer": None}

response_model=Item：指定響應數據的模型，FastAPI會自動將返回的字典轉換爲Item模型，並生成對應JSON結構
響應會包含name、price和is_offer字段，即使模型中某些字段爲None

5.2 返回狀態碼¶

使用status_code參數指定HTTP狀態碼：

@app.post("/items/", status_code=201)  # 201表示"創建成功"
def create_item(item: Item):
    return item  # 返回創建的Item數據

常見狀態碼：
- 200 OK：默認狀態碼（GET/POST成功）
- 201 Created：資源創建成功（POST）
- 404 Not Found：資源不存在
- 400 Bad Request：請求參數錯誤

5.3 返回字典或簡單類型¶

@app.get("/hello/{name}")
def say_hello(name: str):
    return {"message": f"Hello, {name}!"}  # 返回字典

或返回字符串：

@app.get("/version", response_class=str)
def get_version():
    return "1.0.0"  # 返回字符串

6. 完整示例¶

下面是一個包含路由、請求和響應的完整FastAPI應用：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="FastAPI基礎示例")

# 定義數據模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

# 1. 根路由
@app.get("/")
def read_root():
    return {"message": "歡迎使用FastAPI示例API！"}

# 2. 帶路徑參數的路由
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

# 3. 帶請求體的路由
@app.post("/items/", response_model=Item, status_code=201)
def create_item(item: Item):
    return item  # 返回創建的Item對象

# 4. 另一個帶參數的路由
@app.get("/search")
def search_items(q: str = None, limit: int = 10):
    return {"search_term": q, "limit": limit}

7. 運行和測試¶

保存代碼到main.py文件
使用Uvicorn運行應用：

uvicorn main:app --reload

main:app：表示從main.py文件中導入app實例
--reload：自動重載代碼，開發時方便調試

訪問API文檔：
- Swagger UI：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc

8. 總結¶

通過本文，你應該已經掌握了FastAPI的基礎用法：

使用@app裝飾器定義路由
處理路徑參數和查詢參數
使用Pydantic模型接收請求體
返回響應數據和設置狀態碼
利用自動生成的API文檔進行測試

FastAPI的核心優勢在於它的簡潔性和自動文檔功能，這使得構建和維護API變得更加高效。接下來可以探索更多高級特性，如依賴注入、中間件和異步處理等。