函数参数加或*会破坏接口契约，导致ide补全失效、类型检查不准、文档生成失真；默认值变更属破坏性更新；optional比union更适配pydantic等工具；应避免暴露内部实现细节，优先用配置对象而非裸露参数。
函数参数加了 * 或 ** 之后，调用方就再也绕不开兼容性问题
一旦在函数定义里用了 *（位置参数收集）或 **（关键字参数收集），这个函数就失去了静态可推断的签名。IDE 补全失效、类型检查器（如 mypy）无法准确推导、文档生成工具（如 sphinx）抓取的参数名变成 *args 和 **kwargs —— 调用方只能靠读源码或注释猜行为。
- 常见错误现象：
TypeError: my_func() got an unexpected keyword argument 'timeout'，但你明明在文档里写了支持timeout，只是它被吞进**kwargs里没做校验 - 使用场景：写装饰器、通用封装（如 API 客户端统一加 headers）、框架钩子函数——这些地方确实需要灵活性，但代价是放弃一部分接口契约
- 实操建议：
**kwargs不要裸奔，至少做白名单过滤或透传前记录日志；如果只为了扩展几个可选参数，优先用带默认值的具名参数，而不是一上来就上**kwargs
def f(a: int, b: str = "x") -> bool: 这类签名，改默认值就是破壊性变更
看起来只是改个 b="x" 成 b="y"，但下游可能有代码显式依赖旧默认值做分支判断，比如 if b == "x": do_legacy()。更隐蔽的是，某些测试用例会 mock 函数调用并断言「未传 b 时收到的值是 “x”」，改了默认值就直接挂。
- 参数差异：位置参数默认值变更影响所有不传该参数的调用；关键字参数默认值变更影响所有省略该参数的调用；而类型注解变更（如
str→Optional[str]）虽不报错，但 mypy 会拒绝旧调用 - 性能影响：几乎没有，但兼容性成本远高于运行时开销
- 实操建议：想换默认值？先加新参数（如
b_new），把旧参数标为Deprecated并 warn；等两个大版本后再删。别信「没人用这个默认值」——日志里查调用链比你想象中快
类型注解写成 Union[str, None] 和 Optional[str] 看似一样，mypy 处理逻辑却不同
表面上都是接受 str 或 None，但 Optional[T] 是 Union[T, None] 的语法糖，mypy 在部分上下文中会对前者做特殊简化（比如泛型推导），而后者可能保留更严格的联合类型约束。更实际的问题是：如果你用 Union[str, None] 写在函数返回类型里，某些 json 序列化库（如 pydantic v1）会拒绝识别为可为空字段。
- 常见错误现象：
pydantic.error_wrappers.ValidationError提示「field required」，但你传了None，只因类型写成了Union[str, None]而非Optional[str] - 使用场景：和 pydantic、fastapi、mypy 协同工作时，类型写法直接影响运行时行为，不是纯注释
- 实操建议：统一用
Optional[T]表达「可为空」；Union留给真正多态的场景（如Union[int, str, Float]）；别为了“看起来更底层”刻意展开Optional
函数签名里暴露内部实现细节（比如 cache_ttl: int = 300），等于把重构锁死
一开始加个缓存超时参数是为了快速上线，后来发现得换成 redis 连接池、再后来要支持 per-key TTL 策略……但只要 cache_ttl 还挂在函数签名上，你就没法删、不能重命名、甚至改类型都得考虑兼容。用户已经把它当公共契约在用，哪怕你文档里写了「内部参数，勿依赖」。
立即学习“Python免费学习笔记（深入）”；
- 容易踩的坑：用 kwargs 透传配置项（如
**client_opts）看似灵活，实则把网络超时、重试次数、证书路径全暴露出去，下次换 http 库时一个都收不回来 - 实操建议：把可配置项收进独立配置对象（如
ClientConfig类），函数只接收该对象实例；或者用工厂函数（make_client(cache_ttl=300)）隔离配置生命周期 - 为什么这样做：签名越窄，未来越自由。不是所有参数都值得放进函数头——有些东西本该藏在构造函数里，或者由环境变量/配置中心驱动
最麻烦的不是签名难设计，而是改签名时没人记得去翻三年前的 CI 日志里那条失败的集成测试。