FastAPI 入门指南：从零开始构建高性能 Python API

1. 引言

FastAPI 是一个现代、快速（高性能）的 Python Web 框架，基于 Python 3.7+ 的类型提示（Type Hints）构建。它由 Sebastián Ramírez 开发，自 2018 年发布以来迅速成为 Python 社区最受欢迎的 API 框架之一。

FastAPI 的核心优势在于：

高性能：基于 Starlette 和 Pydantic，性能可与 NodeJS 和 Go 相媲美。
自动生成文档：内置 Swagger UI 和 ReDoc，接口文档自动生成，无需额外配置。
类型安全：充分利用 Python 类型提示，提供自动校验和补全。
异步支持：原生支持 async/await，轻松处理高并发场景。

2. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

Python 3.7 及以上版本
pip 包管理工具
建议使用虚拟环境隔离项目依赖

2.1 安装 FastAPI

使用 pip 安装 FastAPI 和 Uvicorn（ASGI 服务器）：

bash 复制代码

pip install fastapi uvicorn

如果你还需要数据校验和序列化功能，可以一并安装：

bash 复制代码

pip install "fastapi[all]"

2.2 验证安装

创建一个简单的 Python 文件，验证安装是否成功：

python 复制代码

import fastapi

print(fastapi.__version__)

3. 第一个 FastAPI 应用

让我们从最经典的 "Hello World" 开始，创建一个最简单的 FastAPI 应用。

3.1 创建应用

新建一个 main.py 文件：

python 复制代码

from fastapi import FastAPI

app = FastAPI()

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

3.2 运行应用

在终端中运行以下命令启动服务：

bash 复制代码

uvicorn main:app --reload

启动成功后，你会看到类似输出：

复制代码

INFO:     Uvicorn running on http://127.0.0.1:8000

3.3 访问接口

打开浏览器访问以下地址：

接口地址：http://127.0.0.1:8000/
自动文档（Swagger UI）：http://127.0.0.1:8000/docs
备用文档（ReDoc）：http://127.0.0.1:8000/redoc

访问 /docs 页面，你会看到 FastAPI 自动生成的交互式 API 文档，这是 FastAPI 最令人惊艳的特性之一。

4. 路径参数与查询参数

FastAPI 支持灵活的路径参数和查询参数定义，配合类型提示实现自动校验。

4.1 路径参数

python 复制代码

from fastapi import FastAPI

app = FastAPI()

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

当访问 /items/42 时，返回 {"item_id": 42}。如果传入非整数，如 /items/abc，FastAPI 会自动返回 422 校验错误。

4.2 查询参数

python 复制代码

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

访问 /items/?skip=5&limit=20，即可传入查询参数。未传参时使用默认值。

4.3 可选参数

使用 Optional 类型定义可选参数：

python 复制代码

from typing import Optional

@app.get("/users/{user_id}")
def get_user(user_id: int, q: Optional[str] = None):
    return {"user_id": user_id, "q": q}

5. 请求体与 Pydantic 模型

FastAPI 与 Pydantic 深度集成，通过定义数据模型实现请求体的自动解析和校验。

5.1 定义数据模型

python 复制代码

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = False

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

5.2 发送请求

使用 curl 测试 POST 请求：

bash 复制代码

curl -X POST "http://127.0.0.1:8000/items/" \
  -H "Content-Type: application/json" \
  -d '{"name": "Apple", "price": 5.5}'

返回结果：

json 复制代码

{
  "item": {
    "name": "Apple",
    "price": 5.5,
    "is_offer": false
  }
}

5.3 自动校验

如果请求体缺少必填字段或类型错误，FastAPI 会返回详细的 422 错误信息，指出具体哪个字段校验失败。

6. 响应模型

使用 response_model 参数控制接口返回的数据结构，实现数据过滤和类型转换。

python 复制代码

from typing import List

class ItemOut(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=ItemOut)
def create_item(item: Item):
    return item

这样即使传入的 Item 包含 is_offer 字段，返回时也只会包含 name 和 price。

7. 异步支持

FastAPI 原生支持异步编程，适合处理 IO 密集型任务。

python 复制代码

import asyncio

@app.get("/async-demo")
async def async_demo():
    await asyncio.sleep(1)
    return {"message": "Async response"}

对于耗时操作（如数据库查询、外部 API 调用），使用 async def 可以显著提升并发处理能力。

8. 依赖注入

FastAPI 提供了强大的依赖注入系统，用于复用代码逻辑。

python 复制代码

from fastapi import Depends

def common_parameters(q: Optional[str] = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items/")
def read_items(commons: dict = Depends(common_parameters)):
    return commons

依赖注入常用于数据库连接、认证鉴权、日志记录等场景。

9. 总结

FastAPI 凭借其高性能、类型安全、自动文档和简洁的语法，已成为 Python API 开发的首选框架。本文介绍了 FastAPI 的核心特性，包括：

环境搭建与第一个应用
路径参数、查询参数和请求体
Pydantic 数据模型与自动校验
响应模型与数据过滤
异步支持与依赖注入

掌握这些基础后，你就可以开始构建自己的高性能 API 服务了。后续可以深入学习数据库集成（SQLAlchemy）、认证鉴权（JWT）、文件上传、WebSocket 等高级主题。