FastAPI 是一个现代、高性能的 Python Web 框架，专为构建 APIs 设计。它基于 Python 类型提示，支持异步编程，并提供自动生成的交互式文档（Swagger UI 和 ReDoc）。以下是 FastAPI 开发的核心指南：

1. 安装

pip install fastapi
pip install "uvicorn[standard]"  # ASGI 服务器

2. 最小示例

创建 main.py：

from fastapi import FastAPIapp = FastAPI()@app.get("/")
def read_root():return {"Hello": "World"}@app.get("/items/{item_id}")
def read_item(item_id: int, query_param: str = None):return {"item_id": item_id, "query_param": query_param}

运行服务：

uvicorn main:app --reload

访问 http://localhost:8000
文档：http://localhost:8000/docs

3. 核心特性

(1) 路径参数与类型校验

@app.get("/users/{user_id}")
def get_user(user_id: int):  # 自动校验整数类型return {"user_id": user_id}

(2) 查询参数

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

(3) 请求体（Pydantic 模型）

from pydantic import BaseModelclass Item(BaseModel):name: strdescription: str | None = Noneprice: floattax: float | None = None@app.post("/items/")
def create_item(item: Item):  # 自动解析 JSONreturn {"item": item.dict()}

(4) 异步支持

@app.get("/async-demo")
async def async_endpoint():await some_async_task()return {"status": "done"}

(5) 自动文档

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

4. 进阶功能

(1) 依赖注入

from fastapi import Dependsdef query_extractor(q: str | None = None):return q@app.get("/dependency")
def use_dependency(query: str = Depends(query_extractor)):return {"query": query}

(2) 中间件

@app.middleware("http")
async def add_process_time_header(request, call_next):response = await call_next(request)response.headers["X-Custom-Header"] = "Foo"return response

(3) 文件上传

from fastapi import UploadFile, File@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):contents = await file.read()return {"filename": file.filename, "size": len(contents)}

(4) 错误处理

from fastapi import HTTPException@app.get("/error")
def raise_error():raise HTTPException(status_code=404, detail="Item not found")

(5) CORS 配置

from fastapi.middleware.cors import CORSMiddlewareapp.add_middleware(CORSMiddleware,allow_origins=["*"],allow_methods=["*"],
)

5. 项目结构建议

my_project/
├── app/
│   ├── routers/
│   │   ├── items.py
│   │   └── users.py
│   ├── models.py
│   ├── schemas.py
│   └── main.py
├── tests/
├── requirements.txt
└── Dockerfile

6. 部署选项

(1) 使用 Uvicorn 生产环境

uvicorn main:app --host 0.0.0.0 --port 80 --workers 4

(2) Docker 部署

FROM python:3.9
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]

(3) 云服务

AWS: EC2 + ALB, ECS, Lambda
GCP: Cloud Run, Compute Engine
Azure: App Service, Container Instances

7. 性能优化技巧

使用异步数据库驱动（如 asyncpg）

启用响应压缩：

app = FastAPI(docs_url=None, redoc_url=None, compress_level=5)

用 lru_cache 缓存重复计算
启用 HTTP/2（需 HTTPS）

8. 学习资源

官方文档：https://fastapi.tiangolo.com
GitHub 示例：https://github.com/tiangolo/fastapi
书籍：《Building Python Web APIs with FastAPI》

FastAPI 的自动验证、依赖注入和异步支持使其成为构建高性能 API 的理想选择，特别适合微服务和数据密集型应用。