Python接口异常分类设计_业务与系统错误区分【技巧】_技术教程

业务错误应抛自定义BizError异常而非通用Exception，系统异常需分级捕获并隔离处理，错误码须为固定字符串、带前缀枚举或中心化整数ID，严禁动态生成或混用HTTP状态码。

业务错误该不该抛异常

业务错误不是程序崩溃，而是用户操作不合法或业务规则不满足，比如「余额不足」「订单已取消」。这类问题不该用 Exception 无差别兜底，否则上层无法区分是代码 bug 还是业务拒绝。

推荐做法是定义显式业务错误类，继承自 Exception 但语义独立：

class BizError(Exception):
    def __init__(self, code: str, message: str):
        self.code = code
        self.message = message
        super().__init__(message)
使用示例
if order.status == "cancelled":
raise BizError("ORDER_CANCELLED", "该订单已被取消")

BizError 不该被通用 except Exception: 捕获，应显式处理
避免用 ValueError 或 RuntimeError 替代，它们属于系统层语义
前端需要稳定错误码时，code 字段必须是字符串常量，不能拼接或动态生成

系统异常必须分级捕获

数据库超时、网络断连、JSON 解析失败——这些是系统级故障，不可预测且需降级或重试。它们必须和业务错误隔离，否则会导致错误码混乱、监控失真、重试逻辑误触发。

常见系统异常类型及建议处理方式：

requests.exceptions.Timeout：标记为临时性失败，可重试，返回 HTTP 503
psycopg2.OperationalError：连接池耗尽或 DB 挂了，需熔断，返回 HTTP 500
json.JSONDecodeError：上游数据格式错误，属外部依赖问题，记录日志并返回 400（若确认非客户端输入）
ValidationError（来自 Pydantic）：属于输入校验失败，归为客户端错误（HTTP 422），不视为系统异常

FastAPI 中统一错误响应结构

直接在路由函数里 raise 异常，靠异常处理器转成标准 JSON 响应，比每个接口手动 return JSONResponse 更可靠。

关键点：

用 HTTPException 处理客户端错误（4xx），它自带 status_code 和 detail
自定义 BizError 需注册独立 handler，避免被 Exception 兜底覆盖
所有系统异常默认走全局 Exception handler，但必须记录完整 traceback 到日志，不能只打 str(e)

@app.exception_handler(BizError)
async def biz_error_handler(request: Request, exc: BizError):
    return JSONResponse(
        status_code=400,
        content={"code": exc.code, "message": exc.message}
    )
@app.exception_handler(Exception)
async def unhandled_exception_handler(request: Request, exc: Exception):
logger.error("Unhandled exception", exc_info=exc)
return JSONResponse(
status_code=500,
content={"code": "INTERNAL_ERROR", "message": "服务暂时不可用"}
)