Python函数参数详解：位置、关键字与默认值用法

一、形参、实参及核心概念界定

在深入具体规则前，首先需要厘清两个基础术语的定义差异：

• 形参（Parameter）：在函数定义阶段（def 语句）括号内声明的变量名称，用于为接收的数据占位。
• 实参（Argument）：在函数实际调用阶段传入的具体值或引用对象。

Python 支持多种将实参绑定到形参的方式。同一个形参，在调用时既可以通过其在列表中的物理位置完成赋值，也可以显式指明形参变量名进行赋值。

二、位置参数与关键字参数的传递规则

1. 按位置传递（Positional Arguments）

按位置传递是函数调用最基础的形态。解释器根据实参在调用表达式中的先后顺序，自左向右依次对应填入形参列表中。

def build_user(username, email, age):
    return {"name": username, "mail": email, "years": age}

# 调用端按顺序提供 3 个实参
user = build_user("alice", "alice@example.com", 26)
print(user)

位置传参的约束是数量与顺序必须完全一致。如果调用时传入的实参数量少于或多于未设置默认值的形参数量，Python 解释器会直接抛出 TypeError: build_user() takes 3 positional arguments but N were given。

2. 按关键字传递（Keyword Arguments）

关键字实参采用 name=value 的语法形式，在调用时明确将值指派给指定名称的形参。这种传递方式完全不受形参在函数定义中的顺序限制。

# 实参顺序任意调换，解释器按形参名准确填槽
user = build_user(age=30, username="bob", email="bob@example.com")
print(user)

关键字传参显著增强了调用的自解释性。尤其当函数接收多个同类型参数（例如多个连续的布尔值或数值）时，显式指定关键字能有效防止调用者颠倒传参顺序引发的逻辑缺陷。

3. 位置与关键字混合传参的铁律

在单次函数调用中，可以同时使用位置实参与关键字实参，但必须遵守解释器的硬性语法规则：所有位置实参必须位于任何关键字实参之前。

# 正确：位置实参在左，关键字实参在右
user = build_user("carol", age=22, email="carol@example.com")

# 语法错误：位置实参跟在关键字实参之后（直接抛出 SyntaxError）
# user = build_user(username="carol", "carol@example.com", age=22)

三、默认参数的使用规范与求值机制

1. 默认参数的声明与调用

在定义函数时，可以为形参提供预设值（Default Value）。调用者如果没有为该参数传入实参，函数便自动采纳默认值；若调用者显式传入，则覆盖默认值。

def connect_server(host, port=8080, timeout=10):
    return f"连接至 {host}:{port}，超时设定 {timeout} 秒"

# 仅提供必选参数 host
print(connect_server("127.0.0.1"))

# 覆盖 port，timeout 沿用默认值
print(connect_server("192.168.1.1", port=9000))

定义顺序约束：在函数形参列表中，所有带默认值的形参必须排在没有默认值的形参之后。如果违反，Python 会在定义阶段直接抛出 SyntaxError: non-default argument follows default argument。

2. 核心陷阱：可变对象（Mutable Object）作为默认值

这是 Python 初学者和中级开发者最常遭遇的陷阱之一：函数的默认参数只在 def 语句首次执行定义时求值一次，而不是每次调用函数时重新求值。

当使用列表（list）、字典（dict）或自定义类的实例等可变对象作为默认值时，该对象会被挂载在函数自身的 __defaults__ 属性上成为持久单例，导致跨调用之间的状态累积与污染。

def record_log(event, log_list=[]):
    log_list.append(event)
    return log_list

# 期望每次调用返回单元素列表，实际却产生状态累加
print(record_log("启动"))    # ['启动']
print(record_log("连接"))    # ['启动', '连接']
print(record_log("就绪"))    # ['启动', '连接', '就绪']

规范解法：对于可变类型的默认参数，应当使用不可变单例 None 作为占位哨兵值，在函数体内部通过判断动态生成全新的独立容器。

def record_log_safe(event, log_list=None):
    if log_list is None:
        log_list = []
    log_list.append(event)
    return log_list

print(record_log_safe("启动"))  # ['启动']
print(record_log_safe("连接"))  # ['连接']

四、进阶控制：位置仅限与关键字仅限参数

从 Python 3.0 开始支持关键字仅限参数，而在 Python 3.8 中进一步引入了仅限位置参数。通过 / 和 * 这两个特殊的语法分隔符，开发者可以精准限制参数的传入形式。

1. 仅限位置参数（Positional-Only，使用 / 分隔）

位于斜杠 / 左侧的所有形参，只能通过位置实参传入，不能通过参数名作为关键字传入。这种设计常用于：

• 形参名称纯属实现细节，不希望外部调用者形成代码依赖。
• 参数具有显而易见的逻辑语义（如标准库中的 math.sin(x) 或 pow(x, y)）。

2. 仅限关键字参数（Keyword-Only，使用 * 分隔）

位于星号 *（或变长位置形参 *args）右侧的所有形参，只能通过关键字实参传入，禁止通过位置实参传入。这常用于配置项、开关标志等易混淆的可选参数。

def setup_connection(host, port, /, timeout=5, *, retry=3, ssl=True):
    return f"Host: {host}:{port}, Timeout: {timeout}, Retry: {retry}, SSL: {ssl}"

# 合法调用
res = setup_connection("10.0.0.1", 3306, 10, retry=5, ssl=False)

# 非法调用 1：host 是仅限位置参数，使用关键字将报错 TypeError
# setup_connection(host="10.0.0.1", port=3306)

# 非法调用 2：retry 是仅限关键字参数，使用位置传参将报错 TypeError
# setup_connection("10.0.0.1", 3306, 10, 5)

五、参数定义完整顺序与常见异常诊断

当一个复杂的工程函数融合了多种类型的参数时，形参在函数签名中的声明必须严格遵循以下先后次序：

1. 仅限位置参数（若有，后接 /）
2. 普通位置或关键字参数（无默认值）
3. 带默认值的普通参数
4. 可变位置参数（*args）或裸星号（*）
5. 仅限关键字参数（可包含或不包含默认值）
6. 可变关键字参数（**kwargs）

六、调用端常见异常排查清单

在日常开发与测试中，若遇到参数相关的异常提示，可通过以下特征快速锁定根因：

• TypeError: ... missing required positional argument: 'x'
  原因：调用端遗漏了没有默认值的必填形参。
  检查：核对函数签名中无默认值的形参数量，确认入参列表是否完整。
• SyntaxError: positional argument follows keyword argument
  原因：调用语句在书写关键字参数之后，又写了位置参数。
  检查：调整实参书写顺序，确保所有纯值位置实参排列在所有 key=value 之前。
• TypeError: ... got multiple values for argument 'x'
  原因：形参通过位置实参获得了赋值后，调用端在随后的关键字实参中又显式传入了同名参数。
  检查：检查实参映射关系，避免在位置和关键字中重复赋值同一个形参。
• TypeError: ... got an unexpected keyword argument 'x'
  原因：调用时传入的关键字名称拼写错误，或者函数未声明 **kwargs 导致无法接纳扩展关键字。
  检查：核对形参拼写，或者在定义端补充 **kwargs 收集动态参数。