错误码需全局唯一、语义明确，统一用常量类管理；异常须分层捕获并映射到对应错误码；返回结构固定为code/msg/data，msg须静态化、国际化友好；自定义异常应继承BaseBusinessError并带code属性。
错误码必须全局唯一且语义明确
Python接口返回的错误码不是随便编的数字，400、500这类HTTP状态码不能替代业务错误码。业务错误码要能直接对应到具体问题类型，比如用户未登录是1001，参数缺失是1002，库存不足是2003。避免用0或-1这种泛化值表示所有失败——前端无法据此做差异化处理。
建议用常量类统一管理：
class ErrorCode:
USER_NOT_LOGIN = 1001
PARAM_MISSING = 1002
INSUFFICIENT_STOCK = 2003
ORDER_NOT_FOUND = 3001
不要把错误码硬编码在return里，也不要分散在多个模块中定义。
异常捕获要分层：HTTP层不吞业务异常
FastAPI/Flask等框架里，常见错误是把所有异常都用try...except Exception:包住，然后统一返回{"code": 500, "msg": "服务器错误"}。这会让调试变困难，也掩盖了本该由客户端处理的业务异常（如重复提交、余额不足）。
立即学习“Python免费学习笔记（深入）”；
正确做法是分三级捕获：
- 捕获已知业务异常（如
InsufficientStockError），映射到对应ErrorCode.INSUFFICIENT_STOCK - 捕获
ValidationError等框架级异常，转为ErrorCode.PARAM_MISSING - 只对真正未预期的
Exception兜底，记录日志并返回500+ 通用提示
关键点：raise InsufficientStockError()比return {"code": 2003, ...}更利于测试和链路追踪。
错误信息字段要分离code/msg/data
返回结构必须稳定，不能因为调试需要就临时加debug_info字段，也不能把错误详情全塞进msg里。标准格式应为：
{
"code": 1002,
"msg": "缺少必要参数：user_id",
"data": null
}
msg面向前端用户或调用方，需中文、简洁、无技术术语；data可选，用于携带补救信息（如重试时间、跳转链接）；真正的堆栈或上下文必须进日志，不返给客户端。
特别注意：msg不能拼接变量（如f"用户{uid}不存在"），否则无法被前端国际化或埋点统计——应固定文案，靠data传动态值。
自定义异常类必须继承Exception且带code属性
写一个BaseBusinessError作为基类，强制子类提供code和message：
class BaseBusinessError(Exception):
def __init__(self, code: int, message: str):
self.code = code
self.message = message
super().__init__(message)
class ParamMissingError(BaseBusinessError):
def __init__(self, field: str):
super().__init__(ErrorCode.PARAM_MISSING, f"缺少必要参数：{field}")
这样中间件才能统一识别并序列化。别用ValueError或RuntimeError代替——它们没有code属性，后续扩展会卡死。
还有个易忽略点：异常类名要体现领域，比如PaymentTimeoutError比TimeoutError更安全，后者容易和标准库冲突。
