0文章目录一、 FastAPI 的 ORM 生态ORM介绍工作原理优点缺点ORM工具介绍**选型建议**二、Tortoise-ORM配置为什么选择 Tortoise-ORM环境配置配置数据库连接配置说明初始化 FastAPI 应用三、Aerich 迁移工具的使用Aerich 初始化生成和应用迁移模型案例四、Tortoise-ORM 的模型定义模型定义基础基本模型示例说明核心字段类型详解字段参数详解模型元数据Meta 类持续更新中✒️总结一、 FastAPI 的 ORM 生态ORM介绍ORMObject-Relational Mapping对象关系映射是一种编程技术用于在面向对象编程语言和关系型数据库之间建立映射。它允许开发者通过操作对象的方式来与数据库进行交互而无需直接编写复杂的 SQL 语句。主要特点包括对象与数据库表的映射ORM 将数据库中的表映射为编程语言中的类每一行数据对应一个对象表的列对应对象的属性简化数据库操作开发者可以使用面向对象的方法如创建、查询、更新、删除对象来操作数据库而无需手动编写 SQL跨数据库兼容ORM 通常支持多种数据库如 MySQL、PostgreSQL、SQLite通过统一的接口减少数据库切换的成本提高开发效率通过自动化 SQL 生成和查询优化减少重复代码提升开发速度工作原理ORM 框架定义了一个映射层将类和数据库表关联起来开发者通过 ORM 的 API 操作对象ORM 自动将操作翻译成 SQL 语句执行数据库操作并返回结果优点提高代码可读性和维护性减少直接 SQL 操作带来的错误。支持复杂查询和关系如一对多、多对多缺点性能可能略低于原生 SQL因抽象层开销对于非常复杂的查询可能需要直接编写 SQLORM工具介绍SQLAlchemy同步/异步≈80% 企业项目首选功能完备、社区成熟支持复杂查询和事务管理。Tortoise异步语法类似 Django ORM适合异步优先项目集成简便GINO异步轻量级基于 SQLAlchemy Core 的异步扩展适合高性能 API选型建议传统企业项目 →SQLAlchemy成熟稳定全异步微服务 →Tortoise-ORM或GINO提示FastAPI无官方 ORM二、Tortoise-ORM配置为什么选择 Tortoise-ORM异步支持与 FastAPI 无缝集成简单易用的模型定义类似 Django ORM支持复杂关系一对一、一对多、多对多自动生成表结构适合快速开发环境配置安装必要的依赖pipinstalltortoise-orm0.25.0aerich0.9.0aiomysql0.2.0tomlkit0.13.2配置数据库连接Tortoise-ORM 需要一个配置字典来定义数据库连接信息通常存储在 settings.py 或类似的配置文件中。fromtypingimportDict# Tortoise-ORM 配置TORTOISE_ORM:Dict{connections:{# 开发环境使用 SQLite基于文件无需服务器default:sqlite://db.sqlite3,# 生产环境示例PostgreSQL# default: postgres://user:passwordlocalhost:5432/dbname,# 生产环境示例MySQL# default: mysql://user:passwordlocalhost:3306/dbname,},apps:{models:{models:[app.models,aerich.models],# 模型模块和 Aerich 迁移模型default_connection:default,}},# 连接池配置推荐use_tz:False,# 是否使用时区timezone:UTC,# 默认时区db_pool:{max_size:10,# 最大连接数min_size:1,# 最小连接数idle_timeout:30# 空闲连接超时秒}}配置说明connections定义数据库连接字符串SQLitesqlite://db.sqlite3开发环境文件存储在项目根目录PostgreSQLpostgres://user:passwordhost:port/dbname生产环境MySQLmysql://user:passwordhost:port/dbname生产环境apps定义应用模块models 列表包含模型文件路径和 Aerich 的迁移模型db_pool连接池参数优化数据库连接管理适合高并发场景use_tz和timezone控制时间字段的时区行为生产环境建议启用初始化 FastAPI 应用fromfastapiimportFastAPIfromtortoise.contrib.fastapiimportregister_tortoisefromapp.core.configimportTORTOISE_ORM appFastAPI(titleFastAPI with Tortoise-ORM)# 注册 Tortoise-ORMregister_tortoise(app,configTORTOISE_ORM,generate_schemasTrue,# 开发环境自动生成表结构add_exception_handlersTrue,# 添加默认异常处理器)app.get(/)asyncdefroot():return{message:Welcome to FastAPI with Tortoise-ORM!}三、Aerich 迁移工具的使用Aerich 是 Tortoise-ORM 的数据库迁移工具用于管理数据库结构的变更Aerich 初始化在项目根目录运行以下命令aerich init-tmain.TORTOISE_ORM这将生成pyproject.tomlAerich 配置文件指定迁移配置。migrations/迁移文件目录存放生成的 .sql 文件。aerich init-db生成和应用迁移生成迁移文件 当模型发生变更时运行以下命令生成迁移文件aerich migrate--nameinfo应用迁移 运行以下命令将迁移应用到数据库aerich upgrade验证迁移 检查迁移历史aerichhistory回滚迁移回退到指定版本aerich downgrade模型案例fromtortoise.modelsimportModelfromtortoise.fieldsimportCharField,DatetimeField,BooleanFieldclassUser(Model):idCharField(max_length36,pkTrue)# 主键UUID 字符串usernameCharField(max_length50,uniqueTrue)# 用户名唯一emailCharField(max_length255,uniqueTrue)# 邮箱唯一is_activeBooleanField(defaultTrue)# 是否激活created_atDatetimeField(auto_now_addTrue)# 创建时间updated_atDatetimeField(auto_nowTrue)# 更新时间classMeta:tableusers# 自定义表名ordering[-created_at]# 默认按创建时间降序排序def__str__(self):returnself.username效果fromtortoiseimportBaseDBAsyncClientasyncdefupgrade(db:BaseDBAsyncClient)-str:return CREATE TABLE IF NOT EXISTS users ( id VARCHAR(36) NOT NULL PRIMARY KEY, username VARCHAR(50) NOT NULL UNIQUE, email VARCHAR(255) NOT NULL UNIQUE, is_active BOOL NOT NULL DEFAULT 1, created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6), updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6) ) CHARACTER SET utf8mb4; CREATE TABLE IF NOT EXISTS aerich ( id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, version VARCHAR(255) NOT NULL, app VARCHAR(100) NOT NULL, content JSON NOT NULL ) CHARACTER SET utf8mb4;asyncdefdowngrade(db:BaseDBAsyncClient)-str:return 四、Tortoise-ORM 的模型定义模型定义基础Tortoise-ORM 的模型通过继承 tortoise.models.Model 类定义每个模型对应数据库中的一张表。字段定义使用 Tortoise-ORM 提供的字段类型结合字段参数来指定约束和行为。基本模型示例fromtortoise.modelsimportModelfromtortoiseimportfieldsclassUser(Model):idfields.IntField(pkTrue)# 主键字段自动递增usernamefields.CharField(max_length50,uniqueTrue)# 唯一用户名emailfields.CharField(max_length100,indexTrue)# 带索引的邮箱created_atfields.DatetimeField(auto_now_addTrue)# 自动记录创建时间is_activefields.BooleanField(defaultTrue)# 账户激活状态creditfields.DecimalField(max_digits10,decimal_places2,default0.0)# 精确数值classMeta:tableauth_users# 自定义表名ordering[-created_at]# 默认按创建时间倒序unique_together[username,email]#定义联合唯一约束如 unique_together[(field1, field2)]说明继承Model所有模型必须继承 tortoise.models.Model。字段定义每个字段对应数据库表中的一列使用 Tortoise-ORM 的字段类如 CharField、BooleanField。Meta类用于定义模型的元数据如表名、排序规则等。核心字段类型详解Tortoise-ORM 提供了多种字段类型用于定义数据库列的类型和行为。以下是常用的字段类型及其典型用途Python 字段类型数据库类型描述常用参数CharFieldVARCHAR字符串max_length必填、uniqueTrue、indexTrueTextFieldTEXT长文本nullTrue允许为空IntField/BigIntFieldINTEGER/BIGINT整数pkTrue主键、default0FloatFieldDOUBLE/REAL浮点数gt0值需大于0DecimalFieldDECIMAL高精度小数max_digits10,decimal_places2最大10位含2位小数BooleanFieldBOOLEAN布尔值defaultTrueDateFieldDATE日期auto_nowTrue保存时更新DatetimeFieldDATETIME/TIMESTAMP日期时间auto_now_addTrue仅首次保存记录时间JSONFieldJSON/JSONB存储字典或列表encoder自定义编码器、decoder自定义解码器UUIDFieldUUID/CHAR(36)唯一标识符若为主键默认生成 UUID4BinaryFieldBLOB二进制数据不支持过滤或更新操作字段参数详解字段支持多种参数用于定义约束、默认值和其他行为。以下是常用参数max_length字符串字段的最大长度CharField 必填null是否允许字段为空nullTrue 表示数据库允许 NULLdefault字段默认值如 default0、defaultTrueunique是否唯一uniqueTrue 确保字段值在表中唯一index是否创建索引indexTrue 提高查询性能description字段描述用于文档或数据库注释pk是否为主键pkTrue 表示该字段是主键validators自定义验证函数fromtortoise.validatorsimportValidatordefvalidate_credit(value):ifvalue0:raiseValueError(信用值不能为负数)classUser(Model):creditfields.IntField(validators[validate_credit])# 自定义验证函数模型元数据Meta 类Meta 类用于定义模型的元数据控制表结构和查询行为。常用属性包括table自定义数据库表名如 table“users”unique_together定义联合唯一约束如 unique_together[(“field1”, “field2”)]indexes定义索引如 indexes[(“field1”, “field2”)]ordering默认排序规则如 ordering[“-created_at”, “username”]classEvent(Model):nameCharField(max_length100)locationCharField(max_length200)dateDateField()classMeta:tableeventsunique_together[(name,date)]# 名称和日期联合唯一indexes[(location,)]# 为 location 字段创建索引ordering[date]# 按日期升序排序持续更新中✒️总结如果这篇【文章】有帮助到你希望可以给我点个赞创作不易如果有对前端端或者对python感兴趣的朋友,请多多关注咱们一起探讨和努力‍ 个人主页 : 前端初见