fastapi

FastAPI

此技能提供使用 FastAPI 构建 API 的全面指南。

快速导航

主题	参考资料
入门	references/first-steps.md
路径参数	references/path-parameters.md
查询参数	references/query-parameters.md
请求体	references/request-body.md
验证	references/validation.md
高级请求体	references/body-advanced.md
Cookie/请求头	references/cookies-headers.md
Pydantic 模型	references/models.md
表单/文件	references/forms-files.md
错误处理	references/error-handling.md
路径配置	references/path-config.md
依赖项	references/dependencies.md
安全	references/security.md
中间件	references/middleware.md
CORS	references/cors.md
数据库	references/sql-databases.md
项目结构	references/bigger-applications.md
后台任务	references/background-tasks.md
元数据/文档	references/metadata-docs.md
测试	references/testing.md
高级响应	references/responses-advanced.md
WebSocket	references/websockets.md
模板	references/templates.md
设置/环境变量	references/settings.md
生命周期事件	references/lifespan.md
高级 OpenAPI	references/openapi-advanced.md

适用场景

• 使用 Python 创建 REST API
• 添加具有自动验证功能的端点
• 实现 OAuth2/JWT 身份验证
• 使用 Pydantic 模型
• 添加依赖注入
• 配置 CORS、中间件
• 上传文件、处理表单
• 测试 API 端点

安装

需要 Python 3.10+。安装：pip install "fastapi[standard]"（包含 uvicorn 的完整版本），或 pip install fastapi（最小版本）。处理表单/文件时，请添加 python-multipart。

发布亮点（0.139.2 -> 0.141.1）

• 前端开发体验（0.141.0）：app.frontend() 中的 check_dir 现在默认为 "auto"。当 FASTAPI_ENV=development 时，会跳过前端目录是否存在的检查（并发出警告）；其他情况下则会强制检查。fastapi dev 会自动设置 FASTAPI_ENV=development，除非该变量已设置，因此在前端尚未构建时运行开发服务器不再会报错。
• 前端修复（0.141.1）：现在会正确应用前端路由所用依赖项生成的后台任务和响应标头（依赖项支持已在 0.139.0 中添加），不再静默丢弃。FastAPI CLI 指南现已说明 FASTAPI_ENV。
• 依赖注入内存重构（0.140.0 – 0.140.7）：生成 OpenAPI、解析请求参数和处理请求体字段时，不再反复展开内部依赖树，从而降低大型应用的内存使用量；同时提高了依赖解析内部 lru_cache 的上限，以适配更大型的应用。这是内部优化，无需修改代码。
• 流式传输修复（0.140.8 – 0.140.13）：include_router() 不再丢失嵌套路由器中基于 yield 的端点声明的流项目类型；现在，普通（非生成器）端点返回 Iterable[Model] 时，也会应用 response_model_* 参数（例如 response_model_exclude），而不仅限于基于 yield 的端点；SSE/JSONL 流式端点设置的 status_code 现在会生效，不再总是返回 200；新增了 fastapi.sse 专用 API 参考页面。
• jsonable_encoder 修复（0.140.9）：exclude_defaults 现在会传递到字典的键和值中，而不仅限于顶层模型字段。

发布亮点（0.137.0 -> 0.139.2）

• 前端托管（0.138.0）：app.frontend("/", directory="dist") 可直接通过 FastAPI 应用提供已构建的静态前端。0.139.0 为 app.frontend() 添加了依赖项支持，可为前端启用自动 Cookie 身份验证；0.139.1 修复了 /users/john.doe 等带点路径的回退问题。
• 路由器内部机制（0.137.0）：include_router() 现在会保留 APIRouter/APIRoute 实例，而不是克隆路由，因此包含后新增的路由会自动生效，且内存使用量会降低。自定义 APIRouter/APIRoute 子类现已支持 .matches()/.handle()（alpha），用于高级路由。
• 线程安全（0.139.2）：路由构建经过重构，实现了线程安全，主要影响在并行线程中运行的测试。

发布亮点（0.133.0 → 0.136.1）

• **0.134.0：**支持使用 yield 流式传输 JSON Lines 和二进制数据。
• **0.135.0：**正式支持服务器发送事件（SSE）（EventSourceResponse）。
• **0.135.1：**修复了请求异步退出栈中 TaskGroup 的用法问题（稳定性修复）。
• **0.136.1：**FastAPI 更新了 Pydantic v2 代码以避免弃用警告，并将 Starlette 升级至 1.0.0。

补丁说明（0.136.2 → 0.136.3）

• SSE 响应现在会更严格地验证事件字段，因此格式错误的 ServerSentEvent 负载会更早失败，不再悄悄流式传输无效帧。
• 当 convert_underscores=True（默认值）时，标头参数不再接受名称带下划线的传入标头。如果客户端确实会发送带下划线的标头，请声明 Header(convert_underscores=False)，并确认代理链允许这些标头。

快速入门

from fastapi import FastAPI

app = FastAPI()

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

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

运行：fastapi dev main.py

核心模式

类型安全参数

from typing import Annotated
from fastapi import Path, Query

@app.get("/items/{item_id}")
def read_item(
    item_id: Annotated[int, Path(ge=1)],
    q: Annotated[str | None, Query(max_length=50)] = None
):
    return {"item_id": item_id, "q": q}

带验证的请求体

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)

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

依赖项

from fastapi import Depends

async def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/users/")
def list_users(db: Annotated[Session, Depends(get_db)]):
    return db.query(User).all()

身份验证

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
    return decode_token(token)

@app.get("/users/me")
def read_me(user: Annotated[User, Depends(get_current_user)]):
    return user

API 文档

• Swagger UI：/docs
• ReDoc：/redoc
• OpenAPI：/openapi.json

最佳实践

• 对参数使用 Annotated[Type, ...]
• 为请求/响应定义 Pydantic 模型
• 使用 response_model 过滤输出
• 添加 status_code 以设置正确的 HTTP 状态码
• 使用 tags 对 API 进行分类
• 在路由器/应用级别添加 dependencies 进行身份验证

禁止事项

• ❌ 返回原始数据库模型（应使用响应模型）
• ❌ 以明文存储密码（应使用 bcrypt/passlib）
• ❌ 在同一端点中混用 Body 和 Form/File
• ❌ 在异步端点中使用同步阻塞 I/O
• ❌ 错误处理时跳过 HTTPException

链接

• 文档
• 版本发布
• GitHub
• PyPI