当前位置：首页 > news >正文

快速掌握 FastAPI 路由：从基础到进阶

news 2026/4/16 3:24:22

前言

FastAPI 是一个现代的、快速（高性能）的 Web 框架，用于构建 API。它基于 Python 类型注解，支持自动生成 OpenAPI 文档，且性能优越，适合构建高效的 Web API。本文将详细介绍如何在 FastAPI 中使用路由处理请求，帮助新手更好地理解如何使用 FastAPI 创建 Web 应用。

一、什么是 FastAPI 路由？

在 FastAPI 中，路由是将 HTTP 请求与相应的处理函数进行映射的机制。当用户通过浏览器或其他客户端发起请求时，FastAPI 根据请求的 URL 路径和 HTTP 方法（GET、POST、PUT、DELETE等）找到相应的视图函数进行处理。

通过定义不同的路由，FastAPI 能够为各种请求提供相应的响应，并且可以自动生成文档，方便开发者和用户查看和测试 API。

二、FastAPI 路由基础

1. 定义基本路由

FastAPI 中的路由非常简单，主要通过@app.get()、@app.post()等装饰器来定义。最基本的路由示例如下：

fromfastapiimportFastAPI app=FastAPI()@app.get("/")defread_root():return{"message":"Hello, World!"}

代码解析：

@app.get("/")：表示当访问根路径/时，调用read_root()函数。
read_root()：返回一个字典，FastAPI 会自动将其转换为 JSON 响应。

2. 路由支持不同的 HTTP 方法

FastAPI 支持处理不同的 HTTP 请求方法，如GET、POST、PUT、DELETE等。可以使用相应的装饰器来定义不同的方法。

@app.post("/create")defcreate_item(item:dict):return{"message":"Item created","data":item}

代码解析：

@app.post("/create")：定义一个 POST 请求的路由，当访问/create路径时，调用create_item()函数。
item: dict：FastAPI 会自动将 POST 请求的 JSON 数据解析成 Python 字典传递给item参数。

三、路由参数与类型注解

1. 路由参数

FastAPI 允许从路径中提取参数，例如当我们访问/items/42时，42可以作为一个参数传递给视图函数。

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

代码解析：

/{item_id}：FastAPI 会将路径中的item_id提取为一个参数并传递给视图函数。
item_id: int：FastAPI 会自动将路径中的参数转换为指定的类型，保证参数类型的正确性。

2. 路由查询参数

除了路径参数外，我们还可以在 URL 中传递查询参数。例如访问/items?q=python时，可以获取查询参数q。

@app.get("/items")defsearch_items(q:str=None):return{"query":q}

代码解析：

q: str = None：q是一个查询参数，FastAPI 会从 URL 中解析q参数的值，如果没有提供该参数，默认为None。

四、路径参数与查询参数混合

有时我们需要同时使用路径参数和查询参数。FastAPI 完全支持这种需求，可以在函数中同时定义路径参数和查询参数。

@app.get("/items/{item_id}")defread_item(item_id:int,q:str=None):return{"item_id":item_id,"query":q}

代码解析：

/items/{item_id}：从路径中获取item_id。
q: str = None：从查询参数中获取q。

当用户访问/items/42?q=python时，item_id的值为42，q的值为python。

五、验证与类型注解

FastAPI 强大的地方在于它自动进行参数验证和类型检查。你可以通过类型注解来指定参数的类型，FastAPI 会根据这些注解进行自动验证。

1. 请求体的验证

FastAPI 支持将请求体解析为 Python 对象，支持 Pydantic 数据模型。你可以定义一个 Pydantic 模型来验证请求体的数据。

frompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str=Noneprice:floattax:float=None@app.post("/items/")defcreate_item(item:Item):return{"item":item}

代码解析：

Item是一个 Pydantic 模型，它定义了请求体的结构。
create_item(item: Item)：FastAPI 会自动验证请求体是否符合Item模型的要求。

2. 数字范围验证

FastAPI 还支持通过类型注解来定义参数的验证规则，例如你可以限制数字参数的范围。

@app.get("/items/{item_id}")defread_item(item_id:int,price:float=0.0):ifprice<0:raiseValueError("Price cannot be negative")return{"item_id":item_id,"price":price}

代码解析：

price: float = 0.0：提供一个查询参数price，并进行验证，确保它的值是一个非负数。

六、路由重定向与错误处理

1. 路由重定向

在某些情况下，我们可能希望对某些路径进行重定向。FastAPI 提供了简单的机制来实现路由重定向。

fromfastapi.responsesimportRedirectResponse@app.get("/old")defredirect_to_new():returnRedirectResponse(url='/new')

代码解析：

RedirectResponse(url='/new')：当访问/old路径时，会自动重定向到/new路径。

2. 错误处理

FastAPI 也允许我们处理常见的 HTTP 错误。例如，访问不存在的路由时，FastAPI 会返回一个 404 错误。

fromfastapiimportHTTPException@app.get("/items/{item_id}")defread_item(item_id:int):ifitem_id!=42:raiseHTTPException(status_code=404,detail="Item not found")return{"item_id":item_id}

代码解析：

HTTPException(status_code=404, detail="Item not found")：当请求的item_id不为42时，FastAPI 会抛出一个 HTTP 404 错误。

七、高级路由技巧

1. 路由中的依赖注入

FastAPI 支持依赖注入，通过依赖项，我们可以复用逻辑并将其注入到多个路由中。

fromfastapiimportDependsdefcommon_parameters(q:str=None,skip:int=0,limit:int=10):return{"q":q,"skip":skip,"limit":limit}@app.get("/items/")defread_items(commons:dict=Depends(common_parameters)):return{"items":commons}