一、基础知识

先说结论:永远不要用可变对象(如列表、字典、集合)作为函数的默认参数。

什么是"可变对象"?就是内容可以被原地修改的对象,典型的有 list、dict、set。相对地,数字、字符串、元组(内容不含可变元素时)是"不可变"的,改了就会生成新对象。

陷阱的现象是这样的:定义一个函数,让它的某个参数默认是空列表 [],函数内部往这个列表里追加元素。第一次调用结果正常,第二次调用却发现列表里"残留"了上次的数据。

原因藏在 Python 的函数机制里:默认参数的值是在函数被定义(def 语句执行)时计算的,只算一次,之后所有调用共享同一个对象。所以那个 [] 不是在每次调用时新建的,而是函数对象身上挂着的一个固定列表,被反复复用。你往里追加,它就一直增长。

这和其他一些语言"每次调用重新求值默认值"的行为不同,是 Python 初学者最容易踩的坑之一,而且因为它不会报错、只是结果悄悄错,往往到线上才暴露。

记住一句口诀:默认参数只绑定一次,可变默认值等于共享状态。

二、实操步骤

第 1 步:亲手复现这个陷阱

def add_item(item, bucket=[]):
    bucket.append(item)
    return bucket

print(add_item("a"))   # ['a']
print(add_item("b"))   # ['a', 'b']  —— 不是想要的 ['b']!
print(add_item("c"))   # ['a', 'b', 'c']

连续三次调用返回的是同一个不断增长的列表,这就是问题所在。

第 2 步:用 id() 证明它们共享同一个对象

def show_id(bucket=[]):
    print("bucket 的 id:", id(bucket))

show_id()   # 记下这个 id
show_id()   # 再次输出,id 完全相同

两次输出相同的 id,说明自始至终只有一个列表对象。

第 3 步:修复方案一——用 None 作为哨兵(最常用)

def add_item(item, bucket=None):
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket

print(add_item("a"))   # ['a']
print(add_item("b"))   # ['b']  —— 正常了

原理:把默认值设成不可变的 None,在函数内部检测它,若为 None 就现场新建一个列表。这样每次调用拿到的都是新对象。这是社区最推荐的写法。

第 4 步:修复方案二——默认参数传不可变对象,内部转换

def add_item(item, bucket=()):
    bucket = list(bucket)      # 每次都转成新的列表
    bucket.append(item)
    return bucket

print(add_item("a"))   # ['a']
print(add_item("b"))   # ['b']

元组是不可变的,可以安全作默认值;进入函数后复制成列表再操作。注意:这种方式会让调用方传入的列表也被复制,若你希望"传入的列表被原地修改",此法不适用。

第 5 步:修复方案三——用闭包或工厂函数封装状态

当你确实需要"在多次调用间保持一份共享状态"时,与其偷偷用默认参数实现,不如让意图变得清晰明确:

def make_collector():
    bucket = []
    def collect(item):
        bucket.append(item)
        return bucket
    return collect

collector = make_collector()
print(collector("a"))   # ['a']
print(collector("b"))   # ['a', 'b']  —— 这次共享是"故意的"

这样共享状态是显式设计,而不是隐藏的副作用。

第 6 步:写个测试防止回归

下面的测试针对本文最终采用的修复版本(即第 3 步的 None 哨兵写法):

def test_add_item_isolated():
    first = add_item("a")
    second = add_item("b")
    assert first == ["a"]
    assert second == ["b"]
    assert first is not second
    print("通过:每次调用返回独立列表")

用 pytest 或简单的 assert 都能固化这个行为,避免后来有人把代码改回错误的写法。

三、关键细节

  • 不止是列表:dict、set 以及任何可变对象作默认值都有同样问题,例如 def f(config={}): 也是坑。
  • 不可变类型作默认值是安全的:None、数字、字符串、元组(且内部无可变元素)都可以放心使用。
  • is None 而不是 == None:检测哨兵值要用 is,这是判断对象身份的正确方式。
  • 方案一的边界:如果调用方真的想传一个空列表并让它被原地修改,bucket=None 的写法仍然支持——显式传入 [] 时 bucket is None 为假,会直接使用传入的列表。
  • 函数定义时机很关键:默认值在 def 执行时求值,所以把函数写在循环或反复执行的模块里,也可能产生非预期的共享,需留意。

四、常见错误

现象 原因 修正
多次调用结果不断累积旧数据 用了可变默认参数,对象被共享 改用 None 哨兵,函数内新建对象
改用一个新空列表仍复现 只是重新赋值了默认值,函数体里还在原地修改旧对象 检查函数体逻辑,确保每次新建而不是复用
用 == None 判断不够稳妥(风格问题) is 判断对象身份更准确,且不受自定义 __eq__ 重载影响 统一改用 is None
修复后调用方传入的列表不再被修改 用了"元组转列表"方案,导致传入对象被复制 改用 None 哨兵方案,保留原地修改语义
字典默认值导致数据串台 def f(d={}): 与列表同理 同样改为 d=None 再新建
测试时单独跑正常、连跑就错 测试用例共享了同一个默认对象 每个用例独立构造数据,加入 is not 断言

五、排查方法

怀疑代码踩了这个坑,按下面步骤定位:

  1. 搜可疑默认值:全局搜索 def .*=[]、={}、=set( 这类写法,优先排查。
  2. 连续调用复现:写一个脚本连续调用两次目标函数,打印两次返回值,看是否互相影响。
  3. 打印 id:在函数里 print(id(参数)),多次调用对比,id 相同即共享同一对象。
  4. 检查函数体:确认是否有 append、update、add 等原地修改默认参数的操作。
  5. 缩小范围:若函数参数很多,逐个排除,定位到具体是哪个参数在"积累"。
  6. 加断言固化:按第 6 步写测试,明确断言每次调用返回独立对象。
  7. 静态检查:使用代码检查工具自动发现可变默认参数,如 pylint 的 W0102;flake8 本身没有此规则,需安装 flake8-bugbear 插件才有 B006(具体配置以官方文档为准)。

六、注意事项

  • 本文行为以 Python 3 语言规范为准,"默认参数求值一次"是语言层面的定义,不会因小版本改变,但相关静态检查工具的名称与规则号请以官方文档为准。
  • 不要把共享当巧合:有些代码"碰巧"依赖共享默认参数来缓存数据,这种写法脆弱且难维护,应改为显式的缓存或闭包设计。
  • 多线程场景更危险:共享的可变默认值在并发调用下可能产生数据竞争,修复它也是线程安全的基本要求。
  • 与他人协作时写清意图:若确实需要共享状态,用命名清晰的变量或闭包表达,避免后来者误以为是 bug 而"修坏"。
  • 安全提示:该陷阱本身不涉及安全问题,但由它引发的状态污染可能污染缓存、权限列表等敏感数据结构,值得认真对待。

免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。