写过几年Python之后，我越来越意识到一个事实：多数代码的可读性问题，不是出在算法逻辑上，而是出在函数调用上。年后维护一个旧项目时，我又被一排排位置参数折磨了一整个下午——某个绘图函数的定义有七八个参数，调用处全部按照位置传参，没人敢动参数顺序，因为一改就是连锁报错。后来我花了半天时间，把所有涉及到的调用点全部改成具名参数，也就是标题里说的键值参数（keyword arguments），代码瞬间清爽了不少。这篇我就结合自己踩过的坑，把Python中具名参数的用法、设计思路、常见错误和排查技巧一次讲透。
1. 为什么需要具名参数：从一次真实踩坑说起
1.1 一次让人抓狂的函数调用
先还原一下当时的现场。某个数据可视化模块里有一个函数，作用是把一组坐标点画到画布上，它的定义大概是这样的：
def draw_points(data, canvas, color, size, alpha, marker, label, show_grid): # 省略实现这段代码本身没什么问题，问题出在调用端。项目里有人这样用：
draw_points(pts, fig, "red", 5, 0.8, "o", "样本数据", True)读这行代码的时候，你根本不知道True是show_grid还是别的什么开关，也不知道5是size还是line_width。更要命的是，如果中间有人把参数顺序调整了，比如把color和size互换，函数不会报错，但图画出来就完全不对了。
这种问题在业务代码里实在太常见了。函数一多，参数一多，仅靠位置去对应参数，就是在给未来的自己埋雷。而具名参数就是用来拆掉这颗雷的。
所谓具名参数，本质上就是在调用函数的时候，把参数名和值用参数名=值的形式写出来。调用方不再依赖参数的物理位置，而是通过名称直接对号入座；函数定义的接口也变得更加自解释、更好维护。
1.2 具名参数解决的本质问题
在深入语法之前，我想先聊清楚一个底层问题：具名参数到底解决了什么？
第一层，解决的是代码表达能力的问题。下面两段代码，做的是同一件事：
# 完全靠位置，读起来全靠猜 draw_points(pts, fig, "red", 5, 0.8, "o", "样本", True) # 具名参数，读起来就是一句话 draw_points(data=pts, canvas=fig, color="red", size=5, alpha=0.8, marker="o", label="样本", show_grid=True)第二段代码，哪怕是一个完全不懂业务的人来看，也能大致猜到每个参数的含义。这就是我常说的“代码自文档化”——与其写一堆注释解释参数，不如让函数调用本身就清晰易懂。
第二层，解决的是参数顺序耦合的问题。使用具名参数以后，调用方的参数顺序可以和函数定义的顺序完全不一致：
draw_points(label="样本", size=5, data=pts, color="red")这样可以减少“调用时必须按定义顺序写”的强约束。尤其是在参数数量较多、或部分参数经常需要省略的场景，这种灵活性非常值钱。
第三层，解决的是默认参数扩展的问题。函数定义里允许给参数指定默认值，调用方可以只传部分参数，其他用默认值。比如：
def draw_points(data, canvas, color="blue", size=3, alpha=1.0, marker="o", label=None, show_grid=False): pass调用时想用默认的颜色、默认的标记，只是换一下尺寸和透明度，直接写：
draw_points(pts, fig, size=8, alpha=0.5)这种写法在参数很多的场景里极其重要。如果全部用位置参数，你想改第5个参数，就必须把前4个都传一遍，否则参数就会错位。
作为一个写了多年Python的人，我现在给自己定了一条硬规矩：凡是参数超过三个的函数，调用时必须使用具名参数；定义时也尽量通过合理的默认值设计，让调用变得简洁。这个习惯不复杂，但回报率极高。
2. 基础语法拆解：从最简单到最常见的操作模式
2.1 定义一个带具名参数的函数
在Python里定义函数时，参数可以简单地分成两类：必选参数（位置或具名均可传）和带默认值的可选参数。一个最常见的定义长这样：
def create_user(name, email, age=None, city="未知"): print(f"用户: {name}, 邮箱: {email}, 年龄: {age}, 城市: {city}")其中name和email是必填的，调用时不给会直接报TypeError: create_user() missing 1 required positional argument。age和city有默认值，可以根据需要传，也可以省略。
这里有一个非常容易忽略的规则：带默认值的参数必须放在不带默认值的参数之后。下面这种写法会直接触发语法错误：
def create_user(name, age=None, email): # SyntaxError: non-default argument follows default argument pass原因很直白：如果允许默认参数在前，Python解释器就无法判断调用时第一个参数到底对应谁。比如你调用create_user("张三", 25)，这个25到底是给age还是给email？为了消除这种二义性，Python直接规定了默认参数必须靠后。
调用时的规则同样明确。你可以这样传：
create_user("张三", "zhangsan@example.com") create_user("张三", "zhangsan@example.com", 25) create_user("张三", "zhangsan@example.com", age=25, city="上海") create_user(name="张三", email="zhangsan@example.com")但下面这种混写方式是非法的：
create_user("张三", email="zhangsan@example.com", "上海") # SyntaxError规定是：位置参数必须全部排在具名参数之前，一旦出现了参数名=值的写法，后面就禁止再出现裸的位置参数。这个规则和很多人的直觉相反，所以刚接触时经常踩。记住一条原则就好：先位置、后具名、顺序不能反。
2.2 调用时的三种传参方式
实操层面，函数调用的传参方式其实可以拆成三类，写成表格更直观：
| 传参方式 | 写法 | 特点 |
|---|---|---|
| 纯位置参数 | func(a, b, c) | 简洁，但参数多时可读性差 |
| 纯具名参数 | func(a=1, b=2, c=3) | 可读性好，参数顺序可调整 |
| 混合传参 | func(1, b=2, c=3) | 前部用位置传递，后部用名称传递 |
混合传参在真实代码里使用频率最高，因为它能兼顾简洁和清晰。比如一个函数：
def connect(host, port, timeout=30, retries=3): print(f"连接 {host}:{port}, 超时 {timeout}, 重试 {retries}") connect("192.168.1.10", 8080, timeout=10, retries=5)host和port这种“主要角色”用位置传，一眼就知道连的哪；timeout和retries这种“可配置项”用具名传，既不用记住它们的顺序，也省掉了传无关注释的麻烦。
这里我还想多说一句：什么时候不该用混合传参？如果前部的某个位置参数含义不是特别直观，就建议直接连它也改成具名。比如：
# 不好，news_id 和 user_id 单看数字很难区分 fetch_news(1024, 2048) # 明显更好 fetch_news(news_id=1024, user_id=2048)代码最终是写给维护者看的，能清晰一点，就清晰一点。
2.3 强制具名参数：Python 3的星号语法
有时候我们不仅希望支持具名参数，更希望强制某些参数必须用具名方式传入。这就要用到Python 3引入的星号（*）语法：
def save_file(path, content, *, encoding="utf-8", compress=False): print(f"保存到 {path}, 编码 {encoding}, 压缩: {compress}")定义里的*是一个“分隔符”。它之前的所有参数（这里是path和content）可以用位置方式传，也可以具名传；它之后的所有参数（encoding和compress）则必须使用参数名=值的形式传入。
也就是说，下面的调用是合法的：
save_file("/tmp/a.txt", "hello") save_file("/tmp/a.txt", "hello", encoding="gbk", compress=True) save_file(path="/tmp/a.txt", content="hello", encoding="utf-8")而下面的调用会直接报TypeError：
save_file("/tmp/a.txt", "hello", "utf-8", True) # 错误之所以设计这种语法，核心目的是避免那些“辅助性参数”被调用方稀里糊涂地按位置传错。encoding和compress这种参数，看起来都是可选的、影响行为的开关类参数，放在*后面，等于直接告诉所有调用者：请明确写出你的意图。
这种模式在标准库和主流开源项目中非常普遍。比如很多框架的请求处理方法、模型初始化方法，都会大量使用强制具名参数来约束API的使用方式。日常开发中，如果你在写一个有点影响力的基础函数或公共方法，我建议给那些“非核心但容易混淆”的参数加上这个约束。*符号本身不产生任何代价，但对调用方是一个极强的提示。
我自己在给团队做代码评审时，如果看到某个函数有四个以上参数、其中还有两三个布尔开关，就会建议加一个*，把布尔开关全部放到后面。效果立竿见影：调用方再也没出现过把compress和overwrite传反的例子。
3. 进阶玩法：具名参数在工程实践里的几种高价值场景
3.1 用关键字解包让调用更灵活
除了在定义处使用具名参数，Python还有一个非常实用的配套语法：调用时用**来解包字典，把字典中的键值对展开成具名参数。举个例子：
def create_user(name, email, age, city): print(f"{name} / {email} / {age} / {city}") info = { "name": "张三", "email": "zhangsan@example.com", "age": 25, "city": "杭州", } create_user(**info)执行这段代码，Python会自动把info里的每个键值对当作一个具名参数传进去。这个特性在以下几个场景里非常实用。
第一种场景，从配置文件或外部接口读取参数。比如从JSON文件里读出来一个字典，里面正好是某个函数的全部参数，直接**data传过去即可，比手动逐个取键再传参要简洁得多。
第二种场景，动态拼接参数。有些函数支持很多可选参数，但每次需要传哪些，要根据运行时的条件来决定。这时可以先维护一个字典，再按需往里面填键，最后一次性展开传参：
params = {"url": "https://example.com", "method": "GET"} if use_proxy: params["proxies"] = proxy_config if need_auth: params["auth"] = (user, token) requests.request(**params)这样做避免了写一长串if-elif来组装不同数量的参数。
第三种场景，实现参数透传。你写了一个装饰器或包装函数，需要原封不动地把参数转发给被包装的函数，用**kwargs接收再**kwargs转发，是最高效的方案。
不过有一个问题要特别提醒：**展开时，字典里的键必须恰好与函数定义的参数名一致，多一个或少一个都会报错。多出来的键对应不到参数，会报TypeError: create_user() got an unexpected keyword argument 'xxx'；少了必需的参数，则会报缺少参数的错误。如果你需要“只取其中一部分键”，可以在调用前先对字典做过滤，或者让函数本身也加一个**kwargs来容忍多余参数。
3.2 *args 和 **kwargs 的配合使用
聊具名参数，绕不开**kwargs，而**kwargs通常又和*args形影不离。它们的组合可以写出极其灵活的通用接口：
def log_message(level, message, *args, **kwargs): text = f"[{level}] {message}" if args: text += " | 附加位置参数: " + ", ".join(map(str, args)) if kwargs: text += " | 附加具名参数: " + ", ".join(f"{k}={v}" for k, v in kwargs.items()) print(text) log_message("INFO", "服务启动") log_message("ERROR", "连接失败", 10086, retry_times=3, fallback="local")在这个例子里，*args收集多余的位置参数，**kwargs收集多余的具名参数。它们给了函数很强的扩展空间——未来的调用方想临时附加一些信息，都不用改函数签名。
但我要提醒一点：这俩是“兜底”方案，不是“默认选择”。如果一个函数的参数集合是稳定、明确的，那就应该明确写出参数名，而不是统统收进**kwargs里。原因很简单：明确写出参数名时，IDE能给你补全和提示，函数定义本身就是文档；全部收进**kwargs后，调用方根本没法知道有哪些参数可用，排查参数拼写错误也变得更困难。
我见过不少不太合理的写法，比如把函数写成了这样：
def process(data, **kwargs): mode = kwargs.get("mode", "fast") debug = kwargs.get("debug", False) ...这种写法把参数验证的责任从解释器转嫁给了业务代码。如果你传错了参数名，比如mode="fastt"，kwargs.get("mode", "fast")根本不会报错，而是默默采用默认值，问题会被埋得很深。所以我的建议是：能显式声明参数，就尽量显式声明；**kwargs留给真正的透传场景。
对于装饰器来说，*args, **kwargs就是标配了。写一个日志装饰器，需要在包装函数里把你可能收到的任何参数都接住，再原样转给原函数：
import functools def log_call(func): @functools.wraps(func) def wrapper(*args, **kwargs): print(f"调用 {func.__name__}, args={args}, kwargs={kwargs}") return func(*args, **kwargs) return wrapper @log_call def calc(a, b, op="add"): if op == "add": return a + b return a - b calc(3, 4) # 记录 args=(3, 4) calc(3, 4, op="mul") # 记录 args=(3, 4), kwargs={'op': 'mul'}这里*args, **kwargs不仅是为了接收参数，更是在做完整的“参数搬运”。如果你只写def wrapper(a, b, op="add")，那未来原函数加参数，装饰器也要跟着改，显然不利于维护。用*args, **kwargs接收，配合functools.wraps保留原函数的元信息，是我在实际工程里最常用的模式。
3.3 具名参数场景下的函数设计思路
既然标题是“如何使用它们”，光讲语法还不够，我还想聊聊设计端的一些经验：什么时候该用具名参数，什么时候该用配置对象。
我个人的判断标准大概是这样的：如果一个函数有两三个可选参数，用具名参数完全够了；但如果参数数量到了五六个以上，或者多个参数之间有明显的内聚关系，就建议把这些参数组合成对象或字典，再传入函数。否则函数的调用看起来会很长，容易失控。
例如，不要写这样的函数：
def generate_report(data, title, author, date, style, output_format, output_path, include_chart, include_table, include_summary): pass调用它会非常痛苦。更好的方式是用一个配置对象，或者内置一个dataclass：
from dataclasses import dataclass @dataclass class ReportConfig: title: str author: str date: str style: str = "default" output_format: str = "html" output_path: str = "./report" include_chart: bool = True include_table: bool = True include_summary: bool = True def generate_report(data, config: ReportConfig): pass config = ReportConfig(title="月度总结", author="张三", date="2025-01-05") config.include_table = False generate_report(data, config)这样做的优势在于：调用方不需要记得generate_report的第7个参数是什么；配置项可以在一个对象上集中管理、复用、局部修改；新增配置项也不会破坏既有调用。
当然，配置对象不总是必要的。如果你的函数参数就那么两三个，硬塞一个配置类反而是过度设计。我的经验是：先以具名参数起步，等参数多到影响阅读时，再做一次“参数打包”的重构。这个过程非常自然，不用一开始就考虑得太重。
4. 新手最容易踩的坑与排查技巧实录
4.1 可变默认值这个老坑
如果说具名参数这个主题下有一个“全民公敌”，那一定是可变默认值。请看这段代码：
def add_item(item, items=[]): items.append(item) return items print(add_item("苹果")) # 输出 ['苹果'] print(add_item("香蕉")) # 输出 ['苹果', '香蕉']，而不是 ['香蕉']第二次调用的时候，items居然还保留着第一次调用产生的['苹果']。原因是：函数定义时，[]这个默认值只被创建了一次，后续每次调用如果不传items，用的都是同一个列表对象。
这在工程上是个很隐蔽的bug，因为同样一段逻辑，如果换成items=None再在函数内部新建列表，行为就完全正常：
def add_item(item, items=None): if items is None: items = [] items.append(item) return items这是一条铁律：可变对象（列表、字典、集合等）不应该直接作为默认参数值，而是要用None作为占位，在函数内部根据情况初始化。不可变对象如整数、字符串、元组则没有这个问题。
4.2 参数顺序与混用限制
初学者在调用函数时，最常见的错误就是参数顺序或者混用方式不对。Python解释器会抛出的错误主要有几种，我整理成了一张速查表：
| 错误场景 | 报错信息 | 排查方向 |
|---|---|---|
| 缺少必选参数 | missing 1 required positional argument | 检查是否漏传了必填参数 |
| 多传位置参数 | takes 2 positional arguments but 3 were given | 检查调用处参数数量是否超出函数定义 |
| 多余具名参数 | got an unexpected keyword argument 'xxx' | 检查参数名是否拼写错误，或是否确实没定义该参数 |
| 重复传参 | multiple values for argument 'xxx' | 检查同一个参数是否既用位置传又用具名传 |
| 位置参数放在具名参数之后 | positional argument follows keyword argument | 检查调用时是否把裸值写在了参数名=值的后面 |
“重复传参”这个错误非常容易出现在混合传参场景。比如：
def connect(host, port, timeout=30): pass connect("127.0.0.1", 8080, timeout=50) # 正常 connect("127.0.0.1", port=8080, timeout=50) # 正常，port仅通过具名传而下面这种写法就会冲突：
connect("127.0.0.1", 8080, 50) # 前提：函数定义里没有第三个位置参数，会报多传 connect("127.0.0.1", 8080, 50) # 如果函数定义是 connect(host, port, timeout), 这样是合法的关键点在于：如果定义里第3个参数是timeout，那么位置传3个值是合法的；但如果同时再用timeout=50传一次，就是重复给同一个参数赋了两个值：
connect("127.0.0.1", 8080, 50, timeout=50) # TypeError: multiple values for argument 'timeout'理解这个错误的本质，比死记规则更重要：Python不允许参数被“同时用两种方式”赋值，因为解释器分不清哪个才是调用者想要的最终值。
4.3 具名参数的命名冲突与接口兼容
具名参数虽然好用，但在函数演进的过程中有一个容易被忽略的风险：参数名的变更会对所有依赖具名调用的下游代码造成破坏。
举个例子。原函数是：
def calculate(principal, rate=0.05): return principal * (1 + rate)后来你把rate改成了interest_rate，同时加了3%的默认值。如果项目里有调用方写了：
calculate(10000, rate=0.04)那这次改动之后，就会立刻报TypeError: calculate() got an unexpected keyword argument 'rate'。
所以，当你在维护一个被多人使用的公共函数时，改名要非常谨慎。如果确实要改，可以保留旧参数名一段时间作为兼容，在内部做一次映射：
def calculate(principal=0, rate=None, interest_rate=None): if rate is not None and interest_rate is None: interest_rate = rate if interest_rate is None: interest_rate = 0.05 return principal * (1 + interest_rate)这种写法能保证新旧调用方式都暂时可用，再配合废弃告警，逐步引导调用方迁移。
类似的，给函数新增具名参数时也要注意位置。如果你在中间插入一个新参数，比如把def f(a, b)改成def f(a, c, b)，那所有按位置传参的调用方都会出问题；而如果新参数加在末尾，并且带默认值，旧调用就可以不修改地继续运行。这是函数演进时一个很实用的兼容性技巧。
4.4 排查思路方法论
最后分享一套我排查具名参数相关问题的固定套路。
第一步，先看报错信息里的函数名和参数名。Python的错误信息其实相当友好，它会直接告诉你缺了谁、多了谁、重复了谁。不要急着去改代码，先读完整报错。
第二步，如果错误是“unexpected keyword argument”，优先怀疑参数名拼写错误。特别是配置类字典里的键，引号一多，大小写写错、下划线漏写都是高频问题。
第三步，如果错误是“missing required positional argument”，而且你确认自己传了参数，那就要检查你是否把这个参数写成了**kwargs里的内容。换句话说，kwargs是收纳袋，不是保险箱——放进去的键，如果和函数的显式参数不匹配，就不会被正确使用。
第四步，遇到多个错误叠加的情况，我建议先用最小复现实验来定位：单独写一个三行调用，不给任何多余参数，看能否跑通。能跑通说明问题在调用端的数据组装上，不能跑通说明问题在函数定义本身。
这套排查流程，我几乎每周都会用上几次。只要是Python项目，具名参数的错误就无法完全避免，但只要思路清晰，定位起来通常花费不了几分钟。
5. 接收与传递：两个容易被忽略的语法细节
前面讲了很多调用和定义的场景，但还有一个角度值得单独展开：具名参数在接收和传递时的对称关系。理解了这个对称性，很多花哨的用法就都能看懂。
5.1 函数定义里的 **kwargs 与调用处的 **dict 是对称的
函数定义里的**kwargs负责把“多出来的具名参数”收集成字典；调用处的**dict负责把字典展开成“具名参数”。它们的名字其实不要求一致，但语义完全对称。
def wrapper(**kwargs): # kwargs 是一个字典 print(kwargs) params = {"x": 1, "y": 2} wrapper(**params)这就像快递发件和收件的关系：发件时你填一堆字段，收件人被一个包裹收纳起来。两边只要字段名对得上，整个过程就畅通无阻。
这个特性还有一个很有意思的用法：把具名参数动态转发给不同的处理函数。比如一个事件分发器，它收到一个事件字典，再根据事件类型把参数展开转发给对应的处理器：
def handle_login(username, session_id): print("登录事件", username, session_id) def handle_logout(username, reason): print("登出事件", username, reason) event_handlers = { "login": handle_login, "logout": handle_logout, } def dispatch(event_type, **params): handler = event_handlers[event_type] handler(**params) dispatch("login", username="李四", session_id="abc123") dispatch("logout", username="李四", reason="用户主动退出")这种写法在处理Webhook回调、命令行解析、插件系统等场景时非常好用。dispatch不需要知道每个处理器需要什么参数，只需要把事件参数完整转发过去即可。
5.2 在类方法中传递具名参数时的注意点
类方法的参数传递有一个隐含的细节：第一个参数是self，通常不能作为具名参数在调用时显式传入。当你写obj.method(**params)时，参数里不能包含self这个键，否则会报错。
另一个更容易踩的坑是：当用super()调用父类方法时，如果父类的方法签名和子类不一致，具名参数就能体现很大优势。比如：
class Base: def run(self, task, timeout=60, retries=3): pass class Child(Base): def run(self, task, timeout=60, retries=3, notify=False): super().run(task=task, timeout=timeout, retries=retries) if notify: print("任务执行完毕，已通知")这里子类显式地只把父类关心的参数传过去，notify不会被误传到父类。如果改用位置参数，还需要特别注意参数顺序，而且一旦父类新增参数，子类转发也要跟着变。具名参数在这一场景下是天然的防错机制。
5.3 函数参数解包与对象展开的组合技巧
最后再分享一个实用的小技巧：具名参数解包不仅支持字典，也支持实现了keys()和__getitem__()的对象。这意味着你可以自定义一个配置类，让它具备字典的接口，然后在调用函数时直接用**展开。
class Config: def __init__(self, values): self._values = values def keys(self): return self._values.keys() def __getitem__(self, key): return self._values[key] def connect(host, port, timeout=30): print(host, port, timeout) cfg = Config({"host": "localhost", "port": 3306, "timeout": 10}) connect(**cfg)这种写法在写库、中间件、框架内部时较常见。普通业务代码里不需要为了解包而设计这样的类，但看懂这个机制会帮助你理解**的本质——它不是一个“字典专用的魔法”，而是一个“键值展开协议”。凡是能提供键集合和取值能力的对象，都可以参与展开。
我整理这些细节的初衷很简单：具名参数不是背几个语法规则就完事的东西，它在代码设计、重构、维护和调试中扮演的角色远比表面看起来重要。很多复杂的Python技术，比如依赖注入、装饰器链、ORM查询条件构造，底层都在以各种方式利用“键值传递”这个基础能力。
6. 我实际写代码时的几个习惯
说了这么多，最后再分享一些我个人的实操习惯。这些不全是书本上的规范，更多是从踩坑中总结出来的纪律。
第一个习惯：自定义函数时，所有布尔开关默认放在最后。比如verbose=False、use_cache=True这类参数，我会全部排在函数签名尾部，并且如果有三个以上，就用在前面加*的方式强制它们具名传递。
第二个习惯：调用别人写的函数时，除了那种“已知且简单”的常用函数，一律写具名参数。例如len(data)、print(text)这种当然没必要改，但像sorted(data, key=..., reverse=True)、pd.read_csv(file, encoding="utf-8")这类，我会尽量把关键选项具名写出。哪怕拼写速度慢一点，代码的清晰度和改错时的定位速度，都会快很多。
第三个习惯：代码审查时看到新增的公共函数，如果参数超过四个，我会主动提示是否考虑合并参数或使用配置对象。这能有效避免核心工具函数被频繁改签名，减少对下游调用方的冲击。
第四个习惯：善用Type Hints配合具名参数。给参数声明类型，可以让IDE在调用端就发现错误，例如把数字填成了字符串。具名参数加上类型标注，就是双保险：
def download_file(url: str, dest: str = "./downloads", *, overwrite: bool = False, timeout: int = 30) -> str: print(url, dest, overwrite, timeout) return dest这里*后面的overwrite和timeout强制具名，配合类型声明，读起来就是一页清晰的说明文档。
最后说一点总的心得：具名参数看起来是个简单语法，但它体现的是API设计的品味。好的函数接口，应该让调用方几乎不需要查文档就能写出正确的代码；而具名参数正是实现这一目标的基础工具之一。如果你现在维护的代码到处都是长串的位置参数，不妨挑一个高频函数，花十几分钟把调用处改成具名写法，再感受一下后续维护时的差别。这个改动不大，收益却可以很快尝到。
