w wyl123ly 的博客
MD

后端-04-PythonWeb框架

131 KB 2026.10.11 原文件

后端-04-PythonWeb框架

这篇笔记讲什么

Python 的 Web 生态有一个根本性的分水岭:WSGI(同步、阻塞)与 ASGI(异步、非阻塞)。理解这条分界线,就能理解为什么 FastAPI 能在同样硬件上跑出数倍吞吐,也能理解为什么 Django 明明支持异步却仍以同步为主。

本文主线是 FastAPI 深入(类型注解驱动、Pydantic 校验、依赖注入、OpenAPI 自动生成),并给出 Django 与 Flask 的定位对比与核心用法。最后给出一个完整的 FastAPI CRUD + 依赖注入鉴权示例项目,可以直接跑起来。

版本基准:Python 3.15、FastAPI 0.143、Django 6.1、Flask 3.1。版本敏感处已标注「以官方最新文档为准」。


一、是什么:WSGI 与 ASGI 的分水岭

1.1 两个协议规范

Python Web 框架自己不处理网络——它们只负责"给我一个请求对象,我给你一个响应对象"。连接怎么收、请求怎么解析、进程怎么管,由服务器(也叫 WSGI/ASGI 容器)负责。框架与服务器之间的契约就是协议规范。

对比项WSGIASGI
全称Web Server Gateway InterfaceAsynchronous Server Gateway Interface
出现的年份2003(PEP 333),2010 修订(PEP 3333)2016 起
应用的可调用形式app(environ, start_response)async def app(scope, receive, send)
同步/异步仅同步同步与异步都支持
并发模型一个请求占一个线程/进程,直到响应完成一个事件循环处理成百上千个连接
是否支持 WebSocket❌✅
是否支持 HTTP/2、SSE、长连接需 hack✅ 原生支持
典型服务器Gunicorn、uWSGI、mod_wsgi、WaitressUvicorn、Hypercorn、Daphne
典型框架Flask、Django(传统)、BottleFastAPI、Starlette、Django(ASGI 模式)

WSGI 的应用签名长这样(看懂它就知道为什么它无法异步):

# 一个裸 WSGI 应用:完全不需要框架
def application(environ, start_response):
    # environ 是一个普通 dict:请求方法、路径、头、body 流都在里面
    path = environ["PATH_INFO"]
    method = environ["REQUEST_METHOD"]

    status = "200 OK"
    headers = [("Content-Type", "text/plain; charset=utf-8")]
    start_response(status, headers)

    # 返回值必须是"可迭代的 bytes"——注意:函数必须同步返回,
    # 因为 WSGI 规定服务器在拿到这个可迭代对象后才能开始读
    return [f"你请求了 {method} {path}\n".encode("utf-8")]

ASGI 的签名则是纯异步的三段式:

# 一个裸 ASGI 应用:scope / receive / send
async def application(scope, receive, send):
    # scope:这次连接/请求的元信息(类型、路径、头、查询串)
    assert scope["type"] == "http"

    # receive:一个 async 可调用对象,用 await 拿事件(如 http.request)
    event = await receive()

    # send:一个 async 可调用对象,用 await 发事件(如 http.response.start)
    body = f"你请求了 {scope['method']} {scope['path']}\n".encode("utf-8")
    await send({
        "type": "http.response.start",
        "status": 200,
        "headers": [(b"content-type", b"text/plain; charset=utf-8")],
    })
    await send({"type": "http.response.body", "body": body})

关键区别在于"能不能 await"

WSGI 的应用函数必须同步返回,服务器无法在函数内部让出控制权,所以只能靠"多开线程/进程"来并发。

ASGI 的应用是协程,可以在等待数据库或下游 API 时 await 挂起,让事件循环去处理别的请求——一个进程就能扛住大量并发 I/O 等待。

1.2 同步与异步框架的分野

维度同步(WSGI)异步(ASGI)
并发单位线程/进程协程(coroutine)
单进程承载并发数十~数百数千~数万(I/O 密集场景)
单请求 CPU 开销线程切换 + 栈内存协程切换,开销极小
代码心智负担低,顺序执行好理解中,必须区分阻塞/非阻塞调用
出错代价一个请求慢只影响一个线程一次阻塞调用卡住整个进程所有请求
生态成熟度极成熟,库最多成熟,但部分库仍只有同步版本
适合的负载CPU 计算 + 中等并发高并发 I/O 等待(网关、实时、SSE)

交叉引用:后端-02-Nodejs与Express 里讲的"一个死循环拖垮整个服务"在异步 Python 里完全同样成立——FastAPI 的 async def 路由里如果调用了阻塞函数,事件循环就停摆了。


二、为什么这样设计:三种框架的定位差异

2.1 核心对比表

对比项FastAPIDjangoFlask
设计哲学类型注解驱动、API 优先约定优于配置、全栈自带最小内核 + 扩展拼装
协议ASGI(也兼容 WSGI 挂载)WSGI 为主,ASGI 可选WSGI(ASGI 需额外方案)
同步/异步两者皆可,async def 与 def 混用同步为主;ORM/视图支持异步同步为主(3.x 有有限 async 视图)
是否自带 ORM❌(推荐 SQLModel/SQLAlchemy)✅ 自带 ORM + 迁移系统❌(Flask-SQLAlchemy 扩展)
是否自带 Admin 后台❌✅ 开箱即用的 Admin❌
请求校验✅ Pydantic 类型驱动,自动校验表单/DRF Serializer❌ 手工处理(或 marshmallow)
OpenAPI 文档✅ 自动生成(Swagger UI + ReDoc)❌(需 drf-spectacular 等)❌(需 flasgger 等)
依赖注入✅ 内置 Depends❌(靠中间件/装饰器)❌(靠 g 与扩展)
模板渲染Jinja2(需自己配)✅ 自带 DTL 模板✅ 自带 Jinja2
默认项目结构自己定(推荐分层)✅ 脚手架 + 强制 app 结构单文件起步
内置用户认证❌(提供 OAuth2/JWT 工具)✅ 完整 auth 系统❌(Flask-Login 扩展)
学习曲线中(需懂类型注解与异步)陡(东西多,但文档极好)平缓(半小时能上手)
首行代码到上线快(小 API)慢(要理解结构)→ 快(后期)最快(原型)→ 慢(规模上去要自己搭)
典型团队规模1~20 人,微服务/API 团队5~200 人,内容型/管理系统1~5 人,小工具/内部服务

2.2 怎么选:决策树

你的主要产出是什么?
├── 纯 JSON API / 微服务 / ML 模型服务
│   └── FastAPI ✅(自动文档 + 校验 + 异步,几乎无争议)
│
├── 带后台管理的数据录入系统 / CMS / 电商
│   └── Django ✅(Admin 能省掉 60% 的 CRUD 界面开发)
│
├── 主要输出 HTML 页面(服务端渲染)
│   ├── 内容型站点、SEO 重要、要后台 → Django
│   └── 页面数量少、想保持轻量 → Flask
│
└── 一次性脚本 / 内部小工具 / Webhook 接收器
    └── Flask ✅(一个文件就够,别上框架)

三个反直觉的建议

1. 不要因为"FastAPI 更快"就选它。如果你的瓶颈在数据库(99% 的 Web 应用都是),框架本身的速度差异在总响应时间里占比极小。选 FastAPI 的真正理由是开发体验:类型校验、自动文档、依赖注入。

2. 不要因为"Django 重"就避开它。Django 的"重"主要体现在你要读的文档多;一旦上手,Admin + ORM + 迁移 + 认证能省下巨量时间。它的 ORM 也是三者里最成熟的。

3. Flask 的价值在"小而清晰"。一旦你的 Flask 项目开始装 Flask-SQLAlchemy、Flask-Migrate、Flask-Login、Flask-Admin、Flask-RESTful……你其实是在手搓一个更差的 Django。此时应该换框架。


三、FastAPI 深入

3.1 类型注解驱动的开发体验

FastAPI 的核心洞察是:Python 的类型注解已经包含了 Web 框架需要的全部信息。看这个签名:

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

仅凭这些注解,FastAPI 就免费得到了:

注解里的信息FastAPI 自动做的事
item_id 在路径里出现从 URL 路径提取,并转换为 int;转换失败自动返回 422
q 的默认值是 None判定为查询参数(不在路径里 + 有默认值),且可选
`str \None`生成 JSON Schema 的 type: ["string","null"]
short: bool = False把 ?short=1 / ?short=true / ?short=yes 都解析为 True
参数名出现在 OpenAPI 文档里,Swagger UI 自动提供输入框

同样的信息在 Flask 里需要手写:

# Flask 的等价实现:校验、转换、文档全靠自己
@app.get("/items/<item_id>")
def read_item(item_id):
    try:
        item_id = int(item_id)          # 手工转换
    except ValueError:
        return {"error": "item_id 必须是整数"}, 422   # 手工报错
    q = request.args.get("q")            # 手工取值,没有类型校验
    short = request.args.get("short", "false").lower() in ("1", "true", "yes")  # 手工解析布尔
    ...

参数来源的判定规则

| 参数出现的位置 | 被识别为 |

|---|---|

| 出现在路径字符串 {name} 里 | 路径参数 Path |

| 是 Pydantic 模型类型 | 请求体 Body |

| 是单数标量类型(int/str/bool/float…)且不在路径里 | 查询参数 Query |

| 类型是 UploadFile | 文件上传 |

| 用 Header() / Cookie() / Form() 声明 | 对应的位置 |

想强制指定来源,就显式用 Annotated[..., Query()] 之类。

3.2 Pydantic 模型:校验与序列化

Pydantic 是 FastAPI 的校验与序列化引擎。v2 版本用 Rust 重写了核心,速度快了一个数量级。

字段约束

from datetime import datetime
from decimal import Decimal
from typing import Annotated, Literal
from pydantic import BaseModel, Field, EmailStr, ConfigDict


class ProductBase(BaseModel):
    # 用 Annotated + Field 把校验规则贴在类型上,可复用
    name: Annotated[str, Field(min_length=1, max_length=200, description="商品名称")]
    # gt/ge/lt/le 对应 > / >= / < / <=
    price: Annotated[Decimal, Field(gt=0, max_digits=10, decimal_places=2)]
    stock: Annotated[int, Field(ge=0, default=0)]
    # Literal 等价于 JSON Schema 的 enum,非法值会被拒绝
    status: Literal["draft", "on_sale", "sold_out"] = "draft"
    tags: Annotated[list[str], Field(default_factory=list, max_length=10)]


class UserCreate(BaseModel):
    # EmailStr 需要额外安装 email-validator
    email: EmailStr
    # 密码规则:长度 + 正则混合
    password: Annotated[str, Field(min_length=12, max_length=128)]
    # 只在校验时必填,序列化时不输出(见下方 model_config)
    password_confirm: str

    model_config = ConfigDict(
        str_strip_whitespace=True,   # 自动去掉首尾空白,避免"密码前后多打了个空格"
        extra="forbid",              # 出现未声明字段直接报错,防止前端传错字段被静默忽略
    )

嵌套模型

class Address(BaseModel):
    province: str
    city: str
    detail: str
    postal_code: Annotated[str, Field(pattern=r"^\d{6}$")]   # 中国邮编 6 位


class OrderItemIn(BaseModel):
    sku: str
    quantity: Annotated[int, Field(ge=1, le=999)]


class OrderCreate(BaseModel):
    # 嵌套模型会自动递归校验
    shipping_address: Address
    # 列表里的每个元素都会被校验
    items: Annotated[list[OrderItemIn], Field(min_length=1)]
    note: str | None = None

自定义校验器

from pydantic import BaseModel, Field, field_validator, model_validator


class UserCreate(BaseModel):
    email: str
    password: str
    password_confirm: str
    birth_year: int

    # 字段级校验:在类型校验通过后运行
    @field_validator("password")
    @classmethod
    def password_strength(cls, v: str) -> str:
        if not any(c.isdigit() for c in v):
            raise ValueError("密码必须包含至少一个数字")
        if not any(c.isalpha() for c in v):
            raise ValueError("密码必须包含至少一个字母")
        return v

    @field_validator("email", mode="before")
    @classmethod
    def normalize_email(cls, v):
        # mode="before" 在类型校验之前跑,适合做规范化
        return v.strip().lower() if isinstance(v, str) else v

    @field_validator("birth_year")
    @classmethod
    def year_range(cls, v: int) -> int:
        if not 1900 <= v <= 2100:
            raise ValueError("出生年份必须在 1900~2100 之间")
        return v

    # 模型级校验:需要跨字段比较时用它
    @model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.password_confirm:
            raise ValueError("两次输入的密码不一致")
        return self

校验器里的三个坑

1. 不要吞掉异常。校验失败必须 raise ValueError(...)(或 AssertionError),return None 不会让校验失败,只会得到一个 None 值。

2. field_validator 要加 @classmethod(v2 要求)。漏了会得到一个含义模糊的运行时报错。

3. mode="after" 的模型校验器里改字段要用 self.model_copy(update=...) 或直接赋值(Pydantic v2 默认允许在 validator 内赋值),不要试图 return {...} 一个 dict。

序列化控制:响应模型

from pydantic import BaseModel, ConfigDict, Field


class UserBase(BaseModel):
    email: str
    nickname: str


class UserCreate(UserBase):
    password: str


class UserPublic(UserBase):
    """对外暴露的用户信息——绝不包含 password 字段。"""
    id: int
    created_at: datetime

    # 允许从 ORM 对象(带属性的类实例)构造,而不只是从 dict
    model_config = ConfigDict(from_attributes=True)


class UserInDB(UserBase):
    """内部使用的用户模型——包含哈希后的密码。"""
    id: int
    hashed_password: str

用响应模型防止字段泄露

如果路由函数返回 ORM 对象而没声明 response_model,FastAPI 会尝试序列化它的全部属性——包括 hashed_password、internal_note。每一个对外接口都要显式声明 response_model(或用返回类型注解),这是最廉价的安全措施。

另一种写法是用 Field(exclude=True) 标记敏感字段,但显式的 response_model 更清晰、更不容易漏。

3.3 依赖注入 Depends

FastAPI 的依赖注入系统是它最强大也最容易被低估的部分。一个"依赖"就是一个可调用对象,它可以接收和路由函数一样的参数。

from typing import Annotated
from fastapi import Depends, FastAPI, Query

app = FastAPI()


# 依赖项:和路由函数一样声明参数,只是没有装饰器
async def common_parameters(
    q: str | None = None,
    skip: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
) -> dict:
    return {"q": q, "skip": skip, "limit": limit}


# 推荐写法:用 Annotated 把依赖"类型化",这样编辑器能推断出返回类型
CommonsDep = Annotated[dict, Depends(common_parameters)]


@app.get("/items/")
async def read_items(commons: CommonsDep):
    return commons          # commons 就是 common_parameters 的返回值


@app.get("/users/")
async def read_users(commons: CommonsDep):
    # 同一个依赖被复用了,而且它声明的 q/skip/limit 参数
    # 会自动出现在这个路由的查询参数里与 OpenAPI 文档里
    return commons

为什么推荐 Annotated 而不是 = Depends(...)

```python

# 老写法(仍可用)—— 默认值位置被 Depends 占用,无法表达"这个参数还有默认值"

async def read_items(commons: dict = Depends(common_parameters)): ...

# 推荐写法 —— 类型信息完整,可以复用类型别名,且能和默认值共存

CommonsDep = Annotated[dict, Depends(common_parameters)]

async def read_items(commons: CommonsDep): ...

```

FastAPI 从 0.95.0 起支持并推荐 Annotated。官方文档明确提示:使用之前请确保版本 ≥ 0.95.1。

依赖的三类典型用途

① 鉴权:从 Token 解出当前用户

# app/api/deps.py
from typing import Annotated
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer

from app.core.security import decode_access_token
from app.db.session import SessionDep
from app.models.user import User
from app.schemas.token import TokenPayload

# tokenUrl 只是告诉 Swagger UI 该往哪个接口发用户名密码
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
TokenDep = Annotated[str, Depends(oauth2_scheme)]


async def get_current_user(db: SessionDep, token: TokenDep) -> User:
    credentials_error = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="凭证无效或已过期",
        # WWW-Authenticate 是 OAuth2 规范要求的响应头
        headers={"WWW-Authenticate": "Bearer"},
    )
    payload: TokenPayload | None = decode_access_token(token)
    if payload is None:
        raise credentials_error

    user = db.get(User, payload.sub)
    if user is None:
        raise credentials_error
    if not user.is_active:
        # 403 而非 401:身份是真实的,只是没权限
        raise HTTPException(status_code=403, detail="账号已被停用")
    return user


CurrentUser = Annotated[User, Depends(get_current_user)]


async def get_current_superuser(user: CurrentUser) -> User:
    """依赖可以依赖另一个依赖——这就是"子依赖项"。"""
    if not user.is_superuser:
        raise HTTPException(status_code=403, detail="需要超级管理员权限")
    return user


CurrentSuperuser = Annotated[User, Depends(get_current_superuser)]

② 分页参数:把重复的解析逻辑收进一处

from dataclasses import dataclass
from typing import Annotated
from fastapi import Depends, Query


@dataclass(frozen=True, slots=True)
class Pagination:
    page: int
    page_size: int

    @property
    def offset(self) -> int:
        # 用属性而不是方法,调用处更简洁:pagination.offset
        return (self.page - 1) * self.page_size

    @property
    def limit(self) -> int:
        return self.page_size


def get_pagination(
    page: Annotated[int, Query(ge=1, description="页码,从 1 开始")] = 1,
    page_size: Annotated[int, Query(ge=1, le=100, description="每页条数")] = 20,
) -> Pagination:
    return Pagination(page=page, page_size=page_size)


PaginationDep = Annotated[Pagination, Depends(get_pagination)]

③ 数据库会话:用 yield 保证一定释放

# app/db/session.py
from collections.abc import Generator
from typing import Annotated
from fastapi import Depends
from sqlalchemy.orm import Session, sessionmaker

from app.core.config import settings
from app.db.base import engine

SessionLocal = sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)


def get_db() -> Generator[Session, None, None]:
    """每个请求一个 Session;无论成功还是抛异常都会 close。"""
    db = SessionLocal()
    try:
        yield db                # ← yield 之前是"建立",之后是"清理"
    finally:
        db.close()              # 用 finally 保证异常路径也会关闭


SessionDep = Annotated[Session, Depends(get_db)]

yield 依赖的执行时机

```python

async def get_resource():

print("① 建立资源") # 请求处理之前

resource = await acquire()

try:

yield resource # → 交给路由函数使用

except Exception:

print("② 路由抛异常了") # 路由内异常会传进来(不要在这里吞掉)

raise

finally:

print("③ 释放资源") # 响应发送之后

await release(resource)

```

- yield 之后的清理代码在响应发送完成后执行。

- 如果你想在清理代码里改响应(比如加响应头),会得到 RuntimeError: Caught handled exception, but response already started。不要在 yield 之后碰 Response 对象。

- 如果你的清理代码需要 await,依赖本身必须是 async def。

3.4 路径、查询参数与响应

from enum import Enum
from typing import Annotated
from fastapi import FastAPI, Path, Query, status
from pydantic import BaseModel

app = FastAPI(title="示例 API", version="1.0.0")


class SortOrder(str, Enum):
    """继承 str 的枚举:既能被 JSON 序列化,又能用于类型提示。"""
    asc = "asc"
    desc = "desc"


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


@app.get(
    "/items/{item_id}",
    response_model=ItemOut,                        # ← 声明输出结构
    status_code=status.HTTP_200_OK,
    summary="获取单个商品",
    description="按 ID 查询商品详情。**注意**:不存在的 ID 返回 404。",
    response_description="商品详情",
    tags=["items"],                                 # 文档分组
    responses={404: {"description": "商品不存在"}},  # 补充文档里的错误响应
)
async def get_item(
    # Path 用于给路径参数加约束与文档说明
    item_id: Annotated[int, Path(ge=1, description="商品 ID")],
    # Query 用于校验与文档化查询参数
    q: Annotated[str | None, Query(max_length=50)] = None,
    order: SortOrder = SortOrder.asc,
):
    ...


@app.post(
    "/items/",
    response_model=ItemOut,
    # 201 Created 是创建资源的正确状态码
    status_code=status.HTTP_201_CREATED,
)
async def create_item(payload: ItemOut):
    ...

状态码常量:用 fastapi.status 而不是裸数字,可读性差别很大。

常量值用途
status.HTTP_200_OK200通用成功
status.HTTP_201_CREATED201资源创建成功
status.HTTP_204_NO_CONTENT204删除成功,无响应体
status.HTTP_400_BAD_REQUEST400请求语义错误
status.HTTP_401_UNAUTHORIZED401未认证 / 凭证无效
status.HTTP_403_FORBIDDEN403已认证但无权限
status.HTTP_404_NOT_FOUND404资源不存在
status.HTTP_409_CONFLICT409唯一约束冲突
status.HTTP_422_UNPROCESSABLE_ENTITY422校验失败(FastAPI 默认)
status.HTTP_429_TOO_MANY_REQUESTS429触发限流

返回 204 时不要返回 body

```python

# ❌ 会报错或产生非法响应

@app.delete("/items/{id}", status_code=204)

async def delete_item(id: int):

return {"ok": True}

# ✅ 显式返回 Response,或者在签名里声明 response_class=Response

from fastapi import Response

@app.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)

async def delete_item(id: int, db: SessionDep):

...

return Response(status_code=status.HTTP_204_NO_CONTENT)

```

3.5 OpenAPI 文档的生成机制

FastAPI 的文档不是"手写的注释",而是从类型注解推导出来的 JSON Schema。流程是:

Python 类型注解
   ↓ FastAPI 收集(参数、Pydantic 模型、response_model、status_code、tags)
JSON Schema(由 Pydantic 生成,符合 JSON Schema 规范)
   ↓ FastAPI 组装
OpenAPI 3.1 文档(一个 JSON,默认在 /openapi.json)
   ↓ 前端 UI 渲染
Swagger UI (/docs) 与 ReDoc (/redoc)
from fastapi import FastAPI

app = FastAPI(
    title="任务管理 API",
    version="1.0.0",
    description="演示 FastAPI 的自动文档能力。",
    # 生产环境用 docs_url=None 关掉文档,或加鉴权
    docs_url="/docs",        # Swagger UI,可交互"Try it out"
    redoc_url="/redoc",      # ReDoc,更适合阅读
    openapi_url="/openapi.json",
    # 把接口按标签分组显示时的顺序固定下来
    openapi_tags=[
        {"name": "tasks", "description": "任务的增删改查"},
        {"name": "auth", "description": "认证与令牌"},
    ],
)

顺带能做的事:

# ① 生成前端类型定义 / 客户端 SDK(需要 Node)
#    npx openapi-typescript http://localhost:8000/openapi.json -o ./web/src/api-types.ts

# ② 在 CI 里做契约校验:把 openapi.json 固化成快照,接口不兼容变更会让 CI 失败

生产环境不要把 /docs 裸奔

/openapi.json 会暴露你全部的接口路径、参数名、字段名与内部枚举,等于给攻击者一份完整的地图。两个做法:

```python

# 做法 A:生产环境关掉(最简单)

app = FastAPI(

docs_url=None if settings.ENVIRONMENT == "production" else "/docs",

redoc_url=None if settings.ENVIRONMENT == "production" else "/redoc",

openapi_url=None if settings.ENVIRONMENT == "production" else "/openapi.json",

)

```

```python

# 做法 B:给文档加上鉴权(推荐给内部服务)

from fastapi.openapi.docs import get_swagger_ui_html

from fastapi import Depends

@app.get("/docs", include_in_schema=False)

async def protected_docs(user: CurrentSuperuser):

return get_swagger_ui_html(openapi_url="/openapi.json", title="API 文档")

```

3.6 同步路由与异步路由混用:最危险的坑

这是 FastAPI 新手最常闯的祸,也是生产事故的常见原因。

铁律

- async def 路由:运行在事件循环线程里。里面绝不能出现阻塞调用,否则所有并发请求一起卡住。

- def 路由(无 async):FastAPI 会自动丢到线程池里跑(anyio 的工作线程池,默认 40 个线程)。里面写阻塞代码是安全的,但受线程池大小限制。

import time
import requests                       # 同步 HTTP 库
from fastapi import FastAPI
from sqlalchemy.orm import Session

app = FastAPI()


# ❌ 灾难:async 路由 + 阻塞调用
@app.get("/bad/weather")
async def bad_weather():
    # time.sleep 会冻结整个事件循环 2 秒——所有其他请求一起等
    time.sleep(2)
    # requests 也是同步阻塞的:网络等待期间事件循环同样停摆
    r = requests.get("https://api.example.com/weather", timeout=5)
    return r.json()


# ✅ 修法 A:改成 def,让 FastAPI 丢线程池(改动最小)
@app.get("/ok/weather-thread")
def ok_weather_thread():
    time.sleep(2)                     # 阻塞的是线程池里的线程,不影响事件循环
    r = requests.get("https://api.example.com/weather", timeout=5)
    return r.json()


# ✅ 修法 B:保持 async,但改用异步库
import asyncio
import httpx                          # 异步 HTTP 客户端

@app.get("/ok/weather-async")
async def ok_weather_async():
    await asyncio.sleep(2)            # 挂起协程,事件循环去干别的
    async with httpx.AsyncClient(timeout=5) as client:
        r = await client.get("https://api.example.com/weather")
    return r.json()


# ⚠️ 常见误区:以为包一层 asyncio.to_thread 就万事大吉
@app.get("/meh/weather-to-thread")
async def meh_weather():
    # 这样做是"能跑",但每次都新建线程,开销不小;
    # 高并发下线程数会失控。它适合"偶尔调用一次"的场景。
    return await asyncio.to_thread(requests.get, "https://api.example.com/weather")

哪些调用是"阻塞的",需要特别警惕:

阻塞(不能在 async def 里直接调用)异步替代
time.sleep()await asyncio.sleep()
requests.get/post()await httpx.AsyncClient().get()
open() / f.read() 大文件await anyio.Path(...).read_text()/await asyncio.to_thread(...)
psycopg2 / 同步 SQLAlchemy Sessionasyncpg / SQLAlchemy 的 AsyncSession
redis-py 同步客户端redis.asyncio
boto3(AWS SDK)aioboto3 / aiobotocore
同步 subprocess.run()await asyncio.create_subprocess_exec()
CPU 密集计算(图像、加密、大 JSON)worker_processes / ProcessPoolExecutor

三个容易漏掉的细节

1. def 路由跑在线程池里,但依赖项也遵循同样规则。async def 的依赖在事件循环里,def 的依赖在线程池里。混用时要注意:一个 async def 路由配一个 def 依赖(比如同步 DB 会话),FastAPI 会把依赖放到线程池,这是安全的。

2. 线程池默认只有 40 个线程。如果你的 def 路由里有慢查询,40 个并发就排队了。可以通过 anyio.to_thread.current_default_thread_limiter().total_tokens = 100 调整(以官方最新文档为准)。

3. 同步 SQLAlchemy Session 在 async 路由里是灾难。每次 .all() 都会阻塞事件循环。要么用 def 路由,要么换成 AsyncSession + asyncpg。

3.7 中间件与异常处理器

中间件:对每一个请求/响应都生效,适合日志、耗时、request id、CORS。

import time
import uuid
from fastapi import FastAPI, Request, Response
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# CORS 用官方内置中间件,不要手写
app.add_middleware(
    CORSMiddleware,
    # 生产环境必须收敛为白名单;["*"] 不能与 allow_credentials=True 共存
    allow_origins=["http://localhost:5173"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
    allow_headers=["*"],
)


@app.middleware("http")
async def add_request_id_and_timing(request: Request, call_next):
    # 中间件是"洋葱"结构:这里的代码在路由之前
    request_id = request.headers.get("x-request-id") or uuid.uuid4().hex
    # 挂到 request.state 上,路由函数里可以用 request.state.request_id 读到
    request.state.request_id = request_id

    start = time.perf_counter()
    response: Response = await call_next(request)
    elapsed_ms = (time.perf_counter() - start) * 1000

    # 这里的代码在路由之后、响应发送之前
    response.headers["x-request-id"] = request_id
    response.headers["x-process-time-ms"] = f"{elapsed_ms:.1f}"
    return response

异常处理器:把业务异常翻译成统一的 JSON 结构。

from fastapi import FastAPI, Request, status
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()


class AppError(Exception):
    """业务异常基类:带上给前端看的 code 与 HTTP 状态码。"""
    def __init__(self, code: str, message: str, status_code: int = 400):
        self.code = code
        self.message = message
        self.status_code = status_code
        super().__init__(message)


class NotFoundError(AppError):
    def __init__(self, message: str = "资源不存在"):
        super().__init__("NOT_FOUND", message, status.HTTP_404_NOT_FOUND)


class ConflictError(AppError):
    def __init__(self, message: str = "资源冲突"):
        super().__init__("CONFLICT", message, status.HTTP_409_CONFLICT)


def error_body(code: str, message: str, details=None, request_id: str | None = None) -> dict:
    body = {"success": False, "error": {"code": code, "message": message}}
    if details:
        body["error"]["details"] = details
    if request_id:
        body["error"]["requestId"] = request_id
    return body


@app.exception_handler(AppError)
async def app_error_handler(request: Request, exc: AppError):
    return JSONResponse(
        status_code=exc.status_code,
        content=error_body(exc.code, exc.message, request_id=getattr(request.state, "request_id", None)),
    )


@app.exception_handler(RequestValidationError)
async def validation_error_handler(request: Request, exc: RequestValidationError):
    """把 FastAPI 默认的 422 结构改成项目统一的格式。"""
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content=error_body(
            "VALIDATION_ERROR",
            "请求参数校验失败",
            details=exc.errors(),
            request_id=getattr(request.state, "request_id", None),
        ),
    )

异常处理器的三个坑

1. 注册顺序无关,但类型匹配是精确的。@app.exception_handler(AppError) 能捕获 NotFoundError(子类),但如果你同时注册了 AppError 和 NotFoundError,更具体的那个优先。

2. HTTPException 有自己的处理器。想统一格式,要额外注册 @app.exception_handler(StarletteHTTPException)。

3. 500 的错误要在中间件里兜。未捕获的普通 Exception 会变成 500,但响应已经生成,异常处理器拿不到请求上下文。想要统一的 500 响应结构,用一个 try/except 中间件:

```python

@app.middleware("http")

async def catch_all(request: Request, call_next):

try:

return await call_next(request)

except Exception:

logger.exception("未处理的服务端异常") # 完整堆栈进日志

return JSONResponse(status_code=500, content=error_body("INTERNAL_ERROR", "服务器内部错误"))

```

3.8 后台任务

BackgroundTasks 让某些工作在响应返回之后执行,用户不用等。

from fastapi import BackgroundTasks, FastAPI

app = FastAPI()


def send_welcome_email(email: str, name: str) -> None:
    """同步函数会被丢到线程池执行,不会阻塞事件循环。"""
    # 实际项目里换成真正的邮件发送
    print(f"发送欢迎邮件到 {email},称呼:{name}")


def write_audit_log(user_id: int, action: str) -> None:
    print(f"审计日志:用户 {user_id} 执行了 {action}")


@app.post("/users/")
async def create_user(
    email: str,
    name: str,
    background_tasks: BackgroundTasks,      # 声明即可,FastAPI 会注入
):
    user_id = 1                              # 假设已写库
    # 添加任务:按添加顺序依次执行
    background_tasks.add_task(send_welcome_email, email, name)
    background_tasks.add_task(write_audit_log, user_id, "create_user")
    return {"id": user_id, "email": email}

BackgroundTasks 的正确适用边界

| 场景 | 该用什么 |

|---|---|

| 发一封邮件、写一条审计日志、清一个临时文件 | ✅ BackgroundTasks |

| 处理一张图片(几十秒 CPU) | ⚠️ 会占住 worker,应交给独立队列 |

| 需要重试、需要保证执行、需要进度查询 | ❌ 用 Celery / ARQ / RQ + Redis |

| 处理几万条记录 | ❌ 必须用独立任务队列 |

关键限制:BackgroundTasks 与进程同生共死。如果 worker 在任务执行前被重启(部署、OOM、--reload),任务会永久丢失。它没有持久化、没有重试。

另外:必须在返回响应之前 add_task。在后台任务内部再 add_task 不会被执行。

3.9 项目结构推荐

分层的意义

一句话:让依赖方向单向流动。api → services → models/repositories,反过来不行。这样 services 可以被脚本、定时任务、测试直接调用,不需要经过 HTTP。

反面模式:在路由函数里写 SQL、写业务规则、写邮件发送。这样的代码无法测试、无法复用、改一处崩三处。

app/
├── main.py                  # FastAPI 实例、中间件、异常处理器、路由挂载
├── api/
│   ├── deps.py              # 共享依赖:get_db、get_current_user、分页…
│   └── v1/
│       ├── router.py        # 汇总本版本所有路由
│       ├── auth.py
│       └── tasks.py
├── core/
│   ├── config.py            # pydantic-settings 配置
│   ├── security.py          # 密码哈希、JWT 编解码
│   └── logging.py           # 日志配置
├── db/
│   ├── base.py              # ORM Base、engine
│   └── session.py           # SessionLocal、get_db 依赖
├── models/                  # SQLAlchemy 模型(数据库表的映射)
│   ├── __init__.py          # ⚠️ 必须导入全部模型,否则 create_all 建不出表
│   ├── user.py
│   └── task.py
├── schemas/                 # Pydantic 模型(API 的输入输出契约)
│   ├── common.py            # 分页响应、统一错误结构
│   ├── token.py
│   ├── user.py
│   └── task.py
└── services/                # 业务逻辑(不依赖 FastAPI)
    ├── user_service.py
    └── task_service.py
层该放什么绝不该放什么
api/解析请求、调用 service、返回 schemaSQL、业务规则
schemas/Pydantic 模型、字段校验数据库操作、业务逻辑
models/表结构、关系、约束HTTP 概念、请求校验
services/业务规则、事务边界Request/HTTPException
core/配置、安全、日志业务逻辑

四、Django 概览

4.1 MTV 模式

Django 官方不叫 MVC,叫 MTV(Model-Template-View)。对应关系是:

Django 的层对应 MVC职责
ModelModel数据结构与数据库访问(ORM)
TemplateView呈现层:HTML 渲染
ViewController业务逻辑:接收请求、返回响应
(URLconf)—路由:URL → View 的映射
请求 → URLconf (urls.py) → View (views.py) → Model (models.py) ←→ 数据库
                                    ↓
                              Template (*.html) → HTML 响应

4.2 ORM 与迁移

# blog/models.py
from django.db import models


class Author(models.Model):
    name = models.CharField(max_length=200)
    email = models.EmailField(unique=True)

    def __str__(self):
        return self.name


class Post(models.Model):
    class Status(models.TextChoices):
        DRAFT = "draft", "草稿"
        PUBLISHED = "published", "已发布"

    # on_delete 是必填的:CASCADE 表示作者删除时文章一起删
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="posts")
    title = models.CharField(max_length=255, db_index=True)
    body = models.TextField()
    status = models.CharField(max_length=20, choices=Status.choices, default=Status.DRAFT)
    tags = models.ManyToManyField("Tag", blank=True, related_name="posts")
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ["-created_at"]                    # 默认排序
        indexes = [
            # 复合索引:覆盖"按状态过滤 + 按时间排序"这个最常见的查询
            models.Index(fields=["status", "-created_at"]),
        ]

    def __str__(self):
        return self.title


class Tag(models.Model):
    name = models.CharField(max_length=50, unique=True)

    def __str__(self):
        return self.name
# 迁移的两步流程:生成(读模型差异)→ 应用(执行 SQL)
python manage.py makemigrations blog
python manage.py migrate

# 查看将要执行的 SQL(生产环境执行前一定要看)
python manage.py sqlmigrate blog 0001

# 检查模型与迁移是否一致(CI 里当门禁用)
python manage.py makemigrations --check --dry-run

迁移的三个坑

1. makemigrations 只看模型文件,不看数据库。如果有人手改过表结构,Django 不知道,生成的迁移会失败。

2. 改字段类型/加非空字段会导致表锁。大表上要分步:① 加可空字段 → ② 回填数据 → ③ 加非空约束。Django 会问你要默认值,别随便选"立即提供一次性默认值"。

3. 迁移文件必须进版本控制,且不要手工改已应用的迁移。要修错就新加一个迁移。

4.3 Admin 后台

Django 最省时间的功能。注册模型就有完整的增删改查界面:

# blog/admin.py
from django.contrib import admin
from .models import Author, Post, Tag


@admin.register(Author)
class AuthorAdmin(admin.ModelAdmin):
    list_display = ("name", "email")
    search_fields = ("name", "email")


@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    # 列表页显示的列 —— 直接写关联字段用双下划线
    list_display = ("title", "author", "status", "created_at", "tag_list")
    # 右侧过滤器
    list_filter = ("status", "created_at", "author")
    search_fields = ("title", "body")
    # 列表页可直接编辑的字段
    list_editable = ("status",)
    # 预取关联对象,避免列表页 N+1 查询(重要!)
    list_select_related = ("author",)
    prepopulated_fields = {}                      # slug 字段可用它自动填充
    date_hierarchy = "created_at"
    filter_horizontal = ("tags",)                 # 多对多用更友好的穿梭框
    actions = ["mark_published"]

    @admin.display(description="标签")
    def tag_list(self, obj):
        # 这里会为每一行触发一次查询 —— 小数据量可接受,
        # 数据量大时应该在 get_queryset 里 prefetch_related("tags")
        return "、".join(t.name for t in obj.tags.all())

    def get_queryset(self, request):
        # Admin 列表页最容易出 N+1,在这里统一优化
        return super().get_queryset(request).select_related("author").prefetch_related("tags")

    @admin.action(description="批量标记为已发布")
    def mark_published(self, request, queryset):
        # 用 update() 而不是循环 save():一条 SQL 搞定
        updated = queryset.update(status=Post.Status.PUBLISHED)
        self.message_user(request, f"已发布 {updated} 篇文章")


admin.site.register(Tag)

4.4 惰性查询集与 N+1 问题

QuerySet 是惰性的

官方文档原话:"QuerySet objects are lazy -- the act of creating a QuerySet doesn't involve any database activity." 构建、过滤、切片都不会碰数据库,直到你求值它。

# 以下三行:零次数据库查询
q = Post.objects.filter(title__startswith="Django")
q = q.filter(created_at__year=2026)
q = q.exclude(body__icontains="废弃")

# 只有到这一步才真正执行 SQL
list(q)              # 求值

触发求值的时机(记住这几个就够):

操作是否触发查询
list(qs)、for x in qs、len(qs)✅
if qs:(调用 __bool__)✅
qs[0](索引,非切片)✅
qs.count()、qs.exists()、qs.first()✅
repr(qs)(打印)/ Shell 里显示✅
qs.filter(...)、qs.order_by(...)、qs[:5]❌ 仍是 QuerySet
qs[0:5](切片)❌ 仍是 QuerySet

N+1 问题:先查 1 次拿到 N 条记录,然后循环里每条再查 1 次,共 N+1 次查询。

# ❌ N+1:1 次查文章 + N 次查作者
posts = Post.objects.all()            # 查询 1
for post in posts:
    print(post.title, post.author.name)   # 每次访问 .author 都查一次数据库!
# ✅ 用 select_related 一次 JOIN 出来
posts = Post.objects.select_related("author").all()   # 只查询 1 次
for post in posts:
    print(post.title, post.author.name)   # 不再查库,author 已缓存

select_related 与 prefetch_related 的区别与选型

对比项select_related()prefetch_related()
实现方式SQL JOIN,在主查询里一起取回额外的独立查询,在 Python 里做"拼接"
查询次数1 次2 次(主查询 + 1 次 IN 查询)
支持的关系一对一、多对一(ForeignKey、OneToOneField)多对多、一对多(反向 ForeignKey、ManyToManyField)
数据量影响JOIN 会放大结果集(一对多时会重复主表行)不放大主查询结果集
能否加过滤可以用 Prefetch 对象,但受限✅ 可用 Prefetch(queryset=...) 精细控制
适用场景正向取"父对象"(文章→作者)反向取"子对象集合"(作者→所有文章)
# 正向多对一:用 select_related(JOIN)
Post.objects.select_related("author")

# 反向一对多 / 多对多:用 prefetch_related(两条查询)
Author.objects.prefetch_related("posts")
Post.objects.prefetch_related("tags")

# 可以链式组合
Post.objects.select_related("author").prefetch_related("tags")

# 多层关系用双下划线连起来
Post.objects.select_related("author__profile")
# 高级:用 Prefetch 精确控制预取的内容(只取需要的字段、加过滤、改排序)
from django.db.models import Prefetch

published_posts = Post.objects.filter(status=Post.Status.PUBLISHED).only("id", "title", "author_id")

authors = Author.objects.prefetch_related(
    Prefetch("posts", queryset=published_posts, to_attr="published_posts")
)
for author in authors:
    # to_attr 让结果挂到普通列表属性上,可以用 len()/切片
    print(author.name, len(author.published_posts))

怎么发现 N+1

1. django-debug-toolbar:开发时在页面上直接看到本次请求的所有 SQL 与重复次数。

2. django.db.connection.queries:在 Shell 或测试里检查 len(connection.queries)。

3. CI 里加断言:用 assertNumQueries 把查询数固定下来,一旦有人写出 N+1,测试直接失败。

```python

from django.test import TestCase

class PostListViewTests(TestCase):

def test_list_page_query_count(self):

# 一旦有人删掉 select_related,这个测试就会失败

with self.assertNumQueries(2):

self.client.get("/posts/")

```

4.5 settings 分环境管理

反模式:一个巨大的 settings.py 里塞满 if DEBUG:。

推荐模式:settings/ 包 + 分环境文件 + 从环境变量读密钥。

# settings/base.py —— 所有环境共用的配置
from pathlib import Path
import os

BASE_DIR = Path(__file__).resolve().parent.parent.parent

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "rest_framework",
    "blog",
]

# ⚠️ 密钥必须从环境变量读,绝不写死在代码里
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]

# 安全默认值:默认关闭调试
DEBUG = False
ALLOWED_HOSTS: list[str] = []

# 密码哈希:用 Argon2(比默认 PBKDF2 更抗 GPU 暴力破解)
PASSWORD_HASHERS = [
    "django.contrib.auth.hashers.Argon2PasswordHasher",
    "django.contrib.auth.hashers.PBKDF2PasswordHasher",   # 保留以便校验旧哈希
]

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.SessionAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
    "PAGE_SIZE": 20,
    "DEFAULT_THROTTLE_CLASSES": ["rest_framework.throttling.AnonRateThrottle"],
    "DEFAULT_THROTTLE_RATES": {"anon": "100/hour"},
}
# settings/dev.py —— 本地开发
from .base import *          # noqa: F403

DEBUG = True
ALLOWED_HOSTS = ["localhost", "127.0.0.1", "0.0.0.0"]

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",   # noqa: F405
    }
}
# settings/prod.py —— 生产
from .base import *          # noqa: F403
import os

DEBUG = False
ALLOWED_HOSTS = os.environ["DJANGO_ALLOWED_HOSTS"].split(",")

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        # 用独立的 DATABASE_URL 解析,或用 django-environ
        "NAME": os.environ["POSTGRES_DB"],
        "USER": os.environ["POSTGRES_USER"],
        "PASSWORD": os.environ["POSTGRES_PASSWORD"],
        "HOST": os.environ.get("POSTGRES_HOST", "localhost"),
        "PORT": os.environ.get("POSTGRES_PORT", "5432"),
        # 连接复用:每个请求不新建连接(默认就是 0,显式写出来更清楚)
        "CONN_MAX_AGE": 60,
        "OPTIONS": {"connect_timeout": 5},
    }
}

# 安全加固:反向代理后面 + HTTPS
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31_536_000            # 1 年
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

# 静态文件交给 Nginx / whitenoise
STATIC_ROOT = BASE_DIR / "staticfiles"      # noqa: F405
# 通过 DJANGO_SETTINGS_MODULE 切换环境
export DJANGO_SETTINGS_MODULE=settings.dev     # Linux/macOS
$env:DJANGO_SETTINGS_MODULE = "settings.dev"   # Windows PowerShell

python manage.py runserver

4.6 DRF 做 API 的基本结构

Django REST Framework(DRF)是 Django 生态里做 API 的标准方案。

# blog/serializers.py —— 输入校验 + 输出序列化
from rest_framework import serializers
from .models import Post, Tag


class TagSerializer(serializers.ModelSerializer):
    class Meta:
        model = Tag
        fields = ["id", "name"]


class PostSerializer(serializers.ModelSerializer):
    # 只读的嵌套展示
    author_name = serializers.CharField(source="author.name", read_only=True)
    tags = TagSerializer(many=True, read_only=True)
    # 写入用的字段(只接受 ID 列表)
    tag_ids = serializers.PrimaryKeyRelatedField(
        queryset=Tag.objects.all(), many=True, write_only=True, required=False
    )

    class Meta:
        model = Post
        fields = ["id", "title", "body", "status", "author_name", "tags", "tag_ids", "created_at"]
        read_only_fields = ["created_at"]

    def validate_title(self, value):
        # 字段级校验:Django 的约定是 validate_<field_name>
        if len(value.strip()) < 3:
            raise serializers.ValidationError("标题至少 3 个字符")
        return value.strip()

    def create(self, validated_data):
        tag_ids = validated_data.pop("tag_ids", [])
        post = Post.objects.create(**validated_data)
        if tag_ids:
            # 一次 add 多个,减少 SQL 数量
            post.tags.add(*tag_ids)
        return post
# blog/views.py —— 用 DRF 的通用视图,代码量极小
from rest_framework import viewsets, permissions, filters
from rest_framework.pagination import PageNumberPagination
from .models import Post
from .serializers import PostSerializer


class PostPagination(PageNumberPagination):
    page_size = 20
    page_size_query_param = "page_size"
    max_page_size = 100


class PostViewSet(viewsets.ModelViewSet):
    """一次拿到 list / create / retrieve / update / destroy 五个动作。"""
    serializer_class = PostSerializer
    permission_classes = [permissions.IsAuthenticatedOrReadOnly]
    pagination_class = PostPagination
    filter_backends = [filters.SearchFilter, filters.OrderingFilter]
    search_fields = ["title", "body"]
    ordering_fields = ["created_at", "title"]

    def get_queryset(self):
        # ⚠️ 必须在 queryset 上做关联预取,否则列表接口会 N+1
        return Post.objects.select_related("author").prefetch_related("tags")

    def perform_create(self, serializer):
        # 作者从当前登录用户取,不让前端传(否则可以伪造成别人)
        serializer.save(author=self.request.user)
# blog/urls.py
from rest_framework.routers import DefaultRouter
from .views import PostViewSet

router = DefaultRouter()
router.register(r"posts", PostViewSet, basename="post")
urlpatterns = router.urls

DRF vs Django Ninja

DRF 成熟、生态大、文档全;但它是同步的,且序列化器写法偏啰嗦。想在 Django 里获得 FastAPI 那样的类型注解体验,可以看 Django Ninja 或 django-ninja-extra——同样基于 Pydantic,自动生成 OpenAPI。选型时权衡:DRF 的"稳" vs Ninja 的"快"。以官方最新文档为准。


五、Flask 概览

5.1 最小内核与扩展生态

# hello.py —— 完整可运行的 Flask 应用(5 行)
from flask import Flask

app = Flask(__name__)


@app.get("/")
def index():
    return {"message": "Hello, Flask!"}     # 返回 dict 会自动 JSON 化


if __name__ == "__main__":
    # debug=True 只用于开发:会自动重载 + 提供交互式调试器
    app.run(debug=True, port=5000)

# 启动:python hello.py
# 或:  flask --app hello run --debug

Flask 的设计是"内核极小,能力靠扩展":

需求扩展
ORMFlask-SQLAlchemy
数据库迁移Flask-Migrate(封装 Alembic)
登录会话Flask-Login
表单与 CSRFFlask-WTF
管理后台Flask-Admin
REST APIFlask-RESTful / Flask-Smorest
缓存Flask-Caching
限流Flask-Limiter

扩展装多了就不如换框架

当你装上第 5 个扩展,并且开始自己写"统一响应格式""全局异常处理""权限装饰器"时,你已经在手搓一个更差的 Django 或 FastAPI 了。判断标准:如果你的项目需要 Admin 后台 + 用户系统 + ORM 迁移,直接用 Django。

5.2 蓝图(Blueprint)

蓝图是 Flask 的模块化机制,对应 Django 的 app、FastAPI 的 APIRouter。

# app/tasks/views.py
from flask import Blueprint, jsonify, request, abort

# url_prefix 在这里定义,模块内部不需要关心完整路径
bp = Blueprint("tasks", __name__, url_prefix="/api/tasks")

_FAKE_DB: dict[int, dict] = {}


@bp.get("/")
def list_tasks():
    return jsonify(list(_FAKE_DB.values()))


@bp.get("/<int:task_id>")
def get_task(task_id: int):
    task = _FAKE_DB.get(task_id)
    if task is None:
        # abort 抛出 HTTP 异常,交给 Flask 的错误处理器
        abort(404, description="任务不存在")
    return jsonify(task)


@bp.post("/")
def create_task():
    # ⚠️ silent=True 时解析失败返回 None,而不是抛 400
    payload = request.get_json(silent=True)
    if not payload or not payload.get("title"):
        abort(400, description="title 是必填字段")
    task_id = len(_FAKE_DB) + 1
    _FAKE_DB[task_id] = {"id": task_id, "title": payload["title"]}
    # 返回 (body, status) 元组即可设置状态码
    return jsonify(_FAKE_DB[task_id]), 201
# app/__init__.py —— 应用工厂
from flask import Flask
from .tasks.views import bp as tasks_bp


def create_app(config_object="config.DevConfig") -> Flask:
    """应用工厂模式:让测试可以创建独立配置的实例。"""
    app = Flask(__name__)
    app.config.from_object(config_object)

    app.register_blueprint(tasks_bp)

    @app.errorhandler(404)
    def not_found(error):
        return {"success": False, "error": {"code": "NOT_FOUND", "message": str(error)}}, 404

    @app.errorhandler(500)
    def internal_error(error):
        # 5xx 必须记日志,但不把堆栈返回给客户端
        app.logger.exception("服务端错误")
        return {"success": False, "error": {"code": "INTERNAL_ERROR", "message": "服务器内部错误"}}, 500

    return app
# wsgi.py —— 生产入口(Gunicorn 会找这个变量)
from app import create_app

app = create_app("config.ProdConfig")

# 启动:gunicorn -w 4 -b 0.0.0.0:8000 wsgi:app

5.3 request 上下文与 g

Flask 的 request 是一个上下文局部代理(context local proxy),不是全局变量。它在每个请求的上下文中指向不同的对象,这让多线程环境下依然安全。

from flask import Flask, g, request, session

app = Flask(__name__)


@app.before_request
def load_current_user():
    """每个请求开始时执行一次——适合放鉴权与资源准备。"""
    # g 是"请求级"的临时存储:同一个请求内共享,请求结束自动销毁
    g.request_id = request.headers.get("x-request-id", "anonymous")
    g.current_user = None

    token = request.headers.get("authorization", "").removeprefix("Bearer ").strip()
    if token:
        g.current_user = lookup_user_by_token(token)     # 避免在多个视图里重复查询


@app.get("/me")
def me():
    if g.current_user is None:
        return {"error": "未登录"}, 401
    return {"id": g.current_user["id"], "name": g.current_user["name"], "requestId": g.request_id}


@app.teardown_request
def release_resources(exc):
    """请求结束(含异常)时必然执行——用来释放资源。"""
    db = g.pop("db_session", None)
    if db is not None:
        db.close()

request / g / session 三者的适用场景

| 对象 | 生命周期 | 用途 | 注意 |

|---|---|---|---|

| request | 当前请求 | 只读地读取入参:args、json、headers、files | 不要往里塞自定义数据(虽然能塞) |

| g | 当前请求 | 存放本次请求的派生数据:当前用户、DB 会话、request id | 只在请求内有效;后台线程里访问会报 RuntimeError: Working outside of application context |

| session | 跨请求(Cookie 签名) | 登录状态等少量数据 | 数据存在客户端 Cookie 里,用户可读;不能存敏感信息,且总量 < 4KB |

常见错误:把 g 当缓存用(g.cache = {})以为能跨请求复用。它每次请求都是全新的。跨请求缓存应该用 Flask-Caching + Redis。


六、模板渲染(Jinja2)

6.1 语法要点

Jinja2 是 Flask 的默认模板引擎,也被 FastAPI、Ansible 等广泛使用。三种定界符:

语法用途
{{ ... }}表达式:输出变量的值
{% ... %}语句:if / for / block / macro / set
{# ... #}注释:不输出到结果中
{# templates/tasks/list.html #}
{% extends "base.html" %}

{% block title %}任务列表{% endblock %}

{% block content %}
  <h1>任务列表({{ tasks | length }} 条)</h1>

  {% if tasks %}
    <table>
      <thead>
        <tr><th>#</th><th>标题</th><th>状态</th><th>操作</th></tr>
      </thead>
      <tbody>
        {% for task in tasks %}
          {# loop 是循环内置变量:index(从1)、index0、first、last、length #}
          <tr class="{{ loop.cycle('odd', 'even') }}">
            <td>{{ loop.index }}</td>
            {# 自动转义开启时,这里的内容会被 HTML 转义 #}
            <td>{{ task.title }}</td>
            <td>{{ task.status }}</td>
            <td><a href="{{ url_for('tasks.get_task', task_id=task.id) }}">详情</a></td>
          </tr>
        {% else %}
          {# 注意:Jinja 的 for-else 语义是"序列为空时执行",#}
          {# 与 Python 的"循环未 break 时执行"不同 #}
          <tr><td colspan="4">还没有任务</td></tr>
        {% endfor %}
      </tbody>
    </table>
  {% else %}
    <p>暂无数据</p>
  {% endif %}
{% endblock %}

过滤器:用 | 管道串联,前一个的输出作为后一个的输入。

{{ name | striptags | title }}          {# 先去除 HTML 标签,再转标题大小写 #}
{{ price | round(2) }}                   {# 保留 2 位小数 #}
{{ items | join('、') }}                 {# 用顿号连接 #}
{{ created_at | datetimeformat }}        {# 自定义过滤器 #}
{{ user_input | e }}                     {# 显式 HTML 转义 #}
{{ html_snippet | safe }}                {# ⚠️ 危险:标记为"安全",不做转义 #}
{{ content | default('无内容', true) }}  {# 值为假时也使用默认值 #}

模板继承:定义骨架 + 填充块。

{# templates/base.html #}
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>{% block title %}我的站点{% endblock %}</title>
  <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
  {% block head %}{% endblock %}
</head>
<body>
  <nav>{% block nav %}<a href="/">首页</a>{% endblock %}</nav>

  {# 用 with 把 flash 消息缓存到变量,避免多次求值 #}
  {% with messages = get_flashed_messages(with_categories=true) %}
    {% if messages %}
      <ul class="flashes">
        {% for category, message in messages %}
          <li class="{{ category }}">{{ message }}</li>
        {% endfor %}
      </ul>
    {% endif %}
  {% endwith %}

  <main>{% block content %}{% endblock %}</main>
</body>
</html>
{# 子模板用 extends 继承,用 super() 调用父块的原始内容 #}
{% extends "base.html" %}
{% block title %}任务详情 - {{ super() }}{% endblock %}
{% block head %}
  {{ super() }}
  <style>.detail { color: #336699; }</style>
{% endblock %}

6.2 自动转义防 XSS

自动转义是防 XSS 的第一道防线

Jinja 的自动转义默认关闭,但 Flask 会自动为 .html / .htm / .xml / .xhtml 后缀的模板开启它。所以用 Flask 渲染 HTML 时,{{ user_input }} 是安全的。

转义会把 < > & " ' 变成 HTML 实体,因此 <script>alert(1)</script> 会作为文本显示而不是执行。

# 陷阱 1:手动拼接 HTML —— 转义完全失效
# ❌ 只要 name 是 <script>...</script>,这段就是 XSS 漏洞
return f"<h1>你好,{name}!</h1>"

# ✅ 要么用模板,要么显式转义
from markupsafe import escape
return f"<h1>你好,{escape(name)}!</h1>"
# 陷阱 2:关闭了自动转义
app = Flask(__name__)
app.jinja_env.autoescape = False      # ❌ 绝对不要

# 陷阱 3:对不可信数据用了 |safe
# ❌ 用户提交的内容绝不能标记为 safe
{{ user_comment | safe }}

# ✅ 只有你自己生成的、已确认安全的 HTML 才可以用 safe
{{ rendered_markdown_from_trusted_cms | safe }}

三个非模板的 XSS 入口

1. return f"<p>{x}</p>":手拼 HTML 字符串。Flask 只对模板自动转义,对字符串返回值不会。

2. jsonify 到前端后用 innerHTML 渲染:XSS 从模板层转移到了前端,前端必须用 textContent 或框架的转义机制。

3. Content-Type 不对:如果把用户输入当 text/html 返回(而不是 application/json),浏览器会执行其中的脚本。这就是 Helmet/X-Content-Type-Options: nosniff 要防的场景。

交叉引用:后端-09-后端安全与性能。

6.3 何时该用服务端渲染而非前后端分离

维度服务端渲染(SSR / 模板)前后端分离(SPA + JSON API)
首屏速度✅ 快(HTML 直达,无 JS 阻塞)❌ 需下载 JS → 请求 API → 渲染
SEO✅ 搜索引擎直接读到内容⚠️ 需要额外做 SSR/预渲染
交互复杂度❌ 复杂交互需手写 JS✅ 框架天然擅长
前后端协作一个仓库、一个人可全包需定义 API 契约,两个角色
移动端复用❌ 逻辑在 HTML 里,无法复用✅ 同一套 API 给 App 用
状态管理简单(就是页面状态)复杂(需要专门的状态库)
适合的团队1~5 人,内容型站点5 人以上,多端产品

决策建议:

对外是否需要被搜索引擎索引大量页面?(官网、博客、电商列表、文档站)
├── 是 → 服务端渲染(Django 模板 / Jinja2)
└── 否
    ├── 是否为管理后台 / 内部工具?(登录后使用、交互密集、不需要 SEO)
    │   ├── 是 → SPA + JSON API(FastAPI/DRF + Vue/React)
    │   └── 否
    │       └── 移动 App 是主要入口?
    │           ├── 是 → JSON API 优先(一套 API 给 App 与 Web)
    │           └── 否 → 按团队熟悉度选

混合策略往往是正确答案

很多成功产品的做法是:面向公众的内容页用 SSR(保证 SEO 与首屏),登录后的交互密集页用 SPA。Django 的 Admin 就是自带的 SSR 管理界面,不需要你再写一套。

交叉引用:前端-06-Vue 与 前端-07-React 讲 SPA 侧的实现。


七、ASGI 部署

7.1 uvicorn/gunicorn 的关系

这是最容易混淆的一点。它们不是竞品,而是可以组合的两层。

工具角色协议特点
UvicornASGI 服务器ASGI单进程事件循环;--workers 可多进程(内部用 multiprocessing)
Gunicorn进程管理器WSGI 原生 + 可挂 ASGI worker成熟的 master/worker 模型、优雅重启、信号处理完善
HypercornASGI 服务器ASGI支持 HTTP/2、HTTP/3、QUIC

三种部署形态:

# 形态 1:只用 Uvicorn(最简单,适合容器 + 编排器扩容)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
# 容器里更推荐不加 --workers,由 K8s 副本数控制(见下)

# 形态 2:Gunicorn + UvicornWorker(传统单机部署的主流选择)
gunicorn app.main:app \
  --worker-class uvicorn.workers.UvicornWorker \
  --workers 4 \
  --bind 0.0.0.0:8000 \
  --timeout 60 \
  --graceful-timeout 30 \
  --access-logfile - \
  --error-logfile -

# 形态 3:Gunicorn + 同步 worker(仅当你的应用是纯同步 WSGI 时)
gunicorn app.main:app --workers 4 --bind 0.0.0.0:8000

--worker-class uvicorn.workers.UvicornWorker 在新版本中已迁移

这个类的导入路径随 Uvicorn 版本变化过(曾迁移到 uvicorn_worker.UvicornWorker,后整合进 uvicorn-worker 包)。具体路径请以 Uvicorn 与 Gunicorn 的最新官方文档为准,部署前先在本机验证一次启动命令。

更现代的做法是直接使用 uvicorn --workers N,省掉 Gunicorn 这一层。

7.2 worker 数量怎么定

经验公式(来自 FastAPI 官方部署文档的思路):

负载类型建议 worker 数理由
I/O 密集(大量 await 数据库/API)CPU 核数 或更少单 worker 已能扛大量并发,多了反而增加内存与切换开销
CPU 密集(同步计算、图像、加密)CPU 核数 × 2 + 1计算期间需要其他 worker 接手
内存受限减少 worker,增加副本每个 worker 是独立进程,内存不共享
容器(K8s)1 个 worker,靠副本数扩展见下

容器里优先用"1 进程 / 多副本"

原因与 后端-02-Nodejs与Express 里讲的完全一致:

- K8s 的 resources.limits.cpu 是整个容器的限额。容器里跑 4 个 worker 时,CPU 被限流会让 4 个进程互相拖累,延迟毛刺比单进程多副本更严重。

- 日志混在一起,无法按进程归因。

- 扩缩容粒度变成 4 倍,且 terminationGracePeriodSeconds 需要等 4 个进程都优雅退出。

- 内存 limits 需要乘以 worker 数,OOM 排查困难。

正确做法:CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"],用 replicas: N 控制并发度。

7.3 为什么不能用开发服务器跑生产

开发服务器问题
flask run / flask run --debug单进程单线程、有交互式调试器(可在浏览器执行任意代码)、不处理并发、无优雅关闭
uvicorn app:app --reload单进程、文件监听开销大、重启会丢在途请求、--reload 只应在开发用
python manage.py runserverDjango 官方明确说明"不适用于生产"、无静态文件优化、无并发能力
# ❌ 生产环境的错误命令
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
flask run --debug --host 0.0.0.0

# ✅ 生产环境的正确命令
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 1 --no-access-log
gunicorn app.main:app --worker-class uvicorn.workers.UvicornWorker --workers 4

--reload 在生产环境的四个具体危害

1. 请求丢失:文件一变动就重启进程,在途请求被硬切断(客户端看到 502 或连接重置)。

2. 内存翻倍:--reload 会额外跑一个监听文件的父进程,且反复重启可能因句柄未释放而累积内存。

3. inotify 句柄耗尽:容器里 fs.inotify.max_user_watches 有限,监听大量文件(含 node_modules 式的大目录)会触发 OSError: inotify watch limit reached。

4. 掩盖信号处理问题:--reload 自己接管了 SIGTERM,你的优雅关闭逻辑可能根本不被触发,导致生产环境的关闭行为与开发测试时完全不同。

7.4 优雅关闭

# app/main.py —— 用 lifespan 管理启动与关闭
from contextlib import asynccontextmanager
from collections.abc import AsyncIterator
from fastapi import FastAPI

from app.core.logging import logger
from app.db.base import engine
from app.core.redis import redis_client


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    # —— 启动阶段 ——
    logger.info("应用启动中……")
    # 建表(生产环境应该用 Alembic 迁移,这里仅演示)
    # Base.metadata.create_all(bind=engine)
    await redis_client.ping()
    logger.info("依赖就绪,开始接受请求")

    yield                     # ← 应用运行期间

    # —— 关闭阶段 ——
    # Uvicorn 收到 SIGTERM 后:停止接受新连接 → 等待在途请求 → 触发这里
    logger.info("应用关闭中,释放资源……")
    await redis_client.aclose()
    await engine.dispose()    # 关闭数据库连接池
    logger.info("资源已释放")

on_event("shutdown") 已被弃用

旧的 @app.on_event("startup") / @app.on_event("shutdown") 装饰器已被 lifespan 取代。新项目一律用 lifespan;两者的迁移细节以官方最新文档为准。

关键点:lifespan 里 yield 之后的代码才是关闭逻辑,yield 之前是启动逻辑。用 try/finally 包裹 yield 能保证异常路径也会清理。


八、配置与密钥管理

8.1 用 pydantic-settings 做类型安全的配置

环境变量都是字符串,手工 int(os.environ["PORT"]) 既不安全也不优雅。pydantic-settings 把配置也纳入 Pydantic 的校验体系。

# app/core/config.py
from functools import lru_cache
from typing import Annotated, Literal
from pydantic import Field, PostgresDsn, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    # 从 .env 读取(优先级:环境变量 > .env > 默认值)
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=True,
        extra="ignore",              # .env 里有未声明的键时不报错
    )

    # —— 应用 ——
    PROJECT_NAME: str = "Task API"
    API_V1_PREFIX: str = "/api/v1"
    ENVIRONMENT: Literal["development", "test", "production"] = "development"
    DEBUG: bool = False

    # —— 安全 ——
    # 没有默认值 = 必填。缺失时启动直接失败,而不是运行时才 500
    SECRET_KEY: Annotated[str, Field(min_length=32, description="JWT 签名密钥,至少 32 字符")]
    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
    ALGORITHM: str = "HS256"

    # —— 数据库 ——
    # PostgresDsn 会校验 URL 格式,写错立即报错
    DATABASE_URL: PostgresDsn | str = "sqlite:///./app.db"

    # —— CORS ——
    BACKEND_CORS_ORIGINS: list[str] = []

    @field_validator("BACKEND_CORS_ORIGINS", mode="before")
    @classmethod
    def parse_cors(cls, v):
        """支持两种写法:JSON 数组 ["a","b"] 或逗号分隔 "a,b"。"""
        if isinstance(v, str) and not v.startswith("["):
            return [item.strip() for item in v.split(",") if item.strip()]
        return v

    @field_validator("SECRET_KEY")
    @classmethod
    def reject_default_secret(cls, v: str) -> str:
        # 防止有人把示例值直接带到生产
        if v in {"changeme", "secret", "your-secret-key-here"}:
            raise ValueError("SECRET_KEY 不能使用示例默认值,请重新生成")
        return v


@lru_cache
def get_settings() -> Settings:
    """缓存实例:配置只解析一次,避免每次请求都读环境变量。"""
    return Settings()


settings = get_settings()
# .env.example —— 提交到仓库
ENVIRONMENT=development
DEBUG=true
# 生成方法:python -c "import secrets; print(secrets.token_urlsafe(48))"
SECRET_KEY=请替换为随机生成的至少32位字符串
ACCESS_TOKEN_EXPIRE_MINUTES=30
DATABASE_URL=sqlite:///./app.db
BACKEND_CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
# .gitignore
.env
.env.local
.env.*.local
*.db
__pycache__/
.venv/

密钥管理铁律

1. 绝不把密钥提交进仓库。.env 必须在 .gitignore 里。只提交 .env.example(占位值)。

2. 一旦密钥进过 Git 历史,就必须立刻轮换。git rm 不会从历史里删除它——攻击者可以 git log -p 找到。要清理历史得用 git filter-repo,但轮换比清理更省事也更可靠。

3. 生产环境的密钥从密钥管理服务注入,不落盘:K8s Secret / AWS Secrets Manager / Vault / 阿里云 KMS。K8s Secret 默认是 base64 编码(不是加密),要开启 etcd 加密或使用外部 Secret 驱动。

4. 不要在日志里打印配置对象。print(settings) 会把 SECRET_KEY 和数据库密码写进日志。用 SecretStr 类型包裹敏感字段,Pydantic 会在打印时自动脱敏:

```python

from pydantic import SecretStr

class Settings(BaseSettings):

SECRET_KEY: SecretStr

DATABASE_PASSWORD: SecretStr

# 使用时显式取值

settings.SECRET_KEY.get_secret_value()

# repr 输出是 SECRET_KEY=SecretStr('**********')

```

5. 不同的环境用不同的密钥。开发密钥泄露不应该影响生产。


九、完整示例:FastAPI CRUD + 依赖注入鉴权

一个可以直接跑起来的完整项目。用 SQLite(零依赖启动),生产可无痛换成 PostgreSQL。

9.1 目录结构

fastapi-task-api/
├── requirements.txt
├── .env.example
├── .gitignore
├── Makefile                    # 可选,方便记命令
├── tests/
│   └── test_tasks.py
└── app/
    ├── __init__.py
    ├── main.py                 # FastAPI 实例、中间件、异常处理器、lifespan
    ├── api/
    │   ├── __init__.py
    │   ├── deps.py             # 共享依赖
    │   └── v1/
    │       ├── __init__.py
    │       ├── router.py       # 汇总路由
    │       ├── auth.py
    │       └── tasks.py
    ├── core/
    │   ├── __init__.py
    │   ├── config.py
    │   ├── security.py
    │   ├── logging.py
    │   └── exceptions.py
    ├── db/
    │   ├── __init__.py
    │   ├── base.py             # ORM Base
    │   └── session.py          # engine + get_db 依赖
    ├── models/
    │   ├── __init__.py         # ⚠️ 导入所有模型
    │   ├── user.py
    │   └── task.py
    ├── schemas/
    │   ├── __init__.py
    │   ├── common.py
    │   ├── token.py
    │   ├── user.py
    │   └── task.py
    └── services/
        ├── __init__.py
        ├── user_service.py
        └── task_service.py

9.2 requirements.txt

# —— Web 框架与服务器 ——
fastapi==0.143.0
uvicorn[standard]==0.54.0
python-multipart==0.0.32          # 表单/文件上传与 OAuth2 密码表单需要

# —— 数据校验与配置 ——
pydantic==2.14.0
pydantic-settings==2.15.0
email-validator==2.4.0            # EmailStr 需要

# —— 数据库 ——
SQLAlchemy==2.1.4

# —— 安全 ——
PyJWT==2.15.1
bcrypt==5.0.0

# —— 测试 ——
pytest==8.4.2
httpx==0.28.1                     # FastAPI TestClient 依赖(也可直接做异步测试)

版本说明

以上为写作时(2026-10-11)PyPI 上的最新版本,通过 pip index versions <包名> 可核实当前值。

- passlib 未列入:passlib 已多年未更新(1.7.4,2020 年),与新版 bcrypt 存在兼容告警。现代做法是直接用 bcrypt(见 9.4 的 security.py)。

- 生产环境建议改用 Argon2(argon2-cffi),它是密码哈希竞赛的获胜者,抗 GPU 破解能力更强。

- Python 3.15 是当前稳定版;bcrypt 与 SQLAlchemy 等含 C 扩展的包需要已发布对应 wheel 的版本,以官方最新文档与 PyPI 页面为准。

9.3 配置与日志

# app/core/config.py
from functools import lru_cache
from typing import Annotated, Literal
from pydantic import Field, SecretStr, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env", env_file_encoding="utf-8", case_sensitive=True, extra="ignore"
    )

    PROJECT_NAME: str = "Task API"
    API_V1_PREFIX: str = "/api/v1"
    ENVIRONMENT: Literal["development", "test", "production"] = "development"

    SECRET_KEY: Annotated[SecretStr, Field(min_length=32)]
    ALGORITHM: str = "HS256"
    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30

    DATABASE_URL: str = "sqlite:///./app.db"

    BACKEND_CORS_ORIGINS: list[str] = []

    @field_validator("BACKEND_CORS_ORIGINS", mode="before")
    @classmethod
    def parse_cors(cls, v):
        if isinstance(v, str) and not v.startswith("["):
            return [i.strip() for i in v.split(",") if i.strip()]
        return v

    @property
    def is_production(self) -> bool:
        return self.ENVIRONMENT == "production"


@lru_cache
def get_settings() -> Settings:
    return Settings()


settings = get_settings()
# app/core/logging.py
import logging
import sys

from app.core.config import settings


def setup_logging() -> None:
    """统一的日志配置:生产输出 JSON 风格,开发输出可读文本。"""
    level = logging.DEBUG if not settings.is_production else logging.INFO

    handler = logging.StreamHandler(sys.stdout)
    if settings.is_production:
        # 生产:结构化单行格式,便于采集器(Loki/ELK)解析
        handler.setFormatter(
            logging.Formatter(
                '{"ts":"%(asctime)s","level":"%(levelname)s","logger":"%(name)s",'
                '"msg":"%(message)s"}'
            )
        )
    else:
        handler.setFormatter(
            logging.Formatter("%(asctime)s | %(levelname)-8s | %(name)s | %(message)s", "%H:%M:%S")
        )

    root = logging.getLogger()
    root.handlers.clear()
    root.addHandler(handler)
    root.setLevel(level)

    # 降低访问日志噪音;uvicorn 的访问日志由 --no-access-log 或这里控制
    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)


logger = logging.getLogger("app")

9.4 安全模块

# app/core/exceptions.py
class AppError(Exception):
    """业务异常基类:service 层只管 raise,翻译成 HTTP 由处理器负责。"""
    code = "APP_ERROR"
    status_code = 400

    def __init__(self, message: str, details=None):
        self.message = message
        self.details = details
        super().__init__(message)


class NotFoundError(AppError):
    code = "NOT_FOUND"
    status_code = 404


class ConflictError(AppError):
    code = "CONFLICT"
    status_code = 409


class AuthError(AppError):
    code = "UNAUTHORIZED"
    status_code = 401


class PermissionDeniedError(AppError):
    code = "FORBIDDEN"
    status_code = 403
# app/core/security.py
from datetime import UTC, datetime, timedelta

import bcrypt
import jwt

from app.core.config import settings
from app.schemas.token import TokenPayload


def hash_password(password: str) -> str:
    """用 bcrypt 生成密码哈希。

    bcrypt 会自动生成并内嵌 salt,所以不需要单独存 salt 字段。
    """
    # bcrypt 只处理前 72 字节,超长密码必须考虑这一点
    pw = password.encode("utf-8")[:72]
    return bcrypt.hashpw(pw, bcrypt.gensalt()).decode("utf-8")


def verify_password(plain: str, hashed: str) -> bool:
    """校验密码。使用 bcrypt 内置的恒定时间比较,防时序攻击。"""
    try:
        return bcrypt.checkpw(plain.encode("utf-8")[:72], hashed.encode("utf-8"))
    except (ValueError, TypeError):
        # 哈希格式非法(比如历史数据)时返回 False,不要把异常抛给调用方
        return False


def create_access_token(subject: str, expires_minutes: int | None = None) -> str:
    """签发 JWT。

    subject 放用户 ID(字符串),不要放密码或其他敏感信息——
    JWT 的 payload 只是 base64 编码,任何人都能读。
    """
    expire = datetime.now(UTC) + timedelta(
        minutes=expires_minutes or settings.ACCESS_TOKEN_EXPIRE_MINUTES
    )
    payload = {
        "sub": subject,          # subject:JWT 规范里的"主体"
        "exp": expire,           # expiration:过期时间,PyJWT 会自动校验
        "iat": datetime.now(UTC),# issued at
        "type": "access",
    }
    return jwt.encode(payload, settings.SECRET_KEY.get_secret_value(), algorithm=settings.ALGORITHM)


def decode_access_token(token: str) -> TokenPayload | None:
    """解出 payload;任何异常都返回 None,由调用方决定怎么响应。"""
    try:
        raw = jwt.decode(
            token,
            settings.SECRET_KEY.get_secret_value(),
            algorithms=[settings.ALGORITHM],   # 必须显式指定,防算法混淆攻击
        )
        return TokenPayload.model_validate(raw)
    except jwt.PyJWTError:
        # 涵盖过期、签名错误、格式错误等所有情况
        return None

9.5 数据库与模型

# app/db/base.py
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    """所有 ORM 模型的基类。SQLAlchemy 2.0 风格的声明式基类。"""
# app/db/session.py
from collections.abc import Generator
from typing import Annotated

from fastapi import Depends
from sqlalchemy import create_engine
from sqlalchemy.orm import Session, sessionmaker

from app.core.config import settings

# SQLite 需要 check_same_thread=False 才能被多线程使用(FastAPI 的线程池)
connect_args = {"check_same_thread": False} if settings.DATABASE_URL.startswith("sqlite") else {}

engine = create_engine(
    settings.DATABASE_URL,
    connect_args=connect_args,
    pool_pre_ping=True,   # 取连接前先 ping,自动丢弃被数据库断开的死连接
    echo=False,           # 想看 SQL 时改成 True(仅开发)
)

SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False, expire_on_commit=False)


def get_db() -> Generator[Session, None, None]:
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()


SessionDep = Annotated[Session, Depends(get_db)]
# app/models/user.py
from datetime import datetime

from sqlalchemy import Boolean, DateTime, String, func
from sqlalchemy.orm import Mapped, mapped_column, relationship

from app.db.base import Base


class User(Base):
    __tablename__ = "users"

    # Mapped[...] + mapped_column() 是 SQLAlchemy 2.0 的类型化写法,
    # 编辑器能推断出 user.email 是 str 而不是 Any
    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(String(255), unique=True, index=True, nullable=False)
    nickname: Mapped[str] = mapped_column(String(100), nullable=False)
    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), nullable=False
    )

    # 一对多:删除用户时级联删除其任务
    tasks: Mapped[list["Task"]] = relationship(
        back_populates="owner", cascade="all, delete-orphan", lazy="selectin"
    )

    def __repr__(self) -> str:
        # 注意:绝不要把 hashed_password 放进 repr,否则会进日志
        return f"<User id={self.id} email={self.email!r}>"
# app/models/task.py
from datetime import datetime

from sqlalchemy import DateTime, ForeignKey, Index, String, Text, func
from sqlalchemy.orm import Mapped, mapped_column, relationship

from app.db.base import Base


class Task(Base):
    __tablename__ = "tasks"
    # 复合索引覆盖"我的任务 + 按状态过滤 + 按时间排序"这个主要查询
    __table_args__ = (Index("ix_tasks_owner_status", "owner_id", "status"),)

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(200), nullable=False)
    description: Mapped[str | None] = mapped_column(Text, nullable=True)
    status: Mapped[str] = mapped_column(String(20), default="todo", nullable=False)
    due_date: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    owner_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), nullable=False
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
    )

    # lazy="joined":查询任务时自动 JOIN 出 owner,避免访问 task.owner 时触发 N+1
    owner: Mapped["User"] = relationship(back_populates="tasks", lazy="joined")
# app/models/__init__.py
# ⚠️ 这一行至关重要:Base.metadata.create_all() 只认识"已被导入过"的模型类。
# 漏掉导入会导致表建不出来,且报错信息很不直观。
from app.models.task import Task
from app.models.user import User

__all__ = ["Task", "User"]

9.6 Pydantic Schemas

# app/schemas/common.py
from typing import Generic, TypeVar
from pydantic import BaseModel

T = TypeVar("T")


class ApiResponse(BaseModel, Generic[T]):
    """统一成功响应包装。"""
    success: bool = True
    data: T


class PageMeta(BaseModel):
    page: int
    page_size: int
    total: int
    total_pages: int


class PageResponse(BaseModel, Generic[T]):
    success: bool = True
    data: list[T]
    meta: PageMeta


class ErrorDetail(BaseModel):
    code: str
    message: str
    details: list | dict | None = None
    request_id: str | None = None


class ErrorResponse(BaseModel):
    success: bool = False
    error: ErrorDetail
# app/schemas/token.py
from pydantic import BaseModel


class TokenPayload(BaseModel):
    """JWT 的载荷结构。"""
    sub: str            # 用户 ID(字符串形式)
    exp: int
    iat: int
    type: str = "access"


class Token(BaseModel):
    access_token: str
    token_type: str = "bearer"


class LoginRequest(BaseModel):
    email: str
    password: str
# app/schemas/user.py
from datetime import datetime
from typing import Annotated

from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator


class UserBase(BaseModel):
    email: EmailStr
    nickname: Annotated[str, Field(min_length=1, max_length=100)]


class UserCreate(UserBase):
    password: Annotated[str, Field(min_length=12, max_length=128)]

    @field_validator("password")
    @classmethod
    def password_strength(cls, v: str) -> str:
        if not any(c.isdigit() for c in v):
            raise ValueError("密码必须包含至少一个数字")
        if not any(c.isalpha() for c in v):
            raise ValueError("密码必须包含至少一个字母")
        return v


class UserPublic(UserBase):
    """对外暴露的用户信息——刻意不含 password / hashed_password。"""
    id: int
    is_active: bool
    created_at: datetime

    # 允许从 SQLAlchemy 对象构造(读属性而不是读字典键)
    model_config = ConfigDict(from_attributes=True)
# app/schemas/task.py
from datetime import datetime
from typing import Annotated, Literal, Self

from pydantic import BaseModel, ConfigDict, Field, model_validator

TaskStatus = Literal["todo", "doing", "done"]


class TaskBase(BaseModel):
    title: Annotated[str, Field(min_length=1, max_length=200, description="任务标题")]
    description: Annotated[str | None, Field(max_length=2000)] = None
    status: TaskStatus = "todo"
    due_date: datetime | None = None

    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")


class TaskCreate(TaskBase):
    pass


class TaskUpdate(BaseModel):
    """局部更新:所有字段可选,但至少要提供一个。"""
    title: Annotated[str | None, Field(min_length=1, max_length=200)] = None
    description: Annotated[str | None, Field(max_length=2000)] = None
    status: TaskStatus | None = None
    due_date: datetime | None = None

    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")

    @model_validator(mode="after")
    def at_least_one_field(self) -> Self:
        # exclude_unset=True:只统计调用方显式传了的字段,
        # 这样 PATCH {"description": null} 会被正确识别为"有内容"
        if not self.model_dump(exclude_unset=True):
            raise ValueError("至少要提供一个待更新字段")
        return self


class TaskPublic(TaskBase):
    id: int
    owner_id: int
    created_at: datetime
    updated_at: datetime

    model_config = ConfigDict(from_attributes=True)

9.7 服务层(业务逻辑)

# app/services/user_service.py
from sqlalchemy import select
from sqlalchemy.orm import Session

from app.core.exceptions import ConflictError
from app.core.security import hash_password, verify_password
from app.models.user import User
from app.schemas.user import UserCreate


def get_by_id(db: Session, user_id: int) -> User | None:
    # SQLAlchemy 2.0 风格:用 select() + db.scalars(),不用已过时的 Query
    return db.get(User, user_id)


def get_by_email(db: Session, email: str) -> User | None:
    stmt = select(User).where(User.email == email)
    return db.scalars(stmt).first()


def create_user(db: Session, payload: UserCreate) -> User:
    if get_by_email(db, payload.email) is not None:
        # 在 service 层做业务判断并抛业务异常,路由层不用关心细节
        raise ConflictError("该邮箱已被注册")

    user = User(
        email=payload.email,
        nickname=payload.nickname,
        hashed_password=hash_password(payload.password),
    )
    db.add(user)
    db.commit()
    db.refresh(user)     # 取回数据库生成的 id / created_at
    return user


def authenticate(db: Session, email: str, password: str) -> User | None:
    user = get_by_email(db, email)
    if user is None:
        # 即使用户不存在也要走一次哈希校验,避免用响应时间探测账号是否存在
        verify_password(password, "$2b$12$" + "x" * 53)
        return None
    if not verify_password(password, user.hashed_password):
        return None
    return user
# app/services/task_service.py
import math

from sqlalchemy import func, select
from sqlalchemy.orm import Session

from app.core.exceptions import NotFoundError
from app.models.task import Task
from app.schemas.task import TaskCreate, TaskUpdate


def _get_owned_task(db: Session, task_id: int, owner_id: int) -> Task:
    """按 ID + owner 查询。刻意带上 owner_id,防止越权访问别人的数据。"""
    stmt = select(Task).where(Task.id == task_id, Task.owner_id == owner_id)
    task = db.scalars(stmt).first()
    if task is None:
        # 返回 404 而不是 403:不泄露"这个 ID 存在但不属于你"
        raise NotFoundError("任务不存在")
    return task


def list_tasks(
    db: Session,
    *,
    owner_id: int,
    page: int,
    page_size: int,
    status: str | None = None,
    keyword: str | None = None,
) -> tuple[list[Task], int]:
    conditions = [Task.owner_id == owner_id]
    if status:
        conditions.append(Task.status == status)
    if keyword:
        # ilike 是不区分大小写的 LIKE;SQLite 上大小写行为有限制
        conditions.append(Task.title.ilike(f"%{keyword}%"))

    total = db.scalar(select(func.count()).select_from(Task).where(*conditions)) or 0

    stmt = (
        select(Task)
        .where(*conditions)
        # 加一个稳定的次级排序键,避免分页时同一行重复/漏出
        .order_by(Task.created_at.desc(), Task.id.desc())
        .offset((page - 1) * page_size)
        .limit(page_size)
    )
    return list(db.scalars(stmt).all()), total


def total_pages(total: int, page_size: int) -> int:
    return max(1, math.ceil(total / page_size)) if total else 0


def create_task(db: Session, payload: TaskCreate, owner_id: int) -> Task:
    task = Task(**payload.model_dump(), owner_id=owner_id)
    db.add(task)
    db.commit()
    db.refresh(task)
    return task


def get_task(db: Session, task_id: int, owner_id: int) -> Task:
    return _get_owned_task(db, task_id, owner_id)


def update_task(db: Session, task_id: int, payload: TaskUpdate, owner_id: int) -> Task:
    task = _get_owned_task(db, task_id, owner_id)
    # exclude_unset=True:只应用调用方真正传了的字段,
    # 这样 PATCH 不会把没传的字段覆盖成 None
    for field, value in payload.model_dump(exclude_unset=True).items():
        setattr(task, field, value)
    db.commit()
    db.refresh(task)
    return task


def delete_task(db: Session, task_id: int, owner_id: int) -> None:
    task = _get_owned_task(db, task_id, owner_id)
    db.delete(task)
    db.commit()

9.8 依赖项

# app/api/deps.py
from dataclasses import dataclass
from typing import Annotated

from fastapi import Depends, Query
from fastapi.security import OAuth2PasswordBearer

from app.core.exceptions import AuthError, PermissionDeniedError
from app.core.security import decode_access_token
from app.db.session import SessionDep
from app.models.user import User
from app.services import user_service

# tokenUrl 指向登录接口;实际只是给 Swagger UI 的"Authorize"按钮用
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login", auto_error=False)
TokenDep = Annotated[str | None, Depends(oauth2_scheme)]


def get_current_user(db: SessionDep, token: TokenDep) -> User:
    """从 Bearer Token 解出当前用户。所有需要登录的接口都依赖它。"""
    if not token:
        raise AuthError("缺少 Bearer Token")

    payload = decode_access_token(token)
    if payload is None:
        raise AuthError("Token 无效或已过期")

    user = user_service.get_by_id(db, int(payload.sub))
    if user is None:
        raise AuthError("用户不存在")
    if not user.is_active:
        raise PermissionDeniedError("账号已被停用")
    return user


CurrentUser = Annotated[User, Depends(get_current_user)]


def get_current_superuser(user: CurrentUser) -> User:
    """子依赖项:在 get_current_user 之上再加一层权限校验。"""
    if not user.is_superuser:
        raise PermissionDeniedError("需要超级管理员权限")
    return user


CurrentSuperuser = Annotated[User, Depends(get_current_superuser)]


@dataclass(frozen=True, slots=True)
class Pagination:
    page: int
    page_size: int

    @property
    def offset(self) -> int:
        return (self.page - 1) * self.page_size


def get_pagination(
    page: Annotated[int, Query(ge=1, description="页码,从 1 开始")] = 1,
    page_size: Annotated[int, Query(ge=1, le=100, description="每页条数,最大 100")] = 20,
) -> Pagination:
    return Pagination(page=page, page_size=page_size)


PaginationDep = Annotated[Pagination, Depends(get_pagination)]

9.9 路由

# app/api/v1/auth.py
from fastapi import APIRouter, status
from fastapi.security import OAuth2PasswordRequestForm
from typing import Annotated
from fastapi import Depends

from app.api.deps import CurrentUser
from app.core.exceptions import AuthError
from app.core.security import create_access_token
from app.db.session import SessionDep
from app.schemas.common import ApiResponse
from app.schemas.token import Token
from app.schemas.user import UserCreate, UserPublic
from app.services import user_service

router = APIRouter(prefix="/auth", tags=["auth"])


@router.post("/register", response_model=ApiResponse[UserPublic], status_code=status.HTTP_201_CREATED)
def register(payload: UserCreate, db: SessionDep):
    """注册。返回 UserPublic —— 响应模型保证 hashed_password 不会外泄。"""
    user = user_service.create_user(db, payload)
    return ApiResponse(data=UserPublic.model_validate(user))


@router.post("/login", response_model=Token)
def login(
    db: SessionDep,
    form: Annotated[OAuth2PasswordRequestForm, Depends()],
):
    """标准 OAuth2 密码模式登录。

    用 OAuth2PasswordRequestForm 而不是自定义模型,好处是 Swagger UI 的
    Authorize 按钮可以直接工作。它以表单(不是 JSON)接收 username/password。
    """
    user = user_service.authenticate(db, email=form.username, password=form.password)
    if user is None:
        # 不区分"用户不存在"和"密码错误",避免账号枚举
        raise AuthError("邮箱或密码不正确")

    token = create_access_token(subject=str(user.id))
    return Token(access_token=token)


@router.get("/me", response_model=ApiResponse[UserPublic])
def read_me(current_user: CurrentUser):
    """获取当前登录用户。注意这个路由必须放在 /{user_id} 之前,
    否则 "me" 会被当成路径参数去匹配。"""
    return ApiResponse(data=UserPublic.model_validate(current_user))
# app/api/v1/tasks.py
from fastapi import APIRouter, Query, Response, status

from app.api.deps import CurrentUser, PaginationDep
from app.db.session import SessionDep
from app.schemas.common import ApiResponse, PageMeta, PageResponse
from app.schemas.task import TaskCreate, TaskPublic, TaskStatus, TaskUpdate
from app.services import task_service

router = APIRouter(prefix="/tasks", tags=["tasks"])


@router.get("", response_model=PageResponse[TaskPublic], summary="分页列出我的任务")
def list_tasks(
    db: SessionDep,
    current_user: CurrentUser,
    pagination: PaginationDep,
    task_status: TaskStatus | None = Query(default=None, alias="status", description="按状态过滤"),
    q: str | None = Query(default=None, max_length=100, description="按标题模糊搜索"),
):
    items, total = task_service.list_tasks(
        db,
        owner_id=current_user.id,
        page=pagination.page,
        page_size=pagination.page_size,
        status=task_status,
        keyword=q,
    )
    return PageResponse[TaskPublic](
        data=[TaskPublic.model_validate(t) for t in items],
        meta=PageMeta(
            page=pagination.page,
            page_size=pagination.page_size,
            total=total,
            total_pages=task_service.total_pages(total, pagination.page_size),
        ),
    )


@router.post(
    "",
    response_model=ApiResponse[TaskPublic],
    status_code=status.HTTP_201_CREATED,
    summary="创建任务",
)
def create_task(payload: TaskCreate, db: SessionDep, current_user: CurrentUser):
    task = task_service.create_task(db, payload, owner_id=current_user.id)
    return ApiResponse(data=TaskPublic.model_validate(task))


@router.get("/{task_id}", response_model=ApiResponse[TaskPublic], summary="获取单个任务")
def get_task(task_id: int, db: SessionDep, current_user: CurrentUser):
    task = task_service.get_task(db, task_id, owner_id=current_user.id)
    return ApiResponse(data=TaskPublic.model_validate(task))


@router.patch("/{task_id}", response_model=ApiResponse[TaskPublic], summary="局部更新任务")
def update_task(task_id: int, payload: TaskUpdate, db: SessionDep, current_user: CurrentUser):
    task = task_service.update_task(db, task_id, payload, owner_id=current_user.id)
    return ApiResponse(data=TaskPublic.model_validate(task))


@router.delete(
    "/{task_id}",
    status_code=status.HTTP_204_NO_CONTENT,
    summary="删除任务",
)
def delete_task(task_id: int, db: SessionDep, current_user: CurrentUser):
    task_service.delete_task(db, task_id, owner_id=current_user.id)
    # 204 不能有响应体,必须返回 Response 而不是 None(None 会变成 200 + null)
    return Response(status_code=status.HTTP_204_NO_CONTENT)
# app/api/v1/router.py
from fastapi import APIRouter

from app.api.v1 import auth, tasks
from app.core.config import settings

api_router = APIRouter(prefix=settings.API_V1_PREFIX)
api_router.include_router(auth.router)
api_router.include_router(tasks.router)

9.10 应用入口

# app/main.py
import time
import uuid
from contextlib import asynccontextmanager
from collections.abc import AsyncIterator

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException

from app.api.v1.router import api_router
from app.core.config import settings
from app.core.exceptions import AppError
from app.core.logging import logger, setup_logging
from app.db.base import Base
from app.db.session import engine
from app.models import Task, User  # noqa: F401  ← 必须导入,否则 create_all 建不出表

setup_logging()


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    """启动与关闭钩子。yield 之前是启动,之后是关闭。"""
    logger.info("应用启动中……环境=%s", settings.ENVIRONMENT)

    # 演示方便:直接建表。生产环境应改用 Alembic 迁移
    Base.metadata.create_all(bind=engine)
    logger.info("数据库表已就绪,开始接受请求")

    yield

    logger.info("应用关闭中,释放数据库连接池……")
    engine.dispose()
    logger.info("资源已释放")


app = FastAPI(
    title=settings.PROJECT_NAME,
    version="1.0.0",
    lifespan=lifespan,
    # 生产环境关闭文档,避免暴露接口地图
    docs_url=None if settings.is_production else "/docs",
    redoc_url=None if settings.is_production else "/redoc",
    openapi_url=None if settings.is_production else "/openapi.json",
)

# ① CORS:必须在最外层,这样即使后续中间件抛错,浏览器也能读到 CORS 头
app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.BACKEND_CORS_ORIGINS,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
    allow_headers=["*"],
    expose_headers=["x-request-id", "x-process-time-ms"],
)


# ② 请求 ID 与耗时:写在 CORS 之后,这样能覆盖到业务路由
@app.middleware("http")
async def request_context(request: Request, call_next):
    request_id = request.headers.get("x-request-id") or uuid.uuid4().hex[:16]
    request.state.request_id = request_id

    start = time.perf_counter()
    response = await call_next(request)
    elapsed_ms = (time.perf_counter() - start) * 1000

    response.headers["x-request-id"] = request_id
    response.headers["x-process-time-ms"] = f"{elapsed_ms:.1f}"

    if elapsed_ms > 1000:
        logger.warning("慢请求 %s %s 耗时 %.0fms", request.method, request.url.path, elapsed_ms)
    return response


# ③ 兜底 500:中间件是唯一能拿到"响应尚未生成"时刻的地方
@app.middleware("http")
async def catch_unhandled(request: Request, call_next):
    try:
        return await call_next(request)
    except Exception:
        # 完整堆栈进日志,客户端只拿到 requestId 去对照查询
        logger.exception("未处理的服务端异常 path=%s", request.url.path)
        return JSONResponse(
            status_code=500,
            content={
                "success": False,
                "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "服务器内部错误",
                    "request_id": getattr(request.state, "request_id", None),
                },
            },
        )


def _error_body(code: str, message: str, details=None, request_id: str | None = None) -> dict:
    body: dict = {"success": False, "error": {"code": code, "message": message}}
    if details is not None:
        body["error"]["details"] = details
    if request_id:
        body["error"]["request_id"] = request_id
    return body


# ④ 业务异常 → HTTP 响应
@app.exception_handler(AppError)
async def handle_app_error(request: Request, exc: AppError):
    return JSONResponse(
        status_code=exc.status_code,
        content=_error_body(
            exc.code, exc.message, exc.details, getattr(request.state, "request_id", None)
        ),
    )


# ⑤ 把 FastAPI 默认的 422 结构换成项目统一格式
@app.exception_handler(RequestValidationError)
async def handle_validation_error(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content=_error_body(
            "VALIDATION_ERROR",
            "请求参数校验失败",
            # str() 包一层:某些错误上下文含非 JSON 可序列化的对象
            details=[{**e, "ctx": {k: str(v) for k, v in e.get("ctx", {}).items()}} for e in exc.errors()],
            request_id=getattr(request.state, "request_id", None),
        ),
    )


# ⑥ 覆盖 HTTPException,保证 404/405 也是统一结构
@app.exception_handler(StarletteHTTPException)
async def handle_http_exception(request: Request, exc: StarletteHTTPException):
    code = {401: "UNAUTHORIZED", 403: "FORBIDDEN", 404: "NOT_FOUND", 405: "METHOD_NOT_ALLOWED"}.get(
        exc.status_code, "HTTP_ERROR"
    )
    return JSONResponse(
        status_code=exc.status_code,
        content=_error_body(code, str(exc.detail), None, getattr(request.state, "request_id", None)),
    )


# ⑦ 健康检查:不依赖数据库,保证探针不会被下游故障拖垮
@app.get("/healthz", tags=["ops"], include_in_schema=False)
def healthz():
    return {"status": "ok"}


app.include_router(api_router)
# app/__init__.py  —— 保持为空文件即可

9.11 .env.example 与 .gitignore

# .env.example —— 提交;复制成 .env 后填真实值
ENVIRONMENT=development
PROJECT_NAME=Task API

# 生成:python -c "import secrets; print(secrets.token_urlsafe(48))"
SECRET_KEY=dev-only-secret-key-please-replace-with-48-random-chars
ACCESS_TOKEN_EXPIRE_MINUTES=30
ALGORITHM=HS256

DATABASE_URL=sqlite:///./app.db
# 生产示例(需安装 psycopg 或 asyncpg):
# DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/taskapi

BACKEND_CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
__pycache__/
*.py[cod]
.venv/
venv/
.env
.env.local
*.db
*.sqlite3
.pytest_cache/
.mypy_cache/
.ruff_cache/
htmlcov/
.coverage

9.12 启动与验证

# 1. 创建虚拟环境(Python 3.15)
python -m venv .venv

# 激活
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# 2. 安装依赖
python -m pip install --upgrade pip
pip install -r requirements.txt

# 3. 准备环境变量
# Linux / macOS
cp .env.example .env
# Windows PowerShell
Copy-Item .env.example .env

# 4. 启动开发服务器(--reload 仅限开发!)
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

# 打开交互式文档
# http://127.0.0.1:8000/docs      ← Swagger UI,可点 "Try it out" 直接调试
# http://127.0.0.1:8000/redoc     ← ReDoc,阅读体验更好的文档
# 5. 用 curl 走一遍完整流程

# 注册
curl -s -X POST http://127.0.0.1:8000/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.com","nickname":"Alice","password":"Str0ngPassw0rd"}'
# → {"success":true,"data":{"id":1,"email":"alice@example.com",...,"is_active":true}}

# 登录(注意:OAuth2 密码模式用表单,不是 JSON)
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/api/v1/auth/login \
  -d 'username=alice@example.com&password=Str0ngPassw0rd' \
  | python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
echo "Token: ${TOKEN:0:24}..."

# 当前用户
curl -s http://127.0.0.1:8000/api/v1/auth/me -H "Authorization: Bearer $TOKEN"

# 创建任务
curl -s -X POST http://127.0.0.1:8000/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"写 Python Web 框架笔记","status":"doing"}'

# 列表 + 过滤 + 分页
curl -s "http://127.0.0.1:8000/api/v1/tasks?status=doing&page=1&page_size=10" \
  -H "Authorization: Bearer $TOKEN"

# 局部更新
curl -s -X PATCH http://127.0.0.1:8000/api/v1/tasks/1 \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"status":"done"}'

# 删除(期望 204,无响应体)
curl -s -i -X DELETE http://127.0.0.1:8000/api/v1/tasks/1 -H "Authorization: Bearer $TOKEN"

# —— 验证错误处理与鉴权 ——
# 未登录 → 401
curl -s http://127.0.0.1:8000/api/v1/tasks
# → {"success":false,"error":{"code":"UNAUTHORIZED","message":"缺少 Bearer Token",...}}

# 校验失败 → 422(密码太弱)
curl -s -X POST http://127.0.0.1:8000/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"bob@example.com","nickname":"Bob","password":"short"}'

# 字段约束失败 → 422(extra="forbid" 拦下未知字段)
curl -s -X POST http://127.0.0.1:8000/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"x","unknown_field":1}'

# 空 PATCH → 422(model_validator 拦下)
curl -s -X PATCH http://127.0.0.1:8000/api/v1/tasks/1 \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'

# 越权访问别人的任务 → 404(不是 403,避免泄露资源存在性)
curl -s http://127.0.0.1:8000/api/v1/tasks/999 -H "Authorization: Bearer $TOKEN"

# 健康检查
curl -s http://127.0.0.1:8000/healthz
# tests/test_tasks.py —— 一个最小的集成测试
import pytest
from fastapi.testclient import TestClient

from app.db.base import Base
from app.db.session import engine
from app.main import app


@pytest.fixture(scope="module")
def client():
    # 用内存/临时库跑测试,不要碰开发数据
    Base.metadata.create_all(bind=engine)
    with TestClient(app) as c:
        yield c
    Base.metadata.drop_all(bind=engine)


@pytest.fixture(scope="module")
def auth_headers(client: TestClient) -> dict[str, str]:
    client.post(
        "/api/v1/auth/register",
        json={"email": "test@example.com", "nickname": "Tester", "password": "Str0ngPassw0rd"},
    )
    resp = client.post(
        "/api/v1/auth/login",
        data={"username": "test@example.com", "password": "Str0ngPassw0rd"},
    )
    token = resp.json()["access_token"]
    return {"Authorization": f"Bearer {token}"}


def test_health(client: TestClient):
    assert client.get("/healthz").json() == {"status": "ok"}


def test_full_crud_flow(client: TestClient, auth_headers: dict[str, str]):
    # 创建
    created = client.post(
        "/api/v1/tasks", json={"title": "买牛奶"}, headers=auth_headers
    )
    assert created.status_code == 201
    task_id = created.json()["data"]["id"]

    # 读取
    got = client.get(f"/api/v1/tasks/{task_id}", headers=auth_headers)
    assert got.json()["data"]["title"] == "买牛奶"

    # 更新
    patched = client.patch(
        f"/api/v1/tasks/{task_id}", json={"status": "done"}, headers=auth_headers
    )
    assert patched.json()["data"]["status"] == "done"

    # 删除
    assert client.delete(f"/api/v1/tasks/{task_id}", headers=auth_headers).status_code == 204
    assert client.get(f"/api/v1/tasks/{task_id}", headers=auth_headers).status_code == 404


def test_requires_auth(client: TestClient):
    assert client.get("/api/v1/tasks").status_code == 401


def test_rejects_empty_patch(client: TestClient, auth_headers: dict[str, str]):
    created = client.post("/api/v1/tasks", json={"title": "x"}, headers=auth_headers)
    task_id = created.json()["data"]["id"]
    assert client.patch(f"/api/v1/tasks/{task_id}", json={}, headers=auth_headers).status_code == 422
# 运行测试
pytest -q

# 生产启动(无 --reload;容器里通常 1 个 worker + 多副本)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --no-access-log

这个示例里值得注意的设计

| 设计点 | 位置 | 好处 |

|---|---|---|

| response_model 强制声明 | 每个路由 | 敏感字段无法意外外泄 |

| 业务异常 vs HTTP 异常分离 | core/exceptions.py | service 层不依赖 FastAPI,可被脚本复用 |

| 所有查询都带 owner_id | task_service._get_owned_task | 越权访问在数据层就被挡住 |

| 返回 404 而非 403 | _get_owned_task | 不泄露资源存在性 |

| extra="forbid" | TaskCreate/TaskUpdate | 前端字段拼错立即报错,而不是被静默忽略 |

| 统一 x-request-id | request_context 中间件 | 日志与客户端报错可以对齐 |

| /healthz 不碰数据库 | main.py | 数据库故障时不至于被编排系统误杀 |

| lifespan 里 engine.dispose() | main.py | 优雅关闭,连接池干净释放 |


十、注意事项与常见坑

FastAPI 层面

1. async def 里调用阻塞函数(第 3.6 节)。这是最严重的坑:一个 requests.get 就能让整个进程的吞吐跌到 1/N。自检方法:搜代码里所有 async def,逐个检查里面调用的函数是否真的异步。

2. 忘记声明 response_model。ORM 对象的全部字段都会返回,包括 hashed_password。养成"每个路由都有 response_model 或返回类型注解"的习惯。

3. 同步 Session 在 async def 路由里用。db.query(...).all() 会阻塞事件循环。要么路由用 def,要么用 AsyncSession + asyncpg。两者不要混用同一个 engine。

4. 依赖里的 yield 之后碰 Response。会导致 RuntimeError: Caught handled exception, but response already started。清理逻辑只做资源释放,不要改响应。

5. 路由顺序:/tasks/me 这类固定路径必须写在 /tasks/{task_id} 之前,否则 me 会被当作路径参数。

6. BackgroundTasks 不可靠(第 3.8 节)。进程重启就丢任务。需要可靠性就必须上 Celery/ARQ。

7. def 路由的线程池只有 40 个线程。慢查询会把线程占满,表现为"并发上不去但 CPU 不高"。

8. 生产环境必须关掉 /docs,否则等于公开接口地图。

Django 层面

9. N+1 查询(第 4.4 节)。这是 Django 项目最常见的性能问题,尤其在 Admin 列表页和 DRF 列表接口。用 select_related(正向多对一)+ prefetch_related(反向/多对多)解决,并在测试里用 assertNumQueries 固定住。

10. DEBUG = True 上生产。会暴露完整的源代码路径、SQL、环境变量与设置,等于把服务器交出去。生产必须 DEBUG = False + 正确的 ALLOWED_HOSTS。

11. SECRET_KEY 硬编码在 settings.py 里。它进 Git 就等于泄露了 Session 签名密钥,攻击者可以伪造任意用户的会话。

12. 忘记 python manage.py collectstatic。生产环境 DEBUG=False 后 Django 不再自己服务静态文件,Nginx 会 404。

13. 大表上直接加非空字段/改类型。会锁表并阻塞写入。分三步:加可空 → 回填 → 加约束。

14. 迁移文件不入库,或手工改已应用的迁移。会导致多人协作时迁移历史分叉。

Flask 层面

15. 把 g 当缓存。g 的生命周期是单个请求,请求结束就销毁。跨请求缓存用 Flask-Caching + Redis。

16. 手拼 HTML 字符串。Flask 的自动转义只对模板生效,return f"<p>{x}</p>" 是裸的 XSS 漏洞。

17. session 存敏感数据。Flask 的默认 session 是签名但不加密的 Cookie——用户能读到全部内容(改不了,但看得见)。

18. 扩展堆成"手搓 Django"。装上第 5 个扩展并在自己写权限/响应包装时,应该考虑换框架。

部署与配置层面

19. 用开发服务器跑生产(第 7.3 节)。flask run --debug 的交互式调试器允许在浏览器执行任意代码;--reload 会丢在途请求。

20. 容器里堆多个 worker。K8s CPU 限流会让多个进程互相拖累;应该 1 进程 + 多副本。

21. .env 提交进仓库。一旦进过 Git 历史,必须轮换密钥。

22. **allow_origins=["*"] 配 allow_credentials=True**。浏览器会拒绝这个组合,跨域请求仍然失败,排查半天。

23. print(settings) 进日志。密钥与数据库密码会明文落进日志文件。用 SecretStr。

24. 忘记 pool_pre_ping=True。数据库空闲断连后,第一个请求会拿到一个死连接报错。加了它,SQLAlchemy 会在取连接前自动 ping 并重连。


十一、练习题

  1. (基础·类型注解) 下面这个 FastAPI 路由有三个问题,请指出并修正:每个参数分别会被当作路径/查询/请求体参数吗?校验缺失在哪里?

```python

@app.get("/products")

async def list_products(limit, offset=0, category=None):

return db.query(Product).limit(limit).offset(offset).all()

```

  1. (基础·Pydantic) 写一个 ArticleCreate 模型,要求:title 长度 1–200 且自动去首尾空格;slug 只允许小写字母、数字和连字符;tags 是字符串列表,最多 5 个,且每个都是小写;published_at 可选,但若提供了则不能是未来时间;body 与 summary 二选一必填(至少一个非空)。给出完整代码。
  1. (进阶·依赖注入) 实现一个基于角色的访问控制依赖系统,要求:
  • 能写 @router.get("/admin", dependencies=[Depends(require_roles("admin", "editor"))])
  • 需求角色可任意指定,用户拥有其中之一即通过
  • 无 Token 返回 401,有 Token 但角色不足返回 403,并在响应 detail 里说明缺哪个角色
  • 依赖可复用,且能通过 Annotated 声明

给出完整实现与两个使用示例。

  1. (进阶·Django N+1) 有模型 Category(分类)、Product(商品,外键指向 Category)、Review(评论,外键指向 Product)。现在要渲染一个分类列表页,显示每个分类的名称、商品数量、以及每个商品的评论数量。请:

① 写出会产生 N+1 的朴素实现并说明它总共执行多少次查询(设 10 个分类,每类 20 个商品);

② 用 select_related / prefetch_related / annotate 优化,说明优化后的查询次数;

③ 写出用 assertNumQueries 守住这个查询次数的测试。

  1. (进阶·异步陷阱) 下面的 FastAPI 应用在压测时 QPS 只有个位数,但 CPU 使用率不到 10%。请找出所有问题并给出两个版本的修复(一个保持 async def,一个改为 def):

```python

@app.get("/report")

async def report(db: Session = Depends(get_db)):

rows = db.query(Order).filter(Order.created_at >= date.today()).all()

total = sum(r.amount for r in rows)

resp = requests.post("https://analytics.example.com/event", json={"total": total})

time.sleep(0.5)

return {"total": total, "tracked": resp.status_code == 200}

```

  1. (思考题) 你的团队要做一个面向公众的电商站点:商品列表页需要 SEO,用户登录后有个交互复杂的购物车与订单管理页面,同时还要给 iOS/Android App 提供 API。请在 Django、FastAPI、Flask 中给出一个(或一组)技术选型,并说明:
  • 哪些页面用服务端渲染、哪些用前后端分离,为什么;
  • 如果同时用两个框架,如何避免"用户系统做两遍";
  • 部署形态是什么(进程模型、worker 数、副本数);
  • 说出至少三个你可能踩的坑。

十二、常见问题(FAQ)

Q1:FastAPI 真的比 Django 快很多吗?我该为了性能选它吗?

A:分情况,而且通常不该为了性能选它。

FastAPI 快的本质是 ASGI 异步 I/O,优势在"大量并发 + 每个请求大部分时间在等待 I/O"的场景(API 网关、聚合服务、实时推送)。在这种负载下,同等的硬件确实能有数倍于同步框架的吞吐。

但如果你的接口 90% 的时间花在数据库查询上(这是绝大多数业务系统的真实情况),那么:

框架开销 通常是亚毫秒级,而 可能是几十毫秒。把框架从同步换成异步,总响应时间的改善在 5% 以内——而你的 worker 数量、数据库索引与缓存策略的影响要大一个数量级。

所以选择理由应该是:

  • ✅ 选 FastAPI:自动 OpenAPI 文档、Pydantic 校验、类型驱动的开发体验、依赖注入、原生支持 WebSocket/SSE。
  • ✅ 选 Django:需要 Admin 后台、需要成熟的 ORM 与迁移、需要开箱即用的用户/权限系统、团队人数多需要强约定。
  • ❌ 不要:为了"性能好"而选 FastAPI,然后在 async def 里写同步数据库调用——那比 Django 还慢(多了一层事件循环开销)。

Q2:async def 和 def 路由到底怎么选?混用会不会有问题?

A:混用完全没有问题,而且往往是正确做法。FastAPI 的设计就支持两者共存。

决策规则:

你的路由要做什么选择
只调用异步库(httpx、AsyncSession、redis.asyncio)async def
只调用同步库(requests、同步 Session、boto3)def(FastAPI 自动丢线程池)
两者都要调用优先统一成一种;真要混,用 async def + await asyncio.to_thread(同步调用)
CPU 密集计算def(走线程池)或交给独立进程(ProcessPoolExecutor / Celery)
# 最危险的反模式:async def 里用同步 Session
@app.get("/bad")
async def bad(db: Session = Depends(get_db)):
    return db.query(User).all()      # 💥 阻塞事件循环

# 安全的等价写法:改成 def
@app.get("/good")
def good(db: Session = Depends(get_db)):
    return db.query(User).all()      # ✅ 在线程池里执行

# 或者用异步 Session(需要 asyncpg/aiosqlite)
@app.get("/also-good")
async def also_good(db: AsyncSession = Depends(get_async_db)):
    result = await db.execute(select(User))   # ✅ 真异步
    return result.scalars().all()

不要"混用同一个 engine"

同步 create_engine 和异步 create_async_engine 是两套独立的东西,必须用不同的 URL scheme(postgresql+psycopg vs postgresql+asyncpg)和不同的 Session 工厂。一个项目里同时存在两套连接池会让"到底有多少连接"变得无法预测。选一套,坚持到底。


Q3:select_related 和 prefetch_related 我老是分不清,有没有一句话的记法?

A:有的:

一句话记法

"正向用 select_related(JOIN 一次拿回),反向用 prefetch_related(额外一次 IN 查询)。"

展开成判断流程:

你要从当前对象走到关联对象,方向是?
├── 正向:从"多"到"一"
│   (Post → author,Post → category;外键在本表上)
│   └── select_related("author")     ← JOIN,1 次查询
│
└── 反向:从"一"到"多"
    (Author → posts,Post → tags;外键在对方表或中间表)
    └── prefetch_related("posts")    ← 额外 1 次 IN 查询

深度理解的关键是它们在 SQL 层面的差别:

-- select_related("author"):一次 JOIN,结果集里每篇文章都重复带作者字段
SELECT post.*, author.* FROM post INNER JOIN author ON post.author_id = author.id;

-- prefetch_related("tags"):两条独立查询,Python 侧做拼接
SELECT * FROM post;
SELECT * FROM tag INNER JOIN post_tags ON ... WHERE post_tags.post_id IN (1,2,3,...,N);

所以:

  • select_related 只能用于一对一/多对一(因为 JOIN 后主表行数不会爆炸)。
  • 如果对多对多用 select_related,JOIN 会产生笛卡尔积——10 篇文章各 5 个标签就是 50 行,内存与网络都浪费。(Django 会直接报错阻止你这么做。)
  • prefetch_related 永远是 2 次查询(不论 N 多大),且不会放大结果集。

Q4:为什么我的 FastAPI 服务部署后内存一直涨?

A:Python 服务的内存增长通常有四个来源,按出现频率排序:

① 每个 worker 一份的模块级缓存(最常见)

# ❌ 无上限的全局字典
_CACHE: dict[str, Any] = {}

@app.get("/user/{uid}")
def get_user(uid: str):
    if uid not in _CACHE:
        _CACHE[uid] = fetch_from_db(uid)   # 只增不减
    return _CACHE[uid]

# ✅ 用有容量上限 + TTL 的缓存
from cachetools import TTLCache
_CACHE = TTLCache(maxsize=10_000, ttl=300)
# 多 worker 环境要共享缓存 → 用 Redis

② 把整个结果集读进内存

# ❌ 100 万行一次性载入
rows = db.query(Order).all()
# ✅ 分批流式处理
for chunk in db.query(Order).yield_per(1000):
    process(chunk)

③ 每个请求新建 engine / client,连接池泄漏

# ❌ 每个请求建一个 engine —— 连接池永远不释放
@app.get("/bad")
def bad():
    engine = create_engine(settings.DATABASE_URL)   # 💥 每次都新建连接池
    ...

# ✅ engine 是模块级单例,进程内共享
# app/db/session.py 里创建一次

④ PyJWT / bcrypt 等 C 扩展的内存碎片,或其他库的已知泄漏

诊断步骤:

# ① 看趋势:区分"正常缓存"与"真泄漏"
pip install memory-profiler
python -m memory_profiler app/main.py

# 或者用 tracemalloc 直接定位增长点(在代码里)
# 用 tracemalloc 对比两个时间点的内存分配
import tracemalloc
from fastapi import FastAPI

app = FastAPI()
tracemalloc.start(25)      # 保存 25 层调用栈


@app.get("/debug/memory", include_in_schema=False)
def memory_snapshot():
    snapshot = tracemalloc.take_snapshot()
    # 按行统计占用最大的 10 处
    top = snapshot.statistics("lineno")[:10]
    return [{"file": str(s.traceback[0]), "size_kb": s.size / 1024} for s in top]

先分清"泄漏"和"正常占用"

- 正常:内存涨到某个平台期后稳定,每次 GC 后回落到相近的基线。

- 泄漏:每次 GC 后的谷底值持续抬升,且与请求量正相关。

临时的缓解手段是限制 worker 的常驻内存并定期重启(Gunicorn 的 --max-requests 1000 会让 worker 处理 N 个请求后重启,能缓解 C 扩展的碎片问题)。但如果是 Python 层的引用泄漏,重启只是把问题藏起来——泄漏速率会随流量增长,迟早撑不到重启周期。


相关笔记

  • Python-07-进阶特性 —— 装饰器、生成器、类型注解、GIL。FastAPI 的依赖注入与 Pydantic 的校验器都建立在这些特性之上。
  • Python-04-面向对象 —— 类、继承、魔术方法。Pydantic 模型与 SQLAlchemy 模型都重度依赖这些机制。
  • Python-08-虚拟环境与包管理 —— venv、pip、依赖锁定与项目结构,是本文示例能跑起来的前提。
  • 后端-05-数据库操作与ORM —— 连接池、事务、ORM 与 N+1 问题的通用原理,与本文第 4.4 节互补。
  • 后端-01-HTTP与RESTfulAPI设计 —— 示例里的状态码、Location 头、分页参数约定都来自这篇。
  • 后端-06-认证与授权 —— 本文示例只做了最简 JWT,完整的 Session/OAuth2/RBAC 方案在这里。
  • 后端-02-Nodejs与Express —— 另一个异步运行时的对照:事件循环、非阻塞 I/O、优雅关闭的思路完全相通。
  • 后端-07-Docker与容器化 —— 本文第九节的服务如何打包成镜像,以及容器里的进程模型取舍。
  • 版本与官方资源速查 —— Python 与各框架的当前版本状态与官方文档入口。

参考来源

核实时间 2026-10-11。以下链接均已实测可访问:

FastAPI(官方中文文档)

  • FastAPI 中文文档首页(/zh/ 有完整中文版):<https://fastapi.tiangolo.com/zh/>
  • 依赖项(Depends、Annotated 推荐写法、yield 依赖):<https://fastapi.tiangolo.com/zh/tutorial/dependencies/>
  • SQL(关系型)数据库(SQLModel 用法、Session 依赖):<https://fastapi.tiangolo.com/zh/tutorial/sql-databases/>
  • 服务器工作进程(多 worker 部署):<https://fastapi.tiangolo.com/zh/deployment/server-workers/>
  • 设置和环境变量(pydantic-settings 用法):<https://fastapi.tiangolo.com/zh/advanced/settings/>
  • 更大的应用 - 多个文件(分层项目结构):<https://fastapi.tiangolo.com/zh/tutorial/bigger-applications/>

Django(官方简体中文文档)

  • Django 6.1 中文文档首页:<https://docs.djangoproject.com/zh-hans/6.1/>
  • 执行查询(QuerySet 惰性、字段查询、跨关系查询):<https://docs.djangoproject.com/zh-hans/6.1/topics/db/queries/>
  • 数据库访问优化(select_related/prefetch_related、批量方法、避免 N+1):<https://docs.djangoproject.com/zh-hans/6.1/topics/db/optimization/>
  • 配置(settings 组织方式):<https://docs.djangoproject.com/zh-hans/6.1/topics/settings/>
  • 部署检查清单:<https://docs.djangoproject.com/zh-hans/6.1/howto/deployment/checklist/>
  • Django 版本与支持周期(LTS 策略、最新版 6.1.2):<https://www.djangoproject.com/download/>

Flask 与 Jinja2

  • Flask Quickstart(路由、上下文、url_for、session、错误处理):<https://flask.palletsprojects.com/en/stable/quickstart/>
  • Jinja2 模板设计者文档(语法、过滤器、继承、自动转义):<https://jinja.palletsprojects.com/en/stable/templates/>

Python 官方

  • Python 官方教程(类型注解、虚拟环境与包管理):<https://docs.python.org/3/tutorial/>
  • Python 版本状态表(当前稳定版 3.15):<https://devguide.python.org/versions/>

版本与依赖说明

  • 本文以 Python 3.15(当前稳定版)为基准。
  • Django:核实时最新版为 6.1.2;5.2 LTS 的最新补丁为 5.2.18(主流支持已于 2025-12-03 结束,扩展支持至 2028-04)。生产环境建议选 LTS 版本,具体支持周期以官方下载页的版本表为准。
  • FastAPI 0.143.0、Uvicorn 0.54.0、Pydantic 2.14.0、pydantic-settings 2.15.0、Flask 3.1.3、SQLAlchemy 2.1.4、Jinja2 3.1.6、django-rest-framework 3.18.3、gunicorn 26.2.0、PyJWT 2.15.1、bcrypt 5.0.0 —— 以上均为写作时 PyPI 上的最新版本,可通过 pip index versions <包名> 核实当前值。
  • passlib(1.7.4)已多年未更新,与新版 bcrypt 存在兼容性告警,示例中因此改为直接使用 bcrypt。更强的选择是 argon2-cffi。
  • uvicorn.workers.UvicornWorker 的导入路径随版本变化过(曾迁移至独立的 uvicorn-worker 包),使用前请查阅 Uvicorn 与 Gunicorn 的最新官方文档并本机验证。
  • django-debug-toolbar、cachetools、memory-profiler、httpx 等第三方工具的行为与配置项随版本变化,以各自官方文档为准。