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() 判断返回值结构。

• ✅ 清晰：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()

不复杂但容易忽略：易用性藏在命名、默认值、返回值和边界清晰里。写完一个函数，试着不用看实现，只读签名就敢调用——那就接近了。