Header 参数¶
定义Header 参数的方式与定义Query、Path、Cookie 参数相同。
导入Header¶
首先，导入Header：
fromtypingimportAnnotatedfromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(user_agent:Annotated[str|None,Header()]=None):return{"User-Agent":user_agent}🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(user_agent:str|None=Header(default=None)):return{"User-Agent":user_agent}声明Header 参数¶
然后，使用和Path、Query、Cookie 一样的结构定义 header 参数。
第一个值是默认值，还可以传递所有验证参数或注释参数：
fromtypingimportAnnotatedfromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(user_agent:Annotated[str|None,Header()]=None):return{"User-Agent":user_agent}🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(user_agent:str|None=Header(default=None)):return{"User-Agent":user_agent}技术细节
Header 是Path、Query、Cookie 的兄弟类，都继承自共用的Param 类。
注意，从fastapi 导入的Query、Path、Header 等对象，实际上是返回特殊类的函数。
信息
必须使用Header 声明 header 参数，否则该参数会被解释为查询参数。
自动转换¶
Header 比Path、Query 和Cookie 提供了更多功能。
大部分标准请求头用连字符分隔，即减号（-）。
但是user-agent 这样的变量在 Python 中是无效的。
因此，默认情况下，Header 把参数名中的字符由下划线（_）改为连字符（-）来提取并存档请求头 。
同时，HTTP 的请求头不区分大小写，可以使用 Python 标准样式（即snake_case）进行声明。
因此，可以像在 Python 代码中一样使用user_agent ，无需把首字母大写为User_Agent 等形式。
如需禁用下划线自动转换为连字符，可以把Header 的convert_underscores 参数设置为False：
fromtypingimportAnnotatedfromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(strange_header:Annotated[str|None,Header(convert_underscores=False)]=None,):return{"strange_header":strange_header}🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(strange_header:str|None=Header(default=None,convert_underscores=False),):return{"strange_header":strange_header}警告
注意，使用convert_underscores = False 要慎重，有些 HTTP 代理和服务器不支持使用带有下划线的请求头。
重复的请求头¶
有时，可能需要接收重复的请求头。即同一个请求头有多个值。
类型声明中可以使用list 定义多个请求头。
使用 Pythonlist 可以接收重复请求头所有的值。
例如，声明X-Token 多次出现的请求头，可以写成这样：
fromtypingimportAnnotatedfromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(x_token:Annotated[list[str]|None,Header()]=None):return{"X-Token values":x_token}🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(x_token:list[str]|None=Header(default=None)):return{"X-Token values":x_token}与路径操作通信时，以下面的方式发送两个 HTTP 请求头：
X-Token: fooX-Token: bar响应结果是：
{"X-Token values":["bar","foo"]}小结¶
使用Header 声明请求头的方式与Query、Path 、Cookie 相同。
不用担心变量中的下划线，FastAPI 可以自动转换。