路径参数¶
你可以使用与 Python 格式化字符串相同的语法声明路径“参数”或“变量”
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id):
return {"item_id": item_id}
路径参数 item_id 的值将作为参数 item_id 传递给你的函数。
因此，如果你运行此示例并访问 http://127.0.0.1:8000/items/foo，你将看到以下响应：
{"item_id":"foo"}
带类型的路径参数¶
你可以使用标准的 Python 类型注解在函数中声明路径参数的类型
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
在这种情况下，item_id 被声明为 int 类型。
检查
这将在你的函数内部提供编辑器支持，包括错误检查、自动补全等。
数据转换¶
如果你运行此示例并在浏览器中打开 http://127.0.0.1:8000/items/3，你将看到以下响应：
{"item_id":3}
检查
请注意，你的函数接收（并返回）的值是 3，这是一个 Python int 类型，而不是字符串 "3"。
因此，通过这种类型声明，FastAPI 提供了自动请求“解析”功能。
数据验证¶
但如果你在浏览器中访问 http://127.0.0.1:8000/items/foo，你将看到一个友好的 HTTP 错误：
{
"detail": [
{
"type": "int_parsing",
"loc": [
"path",
"item_id"
],
"msg": "Input should be a valid integer, unable to parse string as an integer",
"input": "foo",
"url": "https://errors.pydantic.dev/2.1/v/int_parsing"
}
]
}
因为路径参数 item_id 的值为 "foo"，这不是一个 int 类型。
如果你提供一个 float 而不是 int，也会出现同样的错误，例如： http://127.0.0.1:8000/items/4.2
检查
因此，通过相同的 Python 类型声明，FastAPI 为你提供了数据验证。
请注意，错误还会清楚地指明验证失败的具体位置。
这在开发和调试与你的 API 交互的代码时非常有帮助。
文档¶
当你打开浏览器访问 http://127.0.0.1:8000/docs 时，你将看到一个自动的、交互式的 API 文档，如下所示：
检查
同样，仅仅通过相同的 Python 类型声明，FastAPI 就能为你提供自动的、交互式的文档（集成 Swagger UI）。
请注意，路径参数被声明为整数类型。
基于标准的好处，替代文档¶
由于生成的模式遵循 OpenAPI 标准，因此有许多兼容的工具。
正因为如此，FastAPI 本身提供了另一种 API 文档（使用 ReDoc），你可以在 http://127.0.0.1:8000/redoc 访问它
同样，还有许多兼容的工具。包括针对多种语言的代码生成工具。
Pydantic¶
所有的数据验证都由 Pydantic 在底层执行，因此你将获得其所有好处。而且你知道你使用的是可靠的工具。
你可以使用 str、float、bool 和许多其他复杂数据类型进行相同的类型声明。
其中一些将在教程的后续章节中探讨。
顺序很重要¶
在创建路径操作时，你可能会遇到固定路径的情况。
比如 /users/me，假设它是用于获取当前用户的数据。
然后你也可以有一个路径 /users/{user_id}，用于通过某个用户 ID 获取特定用户的数据。
因为路径操作是按顺序评估的，所以你需要确保 /users/me 的路径在 /users/{user_id} 之前声明
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/me")
async def read_user_me():
return {"user_id": "the current user"}
@app.get("/users/{user_id}")
async def read_user(user_id: str):
return {"user_id": user_id}
否则，/users/{user_id} 的路径也会匹配 /users/me，并“认为”它接收到的参数 user_id 的值是 "me"。
同样，你不能重新定义路径操作
from fastapi import FastAPI
app = FastAPI()
@app.get("/users")
async def read_users():
return ["Rick", "Morty"]
@app.get("/users")
async def read_users2():
return ["Bean", "Elfo"]
第一个将始终被使用，因为路径首先匹配。
预定义值¶
如果你有一个接收路径参数的路径操作，但你希望可能的有效路径参数值是预定义的，你可以使用标准的 Python Enum。
创建一个 Enum 类¶
导入 Enum 并创建一个继承自 str 和 Enum 的子类。
通过继承 str，API 文档将能够知道这些值必须是 string 类型，并能够正确渲染。
然后创建具有固定值的类属性，这些属性将是可用的有效值
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model_name": model_name, "message": "Deep Learning FTW!"}
if model_name.value == "lenet":
return {"model_name": model_name, "message": "LeCNN all the images"}
return {"model_name": model_name, "message": "Have some residuals"}
提示
如果你想知道，“AlexNet”、“ResNet”和“LeNet”只是机器学习模型的名称。
声明一个路径参数¶
然后使用你创建的枚举类（ModelName）作为类型注解，创建一个路径参数
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model_name": model_name, "message": "Deep Learning FTW!"}
if model_name.value == "lenet":
return {"model_name": model_name, "message": "LeCNN all the images"}
return {"model_name": model_name, "message": "Have some residuals"}
检查文档¶
因为路径参数的可用值是预定义的，交互式文档可以很好地显示它们
使用 Python 枚举¶
路径参数的值将是一个枚举成员。
比较枚举成员¶
你可以将其与你创建的枚举 ModelName 中的枚举成员进行比较
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model_name": model_name, "message": "Deep Learning FTW!"}
if model_name.value == "lenet":
return {"model_name": model_name, "message": "LeCNN all the images"}
return {"model_name": model_name, "message": "Have some residuals"}
获取枚举值¶
你可以使用 model_name.value 获取实际值（在本例中为 str），或者通常使用 your_enum_member.value
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model_name": model_name, "message": "Deep Learning FTW!"}
if model_name.value == "lenet":
return {"model_name": model_name, "message": "LeCNN all the images"}
return {"model_name": model_name, "message": "Have some residuals"}
提示
你也可以通过 ModelName.lenet.value 访问值 "lenet"。
返回枚举成员¶
你可以从路径操作返回枚举成员，即使嵌套在 JSON 主体（例如 dict）中也可以。
在将它们返回给客户端之前，它们将被转换为相应的值（在本例中为字符串）
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model_name": model_name, "message": "Deep Learning FTW!"}
if model_name.value == "lenet":
return {"model_name": model_name, "message": "LeCNN all the images"}
return {"model_name": model_name, "message": "Have some residuals"}
在你的客户端，你将收到一个 JSON 响应，如下所示：
{
"model_name": "alexnet",
"message": "Deep Learning FTW!"
}
包含路径的路径参数¶
假设你有一个路径操作，其路径为 /files/{file_path}。
但是你需要 file_path 本身包含一个路径，例如 home/johndoe/myfile.txt。
所以，该文件的 URL 将类似于：/files/home/johndoe/myfile.txt。
OpenAPI 支持¶
OpenAPI 不支持声明一个路径参数包含路径的方式，因为这可能导致难以测试和定义的场景。
然而，你仍然可以在 FastAPI 中使用 Starlette 的一个内部工具来实现它。
并且文档仍然有效，尽管不会添加任何说明该参数应包含路径的文档。
路径转换器¶
通过直接使用 Starlette 的一个选项，你可以使用如下 URL 声明一个包含路径的路径参数：
/files/{file_path:path}
在这种情况下，参数的名称是 file_path，最后一部分 :path 告诉它该参数应该匹配任何路径。
所以，你可以这样使用它：
from fastapi import FastAPI
app = FastAPI()
@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
return {"file_path": file_path}
提示
你可能需要参数包含 /home/johndoe/myfile.txt，带有一个前导斜杠（/）。
在这种情况下，URL 将是：/files//home/johndoe/myfile.txt，在 files 和 home 之间有一个双斜杠（//）。
总结¶
使用 FastAPI，通过使用简短、直观和标准的 Python 类型声明，你将获得：
- 编辑器支持：错误检查、自动补全等。
- 数据“解析”
- 数据验证
- API 注解和自动文档
并且你只需要声明一次。
这可能是 FastAPI 相对于其他框架的主要显著优势（除了原始性能）。