业务错误应抛自定义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)
<h1>使用示例</h1><p>if order.status == "cancelled":
raise BizError("ORDER_CANCELLED", "该订单已被取消")</p>-
BizError不该被通用except Exception:捕获，应显式处理 - 避免用
ValueError或RuntimeError替代，它们属于系统层语义 - 前端需要稳定错误码时，
code字段必须是字符串常量，不能拼接或动态生成
系统异常必须分级捕获
数据库超时、网络断连、JSON 解析失败——这些是系统级故障，不可预测且需降级或重试。它们必须和业务错误隔离，否则会导致错误码混乱、监控失真、重试逻辑误触发。
常见系统异常类型及建议处理方式：
立即学习“Python免费学习笔记（深入）”；
根据ui图生成前端页面
下载
将一个或多个 UI 原型图、线框图、产品截图或设计稿转换为标准化、可直接交付的 PRD 风格文档，供产品、设计、前端和测试共同使用。适用于 Codex 需要分析 PC 网页、桌面端、移动端、响应式页面、独立弹窗、表单、表格、看板、数据大屏或多页面流程截图，还原页面结构与交互，强制套用固定文档模板，抽取跨页面共享规则，或把一组原型沉淀为单页规范文档加整体业务流程文档的场景。不适用于纯视觉审美点评、代码实现、接口设计、埋点方案、竞品分析或无 UI 输入的业务需求创作。
-
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兜底覆盖 - 所有系统异常默认走全局
Exceptionhandler，但必须记录完整 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}
)
<p>@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": "服务暂时不可用"}
)</p>错误码设计别碰这三条红线
错误码不是随便编的字符串，它是前后端联调、监控告警、客服排查的唯一线索。以下三点踩中任一，后续维护成本会指数上升：
- 同一个业务场景在不同接口返回不同错误码（如「库存不足」在下单接口是
STOCK_SHORT，在支付接口变成INSUFFICIENT_STOCK） - 把 HTTP 状态码直接当业务码用（如返回
404作为「用户不存在」的业务标识，导致前端无法区分是资源未找到还是路径写错） - 错误码含变量或上下文信息（如
ORDER_NOT_FOUND_123456），导致监控无法聚合、日志检索失效
真正稳定的错误码只有三类：固定字符串（ORDER_EXPIRED）、带固定前缀的枚举（pay.timeout）、或由中心化配置服务下发的整数 ID（需配套管理后台）。
