FastAPI自学教程（54） - 响应Cookies配置

1.基础用法

from fastapi import FastAPI, Response
app = FastAPI()

@app.get("/cookie-demo")
async def set_cookie(response: Response):
    response.set_cookie(key="session_token", value="abc123xyz")
    return {"message": "Cookie已设置"}

通过路径操作函数声明Response参数设置Cookie
使用response.set_cookie()方法添加Cookie

请求处理流程：

graph TD
  A[客户端请求] --> B[创建Response对象]
  B --> C[执行set_cookie方法]
  C --> D[返回响应]
  D --> E[浏览器存储Cookie]

2.直接返回响应对象

from fastapi.responses import JSONResponse

@app.get("/direct-response")
async def direct_response():
    content = {"status": "success"}
    response = JSONResponse(content=content)
    response.set_cookie(key="auth_token", value="qwe456poi", max_age=3600)
    return response

直接返回JSONResponse等响应对象实例
适用场景：需要完全控制响应内容时
特点：
- 绕过自动响应模型过滤
- 必须手动保证响应数据格式正确性

3.Cookie参数详解

3.1 核心参数配置

response.set_cookie(
    key="secure_cookie",
    value="encrypted_data",
    max_age=86400,       # 有效期1天（秒）
    expires=172800,      # 过期时间戳（优先级高于max_age）
    path="/api",         # 仅/api路径生效
    domain=".example.com",# 子域名共享
    secure=True,         # 仅HTTPS传输
    httponly=True,       # 禁止JS访问
    samesite="lax"       # 跨站策略
)

安全参数说明：
- secure=True：生产环境强制启用
- httponly=True：防御XSS攻击
- samesite="strict"：防止CSRF攻击

3.2 依赖项统一配置

from fastapi import Depends

async def set_common_cookies(response: Response):
    response.set_cookie(key="version", value="v2.3")

@app.get("/items/", dependencies=[Depends(set_common_cookies)])
async def read_items():
    return [{"item": "data"}]

通过依赖项实现全局Cookie设置
优势：复用配置逻辑，保持代码整洁

4.生产环境建议

会话管理：
- 使用JWT等加密令牌替代明文存储敏感信息
- 设置max_age控制会话有效期（建议不超过24小时）

安全加固：

response.set_cookie(
    secure=True,
    httponly=True,
    samesite="lax",
    domain=".yourdomain.com"
)

性能优化：
- 避免单个响应设置过多Cookie（浏览器限制50+个）
- 使用__Host-前缀增强Cookie安全性（仅HTTPS+根路径）
调试技巧：
- 通过浏览器开发者工具检查Cookie属性
- 使用curl -b参数测试Cookie携带效果

测试命令示例：

# 测试基础Cookie设置
curl -i http://localhost:8000/cookie-demo

# 测试安全Cookie
curl -k --http2 -H "Cookie: secure_cookie=encrypted_data" https://api.example.com/data