08.5 阶段 4:Web 框架主线
所属:全栈开发面试题库 / 学习路径 / 08 Python 全栈
本页目录
一、阶段定位
前面四个阶段解决「语言写对、工程规范、工具链齐全」,本阶段第一次真正对外提供 HTTP 接口。主线是 FastAPI(异步、类型注解驱动),同时讲清楚 Django 全家桶与 Flask 的定位。重点不是「写一个 hello world」,而是把请求从路由进入、依赖注入、Pydantic 校验、ORM 查询、响应序列化的完整链路串起来;理解 Session 为什么不能跨请求复用、N+1 查询为什么必须预加载、迁移文件为什么要纳入版本管理。
与前后阶段的衔接:因为阶段 3 已经把类型注解写成了契约,本阶段的 FastAPI 直接从注解生成请求校验与 OpenAPI 文档;因为阶段 1 理解了可变对象与引用,本阶段的 Session 生命周期才有抓手。跳过本阶段直接进阶段 5 的数据层,会在「ORM 跨请求复用导致状态串扰」「N+1 拖慢接口」上反复踩坑。
原有卡点及判断依据:
- 把 FastAPI 依赖注入当普通函数调用理解:判断现象是不知道
Depends(get_db)为什么能在请求结束后自动关闭连接,把get_db()当普通函数直接调。见 5.2。 - ORM 遍历关联对象不做预加载引发 N+1:判断现象是接口返回 100 条订单,日志里出现 101 次 SQL。见 5.5。
- Session 生命周期跨请求复用导致状态串扰:判断现象是多个请求共享同一个 Session,前一个请求未提交的数据在后一个请求里可见。见 5.4。
- 把 Django 信号当异步任务使用:判断现象是在信号里发邮件、调外部 API,导致请求变慢。见 5.7。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
| 能用 FastAPI 写带路由、依赖注入、Pydantic 校验的接口 | 启动 uvicorn,访问 /docs 看到自动文档 |
能解释 Depends(get_db) 的 yield 依赖在请求结束时做了什么 |
在 yield 后打印日志,确认请求结束时执行 |
| 能用 SQLAlchemy 2.0 写声明式模型,理解 Session 的请求级生命周期 | 跨请求不复用 Session,异常时自动 rollback |
能用 selectinload/joinedload 解决 N+1 |
接口日志里 SQL 次数从 N+1 降到固定几次 |
| 能用 Alembic 生成、升级、回滚迁移 | alembic upgrade head 与 alembic downgrade -1 都能跑 |
| 能说清 Django MTV、中间件、信号的定位与 Flask 的取舍 | 不混淆信号与异步任务 |
建议学时:
- 全职:3 周,约 90 小时。FastAPI 与 Pydantic 25 小时、SQLAlchemy 2.0 30 小时、Alembic 10 小时、Django/Flask 对照 25 小时。
- 在职:7–8 周,约 100 小时。
学时分配建议:FastAPI 路由与依赖 20%、Pydantic v2 15%、SQLAlchemy 2.0 与 Session 25%、预加载与 N+1 15%、Alembic 10%、Django/Flask 15%。
三、先修自检
| 先修项 | 合格标准 | 不合格时回到 |
|---|---|---|
| 类型注解 | 能写完整注解 | 08.3 阶段 2 |
| venv 与依赖管理 | uv 工程可用 | 08.4 阶段 3 |
| HTTP 基础 | 能说清 GET/POST 与状态码 | 08.1 阶段 0 |
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| FastAPI 路由 | APIRouter、路径参数、查询参数、状态码 | 会用 | 04.7 Python |
| 依赖注入 | Depends、yield 依赖、依赖缓存、覆盖 |
能讲清原理 | 04.7 Python |
| Pydantic v2 | 模型、字段校验、嵌套模型、序列化、model_dump |
会用 | 04.7 Python |
| SQLAlchemy 2.0 | 声明式模型、Session、事务、select() 写法 |
能讲清原理 | 04.7 Python |
| 关系加载 | selectinload/joinedload、N+1、懒求值 |
能讲清原理 | 05.1 关系型数据库通用能力 |
| Alembic | 迁移生成、upgrade/downgrade、漂移 | 会用 | 05.1 关系型数据库通用能力 |
| Django/Flask | MTV、中间件、信号、应用工厂 | 了解 | 04.7 Python |
进度管理建议:本阶段代码量最大,建议按「FastAPI 接口 → SQLAlchemy 模型 → 预加载 → 迁移」顺序推进。《知识点全清单》「Web」段是全量清单。
五、分模块精讲
5.1 FastAPI 路由与 APIRouter
为什么需要它:路由是接口的入口。APIRouter 让大工程按模块拆分路由,而不是把所有接口堆在一个文件里。类型注解直接生成请求校验与 OpenAPI 文档。
核心机制:
@app.get("/items/{item_id}")路径参数;查询参数q: str | None = None自动从 query string 取。APIRouter(prefix="/api/v1"):把路由按模块分组,app.include_router(router)挂载。- 类型注解即契约:
item_id: int自动转换并校验,传字符串返回 422。 - 响应模型
response_model=ItemOut:过滤输出字段,避免内部字段泄露。
最小可运行示例:
# main.py
from fastapi import FastAPI, APIRouter, HTTPException
from pydantic import BaseModel
app = FastAPI(title="演示")
router = APIRouter(prefix="/api/v1")
class ItemOut(BaseModel):
id: int
name: str
@router.get("/items/{item_id}", response_model=ItemOut)
def get_item(item_id: int, q: str | None = None):
if item_id <= 0:
raise HTTPException(status_code=404, detail="不存在")
return {"id": item_id, "name": f"item-{item_id}", "q": q}
app.include_router(router)
uvicorn main:app --reload
# 访问 http://127.0.0.1:8000/docs 看自动文档
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 路径参数传字符串返回 422 | item_id: int 自动校验 |
这是预期行为;前端传正确类型 |
| 内部字段(如密码)出现在响应 | 没设 response_model |
用 response_model=ItemOut 过滤 |
面试考法:常问「FastAPI 为什么自动生成 OpenAPI」。答「类型注解 + Pydantic 模型在启动时被收集,生成 OpenAPI schema」。
5.2 依赖注入与 yield 依赖
为什么需要它:每个请求都需要数据库连接、当前用户、配置——这些如果在函数里手动创建,会散落各处且忘记释放。Depends 把依赖抽成可复用单元,yield 依赖在请求结束时自动清理。
核心机制:
async def get_db(): db = SessionLocal(); try: yield db; finally: db.close():yield 前是设置,yield 后是清理。- FastAPI 在每个请求开始时调用依赖,注入到端点;请求结束(无论成功失败)执行 yield 后的清理。
- 依赖缓存:同一个请求内,
Depends(get_db)在多个参数中只调用一次,保证整个请求用同一个 Session。 - 测试覆盖:
app.dependency_overrides[get_db] = mock_get_db。
最小可运行示例:
from fastapi import Depends, FastAPI
from sqlalchemy.orm import Session
app = FastAPI()
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
@app.get("/users/{uid}")
def get_user(uid: int, db: Session = Depends(get_db)):
user = db.query(User).get(uid)
if not user:
raise HTTPException(404, "未找到")
return user
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 请求结束后连接没关闭 | 用了普通 return 而非 yield |
用 yield + finally: close() |
| 跨请求复用 Session | 在模块级创建 Session 单例 | 每个请求新建 Session |
| 测试里还在用真实 DB | 没覆盖依赖 | 用 app.dependency_overrides[get_db] |
面试考法:常问「Depends 与普通函数调用的区别」。答「Depends 由框架在请求生命周期管理,支持 yield 清理、请求内缓存、测试覆盖;普通函数调用框架不接管」。
5.3 Pydantic v2 校验与序列化
为什么需要它:请求 body 是不可信的字符串,必须经过校验才能进入业务逻辑。Pydantic v2 用 Rust 实现,比 v1 快 5–50 倍,自动生成 OpenAPI schema。
核心机制:
class UserIn(BaseModel): name: str; age: int = 0:字段类型即校验规则。- 校验失败自动返回 422,错误信息包含字段与原因。
- 嵌套模型:
class Post(BaseModel): author: UserIn。 model_dump()转 dict;model_dump_json()转 JSON 字符串。- v1 与 v2 差异:v2 用
model_dump()替代 v1 的dict(),性能大幅提升。
最小可运行示例:
from pydantic import BaseModel, Field, EmailStr
class UserCreate(BaseModel):
name: str = Field(min_length=2, max_length=20)
email: EmailStr
age: int = Field(default=0, ge=0, le=150)
# 校验失败
UserCreate(name="A", email="bad", age=-1)
# pydantic.ValidationError: 3 validation errors
# 校验通过
user = UserCreate(name="Ann", email="ann@example.com", age=30)
print(user.model_dump())
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
用了 v1 的 dict() 报错 |
v2 改名 | 用 model_dump() |
| 字段校验失败但没返回 422 | 手动构造 Pydantic 模型没接异常 | 在 FastAPI 端点用模型做参数,框架自动处理 |
面试考法:常问「Pydantic v2 比 v1 快多少、为什么」。答「Rust 核心,快 5–50 倍;API 兼容,model_dump 替代 dict」。
5.4 SQLAlchemy 2.0 模型与 Session 生命周期
为什么需要它:ORM 把 Python 类映射到数据库表,但 Session 是「工作单元」——它跟踪对象状态、管理事务边界。理解 Session 为什么是请求级的,才能避免跨请求状态串扰。
核心机制:
class User(Base): __tablename__ = "users"; id: Mapped[int] = mapped_column(primary_key=True)。- Session 是工作单元:
db.add(obj)、db.commit()写库、db.rollback()回滚。 - Session 不是线程安全的,也不能跨请求复用:每个请求新建,结束关闭。
- 提交后对象默认过期,下次访问会重新查询(过期对象)。
最小可运行示例:
from sqlalchemy import create_engine, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, sessionmaker
engine = create_engine("sqlite:///./app.db", echo=True)
SessionLocal = sessionmaker(bind=engine)
class Base(DeclarativeBase):
pass
class User(Base):
__tablename__ = "users"
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str] = mapped_column(String(50))
Base.metadata.create_all(engine)
# 请求级使用
db = SessionLocal()
try:
user = User(name="Ann")
db.add(user)
db.commit()
db.refresh(user) # 拿到自增 id
except Exception:
db.rollback()
raise
finally:
db.close()
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 跨请求看到上一个请求未提交的数据 | 复用了同一个 Session | 每个请求新建,yield 依赖关闭 |
sqlalchemy.exc.IntegrityError |
唯一约束冲突 | 捕获后 rollback,给业务错误提示 |
提交后访问属性触发 DetachedInstanceError |
Session 已关闭 | 关闭前 db.refresh() 或在端点内返回 |
面试考法:常问「Session 为什么不能跨请求复用」。答「Session 是工作单元,跟踪未提交状态;跨请求会导致状态串扰、连接泄漏、线程不安全」。
5.5 关系加载策略与 N+1
为什么需要它:ORM 默认懒加载——访问 order.user 时才发 SQL。如果接口返回 100 条订单,每条都访问 order.user,就产生 1 + 100 次 SQL,即 N+1。
核心机制:
- 懒加载(默认):访问关联对象时才查询。
selectinload(Order.user):先查主表 100 条,再用WHERE id IN (...)一次查出所有 user,共 2 次 SQL。joinedload(Order.user):JOIN 一次查主表与关联表,1 次 SQL。- 选择:
selectinload适合多对一/一对多集合,joinedload适合多对一。 - Django 对应:
select_related(JOIN,多对一)、prefetch_related(二次查询,一对多)。
最小可运行示例:
from sqlalchemy import select
from sqlalchemy.orm import selectinload
# 错误:N+1
orders = db.scalars(select(Order)).all()
for o in orders:
print(o.user.name) # 每条订单一次 SQL
# 正确:预加载
orders = db.scalars(
select(Order).options(selectinload(Order.user))
).all()
for o in orders:
print(o.user.name) # 共 2 次 SQL
# Django 写法
orders = Order.objects.select_related("user").all()
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 接口日志里 N+1 次 SQL | 没预加载关联 | 用 selectinload/joinedload |
joinedload 导致主表重复行 |
JOIN 产生笛卡尔积 | 用 selectinload 或加 .unique() |
面试考法:常问「N+1 是什么、怎么解决」。答「懒加载导致循环内多次查询;用 selectinload/joinedload 预加载」。
5.6 Alembic 迁移
为什么需要它:改表结构(加字段、改类型)不能手动在生产数据库执行,必须用版本化脚本管理,可升级、可回滚、可 code review。
核心机制:
alembic init alembic创建迁移目录。alembic revision --autogenerate -m "add age column"自动生成迁移脚本(基于模型与数据库差异)。alembic upgrade head升级到最新;alembic downgrade -1回滚上一个版本。- 自动生成可能遗漏变更(如索引、约束),必须人工 review。
- 迁移文件纳入 Git,与代码一起 review。
最小可运行示例:
alembic init alembic
# 修改 alembic.ini 中的 sqlalchemy.url
alembic revision --autogenerate -m "add age to user"
alembic upgrade head
alembic downgrade -1
alembic upgrade head
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 自动生成的迁移为空 | 模型与数据库没差异 | 检查 alembic/env.py 是否导入了 Base |
alembic upgrade 报表已存在 |
之前手动建过表 | 用 alembic stamp head 标记基线 |
面试考法:常问「迁移为什么要纳入版本管理」。答「可 code review、可回滚、多环境一致、可复现」。
5.7 Django MTV 与 Flask 的定位
为什么需要它:FastAPI 不是唯一选择。Django 自带 ORM、Admin、认证、表单,适合快速出后台;Flask 是微框架,适合轻量服务。本阶段只要理解定位,不必精通。
核心机制:
- Django MTV:Model(ORM)、Template(模板)、View(视图函数);中间件在请求前后处理;信号是模型事件钩子(保存后触发)。
- Django 信号是同步的:在请求链路里执行,不适合做发邮件、调外部 API 这类耗时操作。
- Flask:应用工厂
create_app()、蓝图(Blueprint)路由分组、扩展生态(Flask-SQLAlchemy、Flask-Migrate)。
最小可运行示例:
# Django 信号:同步执行,会拖慢请求
from django.db.models.signals import post_save
from django.dispatch import receiver
@receiver(post_save, sender=User)
def send_welcome_email(sender, instance, created, **kwargs):
if created:
# 这里同步发邮件,请求会阻塞
pass # 应改为 Celery 异步任务
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 请求变慢,信号里做了耗时操作 | 信号是同步的 | 把耗时操作移到 Celery |
| Flask 上下文混乱 | 不懂线程局部变量 | 用应用工厂与请求上下文 |
面试考法:常问「FastAPI、Django、Flask 怎么选」。答「新写异步接口选 FastAPI;全栈后台选 Django;轻量微服务选 Flask」。
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| FastAPI hello | 写一个带 APIRouter 的接口 | /docs 自动文档可见 |
1 小时 |
| Pydantic 校验 | 写 UserCreate 模型,传错类型看 422 | 错误信息清晰 | 1 小时 |
| SQLAlchemy CRUD | 建 User 模型,完成增删查改 | 提交与回滚正确 | 2 小时 |
| Alembic 迁移 | 加一个字段,生成并执行迁移 | upgrade/downgrade 都能跑 | 1.5 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 修 N+1 | 给定循环内访问关联对象的代码 | 用 selectinload 预加载,SQL 次数下降 | 2 小时 |
| 修 Session 复用 | 给定模块级 Session 单例 | 改成 yield 依赖请求级 | 1.5 小时 |
| 覆盖依赖测试 | 给一个依赖 get_db 的端点写测试 | 用 dependency_overrides | 1.5 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| FastAPI 单机 API | 实现一个待办 CRUD,含校验与迁移 | 接口可联调,OpenAPI 完整 | 6 小时 |
| Django 业务系统 | 用 Django Admin 快速出一个后台 | 含认证权限、ORM 查询 | 6 小时 |
| 链路笔记 | 画出请求从路由到响应的完整链路 | 标注依赖注入、校验、ORM 各环节 | 2 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
| 422 Unprocessable Entity | 类型不匹配或缺字段 | 看响应 detail | 前端按 Pydantic 模型传参 |
sqlalchemy.exc.IntegrityError |
唯一约束冲突 | 看错误信息哪个字段 | 捕获后 rollback,返回业务错误 |
DetachedInstanceError |
Session 已关闭还访问属性 | 看调用栈 | 关闭前 refresh 或端点内返回 |
| 接口日志 N+1 次 SQL | 没预加载关联 | 开启 echo=True 看 SQL |
用 selectinload/joinedload |
| 请求结束后连接没关闭 | 依赖没写 yield | 看 get_db 实现 | 用 yield + finally close |
alembic revision 为空 |
env.py 没导入 Base | 检查迁移脚本 | 在 env.py 导入 Base.metadata |
| Django 信号里调外部 API 拖慢请求 | 信号是同步的 | 看视图耗时 | 移到 Celery |
八、出口条件
全部勾选后再进入 08.6 阶段 5:数据层、缓存与任务队列。
- [ ] 能用 FastAPI 写带路由、依赖注入、Pydantic 校验的接口
- [ ] 能解释 yield 依赖在请求结束时做了什么
- [ ] 能写 SQLAlchemy 2.0 模型,理解 Session 请求级生命周期
- [ ] 能用 selectinload/joinedload 解决 N+1
- [ ] 能用 Alembic 生成、升级、回滚迁移
- [ ] 能说清 Django MTV、信号与 Flask 的定位
- [ ] 能画出请求从路由到响应的完整链路
自测题(先自己想,再看要点):
Depends(get_db)与普通函数调用get_db()的区别?- 要点:框架管理生命周期,yield 自动清理,请求内缓存,测试可覆盖。
- Session 为什么不能跨请求复用?
- 要点:工作单元跟踪未提交状态;跨请求会状态串扰、连接泄漏、线程不安全。
- N+1 是什么?怎么解决?
- 要点:懒加载导致循环内多次查询;用 selectinload/joinedload 预加载。
selectinload与joinedload的区别?- 要点:selectinload 二次 IN 查询,适合集合;joinedload JOIN 一次查,适合多对一。
alembic upgrade报表已存在怎么办?- 要点:用
alembic stamp head标记基线,再正常 upgrade。
- 要点:用
- Django 信号为什么不适合发邮件?
- 要点:信号是同步的,在请求链路执行,会拖慢响应;应改 Celery 异步任务。
- Pydantic v2 的
model_dump()替代了 v1 的什么?- 要点:
dict();v2 用 Rust 核心,性能快 5–50 倍。
- 要点: