FastAPI Web框架 [1.6]

Posted 2022-03-26 Ch4536251

模式的额外信息 - 例子

from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

#   您可以在JSON模式中定义额外的信息。
#
# 一个常见的用例是添加一个将在文档中显示的example。
#
# 有几种方法可以声明额外的 JSON 模式信息。

#   使用 Config 和 schema_extra 为Pydantic模型声明一个示例
class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

    class Config:
        schema_extra = 
            "example": 
                "name": "Foo",
                "description": "A very nice Item",
                "price": 35.4,
                "tax": 3.2,
            
        

@app.put("/items/item_id")
async def update_item(item_id: int, item: Item):
    results = "item_id": item_id, "item": item
    return results
#   这些额外的信息将按原样添加到输出的JSON模式中。


#   Field 的附加参数
#   在 Field, Path, Query, Body 和其他你之后将会看到的工厂函数，你可以为JSON 模式声明额外信息，你也可以通过给工厂函数传递其他的任意参数来给JSON 模式声明额外信息，比如增加 example:
from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(..., example="Foo")
    description: Optional[str] = Field(None, example="A very nice Item")
    price: float = Field(..., example=35.4)
    tax: Optional[float] = Field(None, example=3.2)


@app.put("/items/item_id")
async def update_item(item_id: int, item: Item):
    results = "item_id": item_id, "item": item
    return results
#   请记住，传递的那些额外参数不会添加任何验证，只会添加注释，用于文档的目的。


#   Body 额外参数
#   你可以通过传递额外信息给 Field 同样的方式操作Path, Query, Body等。
#
# 比如，你可以将请求体的一个 example 传递给 Body:
from typing import Optional

from fastapi import Body, FastAPI
from pydantic import BaseModel
app = FastAPI()

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

@app.put("/items/item_id")
async def update_item(
    item_id: int,
    item: Item = Body(
        ...,
        example=
            "name": "Foo",
            "description": "A very nice Item",
            "price": 35.4,
            "tax": 3.2,
        ,
    ),
):
    results = "item_id": item_id, "item": item
    return results

技术细节

关于 example 和 examples…
JSON Schema在最新的一个版本中定义了一个字段 examples ，但是OpenAPI 基于之前的一个旧版JSON Schema，并没有 examples.
所以 OpenAPI为了相似的目的定义了自己的example (使用 example, 而不是 examples), 这也是文档 UI 所使用的 (使用 Swagger UI).
所以，虽然 example 不是JSON Schema的一部分，但它是OpenAPI的一部分，这将被文档UI使用。

额外数据类型

到目前为止，一直在使用常见的数据类型，如:

int
float
str
bool

下面是一些你可以使用的其他数据类型:

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 一样处理。

from fastapi import FastAPI,Body
from datetime import datetime,timedelta,time
from typing import Optional
from uuid import UUID
app = FastAPI()

@app.put("/items/item_id")
async def read_items(
        item_id:UUID,
        start_datetime: Optional[datetime] = Body(None),
        end_datetime: Optional[datetime] = Body(None),
        repeat_at: Optional[time] = Body(None),
        process_after: Optional[timedelta] = Body(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,
    
#   注意，函数内的参数有原生的数据类型，你可以，例如，执行正常的日期操作

Cookie参数

#   可以像定义 Query 参数和 Path 参数一样来定义 Cookie 参数。
from fastapi import FastAPI,Cookie      #导入 Cookie
from typing import Optional
app = FastAPI()

@app.get("/items/")
async def read_items(ads_id:Optional[str] = Cookie(None)):          #   声明 Cookie 参数
    return "ads_id":ads_id
#   声明 Cookie 参数的结构与声明 Query 参数和 Path 参数时相同。
#   第一个值是参数的默认值，同时也可以传递所有验证参数或注释参数，来校验参数。

#   Cookie 、Path 、Query是兄弟类，它们都继承自公共的 Param 类.
#   但请记住，当你从 fastapi 导入的 Query、Path、Cookie 或其他参数声明函数，这些实际上是返回特殊类的函数。

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

Header参数

#   使用定义 Query, Path 和 Cookie 参数一样的方法定义 Header 参数。
from typing import Optional
from fastapi import FastAPI,Header  #   导入 Header
app = FastAPI()

@app.get("/items/")
async def read_items(user_agent:Optional[str] = Header(None)):          #声明 Header 参数,使用和Path, Query and Cookie 一样的结构定义 header 参数,
    #   第一个值是默认值，你可以传递所有的额外验证或注释参数
    return 
        "User-Agent":user_agent
    
#   Header 是 Path, Query 和 Cookie 的兄弟类型。它也继承自通用的 Param 类.
# 但是请记得，当你从fastapi导入 Query, Path, Header, 或其他时，实际上导入的是返回特定类型的函数。
#   为了声明headers， 你需要使用Header, 因为否则参数将被解释为查询参数。


#   自动转换
#   Header 在 Path, Query 和 Cookie 提供的功能之上有一点额外的功能。

# 大多数标准的headers用 "连字符" 分隔，也称为 "减号" (-)。
# 但是像 user-agent 这样的变量在Python中是无效的。
# 因此, 默认情况下, Header 将把参数名称的字符从下划线 (_) 转换为连字符 (-) 来提取并记录 headers.
# 同时，HTTP headers 是大小写不敏感的，因此，因此可以使用标准Python样式(也称为 "snake_case")声明它们。
# 因此，您可以像通常在Python代码中那样使用 user_agent ，而不需要将首字母大写为 User_Agent 或类似的东西。

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

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: Optional[str] = Header(None, convert_underscores=False)
):
    return "strange_header": strange_header
#   在设置 convert_underscores 为 False 之前，请记住，一些HTTP代理和服务器不允许使用带有下划线的headers。



#   重复的 headers
#   有可能收到重复的headers。这意味着，相同的header具有多个值。
#
# 您可以在类型声明中使用一个list来定义这些情况。
#
# 你可以通过一个Python list 的形式获得重复header的所有值。
#

# 比如, 为了声明一个 X-Token header 可以出现多次，你可以这样写：
from typing import List, Optional
from fastapi import FastAPI, Header
app = FastAPI()

@app.get("/items/")
async def read_items(x_token: Optional[List[str]] = Header(None)):
    return "X-Token values": x_token
#   如果你与路径操作通信时发送两个HTTP headers，就像：
# X-Token: foo
# X-Token: bar
#   响应会是:
#   
#     "X-Token values": [
#         "bar",
#         "foo"
#     ]
# 

#   使用 Header 来声明 header , 使用和 Query, Path 与 Cookie 相同的模式。
#
# 不用担心变量中的下划线，FastAPI 会负责转换它们。