函数参数超过5个应拆分为dataclass或参数对象。优先用dataclass封装语义相关的参数，避免args/*kwargs掩盖设计问题；动态参数可用typeddict校验；重构后需同步更新所有调用点和类型提示。
函数参数超过 5 个就该拆了
Python 函数参数一旦超过 5 个，调用时极易出错、读起来费劲、改起来牵一发而动全身。这不是风格问题，是维护成本陡增的明确信号——def process_user(name, age, city, is_active, role, tags, notify_email) 这种签名已经处在崩溃边缘。
常见错误现象：TypeError: process_user() missing 2 required positional arguments；调用时靠位置传参，顺序一错全崩；加个新参数就得改所有调用点；单元测试里一堆 None 占位。
- 优先把关联参数打包成数据类（
dataclass）或NamedTuple，比如把用户基础信息抽成UserInput - 避免用
*args或**kwargs掩盖设计问题——它们适合插件式扩展，不是参数混乱的遮羞布 - 如果参数有强分组逻辑（如“认证配置”“超时控制”），直接拆成多个参数对象，而不是塞进一个大字典
用 dataclass 替代长参数列表最省力
dataclass 是 Python 3.7+ 最轻量、最直观的重构方案。它不增加运行时开销，IDE 支持好，类型提示天然友好，还能默认生成 __repr__ 和 __eq__。
使用场景：参数之间存在业务语义聚合（如“数据库连接配置”“HTTP 请求头”），且你希望调用方显式构造、不可遗漏关键字段。
立即学习“Python免费学习笔记（深入）”；
示例对比：
本文档主要讲述的是mybatis语法和介绍；MyBatis 是一个可以自定义SQL、存储过程和高级映射的持久层框架。MyBatis 摒除了大部分的JDBC代码、手工设置参数和结果集重获。MyBatis 只使用简单的XML 和注解来配置和映射基本数据类型、Map 接口和POJO 到数据库记录。相对Hibernate和Apache OJB等“一站式”ORM解决方案而言，Mybatis 是一种“半自动化”的ORM实现。感兴趣的朋友可
# 重构前（危险）
def send_notification(title, body, to_user_id, channel, priority, timeout_s, retry_count):
...
<h1>重构后（清晰可读）</h1><p>from dataclasses import dataclass</p><p>@dataclass
class NotificationSpec:
title: str
body: str
to_user_id: int
channel: str = "email"
priority: int = 1
timeout_s: float = 5.0
retry_count: int = 2</p><p>def send_notification(spec: NotificationSpec) -> bool:
...
- 默认值必须放在非默认字段之后，否则报
SyntaxError: non-default argument follows default argument - 如果某些字段只在内部使用、不希望暴露给调用方，用
field(default=..., init=False) - 别为了“看起来参数少”而把不同类型硬塞进同一个
dataclass，比如把user_id和api_key塞进同一个类却不加命名区分
什么时候该用 kwargs 字典而不是 dataclass
不是所有多参数都适合 dataclass。当你面对的是高度动态、结构不确定、或仅由配置文件驱动的参数集时，**kwargs 更实际——但必须加约束。
常见错误现象：send_request(**config) 中 config 来自 YAML，但函数内部对缺失键静默容忍，导致运行时报 KeyError 或逻辑错乱。
- 用
typing.TypedDict（Python 3.8+）为**kwargs提供结构校验，IDE 和 mypy 都能检查 - 在函数入口用
assert或if key not in kwargs显式拒绝缺失必填项，别等到底层才炸 - 避免在同一个函数里混用显式参数 +
**kwargs，除非显式参数是固定钩子（如log_level: str, **options）
重构后别忘了更新调用方和类型提示
改完函数签名只是第一步。真正容易翻车的是调用点没同步更新，尤其当函数被多个模块、测试、CLI 入口调用时。
性能影响几乎为零，但兼容性风险真实存在：旧调用代码会直接报 TypeError，而且如果你用了 mypy 或 PyCharm 的类型检查，未更新的调用会立刻标红。
- 用 IDE 的“重命名”功能（如 PyCharm 的
Shift+F6）批量更新调用点，它能识别dataclass构造调用 - 在函数文档字符串里写清楚迁移方式，比如 “原
name, age参数已合并至UserInput(name=..., age=...)” - 如果项目用了
pydantic模型，注意dataclass和BaseModel的序列化行为差异——别在 API 层混用两者而不做转换
最难的不是怎么拆，而是怎么让所有调用方一致地用新方式。漏掉一个地方，就可能埋下深夜排查的伏笔。
