fastApi知识体系梳理03

知识点笔记

一、项目工程目录结构与各层职责

整个后端项目采用分层架构,不同文件夹承担不同职责,实现业务解耦,便于后期维护与迭代。

  1. crud/:专门封装数据库增、删、改、查逻辑。把SQLAlchemy的查询语句全部放在这一层,路由层只负责接收请求、调用crud函数,路由中不写原生查询代码,做到业务逻辑和数据库操作分离。
  2. models/:存放SQLAlchemy ORM数据库模型。模型类和MySQL数据表一一映射,定义表名、字段、数据类型、约束、外键、索引,相当于Python代码描述数据库表结构。
  3. routers/:路由层,按照业务模块拆分接口文件。定义接口访问地址、请求参数接收,接收前端请求,调用crud完成业务,组装返回结果。不要把所有接口全部写在main.py。
  4. schemas/:Pydantic数据验证模型。负责请求数据校验、响应数据序列化;做字段类型校验、别名映射、ORM对象转字典,约束接口出入参格式。
  5. utils/:通用工具函数目录,存放多个模块可以复用的工具代码。
  6. config/:项目配置目录,存放数据库连接配置、Redis缓存配置等各类环境配置。
  7. main.py:项目入口文件。只做服务初始化工作:导入路由、注册路由、添加中间件、启动FastAPI应用,不写业务接口代码。

项目配套物料说明

  1. 前端Vue项目代码:负责页面渲染、用户交互,通过网络请求调用后端提供的接口。
  2. 接口规范文档:前后端协作标准。定义每个接口的请求方式、请求参数、参数类型、返回数据格式、错误码,前后端按照同一套文档开发。
  3. 数据库SQL文件:包含建表语句、初始化测试数据;直接导入MySQL,不用手动建表造数据。

二、模块化路由 APIRouter

1. 概念

模块化路由就是将不同业务模块的接口拆分到独立的 .py 文件中,再在入口文件 main.py 将多个路由统一注册挂载到FastAPI主app实例上。避免所有接口堆积在main.py,造成文件臃肿。

2. 使用优势

  1. 结构清晰:接口按业务模块归类,新闻、用户、收藏各自独立文件。
  2. 便于维护:修改某个模块接口,只需要打开对应路由文件,不影响其他模块代码。
  3. 文档分组:通过tags参数,自动在接口文档页面对接口进行分组展示。

3. 核心对象与参数

router = APIRouter(prefix="/api/news", tags=["news"])
  • prefix:统一路由前缀,该文件下所有接口自动拼接该路径,不需要每个接口重复写 /api/news。
  • tags:接口文档分组标签,字符串列表。

接口定义完成之后,在main.py中完成注册:

app.include_router(news.router)

4. 完整使用流程

  1. 在routers下新建模块py文件;
  2. 导入APIRouter,创建router实例,指定prefix、tags;
  3. 使用@router.get() / @router.post()装饰器编写接口函数;
  4. main.py导入该router对象,调用app.include_router()完成挂载注册。

三、SQLAlchemy 异步ORM

1. 需要安装依赖包

  • sqlalchemy[asyncio]:ORM框架核心,提供异步支持;
  • aiomysql:MySQL异步驱动,异步引擎需要该驱动和数据库通信。

注意:同步pymysql不能配合异步引擎使用。

2. 核心组件

  1. create_async_engine() 创建异步引擎
    引擎是程序和数据库之间的通信核心。
  • ASYNC_DATABASE_URL:数据库连接字符串,格式:mysql+aiomysql://账号:密码@host:端口/库名?charset=utf8mb4
  • echo=True:开发调试用,控制台打印程序执行的完整SQL语句;生产环境必须关闭,会损耗性能。
  • pool_size:连接池常驻连接数量,程序会维持若干连接不释放,减少频繁创建连接开销。
  • max_overflow:连接池满了之后,允许额外创建的临时连接最大数量。
  1. async_sessionmaker 异步会话工厂
    用来生成数据库会话对象。
  • bind=async_engine:绑定前面创建好的异步引擎;
  • class_=AsyncSession:指定使用异步会话;
  • expire_on_commit=False:执行commit提交后,ORM对象属性不会失效。如果设置True,commit之后访问对象字段会重新向数据库发起查询,开发场景一般设置False。
  1. 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()

逻辑拆解:

  1. yield session:将会话交给接口函数使用;
  2. 接口内全部逻辑正常跑完,执行await session.commit()提交事务,保存改动;
  3. 如果出现异常,执行await session.rollback()事务回滚,放弃本次所有修改,并且把异常继续向外抛出;
  4. finally块一定会执行,关闭会话释放数据库连接还给连接池。

接口中使用:async def func(db:AsyncSession = Depends(get_db))

4. ORM模型类编写规范

  1. 定义基类:class Base(DeclarativeBase): pass,所有数据表模型类都继承Base。
  2. __tablename__ = "表名":指定该模型映射MySQL哪一张数据表。
  3. 字段使用 Mapped[类型] + mapped_column() 定义。可以设置主键、自增、非空、外键、默认值、字段注释。
  4. __table_args__:配置表额外参数,用于创建数据库索引。索引可以大幅提升where条件查询的速度。
__table_args__ = (
    Index('索引名称','字段名'),
)

5. ORM常用操作语法

  1. 查询:select(模型类),配合session执行得到数据。
  2. 分页查询
    • offset偏移量计算公式:offset = (page -1) * page_size
    • 链式调用:select(News).offset(offset).limit(page_size)
    • hasMore(是否还有下一页)判断逻辑:offset + 当前页返回条目数 < 总记录数,条件成立代表存在下一页。
  3. 排序:.order_by(News.字段.desc());.desc()代表降序;不写.desc()默认升序。
  4. 聚合统计总数:使用func.count()做数量统计。
  5. 更新数据:
stmt = update(News).where(条件).values(要修改的字段=值)
result = await db.execute(stmt)

result.rowcount可以获取本次语句实际影响的数据行数,可以用来判断条件是否匹配到数据。

  1. 新增数据:db.add(模型实例对象),commit之后写入数据库。
  2. 删除数据:delete(模型).where(删除条件)。

6. PyCharm导入SQL脚本操作

打开Database数据库插件,连接MySQL;右键数据库连接 → SQL Scripts → Run SQL Script,选择本地.sql文件执行,完成建表与初始化数据。

四、CORS跨域资源共享

1. 什么是跨域

跨域是浏览器的安全保护策略。浏览器会拦截前端JS发起的非同源请求。

同源三要素必须全部相同,才算同源:

  1. 协议(http / https)
  2. IP / 域名
  3. 端口号

例子:前端地址[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中添加中间件,告诉浏览器允许哪些前端源访问后端接口。

关键参数:

  1. allow_origins:允许访问后端的前端源地址列表。开发可以写["*"]代表全部放行;生产环境禁止写[""],要写具体前端域名*。
  2. allow_credentials=True:允许请求携带Cookie、身份凭证。
  3. allow_methods=["*"]:允许所有HTTP请求方式(GET、POST、PUT、DELETE等)。
  4. allow_headers=["*"]:允许所有请求头。

注意:中间件必须在注册路由之前添加。

五、Pydantic v1版本知识点

项目因为SQLAlchemy版本、历史课程代码,使用v1版本,和v2语法有明显区别,极易踩坑。

1. Config内部类配置

class Config:
    orm_mode = True
    allow_population_by_field_name = True
  1. orm_mode=True:旧版配置,等价v2的from_attributes=True。允许直接把ORM查询出来的数据库模型对象,直接给Pydantic模型解析。
  2. 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. 缓存存储思路

  1. 列表结果集缓存:像新闻分类这种小的全量列表,不一条数据一个key;把整个列表序列化为JSON字符串,保存为单个Redis key。减少Redis key数量。
  2. 单条实体缓存:新闻详情适合单条缓存,例如news:detail:1,一条数据对应一个key。

3. 缓存一致性问题

  1. TTL过期失效:设置过期时间,时间到key自动删除,下次请求重新查询数据库写入缓存。
  2. 主动删除缓存(重要):如果程序执行新增、修改、删除数据库操作,此时Redis缓存还是旧数据,会出现数据库和缓存数据不一致。解决方案:完成数据库修改之后,手动delete对应的缓存key。下一次访问接口自动重新查库写入新缓存。

只靠过期时间,修改后立刻访问页面,用户会看到旧数据。

4. 缓存异常隐藏的坑

try:
    await redis_client.setex(...)
except Exception as e:
    print(f"设置缓存失败:{e}")
    return False

仅print打印异常,不向上抛出异常。接口可以正常返回数据库数据,但是缓存完全没有生效,问题很难排查。
开发阶段建议:要么抛出异常,要么使用日志模块记录warning警告,方便定位缓存故障。

5. 详情页缓存业务问题

新闻详情每次访问浏览量+1,浏览量修改直接操作数据库。如果直接返回缓存快照,缓存里面保存的是旧的浏览量,页面上浏览数字不会实时刷新。
解决方案:

  • 方案1:详情接口不开启缓存;
  • 方案2:命中缓存拿到数据后,再从数据库读取实时浏览量覆盖缓存返回的旧浏览量。

七、标准开发完整流程

  1. 使用APIRouter拆分路由文件,编写接口装饰器,接收请求参数;
  2. 编写ORM模型类,映射数据库表;
  3. crud层封装数据库增删改查逻辑;
  4. 路由函数通过Depends(get_db)注入AsyncSession会话对象;
  5. 路由调用crud函数拿到数据;
  6. schemas Pydantic模型做数据序列化,组装统一格式响应返回前端;
  7. main.py注册全部路由,配置CORS等中间件,启动服务。
©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成,浏览时请结合常识与多方信息审慎甄别。
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

友情链接更多精彩内容