Python函数返回值设计应明确区分异常与预期失败，推荐用结构化结果（如Result类）统一返回success/data/error，避免混用None、异常或多重返回值。
Python函数返回值设计的核心，是让调用方能清晰、安全、低认知成本地判断执行状态并获取结果。不推荐用单一返回值混杂“成功数据”和“错误信息”，也不建议过度依赖异常传递业务逻辑结果。
明确区分“异常”与“预期失败”
异常（Exception）应只用于真正意外、无法继续执行的情况，比如文件不存在、网络中断、类型严重不匹配。而业务中常见的“查无此用户”“库存不足”“参数校验未通过”，属于可预期的流程分支，更适合用结构化返回值表达。
例如：
- ✅ 推荐：函数返回
{"success": False, "code": "USER_NOT_FOUND", "data": None}或自定义结果类（如Result.ok(value)/Result.err("msg")） - ❌ 避免：对“用户名重复”抛出
ValueError，迫使调用方用try/except捕获本可预判的业务状态
统一返回结构，降低调用方心智负担
尤其在API层或公共工具函数中，固定返回格式比“有时返回字典、有时返回None、有时抛异常”更可靠。常见做法包括：
立即学习“Python免费学习笔记（深入）”；
- 始终返回一个命名元组或数据类，含
is_success、data、error（或message）字段 - 使用第三方库如
returns（提供Result类型）或轻量封装def safe_call(func, *args): try: return Result.success(func(*args)) except Exception as e: return Result.failure(e) - 避免返回
None表示失败——它和正常返回空列表、空字符串语义冲突，易引发AttributeError
异常该抛就抛，但别绕过类型提示和文档
若确实需要抛异常（如底层IO失败、断言崩溃），请确保：
- 抛出具体异常类型（
FileNotFoundError优于Exception），便于精确捕获 - 函数签名中标明可能抛出的异常（可通过 docstring 的
Raises:或类型检查工具如pyright支持的# type: ignore[raise]注释辅助） - 异常消息包含上下文（如 “Failed to parse config file 'app.yaml': missing required key 'database.url'”），而非仅 “Invalid input”
慎用多重返回值掩盖控制流复杂度
像 def parse_config(): return data, error_msg, warnings 看似灵活，实则增加调用方解包负担和遗漏处理风险。不如返回一个结构体对象，支持链式判断：
result = parse_config()if result.is_ok(): use(result.unwrap())else: log(result.error)
这种模式配合类型提示（如 Result[str, ParseError]），能让IDE自动补全、静态检查更有效。
