FastAPI 的ORM

一、ORM 介绍

ORM（Object-Relational Mapping，对象关系映射）是一种核心编程技术，用于打通面向对象编程语言与关系型数据库之间的壁垒。其核心价值在于：让开发者无需直接编写复杂 SQL 语句，只需通过操作「对象」，就能完成数据库的增删改查（CRUD）操作，大幅降低数据库开发门槛。

1.1 ORM 核心特点

对象与数据库表的映射：ORM 框架会将数据库中的每一张表，映射为编程语言中的一个类；表中的每一行数据，对应这个类的一个实例对象；表的每一列字段，对应对象的一个属性，实现「数据结构化」与「对象化」的统一。
简化数据库操作：开发者无需手动编写 SQL 语句，只需使用面向对象的常规方法（如创建对象、调用对象方法），即可完成数据库操作（如新增数据对应创建对象、查询数据对应获取对象列表）。
跨数据库兼容：主流 ORM 框架均支持多种关系型数据库（如 MySQL、PostgreSQL、SQLite 等），通过统一的 API 封装，开发者无需修改核心代码，即可实现数据库的切换，降低项目迁移成本。
提高开发效率：ORM 会自动生成标准 SQL 语句、优化查询逻辑，同时减少重复的数据库操作代码（如连接数据库、关闭连接），让开发者专注于业务逻辑，提升开发速度和代码质量。

1.2 ORM 工作原理

ORM 框架内部会定义一个「映射层」，这个映射层负责将开发者定义的「数据类」与数据库中的「表」进行关联（配置映射规则）。
开发者通过 ORM 提供的 API 操作对象（如创建对象、修改对象属性、删除对象），ORM 框架会自动将这些「对象操作」翻译成对应的 SQL 语句。
ORM 框架负责执行 SQL 语句，与数据库建立交互，将数据库返回的结果（如查询到的表数据），反向转换为开发者可直接操作的对象，返回给业务逻辑层。

1.3 ORM 优缺点

优点

代码可读性、可维护性大幅提升：对象化的操作方式更贴合编程语言的开发习惯，避免了复杂 SQL 语句的堆砌。
降低错误率：减少直接编写 SQL 带来的语法错误、逻辑错误，ORM 会自动校验数据类型、优化 SQL 语法。
支持复杂关系映射：轻松处理数据库表之间的关联关系（如一对一、一对多、多对多），无需手动编写关联查询 SQL。
简化数据库迁移：多数 ORM 框架自带数据迁移工具，支持表结构的新增、修改、删除，无需手动编写 DDL 语句。

缺点

性能略有损耗：由于多了一层「映射层」的转换，对于高频、高并发的数据库操作，性能会略低于原生 SQL（损耗通常可忽略，除非是极致性能场景）。
复杂查询支持有限：对于一些极度复杂的 SQL 查询（如多表嵌套关联、复杂聚合统计），ORM 生成的 SQL 可能不够高效，此时仍需手动编写原生 SQL 补充。
学习成本：需要学习 ORM 框架的映射规则、API 用法，尤其是复杂场景下的配置和优化。

二、FastAPI 常用 ORM 工具介绍

FastAPI 本身无官方 ORM 框架，开发者可根据项目需求，自由选择适配的 ORM 工具。以下是 FastAPI 生态中最常用、最适配的 3 种 ORM 工具，各有侧重，可按需选型。

2.1 主流 ORM 工具对比

SQLAlchemy（同步/异步）
- 地位：≈80% 企业级 FastAPI 项目首选 ORM 工具，生态最成熟、功能最完备。
- 特点：支持同步和异步两种模式，支持复杂查询、事务管理、数据迁移，社区活跃，文档完善，可适配各种规模的项目（从小型接口到大型微服务）。
- 适配场景：传统企业项目、混合同步/异步项目、对稳定性和功能完整性要求高的项目。
Tortoise-ORM（异步）
- 地位：FastAPI 异步项目的热门选择，语法简洁，上手成本低。
- 特点：原生支持异步，语法与 Django ORM 高度相似，学习成本低；无缝适配 FastAPI 的异步特性，支持自动生成表结构、复杂关系映射，集成简便。
- 适配场景：全异步 FastAPI 项目、小型微服务、快速开发的demo项目、熟悉 Django ORM 语法的开发者。
GINO（异步）
- 地位：轻量级异步 ORM，基于 SQLAlchemy Core 进行封装，兼顾性能和简洁性。
- 特点：原生异步，体积小、性能优，API 简洁，适合对性能要求较高的异步 API 项目；但功能相对精简，复杂场景需额外扩展。
- 适配场景：高性能异步微服务、轻量级接口项目，对 ORM 体积和性能有要求的场景。

2.2 选型建议（重点）

传统企业项目、中大型项目、需要兼容同步/异步场景 → SQLAlchemy（成熟稳定，抗风险能力强）。
全异步 FastAPI 项目、小型微服务、快速开发场景、熟悉 Django ORM → Tortoise-ORM（上手快，集成便捷）。
高性能异步场景、轻量级项目 → GINO（轻量高效，无多余冗余）。

提示：本文档后续重点讲解 Tortoise-ORM 的配置与使用，因其最适配 FastAPI 异步特性，且上手简单，适合新手入门。

三、Tortoise-ORM 完整配置

Tortoise-ORM 是一款原生异步 ORM 框架，设计初衷就是为了适配异步 Python 项目（如 FastAPI），其语法简洁、配置简单，且支持自动生成表结构、数据迁移，是 FastAPI 新手的首选 ORM 工具。

3.1 为什么选择 Tortoise-ORM（适配 FastAPI）

原生异步支持：与 FastAPI 的异步架构完美契合，避免异步项目中使用同步 ORM 带来的性能瓶颈。
语法简单易用：模型定义、数据库操作语法与 Django ORM 高度相似，学习成本低，新手可快速上手。
完善的关系支持：轻松实现一对一、一对多、多对多等表关联关系，无需手动编写关联 SQL。
自动生成表结构：开发环境可自动根据模型定义生成数据库表，无需手动编写 DDL 语句。
集成便捷：提供专门适配 FastAPI 的工具函数，一行代码即可完成 Tortoise-ORM 与 FastAPI 的注册集成。
完善的生态：配套数据迁移工具（Aerich），支持表结构的迁移、回滚，适配生产环境。

3.2 环境配置（安装依赖）

首先安装 Tortoise-ORM 及相关依赖，指定固定版本可避免兼容性问题（适配 FastAPI 0.115.12 版本），终端执行以下命令：

pip install tortoise-orm==0.25.0 aerich==0.9.0 aiomysql==0.2.0 tomlkit==0.13.2

依赖说明

tortoise-orm==0.25.0：核心 ORM 框架，提供对象映射、数据库操作 API。
aerich==0.9.0：Tortoise-ORM 配套的数据迁移工具，用于表结构迁移、回滚（类似 Django 的 makemigrations/migrate）。
aiomysql==0.2.0：MySQL 异步驱动，若使用 MySQL 数据库需安装；若使用 SQLite/PostgreSQL，可替换为对应异步驱动（如 aiosqlite、asyncpg）。
tomlkit==0.13.2：用于解析配置文件，Aerich 迁移工具依赖此包。

3.3 配置数据库连接

Tortoise-ORM 需要通过一个配置字典，定义数据库连接信息、应用模块、连接池等参数。通常将配置放在项目的配置文件中（如 app/core/config.py），便于统一管理和修改。

from typing import Dict

# Tortoise-ORM 核心配置（统一管理，可根据环境切换）
TORTOISE_ORM: Dict = {
    "connections": {
        # 1. 开发环境：使用 SQLite 数据库（无需启动数据库服务，文件存储，便捷高效）
        "default": "sqlite://db.sqlite3",  # 数据库文件存储在项目根目录，命名为 db.sqlite3
        
        # 2. 生产环境：MySQL 数据库（需提前启动 MySQL 服务，替换以下参数）
        # "default": "mysql://user:password@localhost:3306/dbname",
        # 说明：mysql://用户名:密码@数据库地址:端口号/数据库名称
        
        # 3. 生产环境：PostgreSQL 数据库（替换为对应参数）
        # "default": "postgres://user:password@localhost:5432/dbname",
    },
    "apps": {
        # 定义应用模块（可理解为「模型集合」，一个 app 对应一组模型）
        "models": {
            "models": [
                "app.models",  # 自定义模型所在的模块路径（如 app/models.py 中的所有模型）
                "aerich.models"  # Aerich 迁移工具的内置模型（必须添加，否则迁移失败）
            ],
            "default_connection": "default",  # 指定该应用模块使用的默认数据库连接（对应上面的 connections 中的 key）
        }
    },
    # 4. 数据库连接池配置（推荐配置，优化高并发场景下的数据库连接管理）
    "use_tz": False,  # 是否启用时区支持（开发环境可关闭，生产环境建议开启）
    "timezone": "UTC",  # 默认时区（若 use_tz=True，需指定时区，如 "Asia/Shanghai"）
    "db_pool": {
        "max_size": 10,  # 连接池最大连接数（根据并发量调整，不宜过大）
        "min_size": 1,   # 连接池最小连接数（保持至少1个空闲连接，避免频繁创建连接）
        "idle_timeout": 30  # 空闲连接超时时间（秒），超时后自动关闭连接，释放资源
    }
}

3.4 配置参数详细说明

connections（数据库连接配置）

用于定义一个或多个数据库连接，key 为连接名称（如 "default"），value 为连接字符串（不同数据库格式不同），支持多数据库连接（需在 apps 中指定对应连接）。

SQLite（开发首选）：sqlite://数据库文件名，无需用户名、密码，文件存储在项目根目录，无需启动数据库服务。
MySQL（生产常用）：mysql://user:password@host:port/dbname，需替换 user（用户名）、password（密码）、host（数据库地址，本地为 localhost）、port（端口，默认 3306）、dbname（数据库名称，需提前创建）。
PostgreSQL（生产常用）：postgres://user:password@host:port/dbname，参数含义同 MySQL，默认端口 5432。

apps（应用模块配置）

Tortoise-ORM 采用「应用模块」的概念，将一组相关的模型归为一个 app，便于管理。每个 app 需指定对应的模型路径和数据库连接。

"models"：app 名称（可自定义，如 "user_app"、"goods_app"），建议与业务模块对应。
"models" 列表：指定该 app 下的模型所在路径，支持多个模块路径，需包含：
- 自定义模型路径（如 "app.models"，表示 app 文件夹下的 models.py 文件中的所有模型）。
- "aerich.models"：必须添加，Aerich 迁移工具的内置模型，用于记录迁移历史，缺失会导致迁移失败。
"default_connection"：指定该 app 的模型默认使用的数据库连接（对应 connections 中的 key，如 "default"）。

其他配置

use_tz：是否启用时区支持，生产环境建议设置为 True，确保时间字段的一致性。
timezone：时区字符串，若 use_tz=True，需指定正确时区（如 "Asia/Shanghai" 表示中国标准时间），默认 UTC。
db_pool：数据库连接池配置，优化数据库连接的创建和释放，避免高并发场景下的连接耗尽问题，建议根据项目并发量调整 max_size。

3.5 初始化 FastAPI 应用（集成 Tortoise-ORM）

配置完成后，需在 FastAPI 应用启动时，注册 Tortoise-ORM，将配置与 FastAPI 应用绑定，实现 ORM 与框架的无缝集成。

创建项目主文件（如 main.py），写入以下代码：

from fastapi import FastAPI
# 导入 Tortoise-ORM 适配 FastAPI 的注册函数
from tortoise.contrib.fastapi import register_tortoise
# 从配置文件导入 Tortoise-ORM 配置字典
from app.core.config import TORTOISE_ORM

# 创建 FastAPI 应用实例
app = FastAPI(
    title="FastAPI with Tortoise-ORM",  # 项目标题
    description="FastAPI 集成 Tortoise-ORM 完整示例",  # 项目描述
    version="1.0.0"  # 项目版本
)

# 核心步骤：注册 Tortoise-ORM 到 FastAPI 应用
register_tortoise(
    app,  # 传入 FastAPI 应用实例
    config=TORTOISE_ORM,  # 传入 Tortoise-ORM 配置字典
    generate_schemas=True,  # 开发环境：自动根据模型生成数据库表结构（生产环境建议关闭，用迁移工具生成）
    add_exception_handlers=True,  # 添加 Tortoise-ORM 默认异常处理器（捕获数据库操作异常，返回友好响应）
)

# 测试接口：验证应用启动成功
@app.get("/")
async def root():
    return {"message": "Welcome to FastAPI with Tortoise-ORM! 🚀"}

# 程序入口：直接运行脚本启动服务（适配 uvicorn 0.34.2 版本）
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        app="main:app",
        host="127.0.0.1",  # 本地地址
        port=8000,  # 端口号
        reload=True  # 开发环境热重载，修改代码自动重启服务（生产环境关闭）
    )

3.6 关键配置说明（避坑重点）

generate_schemas=True：仅用于开发环境，启动项目时会自动根据模型定义生成数据库表结构，无需手动操作；生产环境必须关闭（设为 False），避免误删、误改表结构，生产环境需使用 Aerich 迁移工具管理表结构。
add_exception_handlers=True：开启后，Tortoise-ORM 会自动捕获数据库操作异常（如连接失败、数据校验失败），并返回符合 FastAPI 规范的错误响应（如 500 服务器错误、422 数据校验错误），无需手动捕获异常。
配置路径问题：确保 from app.core.config import TORTOISE_ORM 中的路径正确，若项目结构不同（如无 app/core 目录），需修改为实际的配置文件路径（如直接在 main.py 中定义 TORTOISE_ORM 配置）。
数据库驱动：若使用 MySQL 数据库，需确保已安装 aiomysql；若使用 PostgreSQL，需安装 asyncpg；若使用 SQLite，无需额外安装驱动（Tortoise-ORM 自带）。

3.7 启动验证

确保配置文件路径正确、依赖已安装；
终端切换到项目根目录，执行 python main.py（或手动执行 uvicorn main:app --reload）；
启动成功后，访问http://127.0.0.1:8000，若返回 {"message": "Welcome to FastAPI with Tortoise-ORM! 🚀"}，说明 FastAPI 与 Tortoise-ORM 集成成功；
查看项目根目录，会自动生成 db.sqlite3 文件（SQLite 数据库），说明数据库连接配置生效。

posted @ 2026-02-04 15:35 向闲而过阅读(0) 评论(0) 收藏举报

刷新页面返回顶部