Python函数接口设计核心是提升易用性以降低出错成本，具体包括：参数命名直白、合理使用默认值与类型提示、单一职责与明确返回契约、避免隐式状态依赖。
Python函数接口设计的核心是让调用者“少想、少错、少查文档”——易用性不是锦上添花，而是降低出错成本、提升协作效率的第一道防线。
参数命名直白，拒绝缩写和黑话
函数参数名应准确反映其语义，优先使用完整单词，避免依赖上下文猜测。比如 user_id 比 uid 更安全，max_retries 比 max_r 更清晰。缩写仅在行业通用（如 url、json）或已有强约定时才可接受。
- ✅ 推荐：
def send_notification(recipient_email: str, message_body: str, is_urgent: bool = False) - ❌ 避免：
def send_notif(to: str, msg: str, urg: bool = 0)
合理使用默认值与类型提示，减少必填负担
对高频使用、有明确常规行为的参数，提供安全合理的默认值；同时配合类型提示（str、Optional[int] 等），让 IDE 自动补全、静态检查更准，也相当于轻量级文档。
- 默认值应是“最无害”的选项：比如日志级别默认
logging.INFO，而非DEBUG；超时默认30.0秒，而非0（易引发阻塞） - 可选参数优先用
None作默认，再内部判断，避免用哨兵值（如-1、""）造成歧义 - 类型提示不强制运行时检查，但能显著提升可读性和工具支持度
单一职责 + 明确返回契约，避免“返回什么都可能”
一个函数只做一件事，并始终按约定返回同一种类型（或明确的联合类型）。不要让调用者每次都要 isinstance() 判断返回值结构。
立即学习“Python免费学习笔记（深入）”；
- ✅ 清晰：
def find_user_by_email(email: str) -> Optional[User]（要么User实例，要么None） - ❌ 模糊：
def find_user_by_email(email: str) -> Union[User, str, None]（返回"not found"字符串？还是异常？调用方得翻源码） - 异常比魔术返回值更易追踪：找不到用户应抛
UserNotFoundError，而不是返回None或空字典
避免隐式状态依赖，输入即全部依据
函数行为应完全由参数决定，不偷偷读全局变量、配置模块或环境变量（除非明确命名为 config 参数）。这保证可测试、可复现、可缓存。
- 需要配置时，显式传入：
def fetch_data(api_url: str, timeout: float = 5.0, retry_policy: RetryConfig = DEFAULT_RETRY) - 若真需全局上下文（如当前请求 ID），通过
contextvars显式绑定，而非直接访问current_request_id - 副作用（如写文件、发 HTTP 请求）应在函数名中体现，例如
save_config_to_disk()而非update_config()
不复杂但容易忽略：易用性藏在命名、默认值、返回值和边界清晰里。写完一个函数，试着不用看实现，只读签名就敢调用——那就接近了。
