Python Web 开发：FastAPI 基本概念与应用

目录

• ✨ 1. FastAPI 路由（定义请求路径）
• 🚀 2. HTTP 请求方法（GET、POST、PUT、DELETE）
• 🔑 3. 参数类型（路径参数、查询参数、请求体）
  • 🌍 查询参数（query）
  • 🛣️ 路径参数（path）
  • 📝 请求体（body）

---

✨ 1. FastAPI 路由（定义请求路径）

在 FastAPI 中，路由是定义在应用实例上的一组函数，用于响应 HTTP 请求。路由的核心是通过 URL 路径和 HTTP 请求方法来匹配请求，这些请求会由相应的函数处理。每个路由装饰器（如 @app.get()、@app.post()）都代表一个特定的请求路径和 HTTP 方法。

路由基本定义

FastAPI 提供了简单而强大的路由机制。定义一个基本的路由时，只需在 FastAPI 实例上使用装饰器来指定 HTTP 方法和路径。以下是一个最简单的示例：

# app/main.py
from fastapi import FastAPI

# 创建 FastAPI 应用实例
app = FastAPI()

# 定义一个 GET 路由
@app.get("/")
def read_root():
    return {"message": "Welcome to FastAPI!"}

在上述代码中，我们通过 @app.get("/") 定义了一个根路径的 GET 请求，当访问 http://127.0.0.1:8000/ 时，会返回 JSON 响应 {"message": "Welcome to FastAPI!"}。

动态路由与路径参数

FastAPI 路由也支持动态路径参数，这使得可以通过 URL 路径传递信息。这些参数可以用于获取数据库中的特定资源，或者进行其他计算。

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

在这个例子中，{item_id} 表示一个路径参数。当访问 http://127.0.0.1:8000/items/42 时，FastAPI 会将路径中的 42 传递给 item_id 变量。

多路径和多方法支持

一个 FastAPI 路由不仅支持单一的路径和方法，实际上，可以为同一路径配置多种 HTTP 方法，比如 GET 和 POST 方法，用于处理不同类型的请求。以下是如何为同一路径添加多个路由：

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"message": f"Fetching item {item_id}"}

@app.post("/items/{item_id}")
def create_item(item_id: int):
    return {"message": f"Creating item {item_id}"}

在这个示例中，同一个路径 /items/{item_id} 通过 GET 和 POST 方法分别提供不同的服务。GET 方法用于获取项目，而 POST 方法用于创建项目。

路由分组与组织

对于复杂应用，随着功能增加，路由管理也会变得更加复杂。FastAPI 提供了路由分组的功能，可以通过 APIRouter 来组织路由，将相关功能的路由分配到不同的模块中。例如，可以创建一个用于管理用户的路由模块，另一个用于处理商品数据的路由模块。

from fastapi import APIRouter

router = APIRouter()

@router.get("/users/{user_id}")
def read_user(user_id: int):
    return {"user_id": user_id}

# 将子路由注册到主应用
app.include_router(router)

通过这种方式，开发者可以保持路由结构的清晰和可维护性，避免单一文件中路由过多导致的代码混乱。

---

🚀 2. HTTP 请求方法（GET、POST、PUT、DELETE）

在 Web 开发中，不同的 HTTP 请求方法有不同的用途，它们是 HTTP 协议的一部分，用来指示客户端请求的意图。在 FastAPI 中，可以通过不同的路由装饰器来定义不同的 HTTP 方法。

GET 请求

GET 请求是最常见的 HTTP 方法，用于请求资源。它通常用于获取数据或展示信息，而不会对服务器上的数据进行任何修改。FastAPI 使用 @app.get() 来处理 GET 请求。

@app.get("/items/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id, "name": "Example Item"}

GET 请求通常是无副作用的，也就是说，它不会修改服务器上的任何数据。它只是请求某些数据。

POST 请求

与 GET 请求不同，POST 请求通常用于提交数据，以便服务器进行处理。这类请求会改变服务器的状态，通常用于创建新的资源。FastAPI 使用 @app.post() 来处理 POST 请求。

@app.post("/items/")
def create_item(item: dict):
    return {"message": "Item created", "item": item}

在这个例子中，POST 请求用于接收一个 JSON 数据，并返回创建的项的信息。POST 请求通常用于向服务器提交表单数据，或创建新的资源。

PUT 请求

PUT 请求用于更新现有的资源。与 POST 请求不同，PUT 请求通常是幂等的，意味着多次执行同样的 PUT 请求不会导致不同的结果。FastAPI 使用 @app.put() 来处理 PUT 请求。

@app.put("/items/{item_id}")
def update_item(item_id: int, item: dict):
    return {"message": f"Item {item_id} updated", "item": item}

PUT 请求接收的数据通常是完整的资源数据，它会替换服务器上指定资源的当前状态。

DELETE 请求

DELETE 请求用于删除服务器上的资源。当客户端发送一个 DELETE 请求时，通常是请求服务器删除某个指定的资源。FastAPI 使用 @app.delete() 来处理 DELETE 请求。

@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"message": f"Item {item_id} deleted"}

DELETE 请求通常用于从数据库中删除指定的数据，或者清理服务器上的某些资源。

小结

通过 GET、POST、PUT 和 DELETE 等 HTTP 请求方法，FastAPI 为开发者提供了处理不同类型请求的灵活性。在实际开发中，了解并正确使用这些请求方法对于设计良好的 API 至关重要。通过合理的 HTTP 方法使用，可以确保 API 的语义清晰且符合 RESTful 风格。

---

🔑 3. 参数类型（路径参数、查询参数、请求体）

FastAPI 提供了强大的参数类型支持，能够非常简便地处理 URL 路径、查询参数以及请求体的参数。这些参数可以帮助开发者在处理请求时灵活获取数据。

🌍 查询参数（query）

查询参数通常出现在 URL 的 ? 后面，并且以 key=value 的形式传递给服务器。在 FastAPI 中，查询参数会自动被映射为函数的参数，可以使用默认值来定义可选的查询参数。

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

在这个例子中，skip 和 limit 是查询参数，它们的默认值分别是 0 和 10。当请求 URL 为 http://127.0.0.1:8000/items/?skip=5&limit=15 时，FastAPI 会将 skip 设置为 5，limit 设置为 15。

查询参数通常用于分页、筛选和排序等场景。通过为查询参数提供默认值，FastAPI 可以轻松实现这些常见的功能。

🛣️ 路径参数（path）

路径参数是在 URL 路径中传递的变量，它们用于标识请求的特定资源。路径参数通常出现在 URL 中的 {} 中，在 FastAPI 中，我们可以通过定义路径参数来动态地处理不同的资源。

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

在这个例子中，item_id 是路径参数，FastAPI 会自动从 URL 中提取路径参数的值，并将其传递给处理函数。在访问 http://127.0.0.1:8000/items/42 时，item_id 会被自动解析为 42。

路径参数通常用于资源标识符，它们是 URL 的一部分，必须匹配请求的路径。

📝 请求体（body）

请求体通常用于发送更复杂的数据，特别是 POST、PUT 或 PATCH 请求。

请求体可以是 JSON 格式的对象、表单数据或文件。FastAPI 支持通过 Pydantic 模型来验证和解析请求体。

from pydantic import BaseModel

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

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

在这个例子中，Item 是一个 Pydantic 模型，它自动验证请求体的数据结构是否符合要求。FastAPI 会自动将请求体的 JSON 数据转换为 Item 实例，并传递给处理函数。

请求体通常用于提交复杂的数据，比如创建或更新资源时所需的信息。

小结

FastAPI 提供了非常灵活的参数处理机制，通过路径参数、查询参数和请求体，开发者可以轻松地从不同的 HTTP 请求中提取数据，并根据需要进行处理。通过自动验证和类型注解，FastAPI 确保了数据的完整性和正确性，减少了开发者的负担。

---