Python代码热重载

Python 代码热重载详解
==============================

热重载（Hot Reload）让开发服务器在代码变更时自动重启，无需手动
中断再启动。本文介绍 watchfiles、uvicorn、watchdog 等方案。

一、watchfiles —— 轻量级文件监控
---------------------------------

# watchfiles 是 Rust 实现的高性能文件监控库
# pip install watchfiles

# watch 函数 —— 监控文件变更并执行回调
from watchfiles import watch

def on_change(changes):
# changes 是变更集列表
# 每个元素为 (change_type, path) 元组
for change_type, path in changes:
if change_type == "modified":
print(f"文件已修改: {path}")
elif change_type == "added":
print(f"文件已添加: {path}")
elif change_type == "deleted":
print(f"文件已删除: {path}")

# 持续监控当前目录
for changes in watch("./src", callback=on_change):
# watch 返回生成器，每次变更产生一组 changes
pass

# 使用过滤器监控特定文件类型
for changes in watch(
"./src",
watch_filter=lambda path: path.endswith(".py"),
):
print(f"Python 文件变更: {changes}")

二、run_process —— 自动重启子进程
----------------------------------

# watchfiles.run_process 监控文件并在变更时重启进程

from watchfiles import run_process

def start_server():
# 定义需要运行的进程
import uvicorn
uvicorn.run("app:app", host="0.0.0.0", port=8000)

# 监控 src 目录，文件变更时自动重启
run_process("./src", target=start_server)

# 增加过滤和参数控制
run_process(
"./src",
target=start_server,
# 监视的文件类型
watch_filter=lambda path: path.endswith((".py", ".yaml")),
# 重启延迟（秒）
step=500,
# 不递归监控
recursive=True,
)

# 在命令行中使用
# watchfiles "uvicorn app:app --reload" ./src

三、uvicorn 热重载
------------------

# uvicorn 内置热重载功能（基于 watchfiles）

# 命令行方式
# uvicorn app:app --reload

# 指定监控目录
# uvicorn app:app --reload --reload-dir ./src

# 指定监控文件类型
# uvicorn app:app --reload --reload-include "*.py" --reload-include "*.yaml"

# 排除监控文件
# uvicorn app:app --reload --reload-exclude "*.pyc" --reload-exclude "tests/*"

# Python 代码中启动
import uvicorn

if __name__ == "__main__":
uvicorn.run(
"app:app",
host="0.0.0.0",
port=8000,
reload=True,
reload_dirs=["./src", "./config"],
reload_includes=["*.py", "*.yaml"],
reload_excludes=["*.pyc", "tests/*"],
# 热重载使用的工作进程数
workers=1,
)

# uvicorn 的热重载在检测到 .py 文件变化时重新加载
# Python 模块，适合 FastAPI / Flask 等 ASGI 应用

四、watchdog —— 跨平台文件监控
-------------------------------

# watchdog 是 Python 实现的跨平台文件系统监控库
# pip install watchdog

# 使用 watchdog 监控目录
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class CodeChangeHandler(FileSystemEventHandler):
# 自定义事件处理器
def on_modified(self, event):
# 文件修改时的回调
if event.src_path.endswith(".py"):
print(f"Python 文件变更: {event.src_path}")

def on_created(self, event):
# 文件创建时的回调
print(f"新建文件: {event.src_path}")

def on_deleted(self, event):
# 文件删除时的回调
print(f"删除文件: {event.src_path}")

def on_moved(self, event):
# 文件移动时的回调
print(f"文件移动: {event.src_path} -> {event.dest_path}")

# 启动文件监控
observer = Observer()
observer.schedule(
CodeChangeHandler(),
path="./src",
recursive=True, # 递归监控子目录
)
observer.start()

try:
# 保持主线程运行
import time
while True:
time.sleep(1)
except KeyboardInterrupt:
observer.stop()
observer.join()

五、Flask 开发服务器热重载
--------------------------

# Flask 开发服务器自带热重载
"""
from flask import Flask

app = Flask(__name__)

# 启用 debug 模式自动开启热重载
if __name__ == "__main__":
app.run(debug=True)
# 或者指定端口
# app.run(debug=True, port=5000)
"""

# Flask 的 extra_files 参数
"""
app.run(
debug=True,
extra_files=[
"config.yaml",
".env",
],
# 监控额外文件变化也会触发重载
)
"""

# 使用 flask CLI
# export FLASK_APP=app.py
# export FLASK_DEBUG=1
# flask run

六、自定义热重载服务器
----------------------

# 使用 watchfiles 实现自定义热重载服务器
"""
import sys
import subprocess
from watchfiles import watch

def run_dev_server():
# 启动 FastAPI 应用
process = subprocess.Popen(
[sys.executable, "-m", "uvicorn", "app:app", "--host", "0.0.0.0"],
)
try:
# 监控文件变化
for changes in watch("./src"):
print("检测到文件变更，重启服务器...")
process.terminate()
process.wait()
process = subprocess.Popen(
[sys.executable, "-m", "uvicorn", "app:app", "--host", "0.0.0.0"],
)
except KeyboardInterrupt:
process.terminate()
process.wait()

if __name__ == "__main__":
run_dev_server()
"""

七、热重载最佳实践
------------------

# 1. 生产环境不应使用热重载
# 热重载仅供开发环境使用，会降低性能和安全性

# 2. 合理设置监控范围
"""
# 仅监控源代码目录
uvicorn app:app --reload --reload-dir ./src

# 不要监控虚拟环境
# --reload-exclude ".venv/*"
"""

# 3. 重启策略
"""
from watchfiles import run_process

def start_app():
uvicorn.run(
"app:app",
host="0.0.0.0",
port=8000,
# 生产环境设置 reload=False
reload=False,
)

# 开发时使用 run_process
if __name__ == "__main__":
run_process("./src", target=start_app)
"""

# 热重载将编辑-重启-验证循环从分钟级别缩短到秒级，
# 保持开发心流，是现代 Python Web 开发的标配工具。