error-handling

错误处理

何时用

• 写任何涉及 IO、网络、数据库、外部 SDK 调用的代码时。
• 在函数/方法中加 try-catch/try-except，需要确定该怎么处理时。
• 联调时前端反馈"不知道哪里出错了"或日志里找不到报错原因时。
• code review 发现 catch 块为空、或者只有 console.log(e) 时。

核心规则

1. 不吞异常：catch 块必须有实质处理

规则： catch/except 块里必须有真正的处理动作——记录日志、触发回滚、重新抛出或转换为业务错误；禁止空 catch 块，禁止仅打印后继续正常流程假装没发生过。

为什么： AI 生成代码时，"先写个 try-catch 让它跑起来"是最常见的反模式——catch (e) {} 或 except: pass。空 catch 会把真实的数据库连接失败、磁盘写入错误、第三方 API 超时全部静默吞掉，函数返回"成功"，上层完全感知不到异常，日志里没有任何线索，用户看到的是数据没有保存但页面显示"操作成功"。定位这类 bug 通常要花几倍时间，因为所有的证据都被主动销毁了。

怎么做：

• 能处理就处理（重试、降级、返回默认值），并记录 warn 级日志。
• 不能处理就重新抛出（throw/raise），让上层决定。
• 需要转换语义时，把底层异常包裹成业务异常再抛：throw new PaymentFailedException("支付网关超时", cause=e)。
• finally 块做资源清理，不要把清理逻辑写在 catch 里然后 return 提前跳出。

---

2. 错误分类：可预期错误与意外错误分开处理

规则： 明确区分两类错误——可预期的业务错误（用户输入非法、资源不存在、权限不足）和意外的系统错误（空指针、数据库宕机、bug）；前者用业务异常类表达，后者进入全局 handler 并触发告警。

为什么： AI 生成的代码经常把所有异常一律 catch (Exception e) 然后返回 500——校验失败返回 500、资源不存在返回 500、真正的 bug 也是 500。监控告警全是噪音，用户看到的错误信息毫无意义，oncall 工程师不知道哪些 500 需要紧急处理、哪些是正常的业务错误被错误分类了。错误分类是可观测性的基础，混在一起会让整个告警体系失效。

怎么做：

# 业务异常基类（可预期，映射到 4xx）
class AppError(Exception):
    def __init__(self, code: str, message: str, http_status: int = 400):
        self.code = code
        self.message = message
        self.http_status = http_status

class ResourceNotFoundError(AppError):
    def __init__(self, resource: str, resource_id):
        super().__init__("RESOURCE_NOT_FOUND", f"{resource} {resource_id} 不存在", 404)

# 意外错误不捕获，让全局 handler 接管，触发告警
def get_user(user_id: int) -> User:
    user = db.query(User).get(user_id)
    if user is None:
        raise ResourceNotFoundError("User", user_id)  # ✅ 业务错误，明确分类
    return user

• 业务异常：校验失败、资源不存在、权限不足、业务规则冲突 → 映射到 4xx，记录 info/warn，不触发 PagerDuty。
• 系统异常：数据库连接失败、空指针、未捕获异常 → 5xx，记录 error，触发告警，保留完整堆栈。

---

3. 错误信息带上下文，但不泄露敏感数据

规则： 错误日志必须包含"哪个操作、哪个输入、在哪一步失败"的上下文；但对外返回的错误信息不能包含数据库表名、SQL 语句、堆栈、密钥、用户密码等敏感内容。

为什么： AI 有两种相反的倾向：要么日志只有 "操作失败" 一句话，查问题像盲人摸象；要么直接把框架抛出的原始异常（含 SQL 语句、文件路径、变量值）直接序列化返回给前端，攻击者可以从中提取数据库结构、推断内部逻辑。两种极端都在真实生产事故中反复出现。