Python带泛型参数的灵活接口函数实现方案及相关术语咨询

你描述的这种编程模式有几个行业内通用的称呼：

• 多形态参数适配：本质是不限制参数的传入形式，通过内部适配逻辑统一处理不同来源的输入
• 鸭子类型接口：不严格校验参数的具体类型，只判断参数是否包含业务逻辑需要的属性/值即可执行后续操作
• 重载兼容接口：Python没有原生的函数重载能力，这种写法是手动实现了不同参数形式的重载兼容效果

• 优先做参数归一化，不要把参数判断逻辑散落在业务代码里
  函数开头就统一把所有输入转换成业务逻辑需要的固定格式（比如属性字典、数据类实例），后续业务逻辑完全不用关心参数的原始传入形式，大幅降低维护成本
• 明确校验规则，不要做模糊匹配
  不要遍历入参搜索需要的属性，要先判断入参类型，再按对应的规则提取值，避免出现意料之外的匹配结果
• 补充类型提示和错误说明，降低调用方理解成本
  用typing.Union标注参数支持的所有类型，非法入参直接抛出明确的类型错误，告诉调用方应该传什么格式的参数，不要静默执行或返回异常结果
• 不要过度设计，明确适配边界
  只覆盖实际需要的2-3种传参形式即可，过度灵活会导致排查问题的难度飙升，出故障时很难定位调用方传入了什么非法参数

from typing import Union, Tuple

class SomeObj(): 
   def __init__(self, obj_attr0, obj_attr1, obj_attrN):
     self.obj_attr0 = obj_attr0
     self.obj_attr1 = obj_attr1
     self.obj_attrN = obj_attrN

def do_foo(params: Union[SomeObj, Tuple[object, object]]):
    # 参数归一化逻辑
    if isinstance(params, SomeObj):
        attr0 = params.obj_attr0
        attr1 = params.obj_attr1
    elif isinstance(params, (tuple, list)) and len(params) >= 2:
        attr0, attr1 = params[0], params[1]
    else:
        raise TypeError(
            "入参仅支持两种格式：1. SomeObj类实例；2. 包含至少2个元素的列表/元组（对应obj_attr0、obj_attr1）"
        )
    
    # 后续业务逻辑完全不用关心参数来源，直接用attr0、attr1即可
    return attr0 + attr1 # 示例业务逻辑，可替换为实际需求

# 两种调用方式效果完全一致
some_obj = SomeObj(1, 2, 3)
print(do_foo(some_obj)) # 输出3
print(do_foo((1, 2))) # 输出3

• 不要直接用*args吞所有参数，否则调用方传多传少都不会第一时间报错，要等到业务逻辑执行时才会触发异常，排查成本极高
• 不要无差别使用hasattr做属性校验，如果某个无关对象刚好也有同名属性，会被误判为合法入参，如果要支持任意带指定属性的对象，一定要在函数文档里明确说明
• 不要省略参数校验，不要为了所谓的灵活性兼容所有奇奇怪怪的入参，明确的规则反而能降低接口的使用成本

内容的提问来源于stack exchange，提问作者nndhawan