FastAPI实战：基于 SQLAlchemy的后端接口开发流程

目录

构建project整体架构

[1. 模块化路由（第一步：拆分与注册）](#1. 模块化路由（第一步：拆分与注册）)

[2. 定义模型类（第二步：数据结构设计）](#2. 定义模型类（第二步：数据结构设计）)

[3. 数据库 CRUD（第三步：数据操作实现）](#3. 数据库 CRUD（第三步：数据操作实现）)

[4. 路由调用逻辑（第四步：接口逻辑组装）](#4. 路由调用逻辑（第四步：接口逻辑组装）)

[5. 跨域资源共享CORS（核心定位：浏览器的"安全门卫+合法通行证"）](#5. 跨域资源共享CORS（核心定位：浏览器的“安全门卫+合法通行证”）)

总结

---

SQLAlchemy 是 Python 生态中最主流的 ORM（对象关系映射）框架，而 FastAPI 是高性能的异步 Web 框架；二者结合是 FastAPI 实战开发中数据库操作的标准方案------FastAPI 负责处理 HTTP 请求 / 响应、依赖注入、接口文档生成，SQLAlchemy（异步版）负责数据库的异步交互（连接管理、数据映射、CRUD 操作），既发挥 FastAPI 的异步高性能优势，又利用 SQLAlchemy 成熟的 ORM 能力简化数据库操作。

构建project整体架构

|-----------|-----------------|-----------------------------------|----------------------|
| 层级 | 目录 | 核心职责 | 技术栈 |
| 1. 路由层 | routers/ | 定义 API 接口，处理 HTTP 请求和响应 | FastAPI APIRouter |
| 2. 数据校验层 | schemas/ | 定义 Pydantic 模型，用于请求 / 响应数据的校验和序列化 | Pydantic |
| 3. 业务逻辑层 | crud/ | 封装数据库的增删改查（CRUD）操作，实现业务逻辑 | SQLAlchemy Async ORM |
| 4. 数据模型层 | models/ | 定义 SQLAlchemy ORM 模型，映射数据库表结构 | SQLAlchemy |
| 5. 工具与配置层 | utils/, config/ | 提供通用工具函数和项目配置 | Python 标准库 / 第三方库 |
| 6. 入口文件 | main.py | 项目启动入口，初始化 FastAPI 应用，注册路由 | FastAPI |

基于 SQLAlchemy的后端接口开发流程：

1.模块化路由（routers）：按业务拆分路由，注册到主应用，遵循接口规范。

2.定义模型类（models）：设计 ORM 模型映射数据库，设计 Pydantic 模型校验数据。

3.实现业务逻辑（crud）：基于异步 ORM 实现增删改查，封装数据操作。

4.组装路由逻辑（routers）：注入数据库依赖，调用 CRUD，返回规范响应。

这个流程的核心是分层解耦，将路由、数据模型、数据操作和业务逻辑清晰分离，既保证了代码的可维护性，又充分利用了 FastAPI 和 SQLAlchemy 的强大特性，实现高效、可靠的接口开发。

**案例：**获取新闻分类内容【127.0.0.1：8000/docs#/news/get_categories(参数skip=0,limit-100)】

1. 模块化路由（第一步：拆分与注册）

这是工程化的起点，核心是按业务拆分路由，避免代码臃肿：

定义 APIRouter 实例 ：在独立的路由文件（如 routers/news.py）中创建 APIRouter，将同业务的接口（如新闻分类、新闻列表）封装在一起。

注册路由 ：在主文件 main.py 中通过 include_router() 将子路由注册到 FastAPI 实例，实现路由的模块化管理。

参照接口规范：所有接口的路径、HTTP 方法、参数定义都严格遵循预先设计的接口文档，确保前后端对齐。

案例：1. 通过装饰器@router.get("/categories")获取新闻分类的列表；

2. 定义模型类（第二步：数据结构设计）

这是数据交互的核心，分为两层模型：

ORM 模型（数据库层）：

定义继承自 DeclarativeBase 的基类，封装公共字段（如创建时间、更新时间）。

定义业务模型（如 Category、News），通过 tablename 映射到数据库表，字段类型和约束与数据库表结构一一对应。

1. 在配置文件中创建数据库联接：数据库URL联接，创建异步引擎，创建会话工程AsyncSessionlocal，核心是创建了get_db这个函数，用于获取数据库的会话。 数据库配置（核心文件：database.py）

   from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
   from sqlalchemy.orm import DeclarativeBase

   1. 定义异步数据库连接 URL

   ASYNC_DATABASE_URL = "mysql+aiomysql://root:密码@localhost:3306/数据库名?charset=utf8"

   2. 创建异步引擎（管理连接池）

   async_engine = create_async_engine(
   ASYNC_DATABASE_URL,
   echo=True, # 开启 SQL 日志（调试用）
   pool_size=10, # 连接池常驻连接数
   max_overflow=20 # 高并发额外连接数
   )

   3. 创建异步会话工厂（生成数据库会话）

   AsyncSessionLocal = async_sessionmaker(
   bind=async_engine,
   class_=AsyncSession,
   expire_on_commit=False # 提交后会话不过期
   )

   4. 定义 ORM 模型基类

   class Base(DeclarativeBase):
   pass

   5. 定义数据库会话依赖项（供路由注入）

   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() # 关闭会话释放连接

2. 定义 ORM 模型（如 models.py）：定义模型类Category(Base)，参照数据库news_category的字段

Pydantic 模型（请求 / 响应层）：

定义请求模型（如 CategoryCreate）和响应模型（如 CategoryResponse），用于数据校验、过滤和结构化输出。

3. 数据库 CRUD（第三步：数据操作实现）

基于 SQLAlchemy 异步 ORM 实现完整的数据操作：

查询（Read） ：使用 select(模型类) 构建查询语句，通过 where() 添加条件，scalars() 提取结果，支持分页、聚合等复杂查询。

新增（Create） ：将 Pydantic 模型转换为 ORM 对象，通过 db.add() 添加到事务，依赖项自动提交。

更新（Update）：先通过主键查询对象，校验存在性后修改属性，事务提交后生效。

删除（Delete） ：先查询对象，校验存在性后调用 await db.delete()，事务提交后删除记录。

查询案例：在CRUD的目录中构建new.py文件，实现查询select（限制在100条）并返回结果。

4. 路由调用逻辑（第四步：接口逻辑组装）

将前面三步的成果串联起来，形成完整的接口：

依赖注入 ：通过 Depends(get_database) 注入数据库会话，统一管理事务的提交、回滚和连接释放。

调用业务逻辑：在路由函数中调用 CRUD 函数，处理请求参数，执行业务逻辑（如数据校验、权限判断）。

返回响应结果：将 ORM 模型或处理后的数据，通过 Pydantic 响应模型返回，确保接口输出规范、安全。

案例：在@router.get("/categories")函数中，增加从数据库查询到的类categories(在CRUD的目录中构建new.py文件)，同时修改返回值的data:categories

******5.**跨域资源共享CORS（核心定位：浏览器的"安全门卫+合法通行证"）

一、CORS的全称是**跨域资源共享（Cross-Origin Resource Sharing）**，它不是"限制"而是"规范"------本质是浏览器的一套安全机制，解决的是"不同网站之间能不能合法共享数据"的问题。

我们先搞懂它的"前置背景"：

浏览器有个叫**同源策略**的默认安全规则，"同源"指的是两个网站的「协议（http/https）、域名、端口」完全一致（比如 `http://localhost:3000` 和 `http://localhost:8000` 因为端口不同，就不算同源）。

这个规则像小区"非住户禁止入内"的规定，默认不允许一个网站直接访问另一个不同源网站的数据，目的是防止恶意网站偷取用户数据。

而CORS就是给这个"严格规则"开的**合法后门**：它让后端服务器能主动告诉浏览器"我允许哪些前端网站来访问我的数据"，浏览器收到服务器的"许可指令"后，就会放行这些跨域请求，既保证安全，又能让正常的跨域需求（比如前端和后端部署在不同地址）得以实现。

二、CORS的核心功能：精准控制跨域访问权限

CORS的核心作用是让后端服务器"精细化管理"跨域访问权限，而非简单的"允许/禁止"，结合之前的FastAPI代码示例，这些权限可以拆解为：

1. **控制"谁能访问"（allow_origins）**

• 比如配置 `allow_origins=["http://localhost:3000"]`，就只允许本地3000端口的前端访问；

• 若配置 `allow_origins=["*"]` 则允许所有前端访问（⚠️ 生产环境禁用，相当于"大门敞开"，有安全风险）。

2. **控制"能不能带身份凭证"（allow_credentials）**

• 设为 `True` 时，前端请求可以携带Cookie、Token等登录凭证（比如用户登录后，前端能带着登录信息访问后端）；

• 设为 `False` 则禁止携带，避免凭证泄露。

3. **控制"能用什么方式访问"（allow_methods）**

• 比如限制只允许GET、POST请求，或用 `["*"]` 允许所有HTTP方法（GET/POST/PUT/DELETE等）。

4. **控制"能带什么信息访问"（allow_headers）**

• 比如允许前端携带自定义请求头（如认证头、数据格式头），`["*"]` 则允许所有请求头。

三、形象化理解

把整个流程比作"前端（访客）去后端（朋友家）串门"：

• 浏览器是小区保安，同源策略是"非本小区住户禁止入内"；

• CORS是朋友（后端）提前给保安的"通行证规则"：指定"谁能进、能不能带身份证（凭证）、走哪个门（请求方法）、能带什么行李（请求头）"；

• 保安（浏览器）按这个规则检查，符合条件就放行，不符合就拒绝，既保证安全，又不影响正常串门。

总结

1. CORS的核心是**解决浏览器同源策略导致的跨域请求限制**，是前端和后端跨域通信的"合法通道"；

2. 它的核心功能是让后端**精细化配置跨域权限**（允许哪些前端、哪些请求方式、是否携带凭证等）；

3. 配置时需注意安全：生产环境禁止用 `allow_origins=["*"]`，应指定具体的可信前端域名，避免恶意访问。

总结

FastAPI 整合 SQLAlchemy 异步版是一套「高性能 + 高便捷性」的数据库解决方案：

• 核心是异步引擎 + 异步会话 + 依赖注入，实现数据库连接的高效管理；
• 优势是ORM 简化操作 + 异步适配高并发 + 生态完善，是 FastAPI 实战开发中处理数据库的首选方案；
• 核心流程：配置数据库 → 定义 ORM 模型 → 实现 CRUD → 路由注入会话 → 接口调用。