第 04 章 FastAPI 数据库认证与工程化

MySQL、ORM、依赖注入与 JWT

本章采用教材式讲解：先说明概念，再给出可运行代码，最后整理练习任务。代码示例尽量保持小而完整，便于直接复制到本地验证。

学习目标：集成 MySQL 数据库实现数据持久化，掌握依赖注入实现认证

第 1 节：数据库基础与 SQLAlchemy ORM

1.1 数据库是什么？为什么需要数据库？

内存 vs 文件 vs 数据库：

存储方式	优点	缺点
变量/列表	速度快	程序退出即丢失
JSON 文件	持久化，简单	并发写入不安全，数据量大查询慢
数据库（MySQL）	支持海量数据、并发、安全、复杂查询	需要额外学习 SQL

MySQL 是什么？ 开源关系型数据库，将数据以表格（行×列）形式存储，支持 SQL 查询语言。FastAPI 通过 ORM（对象关系映射） 框架操作数据库——用 Python 代码代替 SQL 语句。

1.2 SQLAlchemy ORM 核心概念

ORM（Object-Relational Mapping） 的作用：用 Python 类表示数据库表，用类的实例表示表中的行。

数据库表：students
+----+--------+-----+-------+-------+
| id | name   | age | score | email |
+----+--------+-----+-------+-------+
|  1 | Alice  |  20 |  92.5 | a@... |
|  2 | Bob    |  21 |  85.0 | b@... |
+----+--------+-----+-------+-------+

对应的 Python 类：
class Student(Base):
    __tablename__ = "students"   # 数据库表名
    id    = Column(Integer, primary_key=True, autoincrement=True)
    name  = Column(String(64), nullable=False)
    age   = Column(Integer)
    score = Column(Float)
    email = Column(String(128))

为什么用 ORM 而不是直接写 SQL？ - Python 代码更简洁，不需要拼接 SQL 字符串 - 防止 SQL 注入攻击（用户输入被当作数据而非 SQL 代码） - 数据库切换成本低（从 MySQL 换成 PostgreSQL 只需改连接字符串）

1.3 环境准备与连接 MySQL

pip install sqlalchemy pymysql python-dotenv

# .env（不要提交到 Git！）
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=myapp

# database.py
# @author xujl
import os
from dotenv import load_dotenv
from sqlalchemy import create_engine, text
from sqlalchemy.orm import sessionmaker

load_dotenv()

DB_HOST     = os.getenv("DB_HOST", "127.0.0.1")
DB_PORT     = os.getenv("DB_PORT", "3306")
DB_USER     = os.getenv("DB_USER", "root")
DB_PASSWORD = os.getenv("DB_PASSWORD", "")
DB_NAME     = os.getenv("DB_NAME", "myapp")

# mysql+pymysql://用户名:密码@主机:端口/数据库名?编码
DATABASE_URL = f"mysql+pymysql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}?charset=utf8mb4"

engine = create_engine(
    DATABASE_URL,
    pool_pre_ping=True,         # 连接断开时自动重连
    pool_size=5,                # 连接池大小
    max_overflow=10             # 最多额外10个连接
)

SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# 创建数据库（如果不存在）
with engine.connect() as conn:
    conn.execute(text(f"CREATE DATABASE IF NOT EXISTS {DB_NAME} CHARACTER SET utf8mb4"))
    conn.commit()

pool_pre_ping：MySQL 有"空闲超时"机制（默认 8 小时无活动自动断开），pool_pre_ping=True 会在使用连接前先 ping 一下服务器，自动重连，避免"连接已断开"错误。

# models.py
# @author xujl
from sqlalchemy import Column, Integer, String, Float, DateTime, Boolean
from sqlalchemy.sql import func
from database import Base

class Student(Base):
    __tablename__ = "students"

    id        = Column(Integer, primary_key=True, index=True, autoincrement=True)
    name      = Column(String(64), index=True, nullable=False)
    age       = Column(Integer, default=0)
    score     = Column(Float, default=0.0)
    email     = Column(String(128), unique=True, index=True)
    is_active = Column(Boolean, default=True)
    created_at = Column(DateTime, server_default=func.now())

# 创建所有表（首次运行后，注释掉这行）
Base.metadata.create_all(bind=engine)

# 依赖注入：每个请求自动获取独立的数据库连接
# @author xujl
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

依赖注入是什么？ get_db() 函数被 FastAPI 的 Depends() 调用。每个 HTTP 请求进入时，FastAPI 调用 get_db() 创建一个数据库连接，请求处理完后在 finally 中关闭连接。这样每个请求都有独立的连接，不会互相干扰。

第 2 节：数据库 CRUD

# schemas.py（定义 API 的请求/响应格式，与数据库模型分开）
# @author xujl
from pydantic import BaseModel
from datetime import datetime

class StudentCreate(BaseModel):
    name: str
    age: int = 0
    score: float = 0.0
    email: str

class StudentResponse(BaseModel):
    id: int
    name: str
    age: int
    score: float
    email: str
    is_active: bool
    created_at: datetime

    class Config:
        from_attributes = True  # Pydantic v2：允许从 ORM 对象创建模型

# crud.py（将数据库操作封装为函数）
# @author xujl
from sqlalchemy.orm import Session
from models import Student

def create_student(db: Session, name: str, age: int, score: float, email: str) -> Student:
    student = Student(name=name, age=age, score=score, email=email)
    db.add(student)
    db.commit()
    db.refresh(student)
    return student

def get_student(db: Session, student_id: int) -> Student | None:
    return db.query(Student).filter(Student.id == student_id).first()

def list_students(db: Session, skip: int = 0, limit: int = 10) -> list[Student]:
    return db.query(Student).filter(Student.is_active == True).offset(skip).limit(limit).all()

def delete_student(db: Session, student_id: int) -> bool:
    student = db.query(Student).filter(Student.id == student_id).first()
    if not student:
        return False
    student.is_active = False  # 软删除（标记删除，保留数据）
    db.commit()
    return True

第 3 节：JWT 认证

3.1 为什么需要认证？

HTTP 协议本身无状态——每个请求都是独立的，服务器不知道请求来自哪个用户。JWT（JSON Web Token）是解决无状态认证的主流方案。

3.2 JWT 工作原理

用户登录 → 服务器验证密码 → 服务器签发 JWT（内含用户身份信息）
                                              ↓
用户后续请求 → 携带 JWT（Authorization: Bearer xxx）
                      ↓
              服务器验证 JWT → 有效则提取用户身份 → 无效则返回 401

JWT 结构：三段 Base64，用 . 连接

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMDEiLCJleHAiOjE3MTYwMDAwMDB9.AFx7mKk8pLr2Q
   ↓ Header（算法）                   ↓ Payload（数据）                    ↓ Signature（签名）

3.3 完整 JWT 实现

# auth.py
# @author xujl
import os
from datetime import datetime, timedelta
from typing import Optional
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from sqlalchemy.orm import Session
from dotenv import load_dotenv
from database import get_db
from models import Student

load_dotenv()

SECRET_KEY  = os.getenv("SECRET_KEY", "your-secret-key-change-in-production")
ALGORITHM   = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 60

pwd_context  = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/token")

# ---------- 密码工具 ----------
def hash_password(password: str) -> str:
    """将密码哈希后存储——永远不要明文存储密码！"""
    return pwd_context.hash(password)

def verify_password(plain: str, hashed: str) -> bool:
    """验证密码：传入明文密码和存储的哈希值"""
    return pwd_context.verify(plain, hashed)

# ---------- JWT 工具 ----------
def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
    """签发 JWT"""
    to_encode = data.copy()
    expire = datetime.utcnow() + (expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES))
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

def decode_token(token: str) -> Optional[dict]:
    """验证并解析 JWT"""
    try:
        return jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
    except JWTError:
        return None

# ---------- 依赖：获取当前用户 ----------
async def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: Session = Depends(get_db)
) -> Student:
    """从 JWT 中提取用户身份，并从数据库查询完整用户信息"""
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Token 无效或已过期",
        headers={"WWW-Authenticate": "Bearer"},
    )
    payload = decode_token(token)
    if payload is None:
        raise credentials_exception

    username: str = payload.get("sub")
    if username is None:
        raise credentials_exception

    user = db.query(Student).filter(Student.name == username, Student.is_active == True).first()
    if user is None:
        raise credentials_exception
    return user

# ---------- 响应模型 ----------
class Token(BaseModel):
    access_token: str
    token_type: str = "bearer"

class UserInDB(BaseModel):
    id: int
    name: str
    email: str
    is_active: bool

    class Config:
        from_attributes = True

# 在 main.py 或 auth_router.py 中：
# @author xujl
@router.post("/token", response_model=Token)
def login(
    form_data: OAuth2PasswordRequestForm = Depends(),
    db: Session = Depends(get_db)
):
    """登录接口：验证用户名密码，返回 JWT"""
    user = db.query(Student).filter(Student.name == form_data.username).first()
    if not user or not verify_password(form_data.password, user.password_hash):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="用户名或密码错误",
            headers={"WWW-Authenticate": "Bearer"},
        )

    access_token = create_access_token(data={"sub": user.name})
    return {"access_token": access_token, "token_type": "bearer"}

@router.get("/me", response_model=UserInDB)
def read_me(current_user: Student = Depends(get_current_user)):
    """获取当前登录用户信息（需要认证）"""
    return current_user

使用认证：

# 在需要认证的路由中添加 Depends(get_current_user)
# @author xujl
@router.post("/students", response_model=StudentResponse)
def create_student_route(
    student: StudentCreate,
    db: Session = Depends(get_db),
    current_user: Student = Depends(get_current_user)
):
    """创建学生（需要登录）"""
    return crud.create_student(db, name=student.name, age=student.age,
                                score=student.score, email=student.email)

本章练习

启动本地 MySQL（或用 Docker：docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=root mysql:8）
配置 .env 文件连接 MySQL
完成带用户认证的 Todo API：注册、登录、增删改查（登录后才能操作）
用 /docs 界面测试带 Token 和不带 Token 的请求，验证认证逻辑

深度拓展：把演示接口推进到工程项目

场景引入：为什么内存数据不够用

内存版 API 重启后数据会消失，也无法支撑多人协作和长期业务记录。数据库的价值在于持久化、查询、约束和事务。学习本章时，要把数据库从“存数据的地方”讲成“业务事实的记录系统”。

深入理解：分层是为了减少混乱

后端项目变复杂后，所有代码写在 main.py 会很快失控。建议把项目拆成几层：

层次	负责内容
router	接收请求、返回响应
schema	定义请求和响应结构
model	定义数据库表结构
crud/service	封装业务操作
database	管理连接和会话
auth	认证、鉴权和用户身份

综合实战：数据库会话依赖

# @author xujl
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker


DATABASE_URL = "mysql+pymysql://root:password@127.0.0.1:3306/app?charset=utf8mb4"

engine = create_engine(DATABASE_URL, pool_pre_ping=True)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)


def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

这段代码必须讲清楚两个点：第一，每个请求应该拿到独立会话；第二，请求结束后必须关闭连接。否则项目运行一段时间后，数据库连接会被耗尽。

认证流程讲解

JWT 认证可以按四步讲：

用户提交用户名和密码。
后端校验密码，生成带过期时间的 Token。
前端后续请求把 Token 放在请求头。
后端解析 Token，得到当前用户身份。

课程中要强调：JWT 不是加密用户数据的保险箱，它更像带签名的身份凭证。敏感信息不要直接塞进 Token。

本章能力检查

读者应能完成一个带数据库持久化和登录认证的 Todo API。至少包含用户注册、登录、创建任务、查询任务、更新任务、删除任务六个接口。

示例代码加练：数据库与认证的工程细节

示例一：环境变量读取配置

# @author xujl
import os
from dataclasses import dataclass


@dataclass
class Settings:
    db_host: str
    db_port: int
    db_name: str
    secret_key: str


def load_settings():
    return Settings(
        db_host=os.getenv("DB_HOST", "127.0.0.1"),
        db_port=int(os.getenv("DB_PORT", "3306")),
        db_name=os.getenv("DB_NAME", "smart_backend"),
        secret_key=os.getenv("SECRET_KEY", "dev-only-secret"),
    )


settings = load_settings()
print(settings)

[执行结果]
Settings(db_host='127.0.0.1', db_port=3306, db_name='smart_backend', secret_key='dev-only-secret')

示例二：密码哈希与校验

# @author xujl
from passlib.context import CryptContext


pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")


def hash_password(password):
    return pwd_context.hash(password)


def verify_password(password, password_hash):
    return pwd_context.verify(password, password_hash)


hashed = hash_password("Python@2026")
print(verify_password("Python@2026", hashed))
print(verify_password("wrong-password", hashed))

[执行结果]
True
False

示例三：按当前用户过滤数据

# @author xujl
def list_user_todos(all_todos, current_user_id):
    return [
        todo for todo in all_todos
        if todo["owner_id"] == current_user_id
    ]


todos = [
    {"id": 1, "title": "学习 ORM", "owner_id": 1001},
    {"id": 2, "title": "复习 JWT", "owner_id": 1002},
    {"id": 3, "title": "整理接口文档", "owner_id": 1001},
]

print(list_user_todos(todos, current_user_id=1001))

[执行结果]
[{'id': 1, 'title': '学习 ORM', 'owner_id': 1001}, {'id': 3, 'title': '整理接口文档', 'owner_id': 1001}]

本章小结

本章的重点不是记住所有语法细节，而是建立稳定的工程判断：什么时候该拆函数、什么时候该建模型、什么时候该把配置、数据访问和业务逻辑分离。后续章节会在这个基础上逐步连接 Web 服务、数据库和 AI 应用。

Python 与 AI 后端开发地图