【Python】FastAPI：请求与响应

在 FastAPI 中，前端和后端之间的通信主要通过 HTTP 请求和响应进行。了解请求和响应的格式、代码书写方式，以及它们在前后端交互中的作用，是开发 FastAPI 应用的重要环节。以下是对这些内容的详细介绍，分模块讲解。

HTTP 请求格式

请求方法

HTTP 请求方法定义了客户端希望在服务器上执行的操作。常见的 HTTP 请求方法包括：

• GET：请求资源的表示形式。通常用于读取数据。
• POST：将数据发送到服务器以创建资源。
• PUT：将资源的全部内容替换为请求体中的内容。
• PATCH：部分修改资源。
• DELETE：删除资源。

请求 URL 和路径参数

请求 URL 是前端与后端通信的基础，它包含了资源的路径。路径参数是 URL 的一部分，可以动态变化，例如：

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

在这个例子中，item_id 是一个路径参数，前端可以发送 /items/5 来请求 ID 为 5 的物品。

查询参数

查询参数附加在 URL 后，用于传递额外的参数，通常用于过滤或排序。例如：

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

在这个例子中，skip 和 limit 是查询参数，前端可以发送 /items/?skip=0&limit=10。

请求体

请求体通常用于 POST、PUT、PATCH 方法，用来传递数据到服务器。请求体可以是 JSON 格式，表单数据或其他类型。在 FastAPI 中，通常使用 Pydantic 模型来声明请求体的数据结构：

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

@app.post("/items/")
async def create_item(item: Item):
    return item

在这个例子中，请求体是一个 JSON 对象，例如：

{
    "name": "Widget",
    "description": "A useful item",
    "price": 19.99,
    "tax": 1.99
}

HTTP 响应格式

响应状态码

响应状态码是后端返回给前端的结果状态，常见的状态码包括：

• 200 OK：请求成功。
• 201 Created：资源创建成功（通常用于 POST 请求）。
• 400 Bad Request：请求无效，通常是请求数据格式错误。
• 404 Not Found：请求的资源不存在。
• 500 Internal Server Error：服务器内部错误。

响应体

响应体是服务器返回给客户端的数据，通常以 JSON 格式返回。在 FastAPI 中，您可以直接返回字典、列表、Pydantic 模型或其他类型的数据：

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id, "name": "Widget", "price": 19.99}

这个例子返回一个 JSON 对象：

{
    "item_id": 5,
    "name": "Widget",
    "price": 19.99
}

自定义响应

您可以使用 JSONResponse 或 Response 自定义响应，例如设置状态码、响应头等：

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    return JSONResponse(status_code=201, content={"message": "Item created", "item": item.dict()})

在这个例子中，status_code 被设置为 201 Created，响应体是自定义的 JSON 对象。

代码书写方式

路径操作函数

路径操作函数是 FastAPI 应用的核心，它们定义了应用的 API 端点以及如何处理请求。每个路径操作函数都由一个装饰器（如 @app.get）和一个 Python 函数组成：

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

请求参数和路径参数

路径参数在路径操作函数中作为函数参数定义，并且类型注释可以用于类型验证：

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

查询参数和请求体参数也是通过函数参数定义的：

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

@app.post("/items/")
async def create_item(item: Item):
    return item

响应模型

您可以使用 Pydantic 模型定义响应的格式，以确保输出数据的一致性：

from pydantic import BaseModel

class ItemResponse(BaseModel):
    name: str
    price: float
    tax: float | None = None

@app.get("/items/{item_id}", response_model=ItemResponse)
async def read_item(item_id: int):
    return {"name": "Widget", "price": 19.99, "tax": 1.99}

这里，response_model 确保响应的数据结构符合 ItemResponse 模型的定义。

前后端交互流程

1. 前端发送请求：前端发送一个 HTTP 请求，可能包括路径参数、查询参数和请求体。

2. 后端处理请求：FastAPI 在服务器端解析请求，根据路径操作函数处理请求，并使用 Pydantic 验证和处理数据。

3. 后端返回响应：后端生成一个 HTTP 响应，包含状态码和响应体数据，返回给前端。

4. 前端处理响应：前端接收到响应数据后，解析并显示给用户，或进一步处理。

通过这种方式，FastAPI 实现了高效的前后端数据交互，确保了数据的安全性、有效性和一致性。