FastAPI入门与异步特性 - Web开发-学习笔记-上海佼艾

一、FastAPI概述

FastAPI 是一个现代化的高性能 Python Web 框架，专为构建 API 而设计。它由 Sebastian Ramirez 于 2018 年创建，基于 Starlette（高性能 ASGI 框架）和 Pydantic（数据验证库）构建，充分利用了 Python 3.6+ 的类型提示系统（type hints），提供了自动生成 API 文档、请求验证、依赖注入等强大功能。

核心特性

高性能：得益于 Starlette 的异步处理能力，FastAPI 的性能可与 Node.js 和 Go 语言相媲美，是当前最快的 Python Web 框架之一。
自动文档生成：无需额外配置，基于 OpenAPI 规范自动生成 Swagger UI 和 ReDoc 交互式文档，方便前后端协作。
类型提示驱动：利用 Python 的类型注解实现参数声明、数据验证和编辑器自动补全，大幅提升开发效率。
异步支持：原生支持 async/await 语法，高效处理 I/O 密集型任务和高并发场景。
依赖注入系统：内置强大的依赖注入机制，支持资源共享、权限验证等逻辑的模块化管理。

技术栈解析

Starlette 是一个轻量级的 ASGI 框架/工具包，提供了路由、中间件、WebSocket 支持、请求/响应处理等底层能力。FastAPI 在此基础上封装了更高层的 API 开发体验，但开发者仍然可以直接访问 Starlette 的所有功能。

Pydantic 是基于 Python 类型提示的数据验证库，在 FastAPI 中承担所有请求体、响应模型的数据校验和序列化工作。Pydantic 使用 Python 标准库的 typing 模块定义数据模型，支持复杂嵌套结构、自定义验证器和 JSON Schema 生成。

框架横向对比

特性	FastAPI	Flask	Django
性能	极高（异步）	中等（同步）	中等（同步/异步有限）
学习曲线	中等	平缓	较陡
类型提示	原生支持	不强制	部分支持
自动文档	内置（Swagger + ReDoc）	需插件	需插件
异步支持	原生异步	有限	Django 3.0+ 开始支持
ORM集成	灵活（SQLAlchemy/Tortoise-ORM）	灵活（SQLAlchemy）	内置 Django ORM
适用场景	微服务、高性能API、实时应用	小型应用、原型开发	全栈应用、内容管理系统
社区生态	快速增长	成熟庞大	成熟庞大

小结：FastAPI 的定位并非替代 Flask 或 Django，而是在高性能 API 和微服务领域提供了更优的选择。对于需要高并发、自动文档和现代化开发体验的项目，FastAPI 是当前 Python 生态中的最佳实践。

二、安装与快速入门

环境准备

FastAPI 需要 Python 3.7 及以上版本。推荐使用虚拟环境进行项目隔离。安装方式极其简洁：

pip install fastapi
pip install "uvicorn[standard]"

fastapi 是核心框架包，而 uvicorn 是一个高性能的 ASGI 服务器，用于运行 FastAPI 应用。uvicorn 的 [standard] 安装选项会附带 uvloop（事件循环）、httptools（HTTP解析）等性能优化组件。此外，也可以使用 Daphne 或 Hypercorn 作为 ASGI 服务器。

第一个 FastAPI 应用

以下代码创建了一个最简单的 FastAPI 应用：

from fastapi import FastAPI

app = FastAPI()

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

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

启动服务

将上述代码保存为 main.py，然后使用 uvicorn 启动：

# 开发模式，--reload 开启热重载
uvicorn main:app --reload --host 0.0.0.0 --port 8000

其中 main:app 表示从 main.py 文件中导入 app 实例。--reload 会在代码变更时自动重启服务器，极大提升开发效率。--host 0.0.0.0 允许局域网内其他设备访问。--port 8000 指定端口，默认即为 8000。

自动交互文档

FastAPI 会自动生成两份 API 文档，可直接在浏览器中访问：

Swagger UI（http://127.0.0.1:8000/docs）：提供可交互的 API 测试界面，支持在线发送请求并查看响应。
ReDoc（http://127.0.0.1:8000/redoc）：以更清晰的排版展示 API 文档，适合阅读和分享。

这两份文档均完全基于 OpenAPI 规范自动生成，涵盖了所有已定义的 API 路由、参数、请求体和响应模型，无需任何额外配置。

提示：在开发初期就可以利用 /docs 端点调试 API，前后端可以基于文档并行开发，这是 FastAPI 相比传统框架最显著的生产力优势之一。

三、路径操作

路径操作（Path Operations）是 FastAPI 最核心的概念之一，它定义了 API 端点（Endpoint）所承载的 HTTP 方法和具体逻辑。

HTTP 方法装饰器

FastAPI 为每个标准 HTTP 方法提供了对应的装饰器，使代码语义清晰：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")       # 获取资源列表
@app.post("/items/")      # 创建新资源
@app.put("/items/{id}")   # 更新资源（全量替换）
@app.patch("/items/{id}") # 部分更新资源
@app.delete("/items/{id}")# 删除资源

路径参数

通过在路径中使用 Python 格式化字符串语法 {参数名} 来声明路径参数，FastAPI 会自动从 URL 中提取对应的值：

@app.get("/users/{user_id}")
def get_user(user_id: int):
    """路径参数 user_id 会被自动转换为 int 类型"""
    return {"user_id": user_id}

由于声明了 user_id: int，FastAPI 会自动进行类型转换，并在类型不匹配时返回 HTTP 422 验证错误，无需手动编写验证逻辑。

查询参数

路径函数中的非路径参数会被自动解释为查询参数。查询参数通常用于过滤、排序和分页：

@app.get("/items/")
def list_items(skip: int = 0, limit: int = 10, category: str | None = None):
    """skip和limit有默认值则为可选查询参数"""
    if category:
        return {"items": db[category][skip:skip + limit]}
    return {"items": db[skip:skip + limit]}

参数优先级与排序规则

当路径参数和查询参数同时存在时，FastAPI 遵循明确的排序规则：

路径参数优先匹配：先声明路径参数，再声明查询参数。
固定路径优先于动态路径：/users/me 优先于 /users/{user_id}，以避免路由冲突。
顺序定义：如果两个路径具有相同的匹配规则，先定义的会优先匹配。
参数别名：使用 Query(alias="element-count") 可以映射前端不兼容的字段名。

最佳实践：路径参数用于标识唯一资源（如 ID、Slug），查询参数用于筛选、排序和分页。请求体参数用于传输复杂数据。合理区分三者能显著提升 API 设计的可读性和 RESTful 规范度。

四、异步特性

异步支持是 FastAPI 相较于 Flask 最核心的竞争优势之一。FastAPI 允许开发者使用 async def 或 def 定义路径操作函数，并在同一个应用中混合使用。

async def 路径函数

当路径操作函数使用 async def 声明时，FastAPI 会调用 Starlette 的异步线程池执行该函数，确保在 I/O 等待期间事件循环可以处理其他请求：

@app.get("/async-data")
async def get_async_data():
    """异步请求数据库或外部API"""
    data = await fetch_from_database()
    result = await call_external_api(data)
    return {"result": result}

同步 def 路径函数

当路径操作函数使用普通的 def 声明时，FastAPI 会自动将其运行在线程池中，避免阻塞事件循环。这使得同步代码也能获得异步环境下的并发能力：

@app.get("/sync-data")
def get_sync_data():
    """CPU密集型或同步I/O操作"""
    result = perform_heavy_computation()
    return {"result": result}

选择合适的函数类型

async def：适用于数据库查询、HTTP 请求、文件读写等 I/O 密集型操作。使用 await 关键字在等待期间让出 CPU，由事件循环处理其他任务。
def：适用于 CPU 密集型操作（复杂计算、图像处理、加密解密）。FastAPI 会在独立线程中执行这些操作，避免阻塞事件循环。

并发与并行

FastAPI 的异步特性主要解决的是并发问题而非并行问题。并发是指多个任务在同一个 CPU 核心上交替执行，适用于 I/O 密集型场景；而并行需要多核心同时处理，适用于 CPU 密集型场景。Python 的 asyncio 擅长处理 I/O 密集型并发，这是 FastAPI 高性能的主要原因。对于 CPU 密集型任务，可以结合 multiprocessing 或分布式任务队列（如 Celery）来实现真正的并行处理。

经验之谈：在实际项目中，80% 的 API 操作都是 I/O 密集型的——查询数据库、读写缓存、调用微服务。这些场景下 FastAPI 的异步优势得到充分发挥。对于少量 CPU 密集型操作，FastAPI 也能通过线程池优雅处理，无需额外引入复杂的并发模型。

五、请求体

FastAPI 使用 Pydantic 模型来声明请求体（Request Body），实现自动验证、序列化和文档生成。

基础用法

首先定义一个继承自 BaseModel 的 Pydantic 模型，然后在路径函数中将其作为参数类型声明：

from pydantic import BaseModel

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

@app.post("/items/")
def create_item(item: Item):
    """FastAPI会自动解析JSON请求体并验证类型"""
    return {"item": item}

请求体 + 路径参数 + 查询参数

FastAPI 支持在同一个路径函数中同时使用三种参数类型，框架能通过参数声明的位置智能区分：

@app.put("/items/{item_id}")
def update_item(
    item_id: int,                # 路径参数
    item: Item,                  # 请求体参数
    q: str | None = None,        # 查询参数
    discount: float = 0.0        # 查询参数
):
    result = item.model_dump()
    result.update({"item_id": item_id, "q": q})
    return result

嵌套模型与复杂结构

Pydantic 支持深度嵌套的数据结构定义，FastAPI 会递归验证整个请求体：

class Image(BaseModel):
    url: str
    name: str

class Product(BaseModel):
    name: str
    price: float
    tags: list[str] = []
    images: list[Image] | None = None
    specifications: dict[str, str] = {}

@app.post("/products/")
def create_product(product: Product):
    """自动验证嵌套的Image列表、字典等复杂结构"""
    return product

字段验证

Pydantic 提供了丰富的字段验证器，可以在模型定义时添加约束：

from pydantic import BaseModel, Field, EmailStr

class User(BaseModel):
    username: str = Field(min_length=3, max_length=50, pattern="^[a-zA-Z0-9_]+$")
    email: EmailStr
    age: int = Field(ge=0, le=150)
    website: str | None = Field(default=None, max_length=200)

Field 函数支持 min_length、max_length、ge（大于等于）、le（小于等于）、pattern（正则表达式）等参数，在声明阶段即可完成数据清洗和验证规则的定义。

六、响应模型

响应模型（Response Model）让 FastAPI 能够自动序列化、过滤和文档化 API 的返回值。通过 response_model 参数，可以精确控制返回给客户端的数据结构。

基础用法

from pydantic import BaseModel

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

class ItemIn(BaseModel):
    name: str
    price: float
    password: str  # 敏感字段，不应返回给客户端

@app.post("/items/", response_model=ItemOut)
def create_item(item: ItemIn):
    """即使内部使用了ItemIn（包含password），返回时也会自动过滤为ItemOut的结构"""
    db_item = save_to_db(item)
    return db_item

response_model_exclude_unset

当设置为 True 时，响应中只包含用户明确设置过的字段，未设置的字段不会被包含：

@app.patch("/items/{item_id}", response_model=ItemOut, response_model_exclude_unset=True)
def partial_update(item_id: int, item: ItemIn):
    """只返回用户更新的字段，减少不必要的网络传输"""
    return item

响应模型继承

通过 Pydantic 模型的继承机制，可以复用基础字段并扩展：

class BaseUser(BaseModel):
    username: str
    email: str

class UserOut(BaseUser):
    """对外接口不暴露敏感字段"""
    pass

class UserIn(BaseUser):
    password: str  # 仅用于输入

class UserInDB(BaseUser):
    hashed_password: str  # 仅用于存储

状态码设置

FastAPI 允许通过 status_code 参数自定义 HTTP 状态码，同时也支持使用 HTTPStatus 枚举：

from fastapi import FastAPI, status

@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item(item: Item):
    """创建成功返回201状态码"""
    return item

@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(item_id: int):
    """删除成功返回204，无响应体"""
    delete_from_db(item_id)

合理设置状态码是 RESTful API 设计的重要环节。FastAPI 的 status 模块提供了完整的 HTTP 状态码命名常量，避免了硬编码数字的弊端。

七、自动文档

自动生成 API 文档是 FastAPI 最受开发者欢迎的特性之一。它基于标准的 OpenAPI 规范（原 Swagger 规范），确保文档的兼容性和可移植性。

Swagger UI（/docs）

Swagger UI 提供了一个交互式的 API 测试界面。在浏览器中访问 /docs 端点，可以看到所有已注册的路由、请求参数格式和响应模型。每个端点旁都有 "Try it out" 按钮，可以直接在浏览器中发送请求并查看实时响应数据。这对于调试接口和前后端联调极其便利。

ReDoc（/redoc）

ReDoc 以更加清晰和规范的三栏布局展示完整的 API 文档。左侧为目录导航，中间为详细说明（包含请求/响应模型的所有字段说明），右侧为示例代码。ReDoc 的布局更适合阅读和分享，也支持导出为 PDF 等格式。

自定义文档信息

在创建 FastAPI 实例时，可以通过参数自定义文档的标题、描述和版本号等元信息：

app = FastAPI(
    title="电商平台API",
    description="这是一个高性能的电商平台后端API，支持商品管理、订单处理和用户认证。",
    version="2.0.0",
    contact={
        "name": "API Support",
        "email": "api@example.com",
    },
    license_info={
        "name": "MIT",
    },
    docs_url="/api/docs",   # 自定义Swagger UI路径
    redoc_url="/api/redoc", # 自定义ReDoc路径
    openapi_url="/api/openapi.json", # OpenAPI规范文件路径
)

OpenAPI 规范深度支持

FastAPI 自动为每个端点生成完整的 OpenAPI 规范定义，包括：

路径参数的类型、格式和验证规则
查询参数的默认值、描述和是否必需
请求体的 JSON Schema 定义
响应模型的完整结构（包括嵌套模型）
HTTP 状态码和错误响应模式
认证和授权方案（OAuth2、JWT、API Key 等）

生成的 openapi.json 文件可以导入到 Postman、Insomnia 等 API 测试工具中，也可以用于生成客户端 SDK 代码，实现前后端 API 契约的一致性和自动化。

设计理念：FastAPI 的作者 Sebastian Ramirez 曾提到，自动文档不仅仅是"附加功能"，而是贯穿整个框架设计的核心原则。通过类型提示驱动文档生成的机制，确保了文档与代码始终同步——文档不是事后补充的手册，而是代码的自然产物。

八、核心要点总结

FastAPI 的技术栈：基于 Starlette（ASGI）和 Pydantic（数据验证），是当前 Python 生态中性能最高的 Web 框架之一，性能与 Node.js/Go 相当。
类型提示驱动：利用 Python 3.6+ 的类型注解实现自动参数验证、序列化和文档生成，大幅减少样板代码。
异步原生支持：原生支持 async/await，但同步代码也能在线程池中并发执行，兼顾开发便利性和运行效率。
自动文档：基于 OpenAPI 规范自动生成 Swagger UI 和 ReDoc，支持交互式调试，文档与代码天然同步。
请求体验证：通过 Pydantic 模型定义请求体，支持嵌套结构、自定义验证器和 JSON Schema 生成。
响应控制：通过 response_model 精确控制输出数据，支持字段过滤、排除未设置字段和模型继承。
适用场景：微服务架构、高并发 API、前后端分离项目、实时应用（结合 WebSocket）、机器学习模型部署。

九、进一步思考

FastAPI 作为 Python Web 开发的重要里程碑，其设计理念具有深远的借鉴意义。类型提示从 Python 3.5 引入的可选特性，在 FastAPI 中变成了驱动整个框架的核心引擎——验证规则、API 文档、序列化、编辑器补全都由类型注解一站式生成。这种"声明式 API"的设计哲学，让开发者专注于"做什么"而非"怎么做"。

在实际项目选型中，选择 FastAPI 还是 Flask/Django，应基于团队技术栈、项目规模和生态需求综合判断。FastAPI 在高性能 API、微服务和异步场景下优势明显，但 Django 的全栈能力和 Flask 的灵活性在特定领域仍有不可替代的价值。技术的选择始终服务于业务需求，而非追逐热门框架。

展望未来，随着 ASGI 生态的不断完善、Python 异步能力的持续增强（如偏生成器、结构化并发等新特性的引入），FastAPI 的发展空间值得期待。对于正在学习 Python Web 开发的工程师而言，掌握 FastAPI 是一项对职业发展非常有价值的投资。