Programming · Building & coding
error-handling
/error-handling
错误处理规范专家助手。提供跨语言的系统化错误处理方法论,确保异常场景可感知、可追踪、可恢复,减少因错误处理不当导致的线上故障。
For whom
- Author
- dkbnull ↗
- Repository
- hello-skill ↗
- Licence
- MIT
- Last repository change
- 02.07.2026
Assessment and security
96/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
Deprecation
No signals detected. Repository changed on 02.07.2026, without references to retired models or APIs.
Licence
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
错误处理规范专家助手。提供跨语言的系统化错误处理方法论,确保异常场景可感知、可追踪、可恢复,减少因错误处理不当导致的线上故障。
Original author description
错误处理规范专家助手。提供跨语言的系统化错误处理方法论,确保异常场景可感知、可追踪、可恢复,减少因错误处理不当导致的线上故障。
How it works
- 核心原则
- 错误分类体系
- 错误处理模式
- 日志规范
- 跨语言错误处理对照
- AI 常见错误处理遗漏
Original SKILL.md headings · 197 lines, 583 words
SKILL.md preview
---
name: "error-handling"
description: "错误处理规范专家助手。提供跨语言的系统化错误处理方法论,确保异常场景可感知、可追踪、可恢复,减少因错误处理不当导致的线上故障。"
---
# 错误处理规范技能
你是一位错误处理规范专家。在编写代码时,必须按照以下规范处理错误,确保异常场景可感知、可追踪、可恢复。
## 核心原则
1. **错误必须被感知**:不允许静默失败,错误必须有迹可循
2. **错误必须可追踪**:错误信息包含足够上下文,能定位到具体位置和原因
3. **错误必须可恢复**:优先恢复而非崩溃,降级优于中断
4. **错误必须可区分**:业务异常和系统异常必须分开处理
5. **错误必须可沟通**:面向用户的错误信息友好,面向开发者的错误信息详细
## 错误分类体系
### 按来源分类
| 类型 | 特征 | 处理策略 | 示例 |
|------|------|---------|------|
| 用户输入错误 | 用户提供了非法数据 | 提示用户修正 | 邮箱格式错误 |
| 业务规则错误 | 违反业务约束 | 返回业务错误码 | 余额不足 |
| 外部依赖错误 | 第三方服务异常 | 重试 + 降级 | 支付接口超时 |
| 系统内部错误 | 程序 Bug 或资源不足 | 告警 + 降级 | 空指针、OOM |
### 按严重程度分类
| 级别 | 定义 | 处理策略 | 告警 |
|------|------|---------|------|
| P0 致命 | 系统不可用 | 立即熔断 + 告警 | 电话 + 短信 |
| P1 严重 | 核心功能受损 | 降级 + 告警 | 短信 + 邮件 |
| P2 一般 | 非核心功能异常 | 记录 + 降级 | 邮件 |
| P3 轻微 | 体验性问题 | 记录 | 日志 |
## 错误处理模式
### 模式一:分层错误处理
```
┌─────────────────────────────────────┐
│ Controller 层 │
│ - 捕获所有异常 │
│ - 转换为统一响应格式(code/message/data)│
│ - 成功码固定为 0,失败使用5位分段编码 │
│ - 绝大部分接口返回 HTTP 200 │
│ - 记录错误日志 │
├─────────────────────────────────────┤
│ Service 层 │
│ - 抛出业务异常 │
│ - 不处理系统异常(向上传播) │
│ - 标注异常类型 │
├─────────────────────────────────────┤
│ Repository 层 │
│ - 捕获技术异常 │
│ - 转换为领域异常 │
│ - 不吞掉异常 │
└─────────────────────────────────────┘
```
### 模式二:错误码体系
```
编码规则:5位分段编码 {模块码(2位)}{错误序号(3位)}
成功码:0
模块码分配:
- 10:通用/公共
- 20:认证授权
- 30:用户
- 40:订单
- 50:商品
- 60:支付
- 70:消息
- 90:系统
示例:
- 0:成功
- 10001:通用-参数校验失败
- 10002:通用-请求过于频繁
- 20001:认证-Token过期
- 20002:认证-Token无效
- 20003:认证-未登录
- 30001:用户-用户不存在
- 30002:用户-用户已存在
- 40001:订单-订单不存在
- 40002:订单-库存不足
- 90001:系统-服务内部错误
- 90002:系统-外部服务调用失败
- 90003:系统-数据库操作失败
接口统一返回 HTTP 200,通过 code 字段区分业务结果:
- code = 0:业务成功
- code ≠ 0:业务失败,根据5位编码定位模块和具体错误
```
### 模式三:异常链
```
保留原始异常信息,构建异常链:
原始异常(数据库超时)
→ 包装异常(数据访问失败)
→ 业务异常(订单创建失败)
规则:
- 不丢失原始异常(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 |
| 重试无退避 | 雪崩 | 指数退避 |
| 重试非幂等操作 | 数据重复 | 确保幂等后才重试 |
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · dkbnull/hello-skill | 96 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| jcdendrite/claude-config | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| Esposter/Esposter | 100 | Apache-2.0 |
| komluk/scaffolding | 100 | MIT |
| oborchers/fractional-cto | 100 | MIT |
| affaan-m/ECC | 100 | MIT |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
Database snapshot: 13.11.2026 · package version 6115192d437f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95error-handling-patterns
Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling, designing APIs, or improving application reliability. - 95error-handling-patterns
Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling, designing APIs, or improving application reliability. - 100error-handling-patterns
Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling, designing APIs, or improving application reliability. - 100error-handling-patterns
Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling... - 100backend-error-handling
Implement error-handling patterns: boundaries, toasts, one API error shape. Use when "error boundary", "error toast", or "standardize API errors". Plan-only audit → plan-error-handling. Sentry triage → debug-sentry-monitor. - 95errors
设计一致的错误码,遵循 PREFIX_CATEGORY_NUMBER 格式。 Use when: 定义错误码、建立错误处理机制、设计 API。 Not for: 日志格式与级别——请用 /logging-guide;处理已经到达生产环境的错误——请用 /incident。 Keywords: error code, error handling, error format, API errors, 错误码, 错误处理, 错误格式.