error-handling

# 错误处理规范技能 你是一位错误处理规范专家。在编写代码时，必须按照以下规范处理错误，确保异常场景可感知、可追踪、可恢复。 ## 核心原则 1. **错误必须被感知**：不允许静默失败，错误必须有迹可循 2. **错误必须可追踪**：错误信息包含足够上下文，能定位到具体位置和原因 3. **错误必须可恢复**：优先恢复而非崩溃，降级优于中断 4. **错误必须可区分**：业务异常和系统异常必须分开处理 5. **错误必须可沟通**：面向用户的错误信息友好，面向开发者的错误信息详细 ## 错误分类体系 ### 按来源分类 | 类型 | 特征 | 处理策略 | 示例 | |------|------|---------|------| | 用户输入错误 | 用户提供了非法数据 | 提示用户修正 | 邮箱格式错误 | | 业务规则错误 | 违反业务约束 | 返回业务错误码 | 余额不足 | | 外部依赖错误 | 第三方服务异常 | 重试 + 降级 | 支付接口超时 | | 系统内部错误 | 程序 Bug 或资源不足 | 告警 + 降级 | 空指针、OOM | ### 按严重程度分类 | 级别 | 定义 | 处理策略 | 告警 | |------|------|---------|------| | P0 致命 | 系统不可用 | 立即熔断 + 告警 | 电话 + 短信 | | P1 严重 | 核心功能受损 | 降级 + 告警 | 短信 + 邮件 | | P2 一般 | 非核心功能异常 | 记录 + 降级 | 邮件 | | P3 轻微 | 体验性问题 | 记录 | 日志 | ## 错误处理模式 ### 模式一：分层错误处理 ``` ┌─────────────────────────────────────┐ │ Controller 层 │ │ - 捕获所有异常 │ │ - 转换为统一响应格式（code/message/data）│ │ - 成功码固定为 0，失败使用5位分段编码 │ │ - 绝大部分接口返回 HTTP 200 │ │ - 记录错误日志 │ ├─────────────────────────────────────┤ │ Service 层 │ │ - 抛出业务异常 │ │ - 不处理系统异常（向上传播） │ │ - 标注异常类型 │ ├─────────────────────────────────────┤ │ Repository 层 │ │ - 捕获技术异常 │ │ - 转换为领域异常 │ │ - 不吞掉异常 │ └─────────────────────────────────────┘ ``` ### 模式二：错误码体系 业务错误码采用 5 位分段编码，成功码固定为 0，接口统一返回 HTTP 200 通过 code 字段区分业务结果；错误码分段规范（编码规则、模块码分配及错误码示例）见 api-design 技能的"业务码规范"。 ### 模式三：异常链 ``` 保留原始异常信息，构建异常链： 原始异常（数据库超时） → 包装异常（数据访问失败） → 业务异常（订单创建失败） 规则： - 不丢失原始异常（cause） - 每层包装添加上下文信息 - 最外层异常面向用户，内层异常面向开发者 ``` ### 模式四：重试模式 ``` 重试策略： - 最大重试次数：3 - 退避策略：指数退避（1s → 2s → 4s） - 可重试异常：网络超时、服务暂时不可用 - 不可重试异常：参数错误、权限不足、业务规则违反 重试必须满足： - 操作幂等 - 有超时保护 - 有最大次数限制 - 有退避策略 ``` ### 模式五：降级模式 ``` 降级策略优先级： 1. 返回缓存数据（推荐） 2. 返回默认值 3. 返回简化结果 4. 返回友好提示 降级条件： - 外部服务超时 - 外部服务错误率超过阈值 - 系统资源接近极限 ``` ## 日志规范 ### 错误日志必须包含 ``` [ERROR] 时间 | TraceId | 类名.方法名 | 错误码 | 错误信息 | 堆栈摘要 示例： [ERROR] 2024-01-01 12:00:00 | trace-abc123 | OrderService.createOrder | 200002 | 创建订单失败：库存不足，商品ID=1001，需求数量=10，可用库存=3 | com.example.exception.BusinessException: 库存不足 at OrderService.checkStock(OrderService.java:45) at OrderService.createOrder(OrderService.java:28) ``` ### 日志级别使用 | 级别 | 使用场景 | 示例 | |------|---------|------| | ERROR | 影响功能的异常 | 支付失败、数据库连接断开 | | WARN | 潜在问题，不影响主流程 | 重试成功、降级触发、接近阈值 | | INFO | 关键业务节点 | 订单创建、用户登录、定时任务执行 | | DEBUG | 调试信息 | SQL 参数、方法入参出参 | ### 日志禁忌 - 禁止在日志中记录密码、Token、身份证号等敏感信息 - 禁止在循环中打印日志（使用批量或条件判断） - 禁止使用 `e.printStackTrace()`（使用日志框架） - 禁止日志信息过于简单（如"操作失败"） - 禁止在日志中拼接大量数据 ## 跨语言错误处理对照 | 模式 | Java | Python | Go | JavaScript | |------|------|--------|-----|-----------| | 异常类型 | try-catch-finally | try-except-finally | error 返回值 | try-catch-finally | | 自定义异常 | extends Exception | extends Exception | 自定义 error 类型 | extends Error | | 资源清理 | try-with-resources | with 语句 | defer | finally | | 错误传播 | throws | raise | return error | throw | | 空值处理 | Optional | None 检查 | 多返回值 | ?. 和 ?? | | 异步错误 | CompletableFuture | asyncio | goroutine + channel | Promise.catch | ## AI 常见错误处理遗漏 | 遗漏 | 风险 | 正确做法 | |------|------|---------| | 空 catch 块 | 错误被吞掉 | 至少记录日志 | | 只打印堆栈 | 无法追踪 | 添加业务上下文 | | 异常信息太简单 | 无法定位 | 包含操作、参数、环境 | | 不区分异常类型 | 无法针对性处理 | 自定义异常分类 | | 遗漏 finally 清理 | 资源泄漏 | try-with-resources | | 异步错误未处理 | 静默失败 | Promise.catch / try-catch | | 重试无退避 | 雪崩 | 指数退避 | | 重试非幂等操作 | 数据重复 | 确保幂等后才重试 |