Python技术债务治理是渐进式改进，核心为小步快跑：补关键路径测试、添加类型提示、拆解巨型函数、锁定依赖版本，每次改动聚焦一个问题且不破坏现有功能。
Python 技术债务治理不是一次性重构，而是通过可衡量、低风险、持续嵌入日常开发的渐进式改进。核心在于“小步快跑”——每次改动只聚焦一个具体问题，确保不破坏现有功能，同时让代码更易理解、测试和扩展。
从测试覆盖开始补缺口
没有测试的技术债就像蒙眼开车。先为关键路径（如核心计算逻辑、外部接口调用、数据转换函数）补充单元测试，不必追求100%，优先覆盖高频出错或近期修改过的模块。
- 用 pytest 写轻量断言，例如验证某个函数对空输入返回默认值、对异常输入抛出预期异常
- 借助 pytest-cov 查看覆盖率报告，重点关注“从未执行”的分支和条件判断
- 把“新增/修改代码必须带测试”写进团队 PR 检查清单，作为硬性门槛
用类型提示收敛隐式契约
Python 动态特性带来灵活性，也埋下大量运行时类型错误隐患。逐步添加 type hints 是成本最低、收益最高的治理动作之一。
- 从函数签名入手：给参数加类型、标注返回值，例如 def process_data(items: List[Dict[str, Any]]) -> pd.DataFrame:
- 配合 mypy 做静态检查，初始可设为宽松模式（--allow-untyped-defs），只校验已标注部分
- 在 CI 中运行 mypy，新提交不允许引入新的类型错误，存量问题打上 # type: ignore 并登记待办
拆解巨型函数与模糊命名
超过 30 行、含多层嵌套、变量名像 tmp 或 res 的函数，是典型的设计债。治理时不求一步重写，而用“提取+重命名”两步走。
立即学习“Python免费学习笔记（深入）”；
- 识别函数中语义独立的代码块（如“解析配置”“组装请求体”“处理响应异常”），用 Extract Method 提取为小函数
- 命名直指意图，避免 get_data_v2，改用 fetch_user_profile_from_api
- 每完成一次提取，立刻运行测试确认行为不变，再提交
约束依赖与环境漂移
requirements.txt 过于宽泛（如 requests>=2.0）、本地能跑线上报错，本质是环境债。需建立可复现、可审计的依赖管理习惯。
- 用 pip-compile（来自 pip-tools）从 requirements.in 生成带哈希的 requirements.txt，锁定精确版本
- 在 CI 和部署脚本中强制使用 pip install --require-hashes
- 将 Python 版本写入 pyproject.toml 的 requires-python = ">=3.9"，避免低版本兼容陷阱
技术债务不会消失，但可以变得可见、可控、可摊销。每一次加类型、补测试、拆函数、锁依赖，都是在为下次迭代减负。不复杂，但需要坚持。
