FastAPI 路由与请求处理机制
📚 目录
- 🛤️ 路径操作函数 (Path Operation Functions) 设计原则
- 🗂️ 路由排序与路径组优化设计
- 🔄 请求方法与 RESTful 风格的语义实现
🛤️ 1. 路径操作函数 (Path Operation Functions) 设计原则
路径操作函数是 FastAPI 中处理 HTTP 请求的核心部分。它负责定义应用的路由、处理逻辑以及返回响应。路径操作函数不仅是 Web 开发的基础模块，还直接关系到接口的可维护性与代码的整洁程度。
🔧 1.1 路径操作函数的基本结构
在 FastAPI 中，每个路径操作函数都通过装饰器进行定义，并与特定的 HTTP 方法绑定。
🌟 代码示例
from fastapi import FastAPIapp = 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 APIRouterrouter = 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."}
🔧 代码解析
- 每个路径操作函数绑定到特定的 HTTP 方法，保持了操作的语义清晰。
- 通过路径参数
item_id进行资源的动态定位，实现细粒度的资源管理。
