17370845950

Python函数应明确区分成功结果与异常情况：正常路径返回业务数据，异常路径抛出具体异常；避免用None等特殊值表示错误，必要时使用结果容器模式并同步更新文档和类型提示。

Python函数返回值设计，核心是让调用者能清晰区分“成功结果”和“异常情况”，避免用返回值掩盖错误、或强迫调用方手动检查特殊值（如None、-1）来判断失败。推荐策略：正常路径明确返回业务数据，异常路径主动抛出异常，不依赖返回值编码错误状态。

该返回数据，就只返回数据

函数职责单一、输入可控时，直接返回计算结果或对象实例。例如：

• 字符串处理函数：返回处理后的新字符串，不返回None表示“失败”，而是对非法输入（如None）直接抛出TypeError；
• 数值计算函数：返回浮点数或整数，除零、溢出等应触发ZeroDivisionError或OverflowError，而非返回float('nan')或None；
• 查找类函数（如find_user_by_id）：若ID必然存在，返回用户对象；若可能不存在，优先抛出ValueError或自定义异常（如UserNotFoundError），而不是返回None——把“不存在”的语义交给异常传达，更主动、更难被忽略。

异常不是“兜底”，而是明确的控制流分支

异常用于表达可预期但非常规的执行路径，不是隐藏逻辑缺陷的遮羞布。使用时注意：

• 捕获具体异常类型，避免裸except:；
• 自定义异常继承Exception，名称体现语义（如InsufficientBalanceError）；
• 异常中附带清晰信息：raise ValueError(f"Invalid age {age}: must be between 0 and 150")；
• 不为性能回避异常——Python中异常开销仅在触发时显著，正常流程无影响。

少数场景可考虑“结果容器”模式

当函数天然存在多种合理输出状态（如“成功/失败/超时/重试”），且调用方需统一处理多态响应时，可封装为显式结果类型，例如：

• 返回dataclass或命名元组：Result[Ok: value, Err: exception]；
• 使用第三方库如result（Ok(value) / Err(error)）；
• 关键：这类模式适用于内部服务协议或FP风格代码，不建议替代常规异常机制，尤其不要在简单脚本或教学示例中引入额外复杂度。

文档与类型提示必须同步更新

返回值策略失效常因文档滞后。务必同步维护：

• docstring中明确写出Raises:段落，列出所有可能抛出的异常及触发条件；
• 用类型提示标注返回类型，如def parse_json(s: str) -> dict[str, Any]:，异常不写进类型签名（PEP 484不支持）；
• 若采用结果容器，类型提示需精确，如-> Result[User, UserNotFoundError]（需配合typing.Union或第三方泛型支持）。