Python函数设计关键在于符合习惯与场景需求，需避免可变默认参数、过度依赖全局变量、参数过多无结构、类型提示与文档不一致四大陷阱。
Python函数设计看似简单，但实际开发中常因细节疏忽导致隐蔽bug、性能下降或维护困难。关键不在语法对错，而在设计逻辑是否符合Python习惯和真实场景需求。
可变对象作默认参数
这是最经典也最容易踩的坑。用列表、字典等可变类型作默认参数，会导致多次调用时状态意外累积。
- 错误写法：def add_item(item, lst=[]): lst.append(item); return lst —— 第二次调用会复用第一次的list
- 正确做法：默认值设为None，函数内显式初始化：def add_item(item, lst=None): if lst is None: lst = []
- 原理：默认参数在函数定义时只创建一次，而非每次调用都新建
过度依赖全局变量或外部状态
函数隐式读写模块级变量或单例对象，会让行为不可预测、难以测试和复用。
- 避免在函数内部直接修改CONFIG、CACHE等全局对象
- 改用显式传参：def process(data, config=None, cache=None)，必要时提供合理默认值
- 若确实需共享状态，考虑封装为类，用实例方法管理生命周期
参数太多且缺乏分组或结构化
当函数参数超过4–5个，尤其是类型混杂（str、int、bool、dict），极易传错顺序或遗漏必填项。
立即学习“Python免费学习笔记（深入）”；
- 优先合并相关参数为数据类或命名元组：from typing import NamedTuple; class QueryOpts(NamedTuple): timeout: int; retries: int; verbose: bool
- 使用**kwargs要谨慎，除非是明确做透传（如装饰器、适配层），否则应明确定义接口
- 布尔参数名要表达正向语义：enable_logging 比 disable_logging 更不易出错
忽视类型提示与文档一致性
写了def func(x: str) -> int:，但实际接受None或bytes，或文档说“返回非负整数”却可能抛异常，都会误导调用方。
- 类型提示应反映真实行为，宁可宽松（Optional[str]）也不要虚假精确
- 文档字符串中明确写出边界条件：Raises ValueError if path is empty
- 用mypy做静态检查，比运行时才发现更早暴露不一致
