Python函数中默认参数的使用技巧与常见陷阱详解

# 没有默认参数——每次都要传timeout
def http_get_v1(url, timeout):
    print(f"请求{url}，超时={timeout}秒")

http_get_v1("https://api.example.com", 30)
http_get_v1("https://api.example.com/users", 30)
http_get_v1("https://api.example.com/items", 30)  # 30这个值重复了无数次！

# ✅ 有默认参数——常用值只需写一次
def http_get_v2(url, timeout=30):
    print(f"请求{url}，超时={timeout}秒")

http_get_v2("https://api.example.com")                # 使用默认30秒
http_get_v2("https://api.example.com/users")          # 使用默认30秒
http_get_v2("https://api.example.com/bigfile", 120)   # 特殊情况，指定120秒

# 基本语法：在定义函数时给参数赋值
def greet(name, greeting="你好"):
    """向用户打招呼——greeting有默认值"你好\""""
    return f"{greeting}，{name}！"

# 不传greeting参数，使用默认值
print(greet("张三"))          # 你好，张三！
print(greet("李四"))          # 你好，李四！

# 传入greeting参数，覆盖默认值
print(greet("tom", "hello"))  # hello，tom！
print(greet("张三", "早上好")) # 早上好，张三！

# 💡 带默认值的参数是可选的——调用者可以不传

# 一个函数可以有多个带默认值的参数
def create_user_profile(
    username,
    age=18,
    city="未知",
    occupation="学生",
    bio="这个人很懒，什么都没写"
):
    """创建用户资料——只有username是必填的"""
    return {
        "username": username,
        "age": age,
        "city": city,
        "occupation": occupation,
        "bio": bio,
    }

# 灵活的调用方式
print(create_user_profile("zhangsan"))
# {'username': 'zhangsan', 'age': 18, 'city': '未知', 'occupation': '学生', 'bio': '这个人很懒，什么都没写'}

print(create_user_profile("lisi", age=25, city="北京"))
# {'username': 'lisi', 'age': 25, 'city': '北京', 'occupation': '学生', 'bio': '这个人很懒，什么都没写'}

print(create_user_profile("wangwu", age=30, city="上海", occupation="工程师", bio="全栈开发"))
# {'username': 'wangwu', 'age': 30, 'city': '上海', 'occupation': '工程师', 'bio': '全栈开发'}

# ⚠️ 规则：带默认值的参数必须放在无默认值参数之后
# 原因很简单：如果默认参数在前面，位置参数就没法正确对应了

# ✅ 正确：默认参数在后面
def func(a, b=1, c=2):
    pass

# ❌ 错误：默认参数在前面
# def func(a=1, b):
#     pass
# syntaxerror: non-default argument follows default argument

# 思考：如果允许默认参数在前面会怎样？
# def func(a=1, b):
#     pass
# func(2)  # 这个2应该给a还是b？python无法确定！

# 多个默认参数时也是一样
# ✅ 正确
def configure(host, port, debug=false, timeout=30, retries=3):
    """配置连接参数"""
    pass

# ❌ 错误
# def configure(host="localhost", port, debug=false):
#     pass
# syntaxerror: non-default argument follows default argument

def send_email(to, subject, body, cc=none, bcc=none, priority="normal", html=true):
    """发送邮件——很多可选参数"""
    print(f"发送邮件给: {to}")
    print(f"主题: {subject}")
    print(f"抄送: {cc}")
    print(f"密送: {bcc}")
    print(f"优先级: {priority}")
    print(f"html格式: {html}")

# 你可能只关心cc而不关心其他可选参数
send_email(
    "user@test.com",
    "会议通知",
    "明天下午3点开会",
    cc="manager@test.com"     # 只指定抄送，其他用默认值
)

# 你可能只关心priority
send_email(
    "admin@test.com",
    "紧急通知",
    "服务器异常，请立即处理！",
    priority="urgent"          # 只指定优先级
)

# 你可以同时指定多个可选参数
send_email(
    "user@test.com",
    "周报",
    "本周工作总结...",
    cc="leader@test.com",
    priority="high",
    html=false                  # 纯文本格式
)

# ⌨️ 证明：默认参数在定义时求值
print("===== 函数定义阶段 =====")

def demo_default(arg=print("默认值被计算了！")):
    print(f"函数被调用，arg={arg}")

print("===== 函数调用阶段 =====")
demo_default()
demo_default()
demo_default()

# 输出：
# ===== 函数定义阶段 =====
# 默认值被计算了！           <--- 注意！在定义时就打印了
# ===== 函数调用阶段 =====
# 函数被调用，arg=none       <--- 调用时不再计算默认值
# 函数被调用，arg=none
# 函数被调用，arg=none

# 💡 这意味着：默认值表达式只在def语句执行时计算一次
# 之后每次调用使用的都是同一个对象！

import time

# 默认值在def语句执行时就被确定了
def log_message(message, timestamp=time.time()):
    """记录日志消息"""
    print(f"[{timestamp}] {message}")

# 第一次调用
log_message("第一条消息")
time.sleep(1)  # 等待1秒

# 第二次调用——时间戳没有变！
log_message("第二条消息")

# 输出类似：
# [1717177200.123456] 第一条消息
# [1717177200.123456] 第二条消息    <--- 时间戳完全相同！
# 因为timestamp的默认值在定义函数时就固定了

# ✅ 如果你想要调用时的时间戳，应该这样写：
def log_message_v2(message, timestamp=none):
    """正确的方式：将默认值设为none，在函数体内部获取时间"""
    if timestamp is none:
        timestamp = time.time()
    print(f"[{timestamp}] {message}")

log_message_v2("第一条消息")
time.sleep(1)
log_message_v2("第二条消息")
# 现在两次调用的时间戳不同了！

import random

# ⚠️ 陷阱示例
def generate_id(prefix="user", random_suffix=random.randint(1000, 9999)):
    """生成用户id"""
    return f"{prefix}_{random_suffix}"

# 多次调用——随机后缀都相同！
print(generate_id())  # user_4521
print(generate_id())  # user_4521
print(generate_id())  # user_4521  <--- 全部一样！不是随机的！
# random.randint(1000, 9999) 只在def执行时调用了一次

# ✅ 正确做法：在函数体内部生成随机数
def generate_id_v2(prefix="user", random_suffix=none):
    """正确版本——每次调用都生成新的随机数"""
    if random_suffix is none:
        random_suffix = random.randint(1000, 9999)
    return f"{prefix}_{random_suffix}"

print(generate_id_v2())  # user_7342
print(generate_id_v2())  # user_1894
print(generate_id_v2())  # user_5621  <--- 每次都不一样

# ⚠️ 这是python中最著名的陷阱之一

# 你以为每次调用都会创建一个新的空列表
# 实际上：同一个列表对象被所有调用共享！
def add_item(item, target_list=[]):
    """将item添加到target_list中"""
    target_list.append(item)
    return target_list

# 第一次调用——看起来正常
print(add_item(1))  # [1]

# 第二次调用——咦？默认值居然保留了上次的数据？
print(add_item(2))  # [1, 2]    <--- 预期是[2]，实际是[1, 2]！

# 第三次调用——越来越多了！
print(add_item(3))  # [1, 2, 3] <--- 预期是[3]，实际是[1, 2, 3]！

# 第四次调用——传入自己的列表
print(add_item(4, []))  # [4]     <--- 这次没问题，但默认列表还在累积！
print(add_item(5))      # [1, 2, 3, 5]  <--- 默认列表还在！

# ⌨️ 深入理解：查看默认参数的"真身"

def add_item(item, target_list=[]):
    """问题函数"""
    target_list.append(item)
    return target_list

# 默认参数存储在函数的__defaults__属性中
print(add_item.__defaults__)  # ([],) ——看到了吗？就是一个列表对象

# 每次调用时，target_list都指向这个同一个列表对象
add_item(1)
print(add_item.__defaults__)  # ([1],) <--- 列表被修改了！

add_item(2)
print(add_item.__defaults__)  # ([1, 2],) <--- 继续累积！

# 💡 本质原因：
# 1. def语句执行时，创建了一个空列表[]
# 2. 这个列表对象被存储在函数的__defaults__中
# 3. 每次调用时，target_list引用的是同一个列表对象
# 4. append()操作修改的是这个共享的对象
# 5. 所以修改会"累积"到下一次调用

# 以下所有可变类型作为默认参数都会出现同样的问题

# ❌ 列表
def bad_list(data=[]):
    data.append(1)
    return data

# ❌ 字典
def bad_dict(data={}):
    data[len(data)] = "value"
    return data

# ❌ 集合
def bad_set(data=set()):
    data.add(len(data))
    return data

# ❌ 字节数组
def bad_bytearray(data=bytearray()):
    data.append(65)
    return data

# 验证——它们都有问题
print(bad_list())  # [1]
print(bad_list())  # [1, 1]  —— 问题！

print(bad_dict())  # {0: 'value'}
print(bad_dict())  # {0: 'value', 1: 'value'}  —— 问题！

print(bad_set())  # {0}
print(bad_set())  # {0, 1}  —— 问题！

# 不可变类型的默认参数不会出问题
def safe_str(data=""):      # str不可变
    data += "a"             # 创建了新字符串，不修改原对象
    return data

print(safe_str())  # "a"
print(safe_str())  # "a"  —— 没有问题，因为+=创建了新的字符串对象

# ✅ 标准做法：默认值用none，在函数体内部创建可变对象

# 列表
def add_item_v2(item, target_list=none):
    """安全版本——每次调用创建新列表"""
    if target_list is none:
        target_list = []    # 在函数体内部创建，每次调用都是新列表
    target_list.append(item)
    return target_list

print(add_item_v2(1))   # [1]
print(add_item_v2(2))   # [2]     <--- 每次都是新的！
print(add_item_v2(3))   # [3]     <--- 符合预期！

# 字典
def update_config(key, value, config=none):
    """安全更新配置"""
    if config is none:
        config = {}
    config[key] = value
    return config

print(update_config("debug", true))     # {'debug': true}
print(update_config("timeout", 30))     # {'timeout': 30}  每次都是新字典

# 集合
def add_tags(new_tags, existing_tags=none):
    """安全添加标签"""
    if existing_tags is none:
        existing_tags = set()
    if isinstance(new_tags, str):
        new_tags = {new_tags}
    existing_tags.update(new_tags)
    return existing_tags

print(add_tags("python"))              # {'python'}
print(add_tags("javascript"))          # {'javascript'}

# 场景：你的函数确实需要区分"调用者没传"和"调用者传了none"

# 问题场景
def process_data(data, options=none):
    """处理数据"""
    if options is none:
        options = {"mode": "fast", "validate": true}
    # 如果调用者真的想传options=none怎么办？
    # 你无法区分"没传"和"传了none"这两种情况！

    return f"处理数据，选项={options}"

# 调用者想传none表示"不需要任何选项"
# process_data(my_data, options=none)
# 但options=none在函数内部被替换成了默认的字典！

# ✅ 解决方案：使用一个独一无二的哨兵对象
# 哨兵对象（sentinel object）——专门用来标记"没有传参"的情况
_unset = object()  # object()创建一个独一无二的对象

def process_data_v2(data, options=_unset):
    """使用哨兵对象区分"没传"和"传了none\""""
    if options is _unset:
        options = {"mode": "fast", "validate": true}  # 默认值
    # 如果调用者传了options=none，options就不是_unset，而是none
    return f"处理数据，选项={options}"

print(process_data_v2("data"))          # 使用默认选项
print(process_data_v2("data", none))    # 明确传none——表示不需要选项
print(process_data_v2("data", {"mode": "slow"}))  # 自定义选项

# 💡 其他哨兵值
# 也可以用专门的枚举或类
class default:
    """用作哨兵的类"""
    pass

def my_func(arg=default):
    if arg is default:
        arg = "默认值"
    return arg

# python内置的ellipsis（...）也可以作为哨兵值
# 尤其是在类型提示广泛的现代python代码中

def search_database(
    query,
    fields=...    # ... 表示"所有字段"
):
    """搜索数据库"""
    if fields is ...:
        fields = ["*"]  # 默认查询所有字段
    elif fields is none:
        fields = []     # 不查询任何字段

    return f"查询: {query}, 字段: {fields}"

print(search_database("select * from users"))      # 使用默认：所有字段
print(search_database("select * from users", none)) # 明确不选字段
print(search_database("select * from users", ["name", "age"]))  # 指定字段

# 虽然可变默认参数是个陷阱，但有时我们正好需要这个"记忆"效果

# 场景：给每个函数调用分配一个递增的id
def get_next_id(_counter=[0]):
    """生成递增的id"""
    _counter[0] += 1
    return _counter[0]

print(get_next_id())  # 1
print(get_next_id())  # 2
print(get_next_id())  # 3
print(get_next_id())  # 4

# ⚠️ 这个技巧利用了可变默认参数的"记忆"特性
# 虽然可行，但不够显式——很多开发者会被迷惑
# 更推荐的写法是使用闭包或类：

# ✅ 更好的实现：使用闭包
def make_counter(start=0):
    """使用闭包创建计数器"""
    count = start
    def counter():
        nonlocal count
        count += 1
        return count
    return counter

next_id = make_counter()
print(next_id())  # 1
print(next_id())  # 2

# ✅ 或者使用类——最清晰的实现
class counter:
    def __init__(self, start=0):
        self.count = start

    def next(self):
        self.count += 1
        return self.count

id_counter = counter()
print(id_counter.next())  # 1
print(id_counter.next())  # 2

# ⚠️ 默认参数不能引用其他参数——因为它们在定义时求值
# def func(a, b=a):   # nameerror: name 'a' is not defined
#     pass

# ✅ 如果需要这种效果，用none做哨兵值
def create_date_range(start_date, end_date=none, step=1):
    """创建日期范围，end_date默认与start_date相同"""
    if end_date is none:
        end_date = start_date  # 在函数体内部引用另一个参数

    return f"从{start_date}到{end_date}，步长={step}"

print(create_date_range("2024-01-01"))
# 从2024-01-01到2024-01-01，步长=1

print(create_date_range("2024-01-01", "2024-01-31"))
# 从2024-01-01到2024-01-31，步长=1

# 复杂场景：默认值依赖于多个参数的计算结果
def setup_logger(name, log_level=none, log_file=none):
    """设置日志器，log_level默认根据name推断"""
    if log_level is none:
        # 如果name中包含"debug"，默认用debug级别
        if "debug" in name.lower():
            log_level = "debug"
        else:
            log_level = "info"

    if log_file is none:
        log_file = f"logs/{name}.log"

    return f"日志器[{name}]：级别={log_level}，文件={log_file}"

print(setup_logger("app"))
# 日志器[app]：级别=info，文件=logs/app.log

print(setup_logger("debug_module"))
# 日志器[debug_module]：级别=debug，文件=logs/debug_module.log

# 场景：api函数，向后兼容
# 假设你最初设计的函数接受一个name参数
def greet_v1(name):
    return f"hello, {name}!"

# 后来你想增加语言支持，但不想破坏现有调用代码
def greet_v2(name, language="en"):
    """向后兼容的升级——原来的调用方式仍然有效"""
    greetings = {
        "en": "hello",
        "zh": "你好",
        "ja": "こんにちは",
        "fr": "bonjour",
    }
    greeting = greetings.get(language, greetings["en"])
    return f"{greeting}, {name}!"

# 旧的调用方式仍然有效
print(greet_v2("alice"))           # hello, alice!

# 新功能也可用
print(greet_v2("张三", "zh"))       # 你好, 张三!
print(greet_v2("tanaka", "ja"))    # こんにちは, tanaka!

# 💡 这就是默认参数在api演进中的巨大价值——向后兼容

# 从python 3.5+开始，可以为默认参数添加类型注解
from typing import optional, list, dict, union

# 基本类型注解
def greet(name: str, greeting: str = "你好") -> str:
    return f"{greeting}，{name}！"

# 使用optional表示参数可以是none
def get_user(user_id: int, default: optional[str] = none) -> optional[dict]:
    """获取用户，默认值none表示找不到时返回none"""
    if default is none:
        return none
    return {"id": user_id, "name": default}

# 可变默认参数的正确注解
def add_items(
    items: list[str],
    target: optional[list[str]] = none  # 默认none，内部创建新列表
) -> list[str]:
    if target is none:
        target = []
    target.extend(items)
    return target

# 复杂默认值的注解
from typing import callable

def transform_data(
    data: list[int],
    transformer: callable[[int], int] = lambda x: x * 2  # 注意lambda的陷阱！
) -> list[int]:
    """转换数据——这里用lambda作为默认值没问题，因为lambda没有副作用"""
    return [transformer(x) for x in data]

import time

class httpclient:
    """模拟http客户端"""

    @staticmethod
    def request(url, method="get", *,
                headers=none, data=none,
                timeout=30, retries=3,
                retry_delay=1, verify_ssl=true):
        """
        发送http请求——大量使用默认参数

        核心参数：url（必须）
        常用可选参数：method（默认get）
        高级可选参数：都在*后面，必须用关键字传递
        """
        if headers is none:
            headers = {}
        if data is none:
            data = {}

        print(f"→ {method} {url}")
        print(f"  超时={timeout}s, 重试={retries}次, ssl验证={verify_ssl}")

        # 模拟请求
        for attempt in range(1, retries + 1):
            print(f"  尝试 {attempt}/{retries}...")
            # 模拟成功
            if attempt <= 2:
                continue  # 前两次模拟失败
            print(f"  ✓ 成功!")
            return {"status": 200, "data": "response data"}

        return {"status": 500, "error": "所有重试均失败"}

# 使用示例——绝大多数场景只需要url
print(httpclient.request("https://api.example.com/ping"))
print("---")

# 需要认证的请求
print(httpclient.request(
    "https://api.example.com/admin",
    method="post",
    headers={"authorization": "bearer token123"},
    data={"action": "restart"},
    timeout=60,
    retries=5
))

import json
import os

def read_config(
    config_path="config.json",
    *,
    default_config=none,
    create_if_missing=true,
    auto_save=true,
    encoding="utf-8"
):
    """
    读取配置文件

    设计思路：
    - config_path用位置参数（常用的可以简写）
    - 其他选项用关键字参数（含义清晰）
    - 默认值体现"最常用"的场景
    """
    if default_config is none:
        default_config = {
            "debug": false,
            "host": "localhost",
            "port": 8080,
            "database": "app.db",
        }

    config = none

    # 尝试读取配置文件
    if os.path.exists(config_path):
        try:
            with open(config_path, "r", encoding=encoding) as f:
                config = json.load(f)
            print(f"✓ 已读取配置：{config_path}")
        except (json.jsondecodeerror, ioerror) as e:
            print(f"⚠ 配置文件损坏：{e}")
            config = none

    # 配置文件不存在
    if config is none:
        if create_if_missing:
            config = default_config.copy()
            if auto_save:
                os.makedirs(os.path.dirname(config_path) or ".", exist_ok=true)
                with open(config_path, "w", encoding=encoding) as f:
                    json.dump(config, f, indent=2, ensure_ascii=false)
                print(f"✓ 已创建默认配置：{config_path}")
        else:
            raise filenotfounderror(f"配置文件不存在：{config_path}")

    return config

# 使用
# config = read_config()                          # 使用所有默认值
# config = read_config("production.json")         # 指定配置文件
# config = read_config("custom.json", create_if_missing=false)  # 不存在就报错

def plot_line_chart(
    x_data,
    y_data,
    *,
    title="折线图",
    x_label="x轴",
    y_label="y轴",
    figsize=(10, 6),
    line_color="#1f77b4",
    line_width=2,
    line_style="-",       # 实线
    marker="o",           # 圆点标记
    marker_size=6,
    grid=true,
    legend=none,
    save_path=none,
    show=true,
    dpi=100
):
    """
    绘制折线图——所有样式参数都有合理默认值

    调用者只需关注数据，样式有"开箱即用"的默认配置
    """
    print(f"绘制折线图: {title}")
    print(f"  数据点数: {len(x_data)}")
    print(f"  画布大小: {figsize}")
    print(f"  线条: color={line_color}, width={line_width}, style={line_style}")
    print(f"  标记: {marker}, size={marker_size}")
    print(f"  网格: {grid}")
    if save_path:
        print(f"  保存到: {save_path}")

    # 实际绘图代码（省略matplotlib调用）
    return {"title": title, "points": len(x_data)}

# 最简单的调用——只用默认样式
plot_line_chart([1, 2, 3, 4, 5], [2, 4, 6, 8, 10])

# 自定义样式
plot_line_chart(
    [1, 2, 3, 4, 5],
    [1, 4, 9, 16, 25],
    title="平方函数",
    x_label="输入",
    y_label="输出",
    line_color="red",
    line_width=3,
    marker="s",          # 方形标记
    save_path="square_plot.png"
)

# ⚠️ 错误1：可变对象作为默认参数
def bad_append(item, lst=[]):
    lst.append(item)
    return lst
# 修复：
def good_append(item, lst=none):
    if lst is none:
        lst = []
    lst.append(item)
    return lst

# ⚠️ 错误2：默认参数位置错误
# def bad_func(a=1, b):   # syntaxerror
#     pass
# 修复：
def good_func(a, b=1):
    pass

# ⚠️ 错误3：在默认值中调用有副作用的函数
current_time = time.time
def bad_timestamp(t=time.time()):  # 定义时求值！
    return t
# 修复：
def good_timestamp(t=none):
    if t is none:
        t = time.time()
    return t

# ⚠️ 错误4：默认参数引用外部可变状态
default_options = {"debug": false}

def bad_config(options=default_options):
    options["processed"] = true  # 修改了外部变量！
    return options

print(default_options)  # {'debug': false}
bad_config()
print(default_options)  # {'debug': false, 'processed': true}  —— 被污染了！

# 修复：
def good_config(options=none):
    if options is none:
        options = {"debug": false}  # 创建副本
    else:
        options = options.copy()    # 或者复制传入的
    options["processed"] = true
    return options