FastAPI 教程：从入门到实践

news2025/6/12 18:38:06

FastAPI 是一个现代、快速（高性能）的 Web 框架，用于构建 API，支持 Python 3.6+。它基于标准 Python 类型提示，易于学习且功能强大。以下是一个完整的 FastAPI 入门教程，涵盖从环境搭建到创建并运行一个简单的 FastAPI 应用的各个步骤。

一、前置准备

在开始之前，请确保你已经安装了 Python 3.7+（推荐 3.7+ 以获得更好的类型提示支持）和一个代码编辑器（如 VS Code 或 PyCharm）。强烈建议使用虚拟环境来隔离项目依赖。

创建虚拟环境

python -m venv .venv

激活虚拟环境

macOS/Linux：

  source .venv/bin/activate

Windows：

  .venv\Scripts\activate

激活虚拟环境后，终端提示符前会显示虚拟环境的名称（通常是 .venv）。

二、安装 FastAPI 和 ASGI 服务器

FastAPI 本身是一个框架，需要一个 ASGI 服务器来运行它。常用的 ASGI 服务器有 Uvicorn 和 Hypercorn。我们通常选择 Uvicorn，因为它高性能且易于使用。

pip install fastapi uvicorn[standard]

fastapi：安装 FastAPI 框架本身。
uvicorn[standard]：安装 Uvicorn ASGI 服务器，[standard] 选项会安装一些常用的可选依赖。

三、创建第一个 FastAPI 应用

创建一个名为 main.py 的文件，并输入以下代码：

from fastapi import FastAPI

app = FastAPI()

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

运行应用

打开终端，进入到 main.py 文件所在的目录，并确保虚拟环境已激活。然后运行 Uvicorn：

uvicorn main:app --reload

main：指代 main.py 文件（模块）。
app：指代在 main.py 文件中创建的 FastAPI() 实例对象。
--reload：开启热重载模式。当你修改代码并保存后，Uvicorn 会自动重启服务器，方便开发调试。

运行成功后，你将看到类似以下的输出：

INFO:     Will watch for changes in these directories: ['/path/to/your/project']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [PID]
INFO:     Started server running on http://127.0.0.1:8000

现在，打开浏览器访问 http://127.0.0.1:8000，你会看到 JSON 响应：{"Hello": "World"}。

四、自动生成的 API 文档

FastAPI 最酷的特性之一是自动生成 API 文档。在服务器运行状态下，访问以下地址：

Swagger UI：http://127.0.0.1:8000/docs
ReDoc：http://127.0.0.1:8000/redoc

你会看到交互式的 API 文档界面，可以直接在里面测试你的 API 端点。

五、处理路径参数和查询参数

路径参数

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

访问 http://127.0.0.1:8000/items/5，你会看到：{"item_id": 5}。

查询参数

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

访问 http://127.0.0.1:8000/items/?skip=0&limit=10，你会看到：{"skip": 0, "limit": 10}。

六、定义请求体

使用 Pydantic 定义请求体模型：

from pydantic import BaseModel

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

定义一个 POST 请求，接收一个 Item 对象作为请求体：

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

FastAPI 会自动将请求体（通常是 JSON）解析并验证。如果数据格式或类型不匹配 Item 模型，FastAPI 会返回 422 Unprocessable Entity 错误。

七、依赖注入

使用 Depends 添加依赖注入：

from fastapi import Depends

def get_common_parameters(q: str = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items_with_dependency/")
async def read_items_with_dependency(commons: dict = Depends(get_common_parameters)):
    return commons