17370845950

Python项目可维护性取决于代码是否易理解、易修改、易调试，核心是单一职责、显式依赖、精准异常处理和聚焦边界测试。

Python 项目可维护性不取决于代码是否“能跑”，而在于别人（或三个月后的你）能否快速看懂意图、安全修改逻辑、精准定位问题。

单一职责：函数/类只做一件事，且名字要直说它在做什么

一个函数承担多个角色（比如读文件 + 解析 JSON + 写日志 + 校验字段），会直接抬高阅读和测试成本。调用方无法预判副作用，改一处可能崩三处。

• parse_user_config() 比 load_and_validate_config() 更清晰——后者隐含了“校验”行为，但没说明校验什么、失败怎么处理
• 如果函数里出现 if mode == "debug" 或 if is_test_env:，大概率该拆：调试逻辑和主逻辑不该混在同一抽象层
• 类名带 Manager、Handler、Utils 是危险信号，往往意味着职责模糊；换成 UserSessionRefresher 或 LegacyCsvImporter 更易理解

显式依赖：别让模块自己去 import 或读环境变量

函数内部硬编码 op

• 把路径、连接串、超时值等作为参数传入，而不是在函数体里拼接或查环境 —— def fetch_data(url: str, timeout: int = 30) 比 def fetch_data() 更可控
• 用依赖注入替代全局状态：用 session: requests.Session 参数代替函数内新建 requests.Session()，方便 mock 和复用连接池
• __init__.py 中避免执行逻辑（如自动注册插件、加载配置），这类隐式行为会让导入顺序影响运行结果，也增加启动时间

错误处理不吞异常，也不裸抛底层细节

捕获 Exception 后只打日志不 re-raise，或者把 FileNotFoundError 直接抛给上层调用者，都会破坏错误传播链和可诊断性。

• 只捕获你明确知道如何处理的异常类型，比如 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，能猜对它干什么、不干什么、失败会怎样吗？