FastAPI自学教程（17） - Header参数模型

1. 模型化声明Header参数

from typing import Annotated
from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()

class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None

@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

• 支持使用Pydantic模型批量管理多个Header参数（FastAPI 0.115.0+特性）
• 自动提取请求头字段并进行数据验证与类型转换
• 模型可复用，适用于需要统一校验规则的接口场景

2. 多版本兼容写法

# Python 3.8+兼容写法
from typing import Union
from fastapi import Header
from pydantic import BaseModel

class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: Union[str, None] = None
    traceparent: Union[str, None] = None

@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

• 推荐优先使用Annotated注解方式（Python 3.10+）
• 旧版本需使用Union类型声明可选参数
• 支持同时定义默认值和字段校验规则

3. 禁止额外Headers配置

class StrictHeaders(BaseModel):
    model_config = {"extra": "forbid"}
    
    host: str
    user_agent: str

@app.get("/strict/")
async def strict_headers(headers: Annotated[StrictHeaders, Header()]):
    return headers

• 通过model_config = {"extra": "forbid"}限制未声明Header
• 客户端发送未定义Header时返回422错误（如x-unexpected）
• 适用于需要严格安全管控的接口场景

4. 注意事项

• 字段转换：默认将参数名的下划线_转换为连字符-（如user_agent→User-Agent）
• 文档交互：Swagger UI自动生成Header参数说明，但需手动发送测试请求
• 验证优先级：模型字段校验规则会覆盖Header参数的基础验证逻辑
• 大小写处理：HTTP headers不区分大小写，可用Python的snake_case风格声明

---