FastAPI Header 参数详解：使用 Header 声明、校验并接收 HTTP 请求头

FastAPI Header 参数详解使用 Header 声明、校验并接收 HTTP 请求头【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文基于 FastAPI 官方教程文档docs/de/docs/tutorial/header-params.md展开系统讲解如何在 FastAPI 中声明 Header 参数、自动下划线转换机制convert_underscores以及重复 Header 的列表接收方式。读完本文你可以掌握与Query/Path/Cookie一致的 Header 参数声明模式理解 FastAPI 底层如何把 Python 风格的user_agent变量映射到 HTTP 头User-Agent并能正确接收多次发送的同一 Header。1. 概述Header 参数与 Query、Path、Cookie 同源在 FastAPI 中Header 参数可以完全按照Query、Path和Cookie参数的方式定义。它们共享同一套参数抽象都能声明默认值default也都能使用全部校验与元数据参数如title、description、min_length、pattern等。2. 导入 Header首先需要从fastapi中导入Headerfrom typing import Annotated from fastapi import FastAPI, Header完整示例见 docs_src/header_params/tutorial001_an_py310.py。技术细节Header 是 Param 的“姐妹”类从 fastapi/params.py 的源码可以看到Param是所有请求位置参数的公共基类它本身继承自 Pydantic 的FieldInfo而Header正是其子类之一class Param(FieldInfo): in_: ParamTypes ... class Header(Param): # type: ignore[misc] in_ ParamTypes.headerParamTypes枚举fastapi/params.py定义了四种参数位置query、header、path、cookie每个子类通过类属性in_标记自己所属的位置。需要特别注意的是从fastapi导入的Header、Query、Path等实际是函数它们内部构造并返回对应的参数类实例。可以查看 fastapi/param_functions.py 中的Header()函数——它的每个参数都带有Annotated[..., Doc(...)]文档注解最终执行return params.Header(...)。这意味着编辑器能通过该函数的类型提示和 Docstring 为Header()调用提供完整的自动补全与文档提示。3. 声明 Header 参数声明 Header 参数时使用与Path、Query、Cookie相同的结构可以定义默认值以及所有额外的校验或元数据参数。现代推荐的Annotated风格写法来自 docs_src/header_params/tutorial001_an_py310.pyfrom typing import Annotated from fastapi import FastAPI, Header app FastAPI() app.get(/items/) async def read_items(user_agent: Annotated[str | None, Header()] None): return {User-Agent: user_agent}等价的“旧式”默认值写法来自 docs_src/header_params/tutorial001_py310.pyfrom fastapi import FastAPI, Header app FastAPI() app.get(/items/) async def read_items(user_agent: str | None Header(defaultNone)): return {User-Agent: user_agent}重要提示必须使用Header来声明 Header 参数。如果不显式使用HeaderFastAPI 会把该参数当作Query 参数处理。这一点在 fastapi/dependencies/utils.py 中可以得到印证当字段没有标记参数位置时field_info.in_ is NoneFastAPI 会默认将其归入ParamTypes.query。4. 自动转换下划线转连字符Header相比Path、Query和Cookie提供了一项额外功能——自动转换。大多数标准 HTTP Header 名称使用连字符-分隔单词。但在 Python 中user-agent是非法变量名。因此Header默认会把参数名中的下划线_转换为连字符-用于从请求头中提取数据并生成 OpenAPI 文档。同时HTTP Header 名称的大小写不敏感所以你可以按标准 Python 风格snake_case声明变量例如写user_agent而不必写成User_Agent之类的怪异形式。源码层面的两处转换点下划线转换发生在两个层面依赖分析阶段运行时取值在 fastapi/dependencies/utils.py 中如果字段设置了convert_underscores且没有显式 alias则生成-形式别名作为提取数据的依据if not field_info.alias and getattr(field_info, convert_underscores, None): alias param_name.replace(_, -) else: alias field_info.alias or param_name field_info.alias alias请求头提取阶段在 fastapi/dependencies/utils.py 中当received_params是 Starlette 的Headers对象时FastAPI 按字段读取各自的convert_underscores设置再把校验别名中的_替换为-去请求头里取值if isinstance(received_params, Headers): convert_underscores getattr( field.field_info, convert_underscores, default_convert_underscores ) if convert_underscores: alias get_validation_alias(field) if alias field.name: alias alias.replace(_, -)OpenAPI 文档阶段在 fastapi/openapi/utils.py 中生成/docs可见的 Schema 时同样会对 header 类型参数执行name.replace(_, -)保证文档中展示的 Header 名如user-agent与线上行为一致。禁用自动转换convert_underscoresFalse如果确实需要禁用下划线到连字符的自动转换把Header的参数convert_underscores设为False示例来自 docs_src/header_params/tutorial002_an_py310.pyfrom typing import Annotated from fastapi import FastAPI, Header app FastAPI() app.get(/items/) async def read_items( strange_header: Annotated[str | None, Header(convert_underscoresFalse)] None, ): return {strange_header: strange_header}convert_underscores的默认值是True在参数类 fastapi/params.py 的Header.__init__中显式定义为关键字参数convert_underscores: bool True并被保存为实例属性self.convert_underscores供后续提取与文档生成逻辑读取。警告在把convert_underscores设为False之前请注意一些 HTTP 代理和服务器不允许使用带下划线的 Header 名称。因此在生产环境中除非有充分理由否则建议保持默认的自动转换行为。另外从源码结构看fastapi/dependencies/utils.py当 Header 以 Pydantic 模型整体声明时禁用convert_underscores的方式是在模型层使用Header(convert_underscoresFalse)FastAPI 会以该模型字段的field_info属性作为default_convert_underscores默认值再叠加每个字段自身可能的Header(...)设置。5. 重复 Header同一个 Header 多个值HTTP 协议允许同一个 Header 名出现多次、携带多个值。FastAPI 通过在类型声明中使用list来接收这类重复 Header声明时把类型写为list[...]例如list[str]FastAPI 会收集该 Header 的全部值最终以 Pythonlist形式传入你的函数。以可重复出现的X-TokenHeader 为例示例来自 docs_src/header_params/tutorial003_an_py310.pyfrom typing import Annotated from fastapi import FastAPI, Header app FastAPI() app.get(/items/) async def read_items(x_token: Annotated[list[str] | None, Header()] None): return {X-Token values: x_token}当客户端向该路径操作发送两个 HTTP HeaderX-Token: foo X-Token: bar响应Response即服务器返回给客户端的数据为{ X-Token values: [ bar, foo ] }这一行为有专门的测试覆盖可参考 tests/test_request_params/test_header/test_list.py 与 tests/test_request_params/test_header/test_optional_list.py它们分别验证了必填列表 Header 与可空列表 Headerlist[str] | None的取值行为。6. Header 参数可用的完整参数清单由于Header继承自Paramfastapi/params.py它继承了 PydanticFieldInfo的大部分能力。结合 fastapi/param_functions.py 中Header()函数的签名常用参数包括参数默认值说明defaultUndefined参数未设置时的默认值Path参数不适用总是必填default_factory_Unset生成默认值的可调用对象aliasNone参数别名用于提取数据和生成 OpenAPIalias_priority_Unset别名优先级影响是否使用别名生成器validation_aliasNone校验阶段的“白名单”别名支持AliasPath/AliasChoicesserialization_aliasNone序列化阶段的别名convert_underscoresTrueHeader 独有是否自动把参数名中的下划线转换为连字符title/descriptionNone人类可读的标题与描述写入 OpenAPIgt/ge/lt/leNone数值大小校验min_length/max_lengthNone字符串长度校验patternNone字符串正则校验regex已废弃用pattern替代strict_Unset是否启用严格校验multiple_of/allow_inf_nan/max_digits/decimal_places_Unset数值约束examplesNone字段示例值列表openapi_examplesNoneOpenAPI 专属示例在/docs中可见deprecatedNone在生成的 OpenAPI 中标记为已弃用include_in_schemaTrue是否包含在生成的 OpenAPI 中json_schema_extraNone附加的 JSON Schema 数据需要注意的默认值语义default的默认值是Undefined而非None这意味着如果声明Annotated[str, Header()]而不给默认值该 Header 就是必填的客户端未提供时会返回 422 校验错误写成Annotated[str | None, Header()] None则是可选参数。7. 总结使用Header声明 Header 参数使用与Query、Path、Cookie完全一致的通用模式并支持全部校验与元数据参数不必担心变量名中的下划线——Header默认convert_underscoresTrue会自动把user_agent转换为user-agent去提取请求头并生成文档确需关闭时显式传入convert_underscoresFalse但要留意部分代理/服务器不支持带下划线的 Header 名需要在fastapi中显式导入并使用Header否则参数会被当作 Query 参数接收重复 Header 时把类型声明为list[...]FastAPI 会把所有值作为 Python 列表传入。相关仓库资源示例源码见 docs_src/header_params/核心实现见 fastapi/params.py、fastapi/param_functions.py、fastapi/dependencies/utils.py 与 fastapi/openapi/utils.py。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考