Python函数参数设计应优先使用必选命名参数表达核心契约，合理运用args处理同类型可变输入、*kwargs用于显式定义的可选配置或下层透传，避免滥用导致接口模糊。
Python函数参数设计的关键在于清晰表达意图、兼顾灵活性与可读性，而不是堆砌语法特性。用好*args和**kwargs的前提，是先理清哪些参数必须显式命名、哪些属于可选扩展、哪些属于下游透传。
必选参数优先，明确核心契约
函数最前面的普通参数（位置参数）应代表不可省略、语义明确的核心输入。它们构成调用者必须理解并提供的最小接口。
- 避免把业务关键字段藏进
**kwargs——比如send_email(to, subject, **kwargs)中to和subject必须显式写出，不能靠字典键传入 - 参数名要有业务含义，不用
data、config这类泛称；user_id比id更安全，避免歧义 - 必要时用
def func(*, timeout=None, retry=True):强制关键字调用，防止位置参数错位
可变参数用于真正不确定数量的同类输入
*args适合处理“零个或多个同类型值”，比如数值计算、路径拼接、批量操作，不是用来规避参数设计的偷懒方式。
- 典型场景：
sum_numbers(*nums)、join_paths(*parts)、log_errors(*exc_info) - 避免混合类型：
*args里同时塞字符串、数字、对象，会增加调用方理解和测试成本 - 如果实际只接受1–3个参数，宁可用默认值或
Optional类型标注，别用*args模糊边界
关键字参数用于可选配置或向下透传
**kwargs本质是“预留扩展槽位”，分两类使用：一类是本层直接消费的可选配置（如timeout、verify_ssl），另一类是原样转给下层函数（如装饰器、基类方法）。
A Python CLI skill for Cutout.Pro visual APIs — background removal, face cutout, and photo enhancement. Supports file upload & image URL input.
下载
调用 Cutout.Pro 视觉处理 API 进行背景移除、人像抠图和照片增强，支持文件上传与图片 URL 输入。
立即学习“Python免费学习笔记（深入）”；
- 显式接收再转发更可控：
def wrapper(**kwargs): return inner_func(**{**default_opts, **kwargs}) - 不要在业务函数里无差别收所有
**kwargs然后黑盒传递——调用方无法知道哪些键有效，IDE也无法提示 - 配合
typing.TypedDict或dataclasses定义合法关键字结构，提升可维护性
组合使用要守住分层边界
常见组合如func(a, b, *args, c=None, **kwargs)是合理的，但需确保每部分职责分明：
-
a, b：强约束主输入 -
*args：追加的同类额外输入（如多个标签、多个过滤条件） -
c=None：本层重要的可选开关或配置 -
**kwargs：明确说明用途，例如“传给requests.post的参数”或“数据库查询选项”
不复杂但容易忽略。
