fastapi-Headers和Cookies

在FastAPI中，Headers是一个特殊的类型，用于处理HTTP请求头（Headers）。Headers允许你接收、访问和修改HTTP请求中的头部信息。

使用Headers，你可以在FastAPI的路由视图中将请求头作为参数接收，并对它们进行操作

Headers

你可以使用定义Query、Path一样的方式来定义Header参数。使用如下：

from fastapi import Header

@router.get("/home")
async def home(authorization: str = Header()):
    return {'code': 1}

也可以这样定义：

from fastapi import Header
from typing import Annotated

@router.get("/home")
async def home(authorization: Annotated[str, Header()]):
    return {'code': 1}

当然，像Query、Path和Body等都可以使用Annotated这样来声明。

在Swagger UI中效果如下：

这样就表示该请求需要接收一个authorization标头，否则将会引发422错误，如下：

{
    "detail": [
        {
            "type": "missing",
            "loc": [
                "header",
                "authorization"
            ],
            "msg": "Field required",
            "input": null,
            "url": "https://errors.pydantic.dev/2.0.3/v/missing"
        }
    ]
}

大多数标准的Headers用"连字符"分隔，也称为"减号"(-)。但是像user-agent这样的变量在Python中是无效的。因此, 默认情况下, Header 将把参数名称的字符从下划线(_)转换为连字符(-)来提取并记录headers.

同时，HTTP headers 是大小写不敏感的，因此，因此可以使用标准Python样式(也称为 “snake_case”)声明它们。因此，您可以像通常在Python代码中那样使用 user_agent，而不需要将首字母大写为User_Agent或类似的东西。如果出于某些原因，你需要禁用下划线到连字符的自动转换，设置Header的参数 convert_underscores为 False:

@router.get("/home")
async def home(sp_name: str = Header(convert_underscores=False)):
    return {'code': 1}

Headers常见参数如下：

• default: 默认值，任何类型。 当设置了该值，表明该参数非必须参数
• default_factory: 生成的默认值的函数，接收一个Callable类型。default与default_factory不可同时存在
• alias: 别名, str类型
• title: Swagger UI中参数的标题，str类型。Path/Query操作不起作用
• description: Swagger UI中参数的描述，str类型
• convert_underscores: 是否将连字符转化为下划线，接收一个bool类型，默认为True
• gt: 大于，数字类型
• ge: 大于或等于，数字类型
• lt: 小于，数字类型
• le: 小于或等于，数字类型
• multiple_of: 接收一个数字类型，表示为几的倍数。例如multiple_of的值为2，那么该字段的值必须是2的倍数
• allow_inf_nan: bool类型，表示是否允许字段为NaN或无穷大(+inf或-inf)。默认为True，为与JSON兼容请设置为False。
• max_digits: int类型，表示最大位数，字段类型须设置为decimal.Decimal类型。长度计算中不包括小数点前的零或小数点后的零
• decimal_places: int类型，表小数最大位数，字段类型须设置为decimal.Decimal类型。长度计算中不包括小数点前的零或小数点后的零
• min_length: 最小长度，int类型
• max_length: 最大长度，int类型
• regex: 正则匹配，str类型
• example: Swagger UI中参数的示例值，任何类型
• examples: Swagger UI中参数的示例值，Dict类型。Path/Query操作不起作用
• deprecated: 是否过期，bool类型，默认False
• include_in_schema: Swagger UI中是否添加对参数的说明，bool类型，默认True

Cookies

在FastAPI中，Cookies是一个特殊的类型，用于处理HTTP请求中的Cookie数据。Cookies允许你接收、访问和修改HTTP请求中的Cookie信息。使用Cookies，你可以在FastAPI的路由视图中将Cookie数据作为参数接收，并对其进行操作。

同样，Cookies也可以像定义Query、Path一样的方式来定义Cookies参数。使用如下：

from fastapi import Cookie

@router.get("/home")
async def home(sp_name: str = Cookie()):
    return {'code': 1}

在Swagger UI中效果如下：

这样就表示该请求需要接收一个sp_nameCookie，否则将会引发422错误，如下：

{
    "detail": [
        {
            "type": "missing",
            "loc": [
                "cookie",
                "sp_name"
            ],
            "msg": "Field required",
            "input": null,
            "url": "https://errors.pydantic.dev/2.0.3/v/missing"
        }
    ]
}

Cookie接收的参数与Header基本相同，这里不做介绍