知识点笔记
一、项目工程目录结构与各层职责
整个后端项目采用分层架构,不同文件夹承担不同职责,实现业务解耦,便于后期维护与迭代。
- crud/:专门封装数据库增、删、改、查逻辑。把SQLAlchemy的查询语句全部放在这一层,路由层只负责接收请求、调用crud函数,路由中不写原生查询代码,做到业务逻辑和数据库操作分离。
- models/:存放SQLAlchemy ORM数据库模型。模型类和MySQL数据表一一映射,定义表名、字段、数据类型、约束、外键、索引,相当于Python代码描述数据库表结构。
- routers/:路由层,按照业务模块拆分接口文件。定义接口访问地址、请求参数接收,接收前端请求,调用crud完成业务,组装返回结果。不要把所有接口全部写在main.py。
- schemas/:Pydantic数据验证模型。负责请求数据校验、响应数据序列化;做字段类型校验、别名映射、ORM对象转字典,约束接口出入参格式。
- utils/:通用工具函数目录,存放多个模块可以复用的工具代码。
- config/:项目配置目录,存放数据库连接配置、Redis缓存配置等各类环境配置。
- main.py:项目入口文件。只做服务初始化工作:导入路由、注册路由、添加中间件、启动FastAPI应用,不写业务接口代码。
项目配套物料说明
- 前端Vue项目代码:负责页面渲染、用户交互,通过网络请求调用后端提供的接口。
- 接口规范文档:前后端协作标准。定义每个接口的请求方式、请求参数、参数类型、返回数据格式、错误码,前后端按照同一套文档开发。
- 数据库SQL文件:包含建表语句、初始化测试数据;直接导入MySQL,不用手动建表造数据。
二、模块化路由 APIRouter
1. 概念
模块化路由就是将不同业务模块的接口拆分到独立的 .py 文件中,再在入口文件 main.py 将多个路由统一注册挂载到FastAPI主app实例上。避免所有接口堆积在main.py,造成文件臃肿。
2. 使用优势
- 结构清晰:接口按业务模块归类,新闻、用户、收藏各自独立文件。
- 便于维护:修改某个模块接口,只需要打开对应路由文件,不影响其他模块代码。
-
文档分组:通过
tags参数,自动在接口文档页面对接口进行分组展示。
3. 核心对象与参数
router = APIRouter(prefix="/api/news", tags=["news"])
-
prefix:统一路由前缀,该文件下所有接口自动拼接该路径,不需要每个接口重复写/api/news。 -
tags:接口文档分组标签,字符串列表。
接口定义完成之后,在main.py中完成注册:
app.include_router(news.router)
4. 完整使用流程
- 在routers下新建模块py文件;
- 导入
APIRouter,创建router实例,指定prefix、tags; - 使用
@router.get()/@router.post()装饰器编写接口函数; - main.py导入该router对象,调用
app.include_router()完成挂载注册。
三、SQLAlchemy 异步ORM
1. 需要安装依赖包
-
sqlalchemy[asyncio]:ORM框架核心,提供异步支持; -
aiomysql:MySQL异步驱动,异步引擎需要该驱动和数据库通信。
注意:同步pymysql不能配合异步引擎使用。
2. 核心组件
-
create_async_engine() 创建异步引擎
引擎是程序和数据库之间的通信核心。
-
ASYNC_DATABASE_URL:数据库连接字符串,格式:mysql+aiomysql://账号:密码@host:端口/库名?charset=utf8mb4 -
echo=True:开发调试用,控制台打印程序执行的完整SQL语句;生产环境必须关闭,会损耗性能。 -
pool_size:连接池常驻连接数量,程序会维持若干连接不释放,减少频繁创建连接开销。 -
max_overflow:连接池满了之后,允许额外创建的临时连接最大数量。
-
async_sessionmaker 异步会话工厂
用来生成数据库会话对象。
-
bind=async_engine:绑定前面创建好的异步引擎; -
class_=AsyncSession:指定使用异步会话; -
expire_on_commit=False:执行commit提交后,ORM对象属性不会失效。如果设置True,commit之后访问对象字段会重新向数据库发起查询,开发场景一般设置False。
-
AsyncSession 数据库会话
所有数据库增删改查操作,全部依靠会话对象完成。会话相当于一次数据库连接会话。
3. 数据库会话依赖函数 get_db()
FastAPI依靠依赖注入,把会话对象传给每一个接口函数。
async def get_db():
async with AsyncSessionLocal() as session:
try:
yield session
await session.commit()
except Exception:
await session.rollback()
raise
finally:
await session.close()
逻辑拆解:
-
yield session:将会话交给接口函数使用; - 接口内全部逻辑正常跑完,执行
await session.commit()提交事务,保存改动; - 如果出现异常,执行
await session.rollback()事务回滚,放弃本次所有修改,并且把异常继续向外抛出; -
finally块一定会执行,关闭会话释放数据库连接还给连接池。
接口中使用:async def func(db:AsyncSession = Depends(get_db))
4. ORM模型类编写规范
- 定义基类:
class Base(DeclarativeBase): pass,所有数据表模型类都继承Base。 -
__tablename__ = "表名":指定该模型映射MySQL哪一张数据表。 - 字段使用
Mapped[类型] + mapped_column()定义。可以设置主键、自增、非空、外键、默认值、字段注释。 -
__table_args__:配置表额外参数,用于创建数据库索引。索引可以大幅提升where条件查询的速度。
__table_args__ = (
Index('索引名称','字段名'),
)
5. ORM常用操作语法
-
查询:
select(模型类),配合session执行得到数据。 -
分页查询
- offset偏移量计算公式:
offset = (page -1) * page_size - 链式调用:
select(News).offset(offset).limit(page_size) -
hasMore(是否还有下一页)判断逻辑:offset + 当前页返回条目数 < 总记录数,条件成立代表存在下一页。
- offset偏移量计算公式:
-
排序:
.order_by(News.字段.desc());.desc()代表降序;不写.desc()默认升序。 -
聚合统计总数:使用
func.count()做数量统计。 - 更新数据:
stmt = update(News).where(条件).values(要修改的字段=值)
result = await db.execute(stmt)
result.rowcount可以获取本次语句实际影响的数据行数,可以用来判断条件是否匹配到数据。
-
新增数据:
db.add(模型实例对象),commit之后写入数据库。 -
删除数据:
delete(模型).where(删除条件)。
6. PyCharm导入SQL脚本操作
打开Database数据库插件,连接MySQL;右键数据库连接 → SQL Scripts → Run SQL Script,选择本地.sql文件执行,完成建表与初始化数据。
四、CORS跨域资源共享
1. 什么是跨域
跨域是浏览器的安全保护策略。浏览器会拦截前端JS发起的非同源请求。
同源三要素必须全部相同,才算同源:
- 协议(http / https)
- IP / 域名
- 端口号
例子:前端地址
[http://localhost:5173](http://localhost:5173),后端地址[http://127.0.0.1:8000](http://127.0.0.1:8000)。域名IP不一致,端口不一致,触发跨域。
2. 跨域报错特征
控制台报错关键字:No 'Access‑Control‑Allow‑Origin' header is present on the requested resource.
3. FastAPI解决跨域:CORS中间件 CORSMiddleware
在main.py中添加中间件,告诉浏览器允许哪些前端源访问后端接口。
关键参数:
-
allow_origins:允许访问后端的前端源地址列表。开发可以写["*"]代表全部放行;生产环境禁止写[""],要写具体前端域名*。 -
allow_credentials=True:允许请求携带Cookie、身份凭证。 -
allow_methods=["*"]:允许所有HTTP请求方式(GET、POST、PUT、DELETE等)。 -
allow_headers=["*"]:允许所有请求头。
注意:中间件必须在注册路由之前添加。
五、Pydantic v1版本知识点
项目因为SQLAlchemy版本、历史课程代码,使用v1版本,和v2语法有明显区别,极易踩坑。
1. Config内部类配置
class Config:
orm_mode = True
allow_population_by_field_name = True
-
orm_mode=True:旧版配置,等价v2的from_attributes=True。允许直接把ORM查询出来的数据库模型对象,直接给Pydantic模型解析。 -
allow_population_by_field_name=True:支持别名解析,接口Query(alias="xxx")依赖这个配置,实现后端下划线变量接收前端驼峰参数。
2. v1与v2方法对照表
| Pydantic v2 新写法 | Pydantic v1旧写法 |
|---|---|
model_validate(obj) |
from_orm(obj) |
model_dump() |
.dict() |
model_dump_json() |
.json() |
坑点:把v2的方法直接复制到v1环境,直接抛出
AttributeError,程序500报错。
3. Query参数别名
category_id: int = Query(..., alias="categoryId")
前端传递驼峰命名categoryId,后端变量使用下划线命名category_id,前后端命名风格兼容。
六、Redis缓存相关知识点
1. Windows Redis5.0版本适配坑
高版本redis-py客户端默认使用RESP3协议,连接Redis5.0服务端时,会发送HELLO 3握手命令,而Redis5不识别该命令,抛出异常。
解决:实例化Redis客户端时增加参数 protocol=2,强制使用RESP2协议。
2. 缓存存储思路
- 列表结果集缓存:像新闻分类这种小的全量列表,不一条数据一个key;把整个列表序列化为JSON字符串,保存为单个Redis key。减少Redis key数量。
-
单条实体缓存:新闻详情适合单条缓存,例如
news:detail:1,一条数据对应一个key。
3. 缓存一致性问题
- TTL过期失效:设置过期时间,时间到key自动删除,下次请求重新查询数据库写入缓存。
- 主动删除缓存(重要):如果程序执行新增、修改、删除数据库操作,此时Redis缓存还是旧数据,会出现数据库和缓存数据不一致。解决方案:完成数据库修改之后,手动delete对应的缓存key。下一次访问接口自动重新查库写入新缓存。
只靠过期时间,修改后立刻访问页面,用户会看到旧数据。
4. 缓存异常隐藏的坑
try:
await redis_client.setex(...)
except Exception as e:
print(f"设置缓存失败:{e}")
return False
仅print打印异常,不向上抛出异常。接口可以正常返回数据库数据,但是缓存完全没有生效,问题很难排查。
开发阶段建议:要么抛出异常,要么使用日志模块记录warning警告,方便定位缓存故障。
5. 详情页缓存业务问题
新闻详情每次访问浏览量+1,浏览量修改直接操作数据库。如果直接返回缓存快照,缓存里面保存的是旧的浏览量,页面上浏览数字不会实时刷新。
解决方案:
- 方案1:详情接口不开启缓存;
- 方案2:命中缓存拿到数据后,再从数据库读取实时浏览量覆盖缓存返回的旧浏览量。
七、标准开发完整流程
- 使用
APIRouter拆分路由文件,编写接口装饰器,接收请求参数; - 编写ORM模型类,映射数据库表;
- crud层封装数据库增删改查逻辑;
- 路由函数通过
Depends(get_db)注入AsyncSession会话对象; - 路由调用crud函数拿到数据;
- schemas Pydantic模型做数据序列化,组装统一格式响应返回前端;
- main.py注册全部路由,配置CORS等中间件,启动服务。