返回专栏
专栏 ·

3.3 函数的定义与参数魔法:位置参数、关键字参数、*args 与 **kwargs 拆包机制

作者: 九路 共 12 章 · 48 小节

3.3 函数的定义与参数魔法:位置参数、关键字参数、*args 与 **kwargs 拆包机制

欢迎回到 HelloWorld 技术社区(www.helloworld.net) 《Python 现代开发实战》专栏。

如果把一个大型 Python 项目比作一台精密的工业机床,那么函数(Function)就是这台机床的标准化接口。接口设计得好不好,直接决定了下游调用者是“丝滑接入”还是“天天对着文档骂娘”。

很多刚从其他语言转过来的开发者,对 Python 函数的理解停留在“位置参数 + 默认值”的初级阶段。然而,当你翻开 FastAPI、PyTorch 或标准库 requests 的源码时,满眼都是 def request(method, url, /, *, params=None, **kwargs): 这样看起来像“火星密码”的签名——尤其是夹在参数中间那两个孤零零的斜杠 / 和星号 *!

今天这一节,我们彻底拆解 Python 函数的完整参数体系、可变参数收集,以及反向的 * / ** 拆包魔法,让你也能写出如顶流开源库般严谨、防呆的函数 API。

一、 参数传递全景图:谁在前,谁在后?

Python 规定函数定义中的参数必须严格遵循以下顺序排列(记不住顺序会直接报 SyntaxError):

Plaintext

  [1. 仅限位置参数]  ->  /  ->  [2. 常规位置或关键字参数]  ->  [3. *args]  ->  [4. 仅限关键字参数]  ->  [5. **kwargs]

我们逐一击破它们在真实工程中的存在意义。

1. 仅限位置参数(/,Python 3.8+):保护底层参数名重构自由

在函数签名中,斜杠 / 左侧的所有参数,调用者只能按顺序传位置参数,严禁写 param=value 的关键字形式。

为什么要这么设计? 两个核心工程痛点:

  1. 防止未来重命名参数引发线上破坏性更新(Breaking Change):如果你写了一个底层工具函数 def get_user(uid, /):,未来某天你想把形参名重构为 user_id,由于调用方全都是按位置传的 get_user(1001),你的重构对全网调用方 100% 透明无感!
  2. 避免与 **kwargs 中的动态键名冲突:设想你要写一个接收任意 JSON 字段并统计里面有没有 "name" 字段的函数 def count_fields(target_dict, /, **kwargs):,如果允许传 target_dict=...,就会和用户传入的动态键值发生命名碰撞。

2. 仅限关键字参数(*):消灭调用端的“布尔盲盒”

在函数签名中,星号 * 右侧的所有参数,调用者必须显式写出 key=value 参数名,严禁按位置偷懒传递。

这是我认为最能提升团队代码可读性的“防呆神器”!不信你看下面这行调用代码:

Python

# ❌ 灾难级的调用体验:如果不点进函数定义,谁知道 True, False, 3 分别代表什么鬼?
send_notification(1001, "您的专栏已通过审核", True, False, 3)

只要在函数定义里加一个星号 *,就能在语法层面强制所有调用者把意图写得清清楚楚:

Python

# ✅ 工业级 API 设计:user_id 与 content 强制位置传递;配置项强制关键字传递
def send_notification(
    user_id: int,
    content: str,
    /,
    *,
    is_urgent: bool = False,
    enable_email: bool = True,
    retry_times: int = 3,
) -> None:
    print(f"向用户 [{user_id}] 发送通知: {content} | 紧急={is_urgent}, 邮件={enable_email}, 重试={retry_times}")


# 正确调用:意图一目了然,哪怕五年后再看也能秒懂
send_notification(1001, "您的专栏已通过审核", is_urgent=True, retry_times=5)

# 若试图按位置传配置项:send_notification(1001, "hi", True)
# Python 直接抛出 TypeError: send_notification() takes 2 positional arguments but 3 were given

二、 万能收集器:*args 与 **kwargs 的底层本质

当你编写装饰器、中间件或封装第三方 SDK 透传接口时,往往无法提前预知调用方会传多少个参数。这时就需要用到可变参数收集器(注意:args 和 kwargs 只是行业约定俗成的变量名,真正起魔法作用的是前面的 * 和 **):

  • *args:将所有多余的位置参数自动打包成一个 元组(tuple);
  • **kwargs:将所有多余的关键字参数自动打包成一个 字典(dict)。

Python

def audit_api_call(endpoint: str, *args: object, **kwargs: object) -> None:
    """通用接口调用审计记录器"""
    print(f"接口路径: {endpoint}")
    print(f"捕获位置参数 (tuple): {args}")
    print(f"捕获关键字参数 (dict): {kwargs}")


audit_api_call("/api/v1/articles", 101, "publish", author="CodeCraft", draft=False)
# 输出:
# 接口路径: /api/v1/articles
# 捕获位置参数 (tuple): (101, 'publish')
# 捕获关键字参数 (dict): {'author': 'CodeCraft', 'draft': False}

三、 逆向魔法:函数调用时的 * 与 ** 拆包(Unpacking)

上面讲的是在定义函数(def)时把零散参数“打包”成元组和字典;而当我们在调用函数时,把 * 和 ** 写在实参前面,则执行完全相反的操作——把容器拆散成独立的参数喂给函数!

实战场景:透传配置字典与合并默认参数

在微服务的 HTTP 客户端封装中,这一招每天都在高频使用:

Python

def create_post(title: str, category: str, is_pinned: bool = False) -> dict:
    return {"title": title, "category": category, "is_pinned": is_pinned}


# 1. 列表/元组拆包 (*) -> 对应位置参数
pos_data = ["Python 3.13 异步实战", "后端架构"]
print(create_post(*pos_data))

# 2. 字典拆包 (**) -> 对应关键字参数
payload_from_frontend = {
    "title": "Ruff 工程化配置指南",
    "category": "工程效能",
    "is_pinned": True,
}
print(create_post(**payload_from_frontend))

# 3. 高阶技巧:利用 ** 合并多个配置字典(后者覆盖前者,非常优雅)
default_config = {"timeout": 5, "retries": 2, "verify_ssl": True}
custom_config = {"timeout": 15, "retries": 5}
final_config = {**default_config, **custom_config}
print("合并后的最终配置:", final_config)  # {'timeout': 15, 'retries': 5, 'verify_ssl': True}

四、 避坑指南:参数设计的三个高频翻车现场

  1. 禁止滥用 **kwargs 掩盖接口契约:有些偷懒的开发者写业务服务函数时,图省事全写成 def update_user(**kwargs):。这会导致 IDE 彻底失去自动补全和类型提示,调用者不翻函数内部实现根本不知道能传哪些字段。原则:业务核心函数必须显式声明具名参数,只有通用装饰器、代理转发层才使用 **kwargs。
  2. 拆包字典时的多余键陷阱:如果前端传来的字典里多了一个函数签名里不存在的字段(例如 "extra_field": 123),直接 create_post(**payload) 会触发 TypeError: unexpected keyword argument。面对不可信的外部输入,务必先用 Pydantic(第 5 章详解)或字典推导式过滤白名单键后再拆包。
  3. 可变默认参数红线(再次敲黑板):永远不要在函数定义里写 def foo(items=[]): 或 def bar(cfg={}):,一律用 None 替代。

💬 HelloWorld 社区实战打卡

学完 / 和 * 参数约束,你已经具备设计工业级开源库 API 的能力了!

今天给大家留一道源自 HelloWorld 社区支付网关 SDK 的接口改造打卡题。下面这段“祖传下单函数”因为参数全是位置/关键字混用,导致新来的实习生把 discount_rate(折扣率)和 tax_rate(税率)传反了,引发了一次线上价格计算事故:

Python

# 待重构的脆弱函数签名
def calculate_order_price(user_id, base_price, discount_rate=1.0, tax_rate=0.06, use_coupon=False):
    final_price = base_price * discount_rate * (1 + tax_rate)
    return round(final_price, 2)

打卡任务: 带 #Python专栏打卡 标签,在评论区重新设计 calculate_order_price 的函数签名(可保留内部逻辑),满足以下两条架构约束:

  1. user_id 和 base_price 强制只能通过位置参数传递(防止未来重命名参数影响下游);
  2. discount_rate、tax_rate 和 use_coupon 强制只能通过关键字参数传递(彻底杜绝传参顺序搞混的事故),并补全完整的现代类型注解!

评论区最先写出标准签名并附带正确调用示例的 3 位同学,直接赠送 50 社区积分!下一节(3.4),我们将攻克第三章的终极核心——作用域与闭包(Closure):LEGB 查找规则、nonlocal 关键字与闭包状态保持。