Python中FastAPI项目使用 Annotated的参数设计

伍华聪2024-08-01 12:29

在FastAPI中，你可以使用PEP 593中的Annotated类型来添加元数据到类型提示中。这个功能非常有用，因为它允许你在类型提示中添加更多的上下文信息，例如描述、默认值或其他自定义元数据。

FastAPI支持Annotated类型，这使得你可以为路径操作函数的参数提供额外的元数据，例如依赖项、查询参数的描述、别名等。

FastAPI介绍

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

FastAPI 的主要特点

  1. 快速：

    • FastAPI 的性能非常接近于 NodeJS 和 Go 等速度较快的语言，并且比其他基于 Python 的框架如 Flask 和 Django 快得多。

  2. 简洁：

    • 通过类型提示和依赖注入，代码简洁易读。
    • 开发者可以更少的代码实现更多的功能。

  3. 自动文档生成：

    • FastAPI 自动生成符合 OpenAPI 规范的文档，这些文档可以通过内置的 Swagger UI 和 ReDoc UI 查看。
    • 自动生成 JSON Schema。

  4. 数据验证：

    • 基于 Pydantic，FastAPI 提供了强大的数据验证功能。
    • 支持复杂的数据验证和数据解析。

  5. 类型提示：

    • 充分利用 Python 3.6+ 的类型提示，帮助开发者编写和维护代码。

  6. 依赖注入：

    • 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}

在这个例子中：

  1. 我们导入了FastAPI和Query类，以及Annotated类型。
  2. 我们创建了一个FastAPI应用实例。
  3. 我们定义了一个路径操作函数read_items，它有一个查询参数q。
  4. 我们使用Annotated类型为查询参数q添加了元数据，这些元数据包括描述、最小长度和最大长度等。
  5. 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

在这个例子中：

  1. 我们定义了一个依赖函数common_parameters，它返回一个包含查询参数q的字典。
  2. 我们使用Annotated类型和Depends将这个依赖项注入到路径操作函数read_items中。
  3. 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构建文档如下所示。

相关推荐
伍华聪24 天前
一问一答学习PyQT6，对比WxPython和PyQt6的差异
python开发
伍华聪1 个月前
WxPython跨平台开发框架之使用PyInstaller 进行打包处理
python开发
伍华聪1 个月前
WxPython跨平台开发框架之模块字段权限的管理
python开发
伍华聪1 个月前
WxPython跨平台开发框架之动态菜单的管理和功能权限的控制
python开发
伍华聪1 个月前
WxPython跨平台开发框架之前后端结合实现附件信息的上传及管理
python开发
伍华聪1 个月前
WxPython跨平台开发框架之图标选择界面
python开发
伍华聪1 个月前
WxPython跨平台开发框架之列表数据的通用打印处理
python开发
伍华聪1 个月前
WxPython跨平台开发框架之复杂界面内容的分拆和重组处理
python开发
伍华聪2 个月前
WxPython跨平台开发框架之参数配置管理界面的设计和实现
python开发
伍华聪2 个月前
WxPython跨平台开发框架之表格数据导出到Excel并打开
python开发
热门推荐
01DeepSeek r1本地安装全指南02【deepseek】deepseek-r1本地部署-第一步：下载LM Studio03将DeepSeek接入Word，打造AI办公助手04使用Ollama 在Ubuntu运行deepseek大模型：以DeepSeek-coder为例05新鲜速递：DeepSeek-R1开源大模型本地部署实战—Ollama + MaxKB 搭建RAG检索增强生成应用06Dell服务器升级ubuntu 22.04失败解决07DeepSeek学术写作测评第一弹：论文润色，中译英效果如何？08如何解压7z文件？8种方法（Win/Mac/手机/网页端）09半导体应用系统一些小知识收集(strip&wafer mapping,EAP&scada)10DeepSeek 云端部署，释放无限 AI 潜力！