codeprobe-error-handling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Standalone Mode

独立模式

If invoked directly (not via the orchestrator), you must first:

Read
```
../codeprobe/shared-preamble.md
```
for the output contract, execution modes, and constraints.
Load applicable reference files from
```
../codeprobe/references/
```
based on the project's tech stack.
Default to
```
full
```
mode unless the user specifies otherwise.

如果直接调用（不通过编排器），您必须先执行以下步骤：

阅读
```
../codeprobe/shared-preamble.md
```
以了解输出约定、执行模式和约束条件。
根据项目技术栈加载
```
../codeprobe/references/
```
中的适用参考文件。
除非用户另行指定，否则默认使用
```
full
```
模式。

Error Handling & Resilience Checker

错误处理与弹性检查器

Domain Scope

领域范围

This sub-skill detects error handling and resilience issues across these categories:

Swallowed Exceptions — Empty catch blocks, catch-and-log-only without rethrow/handle
Missing Error Handling — External API calls without try/catch, unhandled promise rejections
Error Information — Generic error messages, leaking internals, missing structured responses
Retry & Circuit Breaker — No timeout on external calls, no retry for transient failures
Validation — Missing input validation, implicit null assumptions, type coercion bugs
Transaction Safety — Multi-step DB operations without transactions, missing rollback
Logging — No logging on critical paths, missing correlation IDs

此子技能可检测以下类别中的错误处理与弹性问题：

吞掉的异常 —— 空catch块、仅记录日志但不重新抛出/处理的catch块
缺失错误处理 —— 外部API调用未包裹try/catch、未处理的Promise拒绝
错误信息问题 —— 通用错误消息、泄露内部信息、缺失结构化响应
重试与断路器 —— 外部调用未设置超时、瞬态故障未配置重试
验证问题 —— 缺失输入验证、隐式空值假设、类型转换漏洞
事务安全性 —— 多步骤数据库操作未使用事务、缺失回滚机制
日志问题 —— 关键路径无日志记录、缺失关联ID

What It Does NOT Flag

不标记的内容

Sensitive data in logs — covered by
```
codeprobe-security
```
(
```
SEC
```
prefix). This sub-skill flags missing logging and structural issues like no correlation IDs, not data leakage.
Test files — test exception handling follows different patterns and is expected to be simpler.
Framework-generated exception handlers (e.g., Laravel's
```
Handler.php
```
, Next.js error boundaries that are intentionally minimal) — these are scaffolded defaults, not developer oversights.
CLI scripts with intentionally simple error handling (print + exit) — command-line tools often use a valid pattern of printing an error and exiting with a non-zero code.
Catch blocks that deliberately swallow specific known-harmless exceptions with a comment explaining why — if the developer documented the rationale, respect the decision.
Issues that are primarily security vulnerabilities (e.g., authentication bypasses, injection, data exposure) even if they also have error handling implications — these are covered by
```
codeprobe-security
```
. If both sub-skills flag the same location, the orchestrator will deduplicate and keep the security finding as primary.

日志中的敏感数据 —— 由
```
codeprobe-security
```
（前缀
```
SEC
```
）负责检测。此子技能仅标记缺失日志和结构型问题（如无关联ID），不检测数据泄露。
测试文件 —— 测试用例的异常处理遵循不同模式，通常更简洁，不在检测范围内。
框架生成的异常处理器（例如Laravel的
```
Handler.php
```
、Next.js的极简错误边界）—— 这些是脚手架默认配置，不属于开发者疏漏。
故意采用简单错误处理的CLI脚本（打印+退出）—— 命令行工具常使用打印错误并以非零码退出的有效模式。
带有注释说明原因、故意吞掉特定已知无害异常的catch块 —— 如果开发者已记录理由，则尊重该决策。
主要属于安全漏洞的问题（例如身份验证绕过、注入攻击、数据暴露）—— 即使这些问题涉及错误处理，也由
```
codeprobe-security
```
负责检测。如果两个子技能标记了同一位置，编排器会去重并优先保留安全检测结果。

Detection Instructions

检测说明

Swallowed Exceptions

吞掉的异常

ID Prefix	What to Detect	How to Detect	Severity
`ERR`	Empty catch blocks	Search for `catch` blocks with empty body, only `pass` , only `// ignored` , or only a comment. In JS/TS: `catch (e) {}` . In PHP: `catch (\Exception $e) {}` . In Python: `except: pass` or `except Exception: pass` .	Major
`ERR`	Catch-log-only without handling	Find catch blocks that only contain a log/print statement but don't rethrow, return an error, or take any recovery action. The exception is swallowed after logging.	Minor
`ERR`	Overly broad exception catching	`catch (\Exception $e)` , `catch (Exception e)` , bare `except:` in Python, `catch (e)` catching all errors. Flag when a more specific exception type should be caught.	Major

ID前缀	检测内容	检测方式	严重程度
`ERR`	空catch块	搜索空主体的 `catch` 块，仅包含 `pass` 、 `// ignored` 或仅注释的块。在JS/TS中： `catch (e) {}` ；在PHP中： `catch (\Exception $e) {}` ；在Python中： `except: pass` 或 `except Exception: pass` 。	主要
`ERR`	仅记录日志但不处理的catch块	查找仅包含日志/打印语句，但不重新抛出、返回错误或采取任何恢复操作的catch块。异常在记录日志后被吞掉。	次要
`ERR`	过于宽泛的异常捕获	`catch (\Exception $e)` 、 `catch (Exception e)` 、Python中的裸 `except:` 、 `catch (e)` 捕获所有错误。当应该捕获更具体的异常类型时进行标记。	主要

Missing Error Handling

缺失错误处理

ID Prefix	What to Detect	How to Detect	Severity
`ERR`	External API calls without try/catch	Search for HTTP client calls (Guzzle, axios, fetch, requests, HttpClient), payment SDK calls (Stripe, PayPal), AWS SDK calls, and other external service integrations. Flag when these calls are NOT wrapped in try/catch or .catch().	Major
`ERR`	Unhandled promise rejections	Search for async functions or promise chains without `.catch()` or surrounding try/catch. Look for floating promises (async call without await). In Node.js, check for missing `unhandledRejection` handler.	Major
`ERR`	File I/O without error handling	`file_get_contents` , `fopen` , `fs.readFile` , `open()` (Python) without try/catch for IOError/FileNotFoundError.	Minor

ID前缀	检测内容	检测方式	严重程度
`ERR`	外部API调用未包裹try/catch	搜索HTTP客户端调用（Guzzle、axios、fetch、requests、HttpClient）、支付SDK调用（Stripe、PayPal）、AWS SDK调用及其他外部服务集成。当这些调用未被try/catch或.catch()包裹时进行标记。	主要
`ERR`	未处理的Promise拒绝	搜索未配置 `.catch()` 或未被try/catch包裹的异步函数或Promise链。查找浮动Promise（未使用await的异步调用）。在Node.js中，检查是否缺失 `unhandledRejection` 处理器。	主要
`ERR`	文件I/O操作未做错误处理	`file_get_contents` 、 `fopen` 、 `fs.readFile` 、Python中的 `open()` 未针对IOError/FileNotFoundError添加try/catch。	次要

Error Information

错误信息问题

ID Prefix	What to Detect	How to Detect	Severity
`ERR`	Generic error messages	API responses returning only "Something went wrong", "Internal server error", or similar without error codes or actionable detail for the client.	Minor
`ERR`	Leaking internal errors to API consumers	Exception messages, stack traces, SQL errors, or file paths exposed in API JSON/HTML responses. Check error handling middleware configuration.	Major
`ERR`	Missing structured error responses	API endpoints returning errors without consistent structure (no error code field, no message field, inconsistent formats across endpoints).	Minor

ID前缀	检测内容	检测方式	严重程度
`ERR`	通用错误消息	API响应仅返回"Something went wrong"、"Internal server error"或类似内容，未提供错误码或可供客户端操作的详细信息。	次要
`ERR`	向API消费者泄露内部错误	API的JSON/HTML响应中暴露异常消息、堆栈跟踪、SQL错误或文件路径。检查错误处理中间件的配置。	主要
`ERR`	缺失结构化错误响应	API端点返回的错误无一致结构（无错误码字段、无消息字段、端点间格式不一致）。	次要

Retry & Circuit Breaker

重试与断路器

ID Prefix	What to Detect	How to Detect	Severity
`ERR`	External service calls without timeout	HTTP client calls without timeout configuration. Guzzle without `timeout` option, axios without `timeout` , requests without `timeout` param, fetch without AbortController.	Major
`ERR`	No retry for transient failures	External API calls that could fail transiently (HTTP 429, 503, network errors) with no retry mechanism.	Minor
`ERR`	No circuit breaker for cascading failures	Service-to-service calls in microservice architectures with no circuit breaker or fallback pattern.	Suggestion

ID前缀	检测内容	检测方式	严重程度
`ERR`	外部服务调用未设置超时	未配置超时的HTTP客户端调用。Guzzle未设置 `timeout` 选项、axios未设置 `timeout` 、requests未传入 `timeout` 参数、fetch未使用AbortController。	主要
`ERR`	瞬态故障未配置重试	可能发生瞬态故障（HTTP 429、503、网络错误）的外部API调用未配置重试机制。	次要
`ERR`	未配置断路器以防止级联故障	微服务架构中的服务间调用未使用断路器或降级模式。	建议

Validation

验证问题

ID Prefix	What to Detect	How to Detect	Severity
`ERR`	Missing input validation before processing	Functions that accept external input (request params, file contents, API payloads) and use them directly without validation.	Major
`ERR`	Implicit null assumptions	Accessing properties or calling methods on values that could be null/undefined without null checks. Chaining `.` access on possibly-null return values.	Minor
`ERR`	Type coercion bugs	PHP `==` instead of `===` for security-sensitive comparisons. JS `==` instead of `===` . Implicit type conversions that could produce unexpected results.	Minor

ID前缀	检测内容	检测方式	严重程度
`ERR`	处理前缺失输入验证	接收外部输入（请求参数、文件内容、API负载）并直接使用，未做验证的函数。	主要
`ERR`	隐式空值假设	访问可能为null/undefined的值的属性或调用其方法，未做空值检查。对可能为null的返回值进行链式 `.` 访问。	次要
`ERR`	类型转换漏洞	PHP中在安全敏感比较时使用 `==` 而非 `===` ；JS中使用 `==` 而非 `===` ；可能产生意外结果的隐式类型转换。	次要

Transaction Safety

事务安全性

ID Prefix	What to Detect	How to Detect	Severity
`ERR`	Multi-step DB ops without transactions	Multiple `INSERT` / `UPDATE` / `DELETE` queries in sequence (same method) without `DB::transaction()` , `atomic()` , `BEGIN` / `COMMIT` , or equivalent. If any step fails, data is left in an inconsistent state.	Critical
`ERR`	Transaction without proper rollback	Transaction blocks that catch exceptions but don't rollback, or that have code after the transaction that assumes success without checking.	Major

ID前缀	检测内容	检测方式	严重程度
`ERR`	多步骤数据库操作未使用事务	连续执行多个 `INSERT` / `UPDATE` / `DELETE` 查询（同一方法内），未使用 `DB::transaction()` 、 `atomic()` 、 `BEGIN` / `COMMIT` 或等效机制。若任何步骤失败，数据会处于不一致状态。	严重
`ERR`	事务未配置正确回滚	捕获异常但不执行回滚的事务块，或事务后存在假设操作成功而未做检查的代码。	主要

Logging

日志问题

ID Prefix	What to Detect	How to Detect	Severity
`ERR`	No logging on critical failure paths	Catch blocks in critical business logic (payment, auth, order processing) that don't include any logging. Failures happen silently.	Major
`ERR`	Missing correlation/request IDs	Log statements in request-handling code without correlation ID, request ID, or trace ID. Makes debugging distributed issues impossible.	Minor

ID前缀	检测内容	检测方式	严重程度
`ERR`	关键故障路径无日志记录	关键业务逻辑（支付、认证、订单处理）中的catch块未包含任何日志记录。故障会静默发生。	主要
`ERR`	缺失关联/请求ID	请求处理代码中的日志语句未包含关联ID、请求ID或跟踪ID。这会导致无法调试分布式问题。	次要

ID Prefix & Fix Prompt Examples

ID前缀与修复提示示例

All findings use the

ERR-

prefix, numbered sequentially:

ERR-001

ERR-002

, etc.

所有检测结果使用

ERR-

前缀，按顺序编号：

ERR-001

、

ERR-002

等。

Fix Prompt Examples

修复提示示例

"Wrap the Stripe API call in
```
PaymentService@charge
```
(line 55) in a try/catch for
```
\Stripe\Exception\ApiErrorException
```
. Log the error with context (
```
$orderId
```
,
```
$amount
```
) and throw a domain-specific
```
PaymentFailedException
```
with a user-friendly message."
"Add
```
DB::transaction()
```
around the order creation flow in
```
OrderService@create
```
(lines 40-65) which currently creates an Order, OrderItems, and Payment record in three separate queries. If any step fails, all should roll back."
"Replace the empty catch block at
```
app/Services/NotificationService.php:88
```
with proper error handling: log the exception with notification context, then decide whether to rethrow (critical notification) or swallow with a metric (non-critical)."
"Add timeout and retry configuration to the HTTP client call at
```
ExternalApiClient.php:30
```
. Use
```
->timeout(10)->retry(3, 100)
```
for the Guzzle request to handle transient network failures."

"将
```
PaymentService@charge
```
（第55行）中的Stripe API调用包裹在针对
```
\Stripe\Exception\ApiErrorException
```
的try/catch中。记录包含上下文（
```
$orderId
```
、
```
$amount
```
）的错误，并抛出特定领域的
```
PaymentFailedException
```
，返回用户友好的消息。"
"在
```
OrderService@create
```
（第40-65行）的订单创建流程中添加
```
DB::transaction()
```
，当前该流程通过三个独立查询创建Order、OrderItems和Payment记录。若任何步骤失败，所有操作应回滚。"
"将
```
app/Services/NotificationService.php:88
```
处的空catch块替换为正确的错误处理：记录包含通知上下文的异常，然后决定是重新抛出（关键通知）还是通过指标吞掉（非关键通知）。"
"为
```
ExternalApiClient.php:30
```
处的HTTP客户端调用添加超时和重试配置。对Guzzle请求使用
```
->timeout(10)->retry(3, 100)
```
以处理瞬态网络故障。"