FastAPI开发文档教程-Header参数

admin
admin
admin
0
文章
0
评论
2026-01-10 10:52:53 编程 来源：ZONE.CI 全球网 0 阅读模式
  • 导入 Header
  • 声明 Header 参数
  • 自动转换
  • 重复的请求头
  • 小结

    定义 Header 参数的方式与定义 Query、Path、Cookie 参数相同。

    导入 Header

    首先，导入 Header：

    Python 3.10+ Python 3.9+ Python 3.8+Python 3.10+ non-Annotated Python 3.8+ non-Annotated

    1. from typing import Annotated
    3. from fastapi import FastAPI, Header 
    4. app = FastAPI()
    6. @app.get("/items/")
    7. async def read_items(user_agent: Annotated[str | None, Header()] = None):
    8.     return {"User-Agent": user_agent}
    1. from typing import Annotated, Union
    3. from fastapi import FastAPI, Header 
    4. app = FastAPI()
    6. @app.get("/items/")
    7. async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
    8.     return {"User-Agent": user_agent}
    1. from typing import Union
    3. from fastapi import FastAPI, Header from typing_extensions import Annotated
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
    9.     return {"User-Agent": user_agent}

    尽可能选择使用 Annotated 的版本。

    1. from fastapi import FastAPI, Header 
    2. app = FastAPI()
    4. @app.get("/items/")
    5. async def read_items(user_agent: str | None = Header(default=None)):
    6.     return {"User-Agent": user_agent}

    尽可能选择使用 Annotated 的版本。

    1. from typing import Union
    3. from fastapi import FastAPI, Header 
    4. app = FastAPI()
    6. @app.get("/items/")
    7. async def read_items(user_agent: Union[str, None] = Header(default=None)):
    8.     return {"User-Agent": user_agent}

    声明 Header 参数

    然后，使用和 Path、Query、Cookie 一样的结构定义 header 参数。

    第一个值是默认值，还可以传递所有验证参数或注释参数：

    Python 3.10+ Python 3.9+ Python 3.8+Python 3.10+ non-Annotated Python 3.8+ non-Annotated

    1. from typing import Annotated
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(user_agent: Annotated[str | None, Header()] = None):
    9.     return {"User-Agent": user_agent}
    1. from typing import Annotated, Union
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
    9.     return {"User-Agent": user_agent}
    1. from typing import Union
    3. from fastapi import FastAPI, Header
    4. from typing_extensions import Annotated
    6. app = FastAPI()
    8. @app.get("/items/")
    9. async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
    10.     return {"User-Agent": user_agent}

    尽可能选择使用 Annotated 的版本。

    1. from fastapi import FastAPI, Header
    3. app = FastAPI()
    5. @app.get("/items/")
    6. async def read_items(user_agent: str | None = Header(default=None)):
    7.     return {"User-Agent": user_agent}

    尽可能选择使用 Annotated 的版本。

    1. from typing import Union
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(user_agent: Union[str, None] = Header(default=None)):
    9.     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：

    Python 3.10+ Python 3.9+ Python 3.8+Python 3.10+ non-Annotated Python 3.8+ non-Annotated

    1. from typing import Annotated
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(
    9.  strange_header: Annotated[str | None, Header(convert_underscores=False)] = None, ):
    10.     return {"strange_header": strange_header}
    1. from typing import Annotated, Union
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(
    9.     strange_header: Annotated[
    10.  Union[str, None], Header(convert_underscores=False)    ] = None,
    11. ):
    12.     return {"strange_header": strange_header}
    1. from typing import Union
    3. from fastapi import FastAPI, Header
    4. from typing_extensions import Annotated
    6. app = FastAPI()
    8. @app.get("/items/")
    9. async def read_items(
    10.     strange_header: Annotated[
    11.  Union[str, None], Header(convert_underscores=False)    ] = None,
    12. ):
    13.     return {"strange_header": strange_header}

    尽可能选择使用 Annotated 的版本。

    1. from fastapi import FastAPI, Header
    3. app = FastAPI()
    5. @app.get("/items/")
    6. async def read_items(
    7.  strange_header: str | None = Header(default=None, convert_underscores=False), ):
    8.     return {"strange_header": strange_header}

    尽可能选择使用 Annotated 的版本。

    1. from typing import Union
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(
    9.  strange_header: Union[str, None] = Header(default=None, convert_underscores=False), ):
    10.     return {"strange_header": strange_header}

    注意，使用 convert_underscores = False 要慎重，有些 HTTP 代理和服务器不支持使用带有下划线的请求头。

    重复的请求头

    有时，可能需要接收重复的请求头。即同一个请求头有多个值。

    类型声明中可以使用 list 定义多个请求头。

    使用 Python list 可以接收重复请求头所有的值。

    例如，声明 X-Token 多次出现的请求头，可以写成这样：

    Python 3.10+Python 3.9+Python 3.8+Python 3.10+ non-AnnotatedPython 3.9+ non-AnnotatedPython 3.8+ non-Annotated

    1. from typing import Annotated
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
    9.     return {"X-Token values": x_token}
    1. from typing import Annotated, List, Union
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
    9.     return {"X-Token values": x_token}
    1. from typing import List, Union
    3. from fastapi import FastAPI, Header
    4. from typing_extensions import Annotated
    6. app = FastAPI()
    8. @app.get("/items/")
    9. async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
    10.     return {"X-Token values": x_token}

    尽量选择 Annotated 版本.

    1. from fastapi import FastAPI, Header
    3. app = FastAPI()
    5. @app.get("/items/")
    6. async def read_items(x_token: list[str] | None = Header(default=None)):
    7.     return {"X-Token values": x_token}

    尽可能选择使用 Annotated 的版本。

    1. from typing import Union
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(x_token: Union[list[str], None] = Header(default=None)):
    9.     return {"X-Token values": x_token}

    尽可能选择使用 Annotated 的版本。

    1. from typing import List, Union
    3. from fastapi import FastAPI, Header
    5. app = FastAPI()
    7. @app.get("/items/")
    8. async def read_items(x_token: Union[List[str], None] = Header(default=None)):
    9.     return {"X-Token values": x_token}

    与路径操作通信时，以下面的方式发送两个 HTTP 请求头：

    X-Token: foo X-Token: bar

    响应结果是：

    { "X-Token values": [ "bar", "foo" ] }

    小结

    使用 Header 声明请求头的方式与 Query、Path 、Cookie 相同。

    不用担心变量中的下划线，FastAPI 可以自动转换。

    版权声明

    本站仅做备份收录，仅供研究与教学参考之用。
    读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。

    ZONE.CI 全球网 | 安全领域涉猎者-乌云独行地带
    ZONE.CI 全球网
    安全领域涉猎者-乌云独行地带
    FastAPI开发文档教程-额外数据类型 编程

    FastAPI开发文档教程-额外数据类型

    额外数据类型其他数据类型例子 FastAPI学习教程 - 用户指南 额外数据类型到目前为止，您一直在使用常见的数据类型，如:intfloatstrbool 但是您也可以使用更复杂的数据类型。 您仍然会
    01-100 评论
    ZONE.CI 全球网 | 安全领域涉猎者-乌云独行地带
    安全领域涉猎者-乌云独行地带
    ZONE.CI 全球网
    评论：0   参与：  0