常见 Bug 排查——Python 中 mutable default argument 陷阱（可变默认参数导致的共享状态Bug）

> 🔴 **严重程度：高** | 分类：Python 陷阱 | 2026-05-16

## Bug 现象

你写了一个简单的函数，用一个空列表作为默认参数。第一次调用一切正常，但第二次调用时，返回值竟然"记住"了上次的结果！

```python
def append_item(item, bucket=[]):
    bucket.append(item)
    return bucket

print(append_item("a"))  # ['a'] ✅
print(append_item("b"))  # ['a', 'b'] ❌ 期望 ['b']！
```

这绝不是你想要的行为——每次调用都应该从空列表开始，但实际上所有调用共享了同一个列表对象。

![Bug复现流程图](/media/202605/2026-05-16_190557_5876310.09986299418423517.png)

## 复现步骤

1. 定义一个函数，使用可变对象（`list`、`dict`、`set`）作为默认参数
2. 在函数体内修改该默认参数
3. 不传参数调用两次
4. 观察第二次调用的结果被第一次调用"污染"

```python
def register(user, db={}):
    db[user] = True
    return db

register("alice")  # {'alice': True}
register("bob")    # {'alice': True, 'bob': True} ❌
```

## 根因分析

Python 的默认参数值在**函数定义时**（而非调用时）求值一次，并绑定到函数对象的 `__defaults__` 属性上。

![根因分析图](/media/202605/2026-05-16_190558_5370980.6612265190579586.png)

```python
def foo(x=[]):
    x.append(1)
    return x

# 证据：默认参数是函数对象的属性
print(foo.__defaults__)  # ([1],)  ← 被污染了！
print(id(foo.__defaults__[0]))  # 同一个对象
```

**核心机制**：
- 函数定义时，`[]` 被创建一次，存入 `foo.__defaults__`
- 每次调用 `foo()` 不传参数时，`x` 指向**同一个**列表对象
- 在函数内修改 `x`，就是修改这个共享对象
- 这个对象在函数调用之间持久存在

**为什么 `int`、`str` 没这个问题？** 因为它们是不可变类型。你无法"修改"一个整数，只能重新赋值——而重新赋值只是让局部变量指向了新对象，不影响 `__defaults__`。

## 修复方案

### 修复前 vs 修复后

![修复前后对比图](/media/202605/2026-05-16_190558_0405400.7518958969134906.png)

### 方案一：使用 None 作为哨兵值（推荐）

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

print(append_item("a"))  # ['a'] ✅
print(append_item("b"))  # ['b'] ✅
```

**原理**：每次调用时，`bucket` 默认指向 `None`（不可变），在函数体内创建新的列表。每次调用都使用独立的列表对象。

### 方案二：使用工厂函数

```python
def append_item(item, bucket_factory=list):
    bucket = bucket_factory()
    bucket.append(item)
    return bucket
```

### 方案三：强制要求显式传参

```python
def append_item(item, bucket):  # 没有默认值
    bucket.append(item)
    return bucket

append_item("a", [])  # 调用者必须显式创建
```

## 预防措施

1. **永远不要用可变对象作为默认参数**——`list`、`dict`、`set`、`bytearray`、自定义对象都不行
2. **使用 `None` 作为哨兵值**，在函数体内创建新的可变对象
3. **启用 linter 检查**——`flake8-bugbear` 的 `B006` 规则会自动检测可变默认参数：
   ```bash
   pip install flake8-bugbear
   flake8 your_code.py  # B006: Do not use mutable data structures for argument defaults
   ```
4. **Code Review 清单**中加入"可变默认参数"检查项
5. **单元测试覆盖**——确保同一函数连续调用不会产生状态泄漏

### flake8 配置示例

```ini
[flake8]
extend-ignore = E501
select = B006
```

## 扩展阅读

- [Python 官方 FAQ: Why are default values shared between objects?](https://docs.python.org/3/faq/programming.html#why-are-default-values-shared-between-objects)
- [Effective Python (3rd Edition)](https://effectivepython.com/) — Item 24: Use None and Docstrings to Specify Dynamic Default Arguments
- [flake8-bugbear B006](https://github.com/PyCQA/flake8-bugbear#list-of-warnings) — 可变默认参数检测规则
- [Python __defaults__ 文档](https://docs.python.org/3/reference/datamodel.html#the-standard-type-hierarchy)

> 💡 **一句话总结**：Python 默认参数在定义时求值，不是调用时。可变默认参数 = 共享状态 = Bug。用 `None` 当哨兵，函数体内创建新对象。