Python项目不可维护的根源在于代码组织混乱、依赖失控、测试缺失、文档断层四大问题；需按业务域划分包结构、用虚拟环境+锁定文件管理依赖、为关键路径补测试并设覆盖率门禁、用docstring和Sphinx自动化文档。
Python 项目变“不可维护”，往往不是因为语言本身，而是随着规模增长、人员更替和需求迭代，一些关键习惯和设计选择被忽视或妥协所致。核心问题通常集中在代码组织混乱、依赖失控、测试缺失、文档断层这四个层面。
模块与包结构随意膨胀
初期一个 main.py 能跑通，后期变成几十个同级脚本，函数跨文件硬引用，__init__.py 空着不管，子模块职责模糊。比如数据处理逻辑散在 utils.py、helpers.py、preprocess.py 里，没有明确边界。
- 按业务域或功能层划分包（如 core/、api/、models/），而非按技术类型堆砌
- 每个包内提供清晰的公共接口（通过 __all__ 或显式 __init__.py 导出）
- 避免跨多层包直接导入（如 from project.src.utils.helpers import x → 应收敛到包入口
依赖管理松散且版本漂移
用 pip install xxx 直接装到全局或虚拟环境，requirements.txt 手动更新、不锁版本，或混用 pip 和 conda。结果是“在我机器上能跑”成为常态，CI 构建频繁失败。
- 始终使用虚拟环境，配合 pip-tools 或 poetry 生成锁定文件（requirements.txt 或 poetry.lock）
- 区分运行时依赖与开发依赖（pyproject.toml 中分组声明）
- 定期检查过时包（pip list --outdated），但升级前需验证兼容性，尤其对 numpy、pandas 等底层库
测试覆盖不足且难以持续运行
单元测试只测 happy path，集成测试缺失，mock 不当导致测试看似通过实则失效；CI 中测试被跳过、超时被忽略、覆盖率报告从不查看。久而久之，没人敢动核心函数——因为“不知道改了会不会崩”。
立即学习“Python免费学习笔记（深入）”；
- 为关键路径（如数据输入解析、模型预测接口、状态转换）优先补测试，哪怕先写桩
- 用 pytest + pytest-cov 做轻量覆盖统计，设最低阈值（如核心模块 ≥70%）并纳入 CI 门禁
- 避免测试强依赖外部服务；用 responses、pytest-mock 或真实轻量 fixture（如 SQLite 内存 DB）隔离依赖
文档与代码长期脱节
README 只有“如何安装”，函数没 docstring，API 变更不更新 Swagger 注释，团队新人靠翻 Git 历史猜逻辑。最典型的是配置项：环境变量名、默认值、是否必填，全靠口口相传。
- 每个公开函数/类加简洁 docstring（Google 或 NumPy 风格），说明作用、参数、返回、异常
- 用 sphinx + sphinx-autodoc 自动从代码生成 API 文档，并随 CI 构建发布
- 配置项集中管理（如 pydantic-settings），通过模型校验+注释自动生成配置说明
不复杂但容易忽略：可维护性不是上线后才开始的事，而是从第一个 commit 就该埋下的习惯。每次合并前问一句——这段代码，三个月后的我能否不看上下文就懂它在做什么、为什么这么做、改了哪里会出问题。
