FastAPI 在何时/何地使用 Body/Path/Query/Field

在本文中，我们将介绍在 FastAPI 中何时和何地使用 Body/Path/Query/Field。FastAPI 是一个高性能的现代化 Web 框架，它提供了简单易用的方式来构建 API。使用 FastAPI，我们可以轻松地处理来自客户端的请求，并返回相应的数据。

阅读更多：FastAPI 教程

什么是 Body/Path/Query/Field？

在开始讨论何时和何地使用 Body/Path/Query/Field 之前，让我们先了解一下它们的含义。

Body：Body 是一个相对于请求体的概念，它用于在请求中携带数据。在 FastAPI 中，我们可以使用 Body 参数来访问请求体中的数据。
Path：Path 是请求 URL 中的一部分，用于传递路径参数。在 FastAPI 中，我们可以使用 Path 参数来获取 URL 中的路径参数。
Query：Query 用于传递查询参数，通常会在 URL 的末尾使用 ? 符号跟上参数。在 FastAPI 中，我们可以使用 Query 参数来访问查询参数。
Field：Field 是 Pydantic 模型中的一个概念，用于定义模型中的字段和字段的一些属性。在 FastAPI 中，我们可以使用 Field 参数来定义模型中的字段和字段的属性。

使用 Body/Path/Query/Field 的场景举例

下面我们将通过一些具体的场景来演示何时和何地使用 Body/Path/Query/Field。

使用 Body 参数传递请求体数据

如果我们需要从请求体中获取数据，我们可以使用 Body 参数。例如，我们需要创建一个 API 来接收一个名为 user 的用户对象，那么我们可以这样定义路由：

from fastapi import FastAPI, Body
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    age: int

@app.post("/users")
async def create_user(user: User = Body(...)):
    return {"message": "User created successfully", "user": user}

在上述示例中，我们使用 Body(...) 参数来指定请求体中的数据应该被解析成 User 类型的对象。这样当我们向 /users 路由发送一个 POST 请求，并传递一个 JSON 格式的用户对象时，FastAPI 将会根据 User 类型的定义来解析并验证请求体中的数据，并将解析后的数据作为 user 参数传递给 create_user 函数。

使用 Path 参数传递路径参数

如果我们需要从 URL 中获取路径参数，我们可以使用 Path 参数。例如，我们需要创建一个 API 来获取指定用户的详细信息，那么我们可以这样定义路由：

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int = Path(..., description="The ID of the user")):
    return {"message": f"Getting details of user with ID: {user_id}"}

在上述示例中，我们使用 Path(...) 参数来指定路径参数的类型和必要性。这样当我们向 /users/{user_id} 路由发送一个 GET 请求，并传递一个代表用户 ID 的整数参数时，FastAPI 将会将该参数解析并传递给 get_user 函数。

使用 Query 参数传递查询参数

如果我们需要从 URL 中获取查询参数，我们可以使用 Query 参数。例如，我们需要创建一个 API 来获取指定页码的用户列表，那么我们可以这样定义路由：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/users")
async def get_users(page: int = Query(1, description="The page number")):
    return {"message": f"Getting users from page: {page}"}

在上述示例中，我们使用 Query(1) 参数来指定查询参数的类型和默认值。这样当我们向 /users 路由发送一个 GET 请求时，如果没有传递页码参数，默认值 1 将被使用；如果传递了页码参数，FastAPI 将会将该参数解析并传递给 get_users 函数。

使用 Field 参数定义模型字段和属性

如果我们需要定义 Pydantic 模型中的字段和属性，我们可以使用 Field 参数。例如，我们需要创建一个 API 来接收一个名为 user 的用户对象，但只验证并接收其中的 name 字段，忽略 age 字段，那么我们可以这样定义模型：

from fastapi import FastAPI, Body, Field
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str = Field(..., description="The name of the user")

@app.post("/users")
async def create_user(user: User = Body(...)):
    return {"message": "User created successfully", "user": user}

在上述示例中，我们使用 Field(...) 参数来指定字段的属性，例如 description，这样当 FastAPI 解析用户传递的数据时，将会按照字段定义和属性进行验证和解析，只接收并验证 name 字段。