Python接口异常处理规范_错误码设计解析【技巧】-Python教程-PHP中文网

错误码需全局唯一、语义明确，统一用常量类管理；异常须分层捕获并映射到对应错误码；返回结构固定为code/msg/data，msg须静态化、国际化友好；自定义异常应继承BaseBusinessError并带code属性。

python接口异常处理规范_错误码设计解析【技巧】

错误码必须全局唯一且语义明确

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": "服务器错误"}。这会让调试变困难，也掩盖了本该由客户端处理的业务异常（如重复提交、余额不足）。

正确做法是分三级捕获：

捕获已知业务异常（如InsufficientStockError），映射到对应ErrorCode.INSUFFICIENT_STOCK
捕获ValidationError等框架级异常，转为ErrorCode.PARAM_MISSING
只对真正未预期的Exception兜底，记录日志并返回500 + 通用提示

关键点：raise InsufficientStockError()比return {"code": 2003, ...}更利于测试和链路追踪。

错误信息字段要分离code/msg/data

返回结构必须稳定，不能因为调试需要就临时加debug_info字段，也不能把错误详情全塞进msg里。标准格式应为：

前端开发

ys-agent 前端（frontend/）功能迭代的工程规范守门 skill。当任何 agent 接到 ys-agent 前端相关任务时——新增页面、新增组件、加 API、加 Pinia store、改路由、写 mock、调整布局、修改样式、对接后端接口、迁移 demo 代码、做主题、加权限、写公共组件、做数据可视化、做表单、做弹窗、做表格、做搜索过滤、调 Element Plus 用法、做响应式、做性能优化，或仅仅是在 frontend/ 目录下编辑任何 .vue / .ts / .scss / .c

下载

{
  "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更安全，后者容易和标准库冲突。