Tortoise-ORM与FastAPI集成：异步模子定义与实践

缠丝猫 · 2025-4-20 11:19:37

title: Tortoise-ORM与FastAPI集成：异步模子定义与实践
date: 2025/04/20 11:38:23
updated: 2025/04/20 11:38:23
author: cmdragon
excerpt:
Tortoise-ORM通过类继承方式定义数据模子，每个模子类对应数据库中的一张表。模子字段类型与数据库类型自动映射，支持主键、唯一约束、索引等配置。模子间通过外键建立关联，支持异步查询和CRUD操作。FastAPI集成时，通过register_tortoise初始化数据库毗连，并结合Pydantic模子实现数据验证。常见错误包括字段验证失败和数据库毗连超时，可通过中间件和毗连池配置解决。
categories:

后端开发
FastAPI

tags:

Tortoise-ORM
FastAPI
异步数据库
模子定义
数据库配置
CRUD接口
错误处置惩罚

扫描二维码关注或者微信搜一搜：编程智域前端至全栈交流与成长
探索数千个预构建的 AI 应用，开启你的下一个伟大创意
第一章 Tortoise-ORM异步模子定义根本

1.1 模子类创建方法

在FastAPI项目中，数据模子是毗连业务逻辑与数据库的核心枢纽。Tortoise-ORM接纳类继承方式定义模子，每个模子类对应数据库中的一张表。以下是用户模子的完整示例：

from tortoise.models import Model
from tortoise import fields
class User(Model):
id = fields.IntField(pk=True) # 主键字段，自动递增
username = fields.CharField(max_length=50, unique=True) # 唯一用户名
email = fields.CharField(max_length=100, index=True) # 带索引的邮箱字段
created_at = fields.DatetimeField(auto_now_add=True) # 自动记录创建时间
is_active = fields.BooleanField(default=True) # 账户激活状态
credit = fields.DecimalField(max_digits=10, decimal_places=2, default=0.0) # 精确数值存储
class Meta:
table = "auth_users" # 自定义表名
ordering = ["-created_at"] # 默认排序规则

复制代码

该模子在数据库中会天生如下结构的表（以PostgreSQL为例）：

CREATE TABLE auth_users
(
id SERIAL PRIMARY KEY,
username VARCHAR(50) NOT NULL UNIQUE,
email VARCHAR(100) NOT NULL,
created_at TIMESTAMP NOT NULL,
is_active BOOLEAN NOT NULL,
credit NUMERIC(10, 2) NOT NULL
);

复制代码

1.2 字段类型映射原理

Tortoise-ORM的字段体系实现了Python类型与数据库类型的智能转换。当我们执行数据库迁徙时，ORM会自动根据模子字段类型天生对应的DDL语句：
Python字段类型PostgreSQL类型MySQL类型SQLite类型CharFieldVARCHARVARCHARTEXTUUIDFieldUUIDCHAR(36)TEXTDatetimeFieldTIMESTAMPDATETIME(6)TEXTJSONFieldJSONBJSONTEXTFloatFieldDOUBLE PRECISIONDOUBLEREAL特殊的字段参数：

auto_now_add=True：仅在对象创建时记录时间
auto_now=True：每次生存对象时更新时间
description='字段说明'：天生数据库注释
db_index=True：创建独立索引（比index参数更灵活）

1.3 模子关联配置

关联关系配置是ORM的核心功能之一。我们通过外键字段建立模子间的关联：

class Author(Model):
name = fields.CharField(max_length=100)
class Book(Model):
title = fields.CharField(max_length=200)
author = fields.ForeignKeyField(
'models.Author',
related_name='books',
on_delete=fields.CASCADE
)
published_date = fields.DateField()

复制代码

关联查询示例：

# 获取作者及其所有书籍
author = await Author.filter(name="J.K. Rowling").prefetch_related('books')
# 创建关联对象
await Book.create(
title="Harry Potter and the Philosopher's Stone",
author=author,
published_date=date(1997, 6, 26)
)

复制代码

第二章 FastAPI集成实践

2.1 数据库配置

在FastAPI启动配置中初始化数据库毗连：

from fastapi import FastAPI
from tortoise.contrib.fastapi import register_tortoise
app = FastAPI()
DB_CONFIG = {
"connections": {
"default": "postgres://user:password@localhost:5432/mydb"
},
"apps": {
"models": {
"models": ["models"],
"default_connection": "default",
}
},
"use_tz": True, # 启用时区支持
"timezone": "Asia/Shanghai"
}
register_tortoise(
app,
config=DB_CONFIG,
generate_schemas=True, # 自动生成表结构
add_exception_handlers=True # 启用ORM异常处理
)

复制代码

2.2 路由与模子结合

创建完整的CRUD接口示例：

from pydantic import BaseModel
from fastapi import APIRouter
router = APIRouter()
class UserCreate(BaseModel):
username: str
email: str
@router.post("/users")
async def create_user(user: UserCreate):
db_user = await User.create(**user.dict())
return {
"id": db_user.id,
"created_at": db_user.created_at.isoformat()
}
@router.get("/users/{user_id}")
async def get_user(user_id: int):
user = await User.get_or_none(id=user_id).values(
"username", "email", "created_at")
return user or {"error": "User not found"}

复制代码

第三章课后Quiz

问题1：如何设置UUID主键？

A) id = fields.UUIDField()
B) id = fields.UUIDField(pk=True)
C) id = fields.UUIDField(primary_key=True)
正确答案：C
分析：在Tortoise-ORM中，设置主键必要显式指定primary_key参数。虽然pk是常用的快捷参数，但UUIDField必须使用完整的primary_key=True才华正确天生主键约束。
问题2：异步查询的上风包括？

A) 减少内存占用
B) 避免阻塞变乱循环
C) 进步CPU使用率
正确答案：B
分析：异步查询允许变乱循环在等待数据库相应时处置惩罚其他使命，特殊适合高并发的I/O麋集型场景。内存占用和CPU使用率主要与步伐实现方式相关，并非异步的直接上风。
第四章常见报错解决方案

4.1 字段验证失败（422错误）

错误示例：

{
"detail": [
{
"loc": [
"body",
"username"
],
"msg": "ensure this value has at most 50 characters",
"type": "value_error.any_str.max_length"
}
]
}

复制代码

解决方法：

检查哀求数据是否符合模子约束
在Pydantic模子中设置相同的验证规则
使用中间件捕捉验证非常：

from fastapi.exceptions import RequestValidationError
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc):
return JSONResponse(
status_code=400,
content={"detail": exc.errors()},
)

复制代码

4.2 数据库毗连超时

错误信息：
DBConnectionError: Can't connect to MySQL server on 'localhost'
排查步骤：

验证数据库服务是否正常运行
检查毗连字符串格式：dialect://user:password@host:port/dbname
增长毗连池配置：

DB_CONFIG = {
"connections": {
"default": {
"engine": "tortoise.backends.asyncpg",
"credentials": {
"host": "localhost",
"port": "5432",
"database": "mydb",
"user": "user",
"password": "password",
"minsize": 3, # 最小连接数
"maxsize": 20 # 最大连接数
}
}
}
}

复制代码

		自动登录	找回密码
密码			立即注册

Tortoise-ORM与FastAPI集成：异步模子定义与实践

本帖子中包含更多资源

0 个回复

快速回复

楼主热帖

标签云

浏览过的版块