FastAPI做项目的后端准备
文章目录
- FastAPI做项目的后端准备
- 前言
- 一、理解框架之间的关系？
- 二、Main里面的配置
- 定义 lifespan 生命周期函数
- 1. 引入必要的库
- 代码说明：
- 2. 多环境配置
- 依赖
- 相关文件一览
- 三个环境对照表
- 配置实现步骤
- 1. 创建配置文件
- 2. 创建环境文件
- 4. 更新 database.py 使用配置
- 5. 更新 main.py 使用配置
- 配置验证
- 3. 解决 Tortoise-ORM 警告：Module "app.models" has no models
- 问题分析
- 解决方案
- 方案一：创建模型文件
- 完整启动流程验证
前言
搭建项目框架，首先明确框架里面的内容
boss-api/├── main.py# FastAPI应用主入口│ ├── requirements.txt# Python依赖包│ └── app/# 应用核心代码├── __init__.py │ │ ├── models/# 数据模型层 (Tortoise ORM)│ ├── __init__.py │ ├── user.py# 用户相关模型│ ├── apis/# API路由层[接受参数,返回数据]│ ├── __init__.py │ └── user_api.py# 用户相关API│ └── schemas/# 数据验证层 (Pydantic)│ ├── __init__.py │ └── user.py# 用户请求/响应模型│ │ ├── services/# 业务服务层 (逻辑)│ ├── __init__.py │ ├── user.py# 用户相关的业务代码/方法│ │ ├── core/# 核心文件│ ├── __init__.py │ ├── database.py# 数据库连接信息├── config/# 配置文件│ ├── __init__.py │ ├── settings.py# 多环境配置提示：以下是本篇文章正文内容，下面案例可供参考
一、理解框架之间的关系？
database:数据库配置文件
这个文件定义了Tortoise-ORM 连接MYSQL 数据库所需的所有配置信息
二、Main里面的配置
定义 lifespan 生命周期函数
1. 引入必要的库
首先，我们需要导入 FastAPI、Tortoise-ORM 以及异步上下文管理器：
fromfastapiimportFastAPIfromtortoiseimportTortoisefromcontextlibimportasynccontextmanager# 数据库配置（示例）TORTOISE_ORM={"connections":{"default":"mysql://user:password@localhost:3306/mydatabase"},"apps":{"models":{"models":["app.models","aerich.models"],"default_connection":"default",}},"use_tz":False,"timezone":"UTC",}## 2. 实现 lifespan 生命周期函数下面是使用 `@asynccontextmanager` 装饰器定义 lifespan 函数的完整示例： ```python@asynccontextmanagerasyncdeflifespan(app:FastAPI):""" 使用 lifespan 管理应用的生命周期。 在应用启动时初始化数据库连接，在应用关闭时释放连接。 这是 FastAPI 推荐的最佳实践。 """# 启动时执行的代码print("🚀 正在初始化 Tortoise-ORM...")# 启动阶段：初始化 Tortoise-ORM 连接awaitTortoise.init(config=TORTOISE_ORM)# 生成数据库表（仅开发环境使用）# await Tortoise.generate_schemas()print("✅ 数据库连接初始化完成")yield# 应用运行阶段# 关闭阶段：销毁数据库连接print("🛑 正在关闭数据库连接...")awaitTortoise.close_connections()print("✅ 数据库连接已关闭")# 创建 FastAPI 应用并传入 lifespanapp=FastAPI(title="Boss API",description="一个使用 FastAPI 和 Tortoise-ORM 的后端项目",version="1.0.0",lifespan=lifespan# 传入生命周期管理器)# 示例路由@app.get("/")asyncdefroot():return{"message":"欢迎使用 Boss API"}@app.get("/health")asyncdefhealth_check():return{"status":"healthy","database":"connected"}代码说明：
@asynccontextmanager装饰器：将异步函数转换为异步上下文管理器lifespan函数：- 启动阶段：在
yield之前执行，用于初始化资源（数据库连接） - 运行阶段：
yield之后应用正常运行 - 关闭阶段：
yield之后执行，用于清理资源（关闭数据库连接）
- 启动阶段：在
Tortoise.init()：初始化数据库连接Tortoise.close_connections()：关闭所有数据库连接app = FastAPI(lifespan=lifespan)：将生命周期管理器传递给 FastAPI 应用
启动成功：
2. 多环境配置
依赖
pipinstallpydantic-settings项目中已使用pydantic_settings.BaseSettings。
相关文件一览
项目根目录/ ├── .env# 各环境共享的少量公共项├── .env.dev# 开发环境├── .env.test# 测试环境├── .env.prod# 生产环境（真实密钥，勿提交公开仓库）├── .gitignore# 忽略 .env.dev / .env.prod 等├── main.py# 使用 settings 初始化 FastAPI└── app/ ├── config/ │ └── settings.py# ★ 本节核心└── core/ └── database.py# ★ 从 settings 读库配置三个环境对照表
| 环境 | 英文 | 典型用途 | 调试 | 数据库 | 密钥来源 |
|---|---|---|---|---|---|
| 开发 | dev | 本机写代码、联调 | 开 | 本地 MySQL | .env.dev |
| 测试 | test | 跑自动化测试、预发验证 | 关 | 测试库（可清空） | .env.test |
| 生产 | prod | 真实用户访问 | 关 | 生产库 | 环境变量 |
配置实现步骤
1. 创建配置文件
首先在app/config/settings.py中创建配置类：
# app/config/settings.pyfrompydantic_settingsimportBaseSettingsfromtypingimportOptionalclassSettings(BaseSettings):"""应用配置类"""# 基础配置APP_NAME:str="Boss API"APP_VERSION:str="1.0.0"DEBUG:bool=False# 数据库配置DATABASE_URL:strDATABASE_POOL_SIZE:int=5DATABASE_MAX_OVERFLOW:int=10# JWT配置SECRET_KEY:strALGORITHM:str="HS256"ACCESS_TOKEN_EXPIRE_MINUTES:int=30# 环境特定配置ENVIRONMENT:str="dev"# dev/test/prodclassConfig:env_file=".env"env_file_encoding="utf-8"case_sensitive=False# 创建全局配置实例settings=Settings()2. 创建环境文件
在项目根目录创建不同环境的.env文件：
.env（共享配置）：
# 各环境共享的少量公共项 APP_NAME=Boss API APP_VERSION=1.0.0 ALGORITHM=HS256 ACCESS_TOKEN_EXPIRE_MINUTES=30 DATABASE_POOL_SIZE=5 DATABASE_MAX_OVERFLOW=10.env.dev（开发环境）：
# 开发环境配置 ENVIRONMENT=dev DEBUG=true DATABASE_URL=mysql://user:password@localhost:3306/boss_dev SECRET_KEY=dev-secret-key-change-in-production.env.test（测试环境）：
# 测试环境配置 ENVIRONMENT=test DEBUG=false DATABASE_URL=mysql://user:password@localhost:3306/boss_test SECRET_KEY=test-secret-key.env.prod（生产环境）：
# 生产环境配置（真实密钥，勿提交公开仓库） ENVIRONMENT=prod DEBUG=false DATABASE_URL=${PROD_DATABASE_URL} # 从环境变量读取 SECRET_KEY=${PROD_SECRET_KEY} # 从环境变量读取4. 更新 database.py 使用配置
修改app/core/database.py从配置读取数据库连接：
# app/core/database.pyfromapp.config.settingsimportsettingsdefget_tortoise_config():"""根据配置生成 Tortoise-ORM 配置"""return{"connections":{"default":settings.DATABASE_URL},"apps":{"models":{"models":["app.models","aerich.models"],"default_connection":"default",}},"use_tz":False,"timezone":"UTC",}TORTOISE_ORM=get_tortoise_config()5. 更新 main.py 使用配置
修改main.py使用配置初始化 FastAPI：
# main.pyfromfastapiimportFastAPIfromtortoiseimportTortoisefromcontextlibimportasynccontextmanagerfromapp.config.settingsimportsettingsfromapp.core.databaseimportTORTOISE_ORM@asynccontextmanagerasyncdeflifespan(app:FastAPI):""" 使用 lifespan 管理应用的生命周期。 在应用启动时初始化数据库连接，在应用关闭时释放连接。 """# 启动时执行的代码print(f"🚀 正在初始化 Tortoise-ORM... [环境:{settings.ENVIRONMENT}]")# 启动阶段：初始化 Tortoise-ORM 连接awaitTortoise.init(config=TORTOISE_ORM)# 仅在开发环境生成数据库表ifsettings.DEBUG:print("🔧 开发环境：生成数据库表...")awaitTortoise.generate_schemas()print("✅ 数据库连接初始化完成")yield# 应用运行阶段# 关闭阶段：销毁数据库连接print("🛑 正在关闭数据库连接...")awaitTortoise.close_connections()print("✅ 数据库连接已关闭")# 创建 FastAPI 应用并传入 lifespanapp=FastAPI(title=settings.APP_NAME,description="一个使用 FastAPI 和 Tortoise-ORM 的后端项目",version=settings.APP_VERSION,lifespan=lifespan,debug=settings.DEBUG,)# 示例路由@app.get("/")asyncdefroot():return{"message":f"欢迎使用{settings.APP_NAME}","version":settings.APP_VERSION,"environment":settings.ENVIRONMENT,}@app.get("/health")asyncdefhealth_check():return{"status":"healthy","database":"connected","environment":settings.ENVIRONMENT,}配置验证
创建验证路由检查当前配置：
# app/apis/config_api.pyfromfastapiimportAPIRouterfromapp.config.settingsimportsettings router=APIRouter(prefix="/config",tags=["配置"])@router.get("/")asyncdefget_config():"""获取当前配置（仅开发环境开放）"""ifnotsettings.DEBUG:return{"message":"配置信息仅在开发环境可见"}return{"app_name":settings.APP_NAME,"version":settings.APP_VERSION,"environment":settings.ENVIRONMENT,"debug":settings.DEBUG,"database_url":settings.DATABASE_URL[:50]+"..."ifsettings.DATABASE_URLelseNone,}3. 解决 Tortoise-ORM 警告：Module “app.models” has no models
从启动日志中可以看到以下警告：
/Users/baimu/PycharmProjects/2603-p3/my/my-boss-fastApiProject/venv/lib/python3.12/site-packages/tortoise/apps.py:42: RuntimeWarning: Module "app.models" has no models self._load_from_config()问题分析
这个警告表示 Tortoise-ORM 在app.models模块中没有找到任何模型定义。在您的TORTOISE_ORM配置中，指定了：
"models":["app.models","aerich.models"]但app.models模块要么不存在，要么存在但没有定义任何 Tortoise 模型类。
解决方案
方案一：创建模型文件
创建 models 目录和文件：
按照项目结构，在app/models/目录下创建模型文件：# app/models/user.pyfromtortoiseimportfields,modelsclassUser(models.Model):"""用户模型"""id=fields.IntField(pk=True)username=fields.CharField(max_length=50,unique=True)email=fields.CharField(max_length=100,unique=True)hashed_password=fields.CharField(max_length=128)is_active=fields.BooleanField(default=True)created_at=fields.DatetimeField(auto_now_add=True)updated_at=fields.DatetimeField(auto_now=True)classMeta:table="users"def__str__(self):returnself.username创建init.py 文件：
在app/models/__init__.py中导入模型：# app/models/__init__.pyfrom.userimportUser __all__=["User"]
完整启动流程验证
修复后，重新启动应用应该看到正常的启动日志：
INFO: Willwatchforchangesinthese directories:['/path/to/your/project']INFO: Uvicorn running on http://127.0.0.1:8000(Press CTRL+C to quit)INFO: Started reloader process[17071]using WatchFiles 🚀 正在初始化 Tortoise-ORM... INFO: Started server process[17073]INFO: Waitingforapplication startup. ✅ 数据库连接初始化完成 INFO: Application startup complete.
