Python中FastAPI项目使用 Annotated的参数设计
在FastAPI中,你可以使用PEP 593中的Annotated
类型来添加元数据到类型提示中。这个功能非常有用,因为它允许你在类型提示中添加更多的上下文信息,例如描述、默认值或其他自定义元数据。
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构建文档如下所示。