# 导入 Pydantic 的 BaseModel
from pydantic import BaseModel

#将数据模型声明为继承自 BaseModel 的类,使用标准的 Python 类型来声明所有属性
class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None

类似查询参数，某字段若非必须，可为其设置一个默认值或可选 None，否则该字段就是必须的。

上面的模型声明了一个这样的 JSON「object」（或 Python dict）：

{
    "name": "Foo",
    "description": "An optional description",
    "price": 45.2,
    "tax": 3.5
}

因为 description 和 tax 是可选的（它们的默认值为 None），那么下面的 JSON「object」也是有效的：

{
    "name": "Foo",
    "price": 45.2
}

② 声明为参数

类似路径参数和查询参数，可以使用相同的方式声明请求体，并且将它的类型声明为你创建的 Item 模型，完整代码：

from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None

app = FastAPI()

@app.post("/items1/")
async def create_item(item: Item):
    return item

此时，我们可以使用交互文档、postman、apifox等工具进行请求测试，后边将使用交互文档进行测试。

仅仅使用了 Python 类型声明，FastAPI 将做以下事情：

将请求体作为 JSON 读取。
校验数据。
如果数据无效，将返回一条清晰易读的错误信息，指出不正确数据的确切位置和内容。
将接收的数据赋值到参数 item 中。
这些模式将成为生成的 OpenAPI 模式的一部分，并且被自动化文档 UI 所使用。

在函数内部，你可以直接访问模型对象的所有属性：

...

@app.post("/items2/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

📌 文档

你所定义模型的 JSON 模式将可以在交互式 API 文档中展示：

【Python开发】FastAPI 03：请求参数—请求体-LMLPHP

③ 请求体 + 路径参数 + 查询参数

你还可以同时声明请求体、路径参数和查询参数。

...

@app.put("/items3/{item_id}")
async def create_item(item_id: int, item: Item, q: Union[str, None] = None):
    result = {"item_id": item_id, **item.dict()}
    if q:
        result.update({"q": q})
    return result

请求参数将依次按如下规则进行识别：

如果在路径中也声明了该参数，它将被用作路径参数。
如果参数属于单一类型（比如 int、float、str、bool 等）它将被解释为查询参数。
如果参数的类型被声明为一个 Pydantic 模型，它将被解释为请求体。

④ 数据模型使用 Field

与使用 Query、Path 类似，你可以使用 Pydantic 的 Field 在 Pydantic 模型内部声明校验和元数据。

from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel, Field #导入 Field

app = FastAPI()

class Item1(BaseModel): #对模型属性使用 Field
    name: str
    description: Union[str, None] = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(
        gt=0, description="The price must be greater than zero"
    )
    tax: Union[float, None] = None

@app.put("/items4/{item_id}")
async def update_item(item_id: int, item: Item1):
    results = {"item_id": item_id, "item": item}
    return results

Field 的工作方式和 Query 和 Path 相同，包括它们的参数等等也完全相同，详情可以查看上一章内容~

1.2 使用 Body

与使用 Query 和 Path 为查询参数和路径参数定义额外数据的方式相同，FastAPI 提供了一个同等的 Body。

① 单一值的请求体

如果该请求参数是一个单一值（比如 str、int 等），但是依旧想让他以请求体的形式存在，那么可以使用 Body 来修饰，不然系统将默认他是一个查询参数。

from typing import Union

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    username: str
    full_name: Union[str, None] = None

@app.put("/items5/{item_id}")
async def update_item(item_id: int, user: User, single: int = Body()):
    results = {"item_id": item_id, "user": user, "single": single}
    return results

此时，FastAPI 期望的请求体如下：

{
    "user": {
        "username": "yinyu",
        "full_name": "yinyuyu"
    },
    "single": 5
}

② 嵌入单个请求体参数

如果你想要这个 JSON 外再带一个 key，那么可以使用嵌入的特殊 Body 参数：

user: User = Body(embed=True)

比如：

...

@app.put("/items6/{item_id}")
async def update_item(item_id: int, user: User = Body(embed=True)):
    results = {"item_id": item_id, "user": user}
    return results

此时，FastAPI 期望的请求体如下：

{
    "user": {
        "username": "yinyu",
        "full_name": "yinyuyu"
    }
}

而不是：

{
    "username": "yinyu",
    "full_name": "yinyuyu"
}

2 请求体中的嵌套模型

使用 FastAPI，你可以定义、校验、记录文档并使用任意深度嵌套的模型（归功于 Pydantic）

2.1 List 字段

① 未声明元素类型

你可以将一个请求体模型的属性/字段定义为拥有子元素的类型。例如 Python list：

from typing import List, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Model1(BaseModel):
    name: str
    price: float
    tags: list = []

@app.put("/model1/{model_id}")
async def update_model(model_id: int, model: Model1):
    results = {"model_id": model_id, "model": model}
    return results

此时，FastAPI 期望的请求体可以如下：

{
  "name": "string",
  "price": 0,
  "tags": [1, "yinyu"]
}

因为 tags 只是一个由元素组成的列表，它没有声明每个元素的类型，因此可以放多个类型的元素进去。

② 声明元素类型

如果我们想指定列表中的元素类型，那么 Python 也提供了一种特定的方法：

要声明具有子类型的类型，例如 list、dict、tuple：

从 typing 模块导入它们
使用方括号 [ ] 将子类型作为「类型参数」传入

from typing import List

my_list: List[str]

因此，在我们的示例中，我们可以将 tags 明确地指定为一个「字符串列表」：

...

class Model2(BaseModel):
    name: str
    price: float
    tags: List[str] = [] #声明具有子类型的列表,要声明具有子类型的类型，例如 list、dict、tuple：

@app.put("/model2/{model_id}")
async def update_model(model_id: int, model: Model2):
    results = {"model_id": model_id, "model": model}
    return results

2.2 Set 类型

如果你希望列表中的元素不能重复，那么 set 这一数据类型可以很好的满足该要求：

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Model3(BaseModel):
    name: str
    price: float
    mtags: Set[str] = set()

@app.put("/model3/{model_id}")
async def update_model(model_id: int, model: Model3):
    results = {"model_id": model_id, "model": model}
    return results

此时，FastAPI 期望的请求体可以如下：

{
  "name": "yinyu",
  "price": 0,
  "mtags": ["handsome","handsome"]
}

正确请求后的响应内容则如下：

{
  "model_id": 1,
  "model": {
    "name": "string",
    "price": 0,
    "mtags": ["1"]
  }
}

这样，即使你收到带有重复数据的请求，后台也会将重复元素进行筛选后保留一项。

2.3 嵌套模型

Pydantic 模型的每个属性/字段都具有类型，那么你可以使得该属性也是一个 Pydantic 模型

from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

#定义一个 Image 模型作为子模型
class Image(BaseModel):
    url: str
    name: str

class Base1(BaseModel):
    name: str
    description: Union[str, None] = None
    image: Union[Image, None] = None #将子模型用作类型

@app.put("/base1/{base_id}")
async def update_base(base_id: int, base: Base1):
    results = {"item_id": base_id, "item": base}
    return results

此时，FastAPI 期望的请求体可以如下：

{
    "name": "yinyu",
    "description": "The pretender",
    "image": {
        "url": "http://yinyu.com",
        "name": "The yinyu live"
    }
}

2.4 特殊的类型和校验

① HttpUrl

在 Image 模型中我们有一个 url 字段，我们可以把它声明为 Pydantic 的 HttpUrl，而不是 str，类似的特殊类型可以在 Field Types - Pydantic 页面查看。

from pydantic import BaseModel, HttpUrl

class Image(BaseModel):
    url: HttpUrl
    name: str

② 纯列表请求体

如果你期望的 JSON 请求体的最外层是一个 JSON array（即 Python list），则可以在路径操作函数的参数中声明此类型，就像声明 Pydantic 模型一样：

from typing import List

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()

class Image(BaseModel):
    url: HttpUrl
    name: str

@app.post("/images/multiple/")
async def create_multiple_images(images: List[Image]):
    return images

此时，FastAPI 期望的请求体可以如下 👇，可以有 n 个 Image。

[
  {
    "url": "www.11.com",
    "name": "yin"
  },
  {
    "url": "www.22.com",
    "name": "yu"
  }
]

3 额外数据类型及参数

3.1 其他数据类型

Python 同样支持更复杂的数据类型：

UUID:
- 一种标准的 "通用唯一标识符" ，在许多数据库和系统中用作ID。
- 在请求和响应中将以 str 表示。
datetime.datetime:
- 一个 Python datetime.datetime.
- 在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 2008-09-15T15:53:00+05:00.
datetime.date:
- Python datetime.date.
- 在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 2008-09-15.
datetime.time:
- 一个 Python datetime.time.
- 在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 14:23:55.003.
datetime.timedelta:
- 一个 Python datetime.timedelta.
- 在请求和响应中将表示为 float 代表总秒数。
- Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", 查看文档了解更多信息。
frozenset:
- 在请求和响应中，作为 set 对待：
- 在请求中，列表将被读取，消除重复，并将其转换为一个 set。
- 在响应中 set 将被转换为 list 。
- 产生的模式将指定那些 set 的值是唯一的 (使用 JSON 模式的 uniqueItems)。
bytes:
- 标准的 Python bytes。
- 在请求和相应中被当作 str 处理。
- 生成的模式将指定这个 str 是 binary "格式"。
Decimal:
- 标准的 Python Decimal。
- 在请求和相应中被当做 float 一样处理。

比如下面的例子，就使用了上述的一些类型：

@app.put("/items/{item_id}")
async def read_items(
    item_id: UUID,
    start_datetime: Union[datetime, None] = Body(default=None),
    end_datetime: Union[datetime, None] = Body(default=None),
    repeat_at: Union[time, None] = Body(default=None),
    process_after: Union[timedelta, None] = Body(default=None),
):
    start_process = start_datetime + process_after
    duration = end_datetime - start_process
    return {
        "item_id": item_id,
        "start_datetime": start_datetime,
        "end_datetime": end_datetime,
        "repeat_at": repeat_at,
        "process_after": process_after,
        "start_process": start_process,
        "duration": duration,
    }

其中函数内的参数有原生的数据类型，可以执行正常的日期操作。

3.2 Cookie 参数

声明 Cookie 参数的结构与声明 Query 参数和 Path 参数时相同，第一个值是参数的默认值，同时也可以传递所有验证参数或注释参数，来对 Cookie 参数进行校验：

from typing import Union

from fastapi import Cookie, FastAPI

app = FastAPI()

@app.get("/items1/")
async def read_items(ads_id: Union[str, None] = Cookie(default=None)):
    return {"ads_id": ads_id}

必须使用 Cookie 来声明 cookie 参数，否则参数将会被解释为查询参数。

3.3 Header 参数

你可以使用定义 Query、Path 和 Cookie 参数一样的方法定义 Header 参数。

① 声明 Header 参数

同样，第一个值是默认值，你可以传递所有的额外验证或注释参数：

from typing import Union

from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items2/")
async def read_items(user_agent: Union[str, None] = Header(default=None)):
    return {"User-Agent": user_agent}

必须使用 Header 来声明 Header 参数，否则参数将会被解释为查询参数。

② 自动转换

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

同时，HTTP headers 是大小写不敏感的，你可以像通常在 Python 代码中那样使用 user_agent ，而不需要将首字母大写为 User_Agent 或类似的东西。

如果出于某些原因，你需要禁用下划线到连字符的自动转换，那么可设置 Header 的参数 convert_underscores 为 False:

from typing import Union

from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items/")
async def read_items(
    strange_header: Union[str, None] = Header(default=None, convert_underscores=False)
):
    return {"strange_header": strange_header}

尹煜

【Python开发】FastAPI 03：请求参数—请求体

1 声明请求体

1.1 使用 Pydantic 模型

① 创建数据模型

② 声明为参数

③ 请求体 + 路径参数 + 查询参数

④ 数据模型使用 Field

1.2 使用 Body

① 单一值的请求体

② 嵌入单个请求体参数

2 请求体中的嵌套模型

2.1 List 字段

① 未声明元素类型

② 声明元素类型

2.2 Set 类型

2.3 嵌套模型

2.4 特殊的类型和校验

① HttpUrl

② 纯列表请求体

3 额外数据类型及参数

3.1 其他数据类型

3.2 Cookie 参数

3.3 Header 参数

① 声明 Header 参数

② 自动转换