5 路由的基本定义

FastAPI 路由基本定义

在构建 API 时，定义路由是核心的一部分。FastAPI 提供了一种非常直观和高效的方式来定义路由，支持 HTTP 请求方法（如 GET、POST、PUT、DELETE 等），并能自动生成 OpenAPI 文档。本文将介绍 FastAPI 中如何定义和使用路由。

1. 安装 FastAPI 和 Uvicorn

首先，我们需要安装 FastAPI 和 Uvicorn。Uvicorn 是一个 ASGI 服务器，用于运行 FastAPI 应用。

pip install fastapi uvicorn

2. 创建第一个路由

FastAPI 的路由通过装饰器来定义。最常用的装饰器是 @app.get()、@app.post() 等，它们分别对应 HTTP 请求方法。这里我们来定义一个简单的 GET 路由。

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

在上面的代码中：python

• @app.get("/")：定义了一个 GET 请求的路由，访问路径为 /。
• read_root：定义了该路由的处理函数。当访问该路由时，返回一个 JSON 响应。

3. 运行应用

保存上面的代码到 main.py，然后使用 Uvicorn 启动 FastAPI 应用：

uvicorn main:app --reload

--reload 参数允许在修改代码后自动重新加载应用。

在浏览器中访问 http://127.0.0.1:8000/，你应该会看到如下的响应：

{
  "message": "Hello, World!"
}

4. 路由参数

FastAPI 支持路由参数，可以将 URL 路径中的变量传递给处理函数。通过在路径中添加大括号 {} 来定义变量。

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

此时访问 /items/42，返回：

{
  "item_id": 42
}

4.1 可选路由参数

FastAPI 还支持给路由参数设置默认值，使其变为可选参数。例如，下面的代码定义了一个带有可选参数的路由：

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

如果访问 /items/42?q=test，将返回：

{
  "item_id": 42,
  "q": "test"
}

如果没有提供 q 参数，返回的响应中 q 将为 None。

5. 支持的 HTTP 请求方法

FastAPI 支持多种 HTTP 请求方法，以下是常见的几种：

• @app.get("/path")：处理 GET 请求
• @app.post("/path")：处理 POST 请求
• @app.put("/path")：处理 PUT 请求
• @app.delete("/path")：处理 DELETE 请求
• @app.patch("/path")：处理 PATCH 请求
• @app.options("/path")：处理 OPTIONS 请求

示例：POST 请求

from pydantic import BaseModel

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

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

上面的代码定义了一个 POST 路由 /items/，并通过 Item 类来接收请求体中的数据。

6. 路由和异步支持

FastAPI 支持异步视图函数。你可以使用 async def 定义异步路由处理函数，这对处理 I/O 密集型操作（如数据库查询、外部 API 调用等）非常有用。

@app.get("/async-example")
async def async_example():
    return {"message": "This is an async route"}

7. 自动生成 API 文档

FastAPI 自动生成 OpenAPI 和 Swagger 文档，可以通过 /docs 查看交互式 API 文档，或者通过 /redoc 查看 ReDoc 文档。这些文档会自动根据你定义的路由和请求参数生成。

例如，访问 http://127.0.0.1:8000/docs 可以查看 API 文档，展示所有定义的路由、请求方法、参数和返回类型。

FastAPI 的路由定义非常简单且功能强大。通过装饰器，可以快速定义多种 HTTP 请求方法的路由，并且支持路由参数、请求体模型验证、异步处理等高级功能。同时，FastAPI 还提供了自动生成文档的功能，极大地提升了开发效率。

如果你正在构建一个现代化的 Web API，FastAPI 是一个非常好的选择，尤其是在性能和开发体验上，FastAPI 都表现得非常出色。