day01-FastAPI初识(补充day0.5)以及Tortoise-ORM
以及Tortoise-ORM)
# 路径参数与查询参数:
1.路径参数（Path Parameters）:
指在路由路径后跟上参数,形如@app.get("/items/{id}"),路径参数是URL路径中的动态可变部分,格式为{参数名}，用于标识「具体的资源」（如物品ID、用户ID）。例如：
/items/1：1是路径参数item_id的值/users/100：100是路径参数user_id的值
FastAPI会自动提取路径中的对应值，并传递给路由处理函数。
2.查询参数（Query Parameters):
查询参数是URL中?后面的键值对组合，格式为key1=value1&key2=value2，用于对资源进行「筛选、分页、排序」等辅助操作。例如：
/items?skip=0&limit=10：skip（跳过条数）、limit（查询条数）是查询参数/users?name=张三&age=20：name（姓名）、age（年龄）是查询参数
核心特点：
- 可选性：默认可省略，可设置默认值
- 辅助性：不用于标识唯一资源，仅用于过滤、分页等
- 灵活性：支持单个键对应多个值（如
/items?tags=fruit&tags=cheap）
3.区别:
对比维度 | 路径参数 | 查询参数 |
位置 | URL路径中（ | URL后缀（ |
必要性 | 必填（默认） | 可选（默认，可设置必填） |
核心用途 | 标识唯一资源（如ID、UID） | 筛选、分页、排序等辅助操作 |
配置工具 |
|
|
示例场景 |
|
|
为什么需要Query类型注解？
基础的查询参数写法（如skip: int = 0）只能实现「类型校验+默认值」，但实际开发中需要更精细的控制：
- 分页参数
limit必须≥1且≤50（范围校验） - 搜索关键词
q长度必须≤100（长度限制） - 筛选标签
tags支持多个值传入（多值参数） - 接口文档需要显示查询参数的详细描述（元数据配置）
Query类型注解正是为解决这些问题而生，它是FastAPI提供的「查询参数高级配置工具」，与Path注解同源（均基于Pydantic），功能互补。
# Tortoise-ORM
我们在django框架的业务功能中采用过ORM查询,与之对应的,FastAPI也有其对应的ORM,称为:Tortoise-ORM
ORM 全称是 Object-Relational Mapping（对象关系映射） 。它的核心思想是：用 Python 类来代表数据库中的表，用类的实例来代表表中的一行记录.没有ORM时,我们需要手写SQL来操作数据库,代码量大且易出错.使用ORM后,我们仅需要操作 Python 对象.
ORM 的优势：
- 面向对象：用 Python 代码替代 SQL 语句，更符合编程思维。
- 安全性：自动进行参数化查询，防止 SQL 注入攻击。
- 跨数据库：同一套代码可以无缝切换 SQLite、PostgreSQL、MySQL 等数据库。
- 关系管理：自动处理表与表之间的外键、多对多等关系。
- 可维护性：表结构集中定义在模型类中，修改和管理更方便。
为什么选择 Tortoise-ORM？
在 Python 异步 Web 开发中，传统的 ORM（如 SQLAlchemy 1.x 的同步模式）在执行数据库查询时会阻塞整个线程，这与 FastAPI 的异步非阻塞理念背道而驰。
Tortoise-ORM 的特点：
- 原生异步：基于
asyncio构建，所有数据库操作都是异步的，不会阻塞事件循环。 - Django 风格的 API：如果你用过 Django ORM，会发现语法非常熟悉，上手极快。
- 轻量级：专注于核心功能，没有冗余的抽象层，性能出色。
- 完整的关系支持：支持外键、一对一、多对多等所有常见关系类型。
- 内置 Pydantic 集成：可以通过
pydantic_model_creator自动从 Tortoise 模型生成 Pydantic 模型，无缝对接 FastAPI 的请求/响应校验。
同步 ORM vs 异步 ORM 对比
维度 | 同步 ORM（如 Django ORM） | 异步 ORM（Tortoise-ORM） |
执行方式 | 阻塞当前线程 | 非阻塞，协程挂起 |
并发能力 | 依赖多线程/多进程 | 单线程高并发 |
语法 |
|
|
适用框架 | Django、Flask | FastAPI、Sanic、aiohttp |
后端 FastAPI 核心开发流程
- 初始化 FastAPI 主应用实例，配置跨域中间件，解决前端网页跨域请求报错
- 定义 Tortoise ORM 数据模型，和 MySQL 数据表字段一一映射，设置主键、默认值、自动创建 / 更新时间
- 编写 Pydantic 数据校验模型：约束前端传入参数的类型、长度、必填项，实现请求数据自动校验
- 逐个编写业务接口（全部使用
async def异步函数，符合 Tortoise 异步 ORM 规范）- 登录接口：接收账号密码，模拟返回 Token 与用户信息（本次作业免后端鉴权校验）
- 查询列表接口：接收查询参数（状态筛选、关键词搜索、排序规则），ORM 链式条件查询返回数据
- 新增接口：接收表单参数，绑定固定用户 ID，ORM 插入单条数据
- 编辑接口：根据路径参数 ID 定位数据，执行字段局部更新
- 单字段状态修改接口：单独更新任务状态，附带业务逻辑（完成则写入完成时间，其他状态清空该字段）
- 删除接口：根据 ID 删除对应数据
- 数据统计接口：使用 ORM 计数聚合查询，统计各类任务数量
- 绑定 Tortoise ORM 与 FastAPI 项目，配置数据库连接地址，实现项目启动自动连接数据库
- 启动 uvicorn 服务，在浏览器
/docs接口文档页面手动调试后端所有接口，确保单后端功能正常