Python项目可维护性取决于代码是否易理解、易修改、易调试，核心是单一职责、显式依赖、精准异常处理和聚焦边界测试。
Python 项目可维护性不取决于代码是否“能跑”，而在于别人（或三个月后的你）能否快速看懂意图、安全修改逻辑、精准定位问题。
单一职责：函数/类只做一件事，且名字要直说它在做什么
一个函数承担多个角色（比如读文件 + 解析 JSON + 写日志 + 校验字段），会直接抬高阅读和测试成本。调用方无法预判副作用，改一处可能崩三处。
-
parse_user_config()比load_and_validate_config()更清晰——后者隐含了“校验”行为，但没说明校验什么、失败怎么处理 - 如果函数里出现
if mode == "debug"或if is_test_env:，大概率该拆：调试逻辑和主逻辑不该混在同一抽象层 - 类名带
Manager、Handler、Utils是危险信号，往往意味着职责模糊；换成UserSessionRefresher或LegacyCsvImporter更易理解
显式依赖：别让模块自己去 import 或读环境变量
函数内部硬编码 open("config.yaml") 或调用 os.getenv("DB_URL")，会让单元测试难写、部署配置难隔离、行为难预测。
- 把路径、连接串、超时值等作为参数传入，而不是在函数体里拼接或查环境 ——
def fetch_data(url: str, timeout: int = 30)比def fetch_data()更可控 - 用依赖注入替代全局状态：用
session: requests.Session参数代替函数内新建requests.Session()，方便 mock 和复用连接池 -
__init__.py中避免执行逻辑（如自动注册插件、加载配置），这类隐式行为会让导入顺序影响运行结果，也增加启动时间
错误处理不吞异常，也不裸抛底层细节
捕获 Exception 后只打日志不 re-raise，或者把 FileNotFoundError 直接抛给上层调用者，都会破坏错误传播链和可诊断性。
立即学习“Python免费学习笔记（深入）”；
- 只捕获你明确知道如何处理的异常类型，比如
json.JSONDecodeError可以转成InvalidConfigError并附带文件路径，但别 catch 住再 silent ignore - 不要用
except:或except Exception:做兜底——这会吞掉KeyboardInterrupt和SystemExit，导致 Ctrl+C 失效 - 自定义异常应继承
Exception（不是BaseException），并确保有清晰的__str__输出，比如包含输入参数或上下文 ID
测试边界比测试实现更重要
可维护的代码不是“被测覆盖率高”，而是“接口契约稳定、边界行为明确”。过度测试私有方法或实现细节，反而会阻碍重构。
- 优先为 public 函数写测试，覆盖空输入、非法输入、典型成功路径、关键失败路径（如网络超时、磁盘满）
- 避免断言具体错误消息内容，比如不用
assert "timeout" in str(e)；改用断言异常类型 + 关键属性，如assert isinstance(e, ConnectionError) - 用
pytest.mark.parametrize覆盖多组输入输出，比写十个相似 test 函数更易读、易扩；但别为了凑覆盖率加无意义的分支测试
真正拖慢维护节奏的，往往不是语法复杂度，而是那些“看起来没问题，但改完就出新 bug”的隐式耦合与模糊契约。每次提交前问一句：这个改动，别人不看实现，光看函数签名和 docstring，能猜对它干什么、不干什么、失败会怎样吗？
