FastAPI 路由与请求处理机制

news2025/1/7 13:41:27

FastAPI 路由与请求处理机制

📚 目录

🛤️ 路径操作函数 (Path Operation Functions) 设计原则
🗂️ 路由排序与路径组优化设计
🔄 请求方法与 RESTful 风格的语义实现

🛤️ 1. 路径操作函数 (Path Operation Functions) 设计原则

路径操作函数是 FastAPI 中处理 HTTP 请求的核心部分。它负责定义应用的路由、处理逻辑以及返回响应。路径操作函数不仅是 Web 开发的基础模块，还直接关系到接口的可维护性与代码的整洁程度。

🔧 1.1 路径操作函数的基本结构

在 FastAPI 中，每个路径操作函数都通过装饰器进行定义，并与特定的 HTTP 方法绑定。

🌟 代码示例

from fastapi import FastAPI

app = FastAPI()

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

🛠️ 代码解析

@app.get("/items/{item_id}")：定义了一个 GET 请求路径，路径中 {item_id} 是路径参数。
item_id: int：路径参数的类型声明，有助于数据验证。
函数返回一个字典，FastAPI 会自动将其转换为 JSON 格式。

🚧 1.2 动态路径参数

路径参数允许开发者在路径中嵌入动态部分，从而实现灵活的接口设计。

🌟 代码示例

@app.get("/users/{user_id}/orders/{order_id}")
def get_user_order(user_id: int, order_id: int):
    return {"user_id": user_id, "order_id": order_id}

🔧 代码解析

多层路径参数可以嵌套，体现 RESTful 风格的设计思路。
每个路径参数都需要在函数参数列表中明确声明其类型。

📍 1.3 查询参数与路径参数的结合

路径参数可以与查询参数结合使用，以实现更复杂的数据过滤和查询逻辑。

🌟 代码示例

@app.get("/products/{product_id}")
def get_product(product_id: int, q: str = None):
    return {"product_id": product_id, "query": q}

🔧 代码解析

q: str = None 定义了一个可选的查询参数 q，可以用于过滤或关键字搜索。
路径参数 product_id 和查询参数 q 可以在同一个路径操作函数中共存。

🗂️ 2. 路由排序与路径组优化设计

路由的排序直接影响到路径匹配的优先级，而路径组的划分可以提升代码的复用性和逻辑清晰度。合理的路径设计可以避免潜在的路径冲突，提升接口的可读性与一致性。

📏 2.1 路由顺序的重要性

路径匹配的顺序遵循“先匹配，先执行”的原则。如果多个路径存在重叠部分，则按照代码的定义顺序进行匹配。

🌟 代码示例

@app.get("/users")
def get_users():
    return {"message": "List of users"}

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

🔧 代码解析

如果将 /users/{user_id} 定义在 /users 之前，那么所有 /users 请求都会匹配为路径参数，导致用户列表接口无法访问。
先定义静态路径 /users，再定义动态路径 /users/{user_id}，符合路径优先级的设计原则。

🧩 2.2 路径分组与标签管理

路径分组可以通过 APIRouter 进行管理，将相似功能的接口归类，有助于模块化开发。

🌟 代码示例

from fastapi import APIRouter

router = APIRouter(prefix="/items", tags=["items"])

@router.get("/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id}

@router.post("/")
def create_item(name: str):
    return {"name": name}

app.include_router(router)

🔧 代码解析

使用 APIRouter 创建路由组，通过 prefix 为路径增加统一前缀。
tags 参数为接口添加标签，便于自动生成的 API 文档分类。

🔄 3. 请求方法与 RESTful 风格的语义实现

RESTful 风格强调资源的表现层状态转换，每个 HTTP 方法对应特定的操作语义。FastAPI 完全遵循这一设计原则，允许开发者通过不同的请求方法实现完整的 CRUD 操作。

🔄 3.1 HTTP 请求方法概览

GET：检索资源。
POST：创建新资源。
PUT：更新完整资源。
PATCH：部分更新资源。
DELETE：删除资源。

🌟 代码示例

@app.post("/items/")
def create_item(name: str):
    return {"message": f"Item '{name}' created."}

@app.put("/items/{item_id}")
def update_item(item_id: int, name: str):
    return {"message": f"Item {item_id} updated to '{name}'."}

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