多参数传入与单一对象传入的接口设计：哪种方案更优？

针对你纠结的两种API接口设计方案，下面从实用性、可维护性、扩展性等维度拆解各自的优劣，以及通用场景下的选型建议：

方案1：参数直传（api_client.init_payment(order_id=..., price=..., ...)） #

优势 #

• 简洁易用：调用方无需额外理解请求对象的结构，直接传入业务参数，代码可读性高，学习成本极低，符合多数开发者的使用习惯。
• 无额外封装成本：调用时不需要先实例化请求对象，减少代码行数，快速完成接口调用。

潜在局限 #

• 扩展性差：后续API新增或调整参数时，必须修改接口方法的签名，若参数过多会导致方法签名臃肿，调用方代码也可能需要同步调整（即使使用默认参数，也会让方法定义越来越复杂）。
• 校验逻辑分散：参数的合法性校验需要在接口方法内逐个处理，无法集中管理，后续修改校验规则时容易遗漏。
• 复杂场景适配弱：如果接口参数存在嵌套结构、多组依赖关系，或者需要支持不同的参数组合变体，直传参数会让调用代码和内部逻辑变得混乱。

方案2：请求对象传参（api_client.init_payment(InitPaymentRequest(order_id=..., price=..., ...))） #

核心合理性 #

• 可维护性强：所有接口相关参数都封装在InitPaymentRequest类中，参数定义、默认值、校验规则可以集中管理，后续调整参数只需修改请求对象，接口方法签名无需变动，避免了频繁修改公共接口的问题。
• 内部逻辑复用：既然你内部已经需要创建该请求对象，直接让调用方传入可以减少一层参数转封装的冗余逻辑，代码更简洁高效。
• 类型安全与提示友好：即使在Python这类动态语言中，通过dataclass或pydantic定义请求对象，也能提供清晰的类型提示，帮助调用方提前发现参数错误；在静态语言中，还能实现编译时类型校验。
• 适配复杂场景：面对参数多、嵌套深、有依赖关系的接口，请求对象可以通过类的继承、组合或不同构造方法，优雅适配多种调用场景，让调用代码更整洁。

通用场景下的选型建议 #

• 简单接口优先选方案1：如果接口参数少（3个以内）、结构稳定，不需要频繁调整，方案1的简洁性更有优势，能降低调用方的使用门槛。
• 复杂/易变接口优先选方案2：如果接口参数多、结构可能迭代，或者存在嵌套/依赖关系，方案2的可维护性和扩展性更适合长期迭代，同时能和你内部的对象复用逻辑契合。
• 折中方案（推荐）：可以同时支持两种调用方式，在接口方法内部做兼容处理，兼顾简洁性和扩展性：

  def init_payment(self, order_id=None, price=None, request=None):
      if request is None:
          request = InitPaymentRequest(order_id=order_id, price=price)
      # 后续统一使用request对象处理逻辑
  

  这样调用方既可以选择直接传参数快速调用，也可以在复杂场景下使用请求对象。

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