目录
一、从“能跑就行”到“能改不怕”——维护性的第一要义
二、单一职责与最小惊讶——维护性的纵深防御
三、可组合的乐高——复用性的第一阶梯
四、面向协议设计——复用性的第二阶梯
五、异常策略与日志——维护性的隐形护盾
七、测试金字塔——维护性的最后护城河
结语
前言
在软件工程里，代码不是写完即弃的一次性草稿，而是需要持续演进、多人协作、不断复用的资产。Python 以简洁语法著称，但若把简洁误当成随意，很容易写出“今天能用、明天就炸”的胶水脚本。本文围绕“维护性”与“复用性”这两个核心属性，通过递进式示例，演示如何把一个 20 行的“一次性脚本函数”逐步重构为可测试、可组合、可演进的通用组件。文章将避免教条式说教，所有结论都源于可运行的代码片段，读者可直接粘贴到 REPL 中体验。
一、从“能跑就行”到“能改不怕”——维护性的第一要义
想象我们接到一个需求：从 CSV 中提取销售额大于阈值的记录，并生成 JSON 文件。新手工程师往往一气呵成：
def do_it():import csv, jsonwith open('sales.csv') as f:rows = [r for r in csv.DictReader(f) if float(r['amount']) > 1000]with open('out.json', 'w') as f:json.dump(rows, f, ensure_ascii=False)
do_it()这段代码的问题在于：所有行为都耦合在函数内部。阈值 1000 是硬编码，文件名写死，异常被吞掉。三天后产品说“阈值要改成 500”，我们不得不打开源码、修改字面量、重新部署——维护成本陡增。
维护性的第一步是参数化。把可变部分抽成形参：
import csv
import json
from pathlib import Pathdef extract_big_sales(src: str | Path, dst: str | Path, threshold: float = 1000.0):src, dst = Path(src), Path(dst)with src.open(newline='') as f:rows = [r for r in csv.DictReader(f) if float(r['amount']) > threshold]with dst.open('w', encoding='utf-8') as f:json.dump(rows, f, ensure_ascii=False, indent=2)现在阈值、路径都成了可注入的“旋钮”，单元测试也能轻松覆盖各种边界值。注意类型注解与 pathlib 的引入：IDE 能即时提示，跨平台路径拼接不再踩坑。
二、单一职责与最小惊讶——维护性的纵深防御
参数化只是起点。随着需求膨胀，函数仍可能变成“瑞士军刀”——内部混杂数据读取、清洗、过滤、序列化等多重职责。一旦某一步骤出错，定位如同大海捞针。
解决之道是拆分职责。把“读 CSV”和“转 JSON”拆成独立函数，再用一个高阶函数把它们串起来：
from typing import Iterable, Dict, Anydef read_sales(src: Path) -> Iterable[Dict[str, Any]]:with src.open(newline='') as f:yield from csv.DictReader(f)def filter_by_threshold(records: Iterable[Dict[str, Any]], threshold: float
) -> Iterable[Dict[str, Any]]:for r in records:if float(r['amount']) > threshold:yield rdef write_json(records: Iterable[Dict[str, Any]], dst: Path) -> None:with dst.open('w', encoding='utf-8') as f:json.dump(list(records), f, ensure_ascii=False, indent=2)拆分后，每个函数名就是其契约，阅读者无需深入实现即可理解意图。更重要的是，它们都返回惰性迭代器，内存占用与源文件大小解耦。
三、可组合的乐高——复用性的第一阶梯
复用性并非“复制粘贴”，而是“像积木一样插拔”。上一步的三个小函数已经具备可组合特性，我们可以用不同的方式拼装：
def pipeline(src, dst, threshold):write_json(filter_by_threshold(read_sales(src), threshold),dst)若需求变成“先过滤，再按金额排序，再取前 100 条”，只需在 pipeline 中再插入一个排序步骤即可，其他函数零改动。
四、面向协议设计——复用性的第二阶梯
当函数需要适应更多数据源时，可以把“读操作”抽象成协议。Python 3.8 引入的 Protocol 允许无继承的结构性子类型：
from typing import Protocol
from io import StringIOclass SalesReader(Protocol):def read(self) -> Iterable[Dict[str, Any]]: ...class CsvSalesReader:def __init__(self, src: Path):self.src = srcdef read(self):with self.src.open(newline='') as f:yield from csv.DictReader(f)class InMemorySalesReader:def __init__(self, text: str):self.text = textdef read(self):yield from csv.DictReader(StringIO(self.text))现在 filter_by_threshold 不再依赖具体实现，而只依赖 SalesReader 协议。测试时可以注入轻量级的 InMemorySalesReader，无需触碰磁盘。
五、异常策略与日志——维护性的隐形护盾
生产代码需要优雅地失败。把异常策略收敛到一个地方，避免每个函数都写重复 try/except：
import logging
from functools import wrapslogging.basicConfig(level=logging.INFO)def log_exceptions(func):@wraps(func)def wrapper(*args, **kwargs):try:return func(*args, **kwargs)except Exception as e:logging.exception(f'{func.__name__} failed: {e}')raisereturn wrapper@log_exceptions
def read_sales(src: Path) -> Iterable[Dict[str, Any]]:...装饰器让横切关注点（日志、重试、指标）与业务逻辑解耦，后期若接入 Prometheus、Sentry 只需再加一层装饰器。
六、可演进的配置——复用性的第三阶梯
阈值、输出格式、字段映射，这些都会随业务变化。硬编码会让函数每次需求变更都“动刀”。使用 Pydantic 定义配置模型，把“可变”彻底外部化：
from pydantic import BaseModel, Fieldclass Config(BaseModel):src: Pathdst: Paththreshold: float = Field(gt=0)top_n: int | None = Nonesort_desc: bool = Truedef run(cfg: Config):records = read_sales(cfg.src)records = filter_by_threshold(records, cfg.threshold)if cfg.top_n:records = sorted(records, key=lambda r: float(r['amount']),reverse=cfg.sort_desc)[:cfg.top_n]write_json(records, cfg.dst)现在函数签名只剩一个 Config，所有细节都可由 YAML/JSON/TOML 注入。CI/CD 只需替换配置文件即可实现灰度发布。
七、测试金字塔——维护性的最后护城河
拆分后的纯函数天然易于单元测试：
from pytest import fixture@fixture
def sample():return [{'id': 1, 'amount': '900'},{'id': 2, 'amount': '1100'},{'id': 3, 'amount': '2000'},]def test_filter(sample):assert [r['id'] for r in filter_by_threshold(sample, 1000)] == [2, 3]协议抽象后，测试还能用假对象（Fake）或桩（Stub）实现毫秒级反馈，无需启动数据库或文件系统。测试越轻，重构越敢下手。
结语
函数的维护性与复用性不是“后期优化”的奢侈品，而是从第一行代码就开始积累的资产。通过参数化、职责拆分、协议抽象、配置外部化、异常收敛和测试保障，我们让函数从“一次性脚本”成长为“可演进的组件”。Python 的动态特性给了我们极大的灵活性，而真正的工程素养体现在：利用这种灵活性去构建“明天还能睡得着”的系统。愿你的每一行代码，都像乐高积木一样，既可独立把玩，又能无限拼接。
