业务错误应抛自定义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": "服务暂时不可用"}
)

错误码设计别碰这三条红线

错误码不是随便编的字符串，它是前后端联调、监控告警、客服排查的唯一线索。以下三点踩中任一，后续维护成本会指数上升：

• 同一个业务场景在不同接口返回不同错误码（如「库存不足」在下单接口是 STOCK_SHORT，在支付接口变成 INSUFFICIENT_STOCK）
• 把 HTTP 状态码直接当业务码用（如返回 404 作为「用户不存在」的业务标识，导致前端无法区分是资源未找到还是路径写错）
• 错误码含变量或上下文信息（如 ORDER_NOT_FOUND_123456），导致监控无法聚合、日志检索失效

真正稳定的错误码只有三类：固定字符串（ORDER_EXPIRED）、带固定前缀的枚举（pay.timeout）、或由中心化配置服务下发的整数 ID（需配套管理后台）。