好的错误信息应明确“谁错了、在哪错、为什么错”：包含出错对象、位置上下文、业务层面原因；避免敏感信息；按环境分级详略；统一英文主动语态。
错误信息要说明“谁错了、在哪错、为什么错”
异常信息不是给机器看的，是给人读的。好的错误信息应该包含三个要素：出错的对象（比如哪个变量、哪个函数）、出错的位置（文件名、行号可选，但上下文要清晰）、出错的原因（不是堆栈，而是业务逻辑层面的解释）。例如：
-
差：
ValueError: invalid input—— 没有主语，没说输入是什么、哪里不对 -
好：
ValueError: expected a positive integer for 'retry_count', got -3 instead—— 明确参数名、期望值、实际值
避免暴露内部实现或敏感信息
生产环境抛出的异常不能泄露路径、数据库名、用户ID、密钥片段等。尤其注意不要把原始异常链（如repr(e)）直接拼进消息里。建议做法：
- 用
str(e)替代repr(e)获取用户友好的原始错误描述 - 对关键字段做脱敏，比如
user_id=12345→user_id=[REDACTED] - 自定义异常类中重写
__str__，统一控制输出内容
按层级区分错误信息的详细程度
开发、测试、生产环境对错误信息的要求不同，可通过日志级别或配置开关动态调整：
-
开发时：可包含文件路径、变量快照、调用链简述（如
called from validate_config() at config.py:42） -
生产时：只保留用户可理解的业务语义，如
Failed to connect to payment gateway: timeout after 5s，技术细节记入日志而非异常消息 - 不建议在异常消息里写“请联系管理员”，而应提供唯一错误码（如
[ERR-2047]），便于后台关联日志定位
统一使用英文，保持动词时态一致
团队协作中，异常消息语言需统一。推荐全部使用英文，并采用现在时主动语态，语义更直接：
- ✅
File not found: '/etc/app/config.yaml' - ✅
Unsupported file format: 'xls', only 'csv' and 'json' are allowed - ❌
The file was not found...（被动语态冗长） - ❌
Config file missing（缺少上下文，不知道是哪个配置）
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
