FastAPI Response Headers 與 Cookies

除了資料內容 (Body) 之外，你可能還需要透過 Header 或 Cookie 傳遞額外資訊給客戶端，例如分頁資訊、追蹤 ID 或 Session。

設定 Response Header

要加入自訂 Header，你可以在路徑操作函數中，宣告一個 Response 型別的參數。

from fastapi import FastAPI, Response

app = FastAPI()

@app.get("/items/")
async def read_items(response: Response):
    # 使用 .headers 加入自訂標頭
    response.headers["X-Process-ID"] = "abcd-1234"
    return {"message": "Success"}

當你存取這個 API 時，回應的 Header 中就會包含 X-Process-ID: abcd-1234。

你可以使用 response.set_cookie() 方法來設定 Cookie。

from fastapi import FastAPI, Response

app = FastAPI()

@app.get("/login/")
async def login(response: Response):
    # 設定一個名稱為 ads_id 的 Cookie
    response.set_cookie(key="ads_id", value="12345678")
    return {"message": "Logged in"}

response.set_cookie() 支援許多參數來精確控制 Cookie 的行為：

參數說明
keyCookie 的名稱。
valueCookie 的值。
max_age有效期限，以秒為單位（例如 3600 為一小時）。
expires過期時間，傳入 datetime 物件或日期字串。
pathCookie 的有效路徑，預設為 /。只有在此路徑及其子路徑下的請求才會帶上此 Cookie。
domainCookie 的有效網域。
secure設定為 True 時，僅允許在 HTTPS 安全連線下傳送。
httponly設定為 True 時，禁止客戶端 JavaScript 存取此 Cookie (防止 XSS 攻擊)。
samesite控制跨站請求行為，可選值為 'lax' (預設), 'strict', 'none' (需搭配 secure=True)。
partitioned設定為 True 時，啟用獨立分區狀態 (CHIPS)，用於處理第三方 Cookie 的隱私限制。

安全設定範例：

response.set_cookie(
    key="session_id",
    value="secret-session-key",
    httponly=True,
    secure=True,
    max_age=3600,
    samesite="lax"
)

如果你想撤銷或刪除客戶端上的 Cookie (例如在「登出」功能中)，可以使用 response.delete_cookie() 方法。

@app.post("/logout")
async def logout(response: Response):
    # 刪除名稱為 session_id 的 Cookie
    response.delete_cookie(key="session_id")
    return {"message": "Logged out"}
注意：刪除 Cookie 時，如果當初設定時有指定 path 或 domain，則呼叫 delete_cookie 時也必須傳入相同的 path 或 domain 參數，否則瀏覽器可能不會成功刪除。

在 HTTPException 中加入 Header

如果你在報錯時也想提供 Header（例如 WWW-Authenticate），可以在 HTTPException 中設定：

from fastapi import HTTPException

raise HTTPException(
    status_code=401,
    detail="Unauthorized",
    headers={"X-Error-Code": "AUTH_FAILED"}
)

總結

  • 透過在函數中宣告 response: Response 物件來操作回應。
  • 使用 response.headers["Key"] = "Value" 設定 Header。
  • 使用 response.set_cookie(...) 設定 Cookie。
  • 設定偏好安全性的 Cookie 參數 (httponly, secure) 是最佳實踐。