先摆上基本的后端目录结构

完整代码

DB_USER=root
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=3306
DB_NAME=task_manager

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from dotenv import load_dotenv
import os

# 加载环境变量
load_dotenv()

# 使用MySQL作为数据库
SQLALCHEMY_DATABASE_URL = f"mysql+pymysql://{os.getenv('DB_USER')}:{os.getenv('DB_PASSWORD')}@{os.getenv('DB_HOST')}:{os.getenv('DB_PORT')}/{os.getenv('DB_NAME')}"
# 创建数据库引擎
engine = create_engine(
    SQLALCHEMY_DATABASE_URL
)
# 创建数据库会话
SessionLocal = sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine)
# 创建数据库模型
Base = declarative_base()

# 依赖项，用于获取数据库会话
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

---

python


深色版本

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from dotenv import load_dotenv
import os

🔧 导入所需模块说明：

模块	作用
create_engine	创建数据库连接引擎，是 SQLAlchemy 与数据库通信的核心
declarative_base	用于创建“基类”，后续所有数据模型都继承它，实现 ORM 映射
sessionmaker	创建数据库会话（Session）的工厂类，用于操作数据库（增删改查）
load_dotenv	从 .env 文件加载环境变量，避免敏感信息硬编码
os	读取操作系统环境变量

---

python


深色版本

# 加载环境变量
load_dotenv()

📦 load_dotenv() 作用：

• 读取项目根目录下的 .env 文件，把里面的键值对加载到环境变量中。
• 例如，.env 文件内容可能是：

env


深色版本

DB_USER=root
DB_PASSWORD=123456
DB_HOST=localhost
DB_PORT=3306
DB_NAME=myapp_db

• 加载后，os.getenv('DB_USER') 就能读取到 root。

✅ 好处：避免将数据库密码等敏感信息写死在代码中，提高安全性，也便于不同环境（开发/测试/生产）切换。

---

python


深色版本

# 使用MySQL作为数据库
SQLALCHEMY_DATABASE_URL = f"mysql+pymysql://{os.getenv('DB_USER')}:{os.getenv('DB_PASSWORD')}@{os.getenv('DB_HOST')}:{os.getenv('DB_PORT')}/{os.getenv('DB_NAME')}"

🌐 SQLALCHEMY_DATABASE_URL：数据库连接字符串

这是 SQLAlchemy 连接数据库的“地址”，格式如下：

深色版本

数据库类型+驱动://用户名:密码@主机:端口/数据库名

分解说明：

部分	示例值	说明
mysql+pymysql	驱动类型	使用 pymysql 驱动连接 MySQL 数据库（也可以用 mysqlconnector 或 mysqldb ）
{os.getenv('DB_USER')}	如 root	数据库用户名
{os.getenv('DB_PASSWORD')}	如 123456	数据库密码
{os.getenv('DB_HOST')}	如 localhost 或 127.0.0.1	数据库服务器地址
{os.getenv('DB_PORT')}	如 3306	MySQL 默认端口
{os.getenv('DB_NAME')}	如 myapp_db	要连接的数据库名称

📌 注意：这个 URL 不应该包含敏感信息明文，所以用 os.getenv() 从环境变量读取。

---

python


深色版本

# 创建数据库引擎
engine = create_engine(
    SQLALCHEMY_DATABASE_URL
)

⚙️ create_engine() 详解

• engine 是 SQLAlchemy 的核心对象，负责：

• • 管理数据库连接池
  • 执行 SQL 语句
  • 与数据库通信

• 它是“懒连接”：创建时不会立即连接数据库，第一次执行操作时才连接。
• 常见参数（你没写，但可加）：

• • echo=True：打印所有 SQL 语句（调试用）
  • pool_size=10, max_overflow=20：连接池设置
  • connect_args={"charset": "utf8mb4"}：传递额外连接参数（如字符集）

✅ 一句话：engine 就是你的“数据库通信司机”。

---

python


深色版本

# 创建数据库会话
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

🧩 sessionmaker() 详解

创建一个“会话工厂”类，用来生成数据库会话（Session）。

参数	作用
autocommit=False	不自动提交。你需要手动调用 db.commit() 才真正保存数据（推荐做法，更安全）
autoflush=False	不自动刷新。不立即执行 SQL，直到你显式查询或提交（提高性能，避免意外查询）
bind=engine	绑定到前面创建的 engine ，告诉这个会话该连接哪个数据库

📌 SessionLocal 是一个类，不是实例。你后面要这样用：

python


深色版本

db = SessionLocal()  # 创建一个会话实例

---

python


深色版本

# 创建数据库模型基类
Base = declarative_base()

🏗️ declarative_base() 作用

• 返回一个基类（通常叫 Base）
• 后续你定义的所有数据模型（如 User, Item）都要继承这个 Base
• 它让 SQLAlchemy 知道：这些类要映射到数据库表（ORM：对象关系映射）

📌 示例：

python


深色版本

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String(50))

Base 是所有模型的“祖先”，它知道如何把类变成表。

---

python


深色版本

# 依赖项，用于获取数据库会话
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

🔄 get_db()：FastAPI 的依赖项（Dependency）

这是 FastAPI 中最常用的数据库会话管理方式。

工作流程：

1. db = SessionLocal() → 创建一个新的数据库会话
2. yield db → 把 db 实例“交给”当前请求的路由函数使用
3. 请求处理完成后，无论成功或出错，都会执行 finally 中的 db.close()

• • 释放数据库连接，归还给连接池

为什么用 yield？

• 因为 FastAPI 支持生成器依赖项（generator dependency）
• yield 实现了“请求开始时获取资源，结束后自动清理”的模式
• 等价于：

python


深色版本

try:
    return db
finally:
    db.close()

如何在路由中使用？

python


深色版本

from fastapi import Depends

@app.get("/users/")
def read_users(db: Session = Depends(get_db)):
    return db.query(User).all()

Depends(get_db) 会调用 get_db()，获取 db，并在请求结束时自动关闭。

---

✅ 总结：整体流程图

深色版本

.env 文件
   ↓ (load_dotenv)
环境变量 → 构建 SQLALCHEMY_DATABASE_URL
                ↓
         create_engine → engine
                ↓
     sessionmaker(bind=engine) → SessionLocal
                ↓
      get_db() 依赖项 → 提供给 FastAPI 路由使用
                ↓
           路由函数中通过 db 增删改查

---

🛡️ 安全与最佳实践建议

1. 不要把 .env 提交到 Git：

gitignore


深色版本

.env

1. 设置连接池（生产环境）：

python


深色版本

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    pool_size=10,
    max_overflow=20,
    pool_pre_ping=True  # 自动检测并重建失效连接
)

1. 使用异步（可选）： 如果你用 FastAPI 异步，可以考虑 sqlalchemy.ext.asyncio 配合 aiomysql。

---

📚 一句话总结

这段代码是 FastAPI 项目中 标准的 SQLAlchemy 数据库配置模板：用环境变量安全连接 MySQL，创建引擎、会话工厂和模型基类，并通过 get_db 依赖项实现请求级数据库会话管理。