Python函数接口设计的核心目标是提升可维护性，需确保签名清晰、职责单一、行为可预测；精简参数、用命名关键字和数据类封装、统一返回类型、最小化副作用、清晰处理异常。
Python函数接口设计的核心目标之一是提升可维护性——即让后续修改、扩展和协作更安全、更高效。这不单靠写清楚文档，更取决于函数签名是否清晰、职责是否单一、行为是否可预测。
参数精简，避免“万能参数”
过多参数（尤其布尔标志位或类型混合的*args/**kwargs）会快速模糊函数意图。比如一个接收8个参数、其中3个互斥的函数，每次调用都要查文档，改起来极易出错。
- 优先用命名关键字参数（def func(*, a, b)）强制调用者显式传名，避免顺序依赖
- 将逻辑相关的参数封装成简单数据类或
NamedTuple，例如把width, height, color, border_style, radius打包为StyleConfig - 真需要灵活性时，用策略模式或配置对象替代层层嵌套的条件分支
返回值一致且可推断
函数返回None、字典、列表、自定义对象甚至异常混用，会让调用方反复做类型检查和防御性处理，显著增加维护成本。
- 明确约定返回类型：单一用途函数尽量只返回一种结构（如总是返回
dict或总是返回Optional[User]） - 用
typing.Union或Result[T, E]（配合第三方库如result）显式表达“可能失败”，而不是靠返回None或空列表隐式表示错误 - 避免在成功路径中返回
True、失败返回str这类类型跳跃设计
副作用最小化，纯函数优先
修改全局状态、就地修改入参、写文件、发HTTP请求等副作用，会让函数行为随上下文漂移，单元测试难写，重构风险高。
立即学习“Python免费学习笔记（深入）”；
- 默认按“输入→输出”设计：相同输入恒得相同输出，不依赖外部状态
- 必须有副作用时，将其分离为独立函数（如
load_config()和validate_config(cfg)），主逻辑保持无副作用 - 若需修改入参，应在函数名中明确体现（如
sort_inplace(items)），否则默认应返回新对象
错误边界清晰，不吞异常
用try...except: pass或裸except:掩盖问题，短期看似“健壮”，长期会让故障定位变慢、掩盖真实缺陷。
- 只捕获你明确知道如何处理的具体异常（如
FileNotFoundError），并给出上下文友好的提示 - 对不可恢复的错误（如类型错误、逻辑矛盾），让异常自然抛出，比返回魔术值（如-1、None）更利于调试
- 在公共接口层做一次统一错误包装（如转为自定义
ApiError），内部实现层保留原始异常链
可维护的接口不是一开始就很完美，而是在每次新增需求、修复bug、阅读他人代码时，都让人少一分犹豫、多一分确定性。从下一个函数开始，试着问自己：三个月后我还能不看注释就理解它该做什么、不该做什么、出错了会怎样。
