Python中FastAPI项目使用 Annotated的参数设计的处理方案

更新时间：2024年08月02日 10:01:28 作者：伍华聪

FastAPI 是一个非常现代化和高效的框架,非常适合用于构建高性能的 API,FastAPI 是一个用于构建 API 的现代、快速（高性能）web 框架,基于 Python 类型提示,这篇文章主要介绍了Python中FastAPI项目使用 Annotated的参数设计,需要的朋友可以参考下

FastAPI介绍

FastAPI 是一个用于构建 API 的现代、快速（高性能）web 框架，基于 Python 类型提示。它的主要特点包括自动生成 OpenAPI 和 JSON Schema 文档、快速代码编写、简洁的代码结构、高效的性能等。FastAPI 使用 Starlette 作为 Web 框架的核心，并使用 Pydantic 进行数据验证。

FastAPI 的主要特点

快速：
- FastAPI 的性能非常接近于 NodeJS 和 Go 等速度较快的语言，并且比其他基于 Python 的框架如 Flask 和 Django 快得多。
简洁：
- 通过类型提示和依赖注入，代码简洁易读。
- 开发者可以更少的代码实现更多的功能。
自动文档生成：
- FastAPI 自动生成符合 OpenAPI 规范的文档，这些文档可以通过内置的 Swagger UI 和 ReDoc UI 查看。
- 自动生成 JSON Schema。
数据验证：
- 基于 Pydantic，FastAPI 提供了强大的数据验证功能。
- 支持复杂的数据验证和数据解析。
类型提示：
- 充分利用 Python 的类型提示，帮助开发者编写和维护代码。
依赖注入：
- FastAPI 提供了一个简单但功能强大的依赖注入系统，可以方便地管理依赖项。

FastAPI 还支持以下功能：

文件上传
安全性（OAuth2、JWT 等）
后台任务
流媒体响应
GraphQL
SQL（通过 SQLAlchemy 等）
数据库事务
后台任务

安装 FastAPI 和 Uvicorn

pip install fastapi
pip install "uvicorn[standard]"

FastAPI 是一个非常现代化和高效的框架，非常适合用于构建高性能的 API。其自动文档生成、数据验证和依赖注入等特性，使得开发者能够更快、更安全地编写代码，并提供出色的用户体验。

FastAPI项目的参数设计，这些您可以在路径操作函数参数或使用Annotated的依赖函数中使用的特殊函数，用于从请求中获取数据。

它包括

Query()
Path()
Body()
Cookie()
Header()
Form()
File()

您可以直接从fastapi导入它们

from fastapi import Body, Cookie, File, Form, Header, Path, Query

1、Query参数-查询参数

Query参数是指我们在URL中带有的查询参数如url/items?q=123&b=234 的类型格式。

假设我们要创建一个API，其中的查询参数需要带有描述和默认值：

from fastapi import FastAPI, Query
from typing import Annotated
app = FastAPI()
@app.get("/items/")
async def read_items(
    q: Annotated[str, Query(description="Query string", min_length=3, max_length=50)] = "default"
):
    return {"q": q}

在这个例子中：

我们导入了FastAPI和Query类，以及Annotated类型。
我们创建了一个FastAPI应用实例。
我们定义了一个路径操作函数read_items，它有一个查询参数q。
我们使用Annotated类型为查询参数q添加了元数据，这些元数据包括描述、最小长度和最大长度等。
Annotated的第一个参数是类型提示，第二个参数是与此类型相关的元数据。

Annotated类型允许你将额外的元数据与类型提示关联，这在创建API时特别有用，因为它可以帮助生成更丰富的API文档并确保参数验证。

下面是一个更复杂的例子，展示了如何使用Annotated类型与依赖项结合：

from fastapi import Depends
def common_parameters(
    q: Annotated[str, Query(description="Query string", min_length=3, max_length=50)] = "default"
):
    return {"q": q}
@app.get("/items/")
async def read_items(params: Annotated[dict, Depends(common_parameters)]):
    return params

在这个例子中：

我们定义了一个依赖函数common_parameters，它返回一个包含查询参数q的字典。
我们使用Annotated类型和Depends将这个依赖项注入到路径操作函数read_items中。
read_items函数返回了从依赖函数中获取的参数字典。

这种方法不仅简化了路径操作函数的参数定义，还使得代码更具可读性和可维护性。

2、Path参数-路径参数

路径参数通常用于从 URL 路径中提取信息。例如，如果你有一个获取用户信息的路径 /users/{user_id}，你可以这样定义路径参数：

from fastapi import FastAPI
from fastapi.params import Path
from typing import Annotated
app = FastAPI()
@app.get("/users/{user_id}")
async def read_user(user_id: Annotated[int, Path(..., title="The ID of the user to get")]):
    return {"user_id": user_id}

在这个示例中，Annotated[int, Path(..., title="The ID of the user to get")] 表示 user_id 是一个整数，并且它是从路径中提取的参数。此外，我们还为这个参数添加了一个标题，用于生成 API 文档。

3、Body参数-请求体参数

求体参数用于处理复杂的数据结构，例如 JSON 请求体。你可以使用 Pydantic 模型来定义请求体的结构，并使用 Annotated 来进一步注解这些参数。例如：

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Annotated
app = FastAPI()
class User(BaseModel):
    name: str
    age: int
@app.post("/users/")
async def create_user(user: Annotated[User, Body(..., title="The user to create")]):
    return {"user": user}

在这个示例中，Annotated[User, Body(..., title="The user to create")] 表示 user 参数是一个 User 模型实例，并且它来自请求体。我们同样为这个参数添加了一个标题。

有时候我们可以结合路径参数和请求体参数进行使用，如下例子：

from fastapi import FastAPI, Path, Body
from pydantic import BaseModel
from typing import Annotated
app = FastAPI()
class User(BaseModel):
    name: str
    age: int
@app.put("/users/{user_id}")
async def update_user(
    user_id: Annotated[int, Path(..., title="The ID of the user to update")],
    user: Annotated[User, Body(..., title="The new user data")]
):
    return {"user_id": user_id, "user": user}

在这个综合示例中，路径参数 user_id 和请求体参数 user 都使用了 Annotated 进行注解，以明确它们的来源和意图，同时为生成的 API 文档提供了更多的上下文信息。

复杂的请求体通常包括嵌套的结构，可以使用 Pydantic 模型来定义。例如：

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List, Annotated
app = FastAPI()
class Address(BaseModel):
    street: str
    city: str
    state: str
    zip: str
class User(BaseModel):
    name: str
    age: int
    addresses: List[Address]
@app.post("/users/")
async def create_user(user: Annotated[User, Body(..., title="The user to create")]):
    return {"user": user}

在这个例子中，User 模型包含一个嵌套的 Address 列表，这样你就可以在请求体中处理复杂的嵌套数据结构。

一个结合路径参数、查询参数和请求体参数的复杂示例：

from fastapi import FastAPI, Path, Query, Body
from pydantic import BaseModel
from typing import Annotated
app = FastAPI()
class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
@app.put("/items/{item_id}")
async def update_item(
    item_id: Annotated[int, Path(..., title="The ID of the item to update")],
    q: Annotated[str | None, Query(None, max_length=50, title="Query string")],
    item: Annotated[Item, Body(..., title="The item to update")]
):
    result = {"item_id": item_id, "item": item}
    if q:
        result.update({"q": q})
    return result

在这个综合示例中，我们使用了路径参数 item_id、查询参数 q 和请求体参数 item，并通过 Annotated 对这些参数进行注解，明确它们的来源和约束。

应用上面的处理方案，我们在项目中应用FastApi构建文档如下所示。

到此这篇关于Python中FastAPI项目使用 Annotated的参数设计的文章就介绍到这了,更多相关Python FastAPI使用 Annotated内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

解决Tkinter中button按钮未按却主动执行command函数的问题
这篇文章主要介绍了解决Tkinter中button按钮未按却主动执行command函数的问题，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-05-05
Python使用openpyxl从URL读取Excel并获取单元格样式
这篇文章主要为大家详细介绍了如何基于openpyxl库实现从URL读取Excel文件并提取单元格内容和样式信息的方法,文中的示例代码讲解详细,感兴趣的小伙伴可以了解下
2026-01-01
python列表的常用操作方法小结
这篇文章主要为大家详细介绍了python字典的常用操作方法，主要内容包含Python中列表(List)的详解操作方法,包含创建、访问、更新、删除、其它操作等,需要的朋友可以参考下
2016-05-05
详解如何在Python中使用Jinja2进行模板渲染
Jinja2 是一个现代的、设计精美的 Python 模板引擎,它使用类似于 Django 的模板语言来渲染文本文件,下面我将通过几个例子展示如何在 Python 中使用 Jinja2 进行模板渲染,文中有详细的代码供大家参考,需要的朋友可以参考下
2024-08-08
利用Python创建位置生成器的示例详解
在这篇文章中，我们将探索如何利用Python在美国各地城市的地图数据和公共电动自行车订阅源上训练一个快速生成的对抗网络（GAN）模型，需要的可以参考一下
2022-06-06
python爬虫beautiful soup的使用方式
这篇文章主要介绍了python爬虫beautiful soup的使用方式，Beautiful Soup依据给定的解释器来解析html文档，其依据html中标签把html文档在内存中转化为类似于二叉树的数据结构，并通过实现的查询方法来查询二叉树以得到我们想要的爬虫数据
2022-08-08
python3.7.2 tkinter entry框限定输入数字的操作
这篇文章主要介绍了python3.7.2 tkinter entry框限定输入数字的操作，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-05-05
python实现多线程及线程间通信的简单方法
这篇文章主要为大家介绍了python实现多线程及线程间通信的简单方法示例，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
2023-07-07
关于numpy强制类型转换的问题
这篇文章主要介绍了关于numpy强制类型转换的问题，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2022-05-05
python用WxPython库实现无边框窗体和透明窗体实现方法详解
这篇文章主要介绍了python用WxPython库实现无边框窗体和透明窗体实现方法详解,需要的朋友可以参考下
2020-02-02