[Python] FastAPI : Python Web 应用开发框架

1 FastAPI 框架

核心认知：FastAPI 的本质优势

  • FastAPI 不是"另一个 Flask"，它的设计哲学是"声明式编程"——你描述数据长什么样，框架自动处理验证、序列化、文档生成。

Pydantic 模型：数据的第一道防线

  • 核心思想：用 Python 类定义数据结构，自动获得验证能力。

详情参见: Python Pydantic 库 = Python 类型提示 + 自动数据校验 + 数据转换 - 博客园/千千寰宇

基础示例

from pydantic import BaseModel, Field, EmailStr
from typing import Optional
from datetime import datetime

class CreateUserRequest(BaseModel):
    """创建用户的请求模型"""
    name: str = Field(min_length=2, max_length=50, description="用户名")
    email: EmailStr  # 自动验证邮箱格式
    age: int = Field(ge=13, le=120, description="年龄范围")  # 边界检查
    password: str = Field(min_length=8, description="密码长度")
    bio: Optional[str] = Field(None, max_length=500)  # 可选字段

class UserResponse(BaseModel):
    """返回给客户端的数据模型（隐藏敏感信息）"""
    id: int
    name: str
    email: str
    created_at: datetime
    # 注意：这里不包含 password！

易错点：

  • ❌ 混淆 CreateUserRequest 和 UserResponse——前者接收输入，后者控制输出，安全的关键
  • ❌ 忘记 Optional 或默认值，导致字段变成必填

路径操作：定义 API 端点

from fastapi import FastAPI, HTTPException, Path, Query

app = FastAPI()

# 路径参数 + 查询参数 + 请求体
@app.post("/users/", response_model=UserResponse, status_code=201)
async def create_user(
    user: CreateUserRequest,  # 请求体自动解析为 Pydantic 对象
    referral_code: Optional[str] = Query(None, description="推荐码")  # 查询参数
):
    """
    创建新用户
    - FastAPI 自动验证 user 是否符合 UserCreate 规则
    - 验证失败时返回 422 错误，无需手动编写
    - response_model 确保只返回 UserResponse 定义的字段
    """
    # 模拟数据库操作
    if email_exists(user.email):
        raise HTTPException(status_code=400, detail="邮箱已被注册")
    
    new_user = save_to_db(user)
    return new_user  # 自动转换为 JSON，过滤敏感字段

关键概念：

  • 依赖注入（Depends）：这是 FastAPI 的杀手级特性，大二阶段必须掌握

依赖注入系统（核心难点）

为什么要用？ 避免在每个端点重复写数据库连接、认证逻辑，实现"关注点分离"。

基础模式：函数依赖

from fastapi import Depends, HTTPException, status
from typing import Annotated  # Python 3.9+ 推荐写法

# 模拟数据库会话
class Database:
    def query(self, sql: str):
        return [{"id": 1, "name": "Alice"}]

# 依赖提供者：负责创建和清理资源
def get_db():
    db = Database()
    try:
        yield db  # 注入给端点使用
    finally:
        # 请求结束后自动执行清理（如关闭连接）
        print("数据库连接已关闭")

# 使用依赖
@app.get("/users/")
async def list_users(
    db: Annotated[Database, Depends(get_db)]  # 推荐新语法
):
    return db.query("SELECT * FROM users")

进阶：带认证的依赖链

# 依赖可以嵌套，形成责任链
def get_current_user(token: str = Header(...)) -> User:
    """从请求头提取当前用户"""
    if not verify_token(token):
        raise HTTPException(status_code=401)
    return User(id=1, name="current_user")

def require_admin(user: Annotated[User, Depends(get_current_user)]):
    """依赖另一个依赖，实现权限检查"""
    if not user.is_admin:
        raise HTTPException(status_code=403, detail="需要管理员权限")
    return user

# 管理员专属接口
@app.delete("/users/{user_id}")
async def delete_user(
    user_id: int,
    admin: Annotated[User, Depends(require_admin)]  # 自动完成认证+鉴权
):
    return {"message": f"管理员 {admin.name} 删除了用户 {user_id}"}

工程价值：测试时可以轻松替换 get_db 为内存数据库，无需修改业务代码

响应模型与错误处理

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Union

class ErrorResponse(BaseModel):
    error: str
    detail: Optional[str] = None

@app.get(
    "/items/{item_id}",
    response_model=ItemResponse,
    responses={404: {"model": ErrorResponse}}  # 文档中标注错误响应
)
async def get_item(item_id: int = Path(..., ge=1)):
    item = find_item(item_id)
    if not item:
        # 自动序列化为 ErrorResponse 格式
        raise HTTPException(status_code=404, detail="物品不存在")
    return item

实用开发技巧（必知）

自动生成的交互式文档

启动服务后访问：

  • Swagger UI: http://localhost:8000/docs（适合测试）
  • ReDoc: http://localhost:8000/redoc（适合阅读）

异步理解要点

# FastAPI 原生支持 async，但要知道什么时候用
@app.get("/cpu-bound")  # CPU 密集型任务不要用 async
def cpu_task():
    return heavy_computation()

@app.get("/io-bound")   # IO 操作（数据库、HTTP 请求）用 async
async def io_task():
    result = await fetch_from_database()  # 释放线程去处理其他请求
    return result

🚀 学习路径建议

建议按此顺序实践：

  1. 第 1 周：纯 Pydantic 模型练习——定义 5-6 个业务模型（电商订单、博客文章等），掌握 Field 验证
  2. 第 2 周：基础 CRUD 接口——实现增删改查，理解 response_model 的安全作用
  3. 第 3 周：依赖注入实战——实现数据库连接、假登录认证，体会"可测试性"
  4. 第 4 周：整合项目——用 FastAPI + SQLAlchemy 做一个完整的小项目

推荐资源：

💡 关键技术点

概念 一句话理解 常见误区
Pydantic "数据结构 + 验证规则"的合体 以为只是数据类，忽略验证能力
Depends "我需要这个工具，框架帮我准备好" 在函数内部手动创建数据库连接
response_model "控制输出字段，防止泄露敏感数据" 直接返回 ORM 对象，暴露密码等字段
async/await "让出线程去服务其他请求" 在 CPU 密集型任务上滥用 async

掌握这4点，即已基本入门，可以开始阅读生产级 FastAPI 项目的源码了。

X 参考文献

posted @ 2026-04-09 13:47  千千寰宇  阅读(6)  评论(0)    收藏  举报