老项目重构最容易的错误起手式是“整体重写”。更现实的做法是先判断三件事:项目能不能在当前机器上稳定跑起来、有没有可以对比的行为基线、改动能不能分次上线并回退。这三条满足,重构才是工程动作;缺一条,先补条件。通常建议从“调用方少、改动频率高、逻辑相对独立”的模块切一小块,做等价替换后再动结构,而不是从最脏、最大的文件开始。
老项目重构能否推进,取决于有没有可重复的运行方式和可对比的行为基线,而不是代码有多脏。先确认“能启动、能复现输入输出、有回退路径”,再动手;从调用方少、改动频繁的模块切一小块,先做等价替换,再谈分层和抽象。缺少验证手段时,先补基线测试、固定依赖版本,这部分不能跳过,否则重构无法判断是否改变了行为。
先确认当前场景和目标
动手前先把“重构”翻译成一句可验收的话:是为了加新功能不被旧结构卡住、为了修某个反复出问题的模块、为了升级依赖或 Python 版本,还是单纯想让新人能读懂。目标不同,切入点和停手位置完全不同。升级解释器版本属于“行为必须等价”的改造,风险在兼容性;加功能属于“可以借机分层”的改造,风险在接口变更影响调用方。
需要先确认的信息,建议逐条打勾:
- 运行环境:依赖能否在本地或容器里装齐,是否有锁定的依赖清单,C 扩展类库是否有可用的轮子或编译条件。
- 入口清单:对外暴露的 HTTP 接口、定时任务、命令行脚本、被其他服务 import 的模块各有哪些,谁在调用。
- 行为基线:有没有测试;没有测试时,能否用真实输入跑一遍并记录输出,作为后续对比样本。
- 发布方式:能否灰度或按模块上线,出问题能否快速回退到旧实现。
- 数据边界:是否涉及数据库结构、序列化格式(如 pickle、JSON 字段)、对外协议,这些一旦变动影响面会超出代码本身。
可以先跑几条只读命令摸清现状,工具是否可用需要结合环境确认:
python -V
python -m pip freeze > requirements.before.txt
python -m compileall -q src/ # 确认是否存在语法层面的历史残留
python -m pytest -q --collect-only # 看现有测试能收集到多少
如果 compileall 就报错、依赖装不上、或者连启动命令都没人说得清,那当前任务不是重构,而是先做环境固定和启动脚本整理。这一步做完再回到重构,顺序不能反。

按这个顺序处理
建议按“固定环境 → 建基线 → 划边界 → 小步等价改造 → 抽接缝”推进,每一步都可单独提交、单独回退。
- 固定运行环境。把依赖版本写进锁文件,容器或虚拟环境固化;这一步只做记录,不改代码逻辑。
- 建立行为基线。对准备改的模块,用一批真实或构造的输入跑出输出并保存,形成可以反复对比的样本。没有测试框架时,一个脚本加 JSON 样本也能用。
- 划边界。明确本次“改哪些文件、不改哪些文件”,把跨模块的隐式依赖(全局变量、模块级连接、单例、猴子补丁)列出来,这些是后面最容易出错的地方。
- 先做机械化改造。格式化、告警清理、语法现代化这类改动不带逻辑变化,先做完能减少后续 diff 噪音。合并提交时不要和逻辑改动混在一起。
- 再做等价替换。每次只替换一个依赖或一段逻辑,改完立刻用基线样本比对输出。
- 最后抽接缝。把难以测试的全局依赖改成可传入的参数或工厂,让模块能被单独测试。
典型的接缝改造,把模块级连接改成可注入,改造前后行为保持一致,但测试时可以传假对象:
# 改造前:模块导入即建立连接,测试无法替换
CONN = create_conn()
def calc_price(uid):
cur = CONN.cursor()
...
# 改造后:连接由调用方或工厂提供,默认行为不变
def calc_price(uid, conn=None):
conn = conn or get_default_conn()
cur = conn.cursor()
...
对应的基线比对脚本可以很朴素,关键是能重复执行、结果可读:
import json
cases = [json.loads(l) for l in open("cases.jsonl", encoding="utf-8")]
for c in cases:
got = calc_price(**c["input"])
if got != c["expected"]:
print("DIFF", c["input"], c["expected"], got)
判断项很直接:diff 为空或差异都在事先说明的范围内,才允许进入下一步;出现意外差异,先停下来确认是不是旧代码本身有隐藏依赖(例如依赖 dict 顺序、依赖本地时区、依赖数据库当前数据)。

改完后怎么验证
验证要覆盖“行为、接口、运行”三个层面,而不是只看程序没报错。
- 行为比对:用同一批样本分别跑旧实现和新实现,逐条比较输出,允许的差异要事先列出并说明原因。
- 接口兼容:确认对外函数签名、返回结构、异常类型没变;被其他模块 import 的路径仍然可用。可以先用 grep 找出所有调用点再改。
- 静态检查:在改动范围内跑类型检查和 lint,关注“新增”的告警而不是历史遗留告警,避免一次改出一大片。
- 运行观察:上线后看日志中的异常堆栈、关键分支命中情况、任务耗时是否与改造前处于同一量级。这里只做同环境对比,不预设提升幅度。
- 回退演练:确认旧实现还留着、开关能切回、数据格式双向兼容,再宣布这次重构结束。
预期信号是:基线样本零差异或差异可解释、调用方没有报错、日志里没有新增的异常类型、回退路径可用。如果只能证明“跑起来了”,那还不能算验证完成。
容易忽略的边界
老项目里一批问题不在语法层,而在运行时的隐含假设,改之前先确认:
- 版本与兼容性:Python 2 到 3 的字符串与字节差异、除法语义、dict 顺序假设、异常链写法;旧版第三方库的行为可能与新版本不同,升级依赖要和改代码分开做。
- 序列化与数据:pickle 依赖类路径,改名或移动模块会导致旧数据无法反序列化;数据库字段、缓存里的 JSON 结构变动需要考虑存量数据。
- 动态行为:getattr 反射、monkey patch、元类、插件式 import,静态搜索很难找全,改动前需要在实际运行中打点确认。
- 权限与环境:数据库账号权限、文件读写路径、定时任务执行用户、CI 上的构建权限,这些在老项目里常和生产不一致。
- 编码与时间:依赖系统 locale 的编码处理、本地时区与 UTC 混用,跨机器运行时表现可能不同。
不适用的情形也要说清:如果模块正在被高频改动、或者与线上资金、强一致性流程强耦合,不建议顺手做结构重构,先把逻辑改动单独上线;如果缺少任何可对比的基线,也不建议直接删代码或换实现,先补样本。回退建议是保留旧入口作为默认实现,用配置或开关切到新实现,确认稳定后再清理旧代码,而不是一次性删除。