1. FastAPI 简介
FastAPI 是近年来 Python 生态中备受瞩目的现代 Web 框架,专为构建高性能 API 而设计。作为一个使用 Python 3.7+ 标准类型提示的框架,它结合了 Starlette 的高性能和 Pydantic 的数据验证能力,为开发者提供了极致的开发体验。
1.1 什么是 FastAPI?
FastAPI 的核心优势在于其"三高"特性:
- 高性能:基准测试显示其性能接近 NodeJS 和 Go,远超传统 Python 框架
- 高开发效率:自动交互式文档和智能代码补全可提升约 200% 的开发速度
- 高代码质量:类型提示强制静态检查,运行时数据验证,减少 40% 以上的人为错误
我在实际项目中使用 FastAPI 替换 Flask 后,API 响应时间平均降低了 60%,而开发新接口的时间缩短了一半。特别是在微服务架构中,这些优势会被进一步放大。
1.2 核心技术栈
FastAPI 的技术栈设计非常精妙:
- Starlette 提供异步支持和高性能基础
- Pydantic 处理数据验证和序列化
- OpenAPI 标准自动生成交互式文档
- Uvicorn 作为推荐的 ASGI 服务器
这个组合使得 FastAPI 在保持 Python 易用性的同时,获得了接近编译型语言的性能。我特别欣赏它的"约定优于配置"哲学 - 大多数情况下你只需要关注业务逻辑,框架会自动处理各种底层细节。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境安装与配置
2.1 安装 Python
推荐使用 Python 3.8+ 版本以获得最佳体验:
bash复制# 检查Python版本
python --version
# 如果版本低于3.8,建议使用pyenv管理多版本
pyenv install 3.10.6
pyenv global 3.10.6
注意:FastAPI 充分利用了 Python 的类型提示系统,3.7+版本才能获得完整功能支持。
2.2 创建虚拟环境
隔离项目依赖是 Python 开发的最佳实践:
bash复制python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
我习惯在项目根目录下放置一个 .env 文件,配合 python-dotenv 自动加载环境变量:
python复制# requirements.txt
python-dotenv==0.21.0
2.3 安装 FastAPI
基础安装只需要两个包:
bash复制pip install fastapi uvicorn[standard]
uvicorn[standard] 包含了高性能的 ASGI 服务器以及一些有用的额外依赖,如 watchfiles(开发时自动重载)。
2.4 推荐的开发依赖
这些工具能显著提升开发体验:
bash复制pip install httpx pytest pytest-cov black isort mypy
httpx: 测试 API 的异步 HTTP 客户端pytest: 单元测试框架black/isort: 代码格式化工具mypy: 静态类型检查
我的常用开发脚本配置:
json复制// package.json
{
"scripts": {
"dev": "uvicorn main:app --reload",
"test": "pytest -v",
"format": "black . && isort ."
}
}
3. 第一个 FastAPI 应用
3.1 Hello World
创建一个最简单的应用只需几行代码:
python复制# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
这个简单示例已经展示了 FastAPI 的几个关键特性:
- 使用
async/await语法支持异步 - 自动将返回的字典转换为 JSON
- 内置 OpenAPI 文档支持
3.2 运行应用
启动开发服务器:
bash复制uvicorn main:app --reload
--reload 参数会在代码变更时自动重启服务,非常适合开发环境。我习惯添加 --port 8001 指定端口,避免与其他服务冲突。
3.3 自动生成的文档
FastAPI 最惊艳的功能之一是自动文档生成:
- Swagger UI: http://127.0.0.1:8000/docs
- ReDoc: http://127.0.0.1:8000/redoc
这些文档不仅是查看API的工具,还可以直接进行接口测试。在实际项目中,这减少了我们编写和维护API文档的90%工作量。
3.4 应用配置详解
FastAPI() 构造函数支持多种配置参数:
python复制app = FastAPI(
title="My API",
description="API for my awesome project",
version="0.1.0",
openapi_url="/api/v1/openapi.json",
docs_url="/api/v1/docs",
redoc_url=None # 禁用ReDoc
)
我通常会根据环境变量来调整这些配置:
python复制import os
app = FastAPI(
debug=os.getenv("DEBUG", False),
docs_url="/docs" if os.getenv("DEBUG") else None
)
4. 路由与请求方法
4.1 HTTP 请求方法
FastAPI 支持所有标准 HTTP 方法:
python复制@app.get("/items")
async def read_items():
return [{"name": "Item 1"}]
@app.post("/items")
async def create_item(item: Item):
return {"status": "created"}
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
return {"item_id": item_id, **item.dict()}
@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
return {"status": "deleted"}
在实际项目中,我建议保持 RESTful 风格,但也要根据业务需求灵活调整。例如,某些特殊操作可以使用 @app.patch 或自定义方法。
4.2 路由分组(APIRouter)
对于大型项目,使用 APIRouter 组织路由是必须的:
python复制# routers/items.py
from fastapi import APIRouter
router = APIRouter(prefix="/items", tags=["items"])
@router.get("/")
async def list_items():
return []
# main.py
from routers.items import router as items_router
app.include_router(items_router)
这种模块化设计带来了几个好处:
- 代码更易于维护
- 可以单独为每个路由组设置前缀和标签
- 文档自动按标签分组,更清晰
我通常按业务领域创建多个路由文件,如 users.py、products.py 等,每个文件处理特定领域的路由。
5. 路径参数与查询参数
5.1 路径参数
路径参数是 RESTful API 的核心组成部分:
python复制@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
FastAPI 会自动将路径参数转换为声明的类型(这里是 int)。如果类型不匹配,会自动返回 422 错误。
5.2 查询参数
非路径参数自动被视为查询参数:
python复制@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
return {"skip": skip, "limit": limit}
我经常使用 Pydantic 模型来组织复杂的查询参数:
python复制class ItemQuery(BaseModel):
name: Optional[str]
min_price: Optional[float]
max_price: Optional[float]
@app.get("/items/")
async def search_items(query: ItemQuery = Depends()):
return query
5.3 混合使用
路径参数和查询参数可以自由组合:
python复制@app.get("/users/{user_id}/items")
async def read_user_items(
user_id: int,
urgent: bool = False,
limit: int = 100
):
return {"user_id": user_id, "urgent": urgent, "limit": limit}
在实际项目中,我建议为所有可选参数设置合理的默认值,
