Python函数参数演进需兼顾兼容性：新增参数须设默认值，避免重命名/删除；用inspect.signature检查Parameter.kind变化；装饰器需手动同步__signature__；慎用**kwargs，优先显式参数；Union注解兼容用字符串字面量或降级写法。
Python 函数签名改了，老代码直接报 TypeError: got an unexpected keyword argument
这是最典型的参数演进断裂点：新增了必需参数、重命名了参数、或把位置参数改成仅关键字参数。Python 不会自动降级兼容，它只认签名。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
inspect.signature()在升级前检查函数签名变化，尤其关注Parameter.kind（比如从POSITIONAL_OR_KEYWORD变成KEYWORD_ONLY） - 若你维护的是被广泛调用的 API，新增参数必须带默认值（
None或合理兜底值），且避免删/重命名已有参数 - 旧版调用方传了新版本已移除的参数？别急着删逻辑——先在函数体内用
**kwargs捕获并静默忽略（或打 warning），给下游留迁移窗口
用 functools.wraps 包装后，help() 和 IDE 提示还是不对
因为 @wraps 只复制了 __name__、__doc__ 等基础属性，不处理签名。IDE 和 help() 依赖 __signature__，而它默认不会被 @wraps 同步。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 手动补全签名：在装饰器内部用
sig = inspect.signature(original_func)，再通过functools.update_wrapper(wrapper, original_func)+setattr(wrapper, '__signature__', sig) - 更省事：用
decorator库（非标准库）或makefun，它们默认处理签名透传 - 别依赖
@wraps自动解决一切——它不是万能签名代理
**kwargs 看似灵活，其实是兼容性黑洞
当函数头写成 def f(a, **kwargs):，表面支持任意参数，实际掩盖了两个风险：一是调用方传错参数名无法被静态检查发现；二是后续想把某个 **kwargs 里的键提升为显式参数时，会破坏所有现有调用。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 只在真正需要“开放扩展”的入口函数（如插件系统、配置加载）里用
**kwargs，且文档明确列出已知接受的 key - 已有
**kwargs的函数要提取新参数？先加显式参数 + 默认值，同时在函数体里从kwargs中 pop 掉同名项，并 warn 用户该参数即将弃用 - 类型检查工具（如 mypy）对
**kwargs基本失效，别指望它帮你守住边界
第三方库升级后，你的 typing.Union 注解突然不 work 了
Python 3.10+ 把 Union[A, B] 语法糖简化为 A | B，但很多老库（尤其 pydantic v1、dataclasses-json）只识别 Union 类型对象，遇到 | 就解析失败或静默忽略。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 跨版本兼容注解：统一用
from __future__ import annotations+ 字符串字面量（"A | B"），延迟求值，避免运行时解析 - 若必须用运行时类型信息（如做字段校验），降级到
Union写法，哪怕 Python 版本支持| - 检查依赖库的 typing 支持状态，别假设 “用了新语法就一定被支持”——类型注解的兼容性比函数签名更隐蔽
参数演进真正的难点不在怎么加新东西，而在怎么让旧调用者毫无感知地继续跑通。每处默认值、每个 **kwargs 的取舍、每次签名变更的 warning 级别，都得按下游的实际升级节奏来卡点，而不是按发版日历。
