Python函数返回值设计_异常与结果解析【指导】

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、有时抛异常”更可靠。常见做法包括：

• 始终返回一个命名元组或数据类，含 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自动补全、静态检查更有效。