FastAPI自学教程（15）- Header参数处理

1. 基础声明方式

from fastapi import FastAPI, Header
from typing import Annotated

app = FastAPI()

@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
    return {"User-Agent": user_agent}

• 使用 Header() 声明参数，否则会被视为查询参数
• 参数名称需与请求头字段完全匹配（支持自动下划线转换机制）
• 推荐使用 Annotated 类型注解方式，兼容性更好

2. 自动转换机制

@app.get("/special/")
async def special_header(
    strange_header: Annotated[str, Header(convert_underscores=False)] 
):
    return {"header": strange_header}

• 默认将参数名的下划线 _ 转换为连字符 -（如 user_agent → User-Agent）
• 可通过 convert_underscores=False 禁用自动转换
• HTTP 头字段不区分大小写，可用 Python 的 snake_case 风格声明

3. 重复 Header 处理

@app.get("/batch/")
async def batch_header(
    x_token: Annotated[list[str], Header()]
):
    return {"tokens": x_token}

• 使用 list 类型接收多个相同名称的请求头值
• 示例请求头：

  curl -H "X-Token: foo" -H "X-Token: bar" http://localhost:8000/batch/

• 响应结果将包含所有值：{"tokens": ["foo", "bar"]}

4. 模型化处理

class CommonHeaders(BaseModel):
    user_agent: str
    x_api_version: str = "v1"

@app.get("/model/")
async def model_header(headers: Annotated[CommonHeaders, Header()]):
    return headers.dict()

• 通过 Pydantic 模型批量管理多个 Header 参数
• 自动验证并转换请求头字段
• 支持复用模型定义，适用于标准化接口场景

5. 注意事项

• 技术细节：Header 继承自 Param 类，与 Query/Path 为兄弟类
• 特殊字符处理：避免在禁用下划线转换时使用非常规字段名
• 文档展示：Swagger UI 自动生成请求头参数说明
• 数据验证：支持与 Field 结合进行参数校验（如长度限制）