Error Handling

affaan-m/ECC/skills/error-handling

作者 affaan-mef648e01899ba3e8dc6371642deaaf64b4477775無授權條款275K 個星標收錄於 2026年10月9日更新於 2026年10月9日儲存庫4 天前更新

Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages. Use when designing error types, retries, circuit breakers, or user-facing failure messages in TypeScript, Python, or Go.

僅含說明Software Development
AI 產生的概覽

適用於 TypeScript、Python 與 Go 的穩健錯誤處理模式，涵蓋具型別錯誤、重試與使用者可見的錯誤訊息。

功能
提供在 TypeScript、Python 與 Go 中維持一致錯誤處理的指引與程式碼模式。內容涵蓋具型別錯誤階層、Result 模式、API 錯誤處理器、React 錯誤邊界、FastAPI 例外處理器、Go 哨兵錯誤與錯誤包裝、含指數退避的重試，以及面向使用者的錯誤訊息。另包含一份合併前的錯誤處理檢查清單。
適用情境
適用於設計錯誤型別或例外階層、為不可靠的相依項目加入重試邏輯或斷路器、審查 API 端點是否缺少錯誤處理，或撰寫面向使用者的失敗訊息。對象為 TypeScript、Python 與 Go 程式碼庫。
執行需求
不需要任何指令碼或工具，僅為純說明的參考文件。這些模式適用於 TypeScript/JavaScript、Python 與 Go 專案，範例中提及 Next.js、Express、Zod、React 與 FastAPI 等函式庫。

Error Handling Patterns

Consistent, robust error handling patterns for production applications.

When to Activate

  • Designing error types or exception hierarchies for a new module or service
  • Adding retry logic or circuit breakers for unreliable external dependencies
  • Reviewing API endpoints for missing error handling
  • Implementing user-facing error messages and feedback
  • Debugging cascading failures or silent error swallowing

Core Principles

  1. Fail fast and loudly — surface errors at the boundary where they occur; don't bury them
  2. Typed errors over string messages — errors are first-class values with structure
  3. User messages ≠ developer messages — show friendly text to users, log full context server-side
  4. Never swallow errors silently — every catch block must either handle, re-throw, or log
  5. Errors are part of your API contract — document every error code a client may receive

TypeScript / JavaScript

Typed Error Classes

typescript
// Define an error hierarchy for your domainexport class AppError extends Error {  constructor(    message: string,    public readonly code: string,    public readonly statusCode: number = 500,    public readonly details?: unknown,  ) {    super(message)    this.name = this.constructor.name    // Maintain correct prototype chain in transpiled ES5 JavaScript.    // Required for `instanceof` checks (e.g., `error instanceof NotFoundError`)    // to work correctly when extending the built-in Error class.    Object.setPrototypeOf(this, new.target.prototype)  }}
export class NotFoundError extends AppError {  constructor(resource: string, id: string) {    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404)  }}
export class ValidationError extends AppError {  constructor(message: string, details: { field: string; message: string }[]) {    super(message, 'VALIDATION_ERROR', 422, details)  }}
export class UnauthorizedError extends AppError {  constructor(reason = 'Authentication required') {    super(reason, 'UNAUTHORIZED', 401)  }}
export class RateLimitError extends AppError {  constructor(public readonly retryAfterMs: number) {    super('Rate limit exceeded', 'RATE_LIMITED', 429)  }}

Result Pattern (no-throw style)

For operations where failure is expected and common (parsing, external calls):

typescript
type Result<T, E = AppError> =  | { ok: true; value: T }  | { ok: false; error: E }
function ok<T>(value: T): Result<T> {  return { ok: true, value }}
function err<E>(error: E): Result<never, E> {  return { ok: false, error }}
// Usageasync function fetchUser(id: string): Promise<Result<User>> {  try {    const user = await db.users.findUnique({ where: { id } })    if (!user) return err(new NotFoundError('User', id))    return ok(user)  } catch (e) {    return err(new AppError('Database error', 'DB_ERROR'))  }}
const result = await fetchUser('abc-123')if (!result.ok) {  // TypeScript knows result.error here  logger.error('Failed to fetch user', { error: result.error })  return}// TypeScript knows result.value hereconsole.log(result.value.email)

API Error Handler (Next.js / Express)

typescript
import { NextRequest, NextResponse } from 'next/server'
function handleApiError(error: unknown): NextResponse {  // Known application error  if (error instanceof AppError) {    return NextResponse.json(      {        error: {          code: error.code,          message: error.message,          ...(error.details ? { details: error.details } : {}),        },      },      { status: error.statusCode },    )  }
  // Zod validation error  if (error instanceof z.ZodError) {    return NextResponse.json(      {        error: {          code: 'VALIDATION_ERROR',          message: 'Request validation failed',          details: error.issues.map(i => ({            field: i.path.join('.'),            message: i.message,          })),        },      },      { status: 422 },    )  }
  // Unexpected error — log details, return generic message  console.error('Unexpected error:', error)  return NextResponse.json(    { error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } },    { status: 500 },  )}
export async function POST(req: NextRequest) {  try {    // ... handler logic  } catch (error) {    return handleApiError(error)  }}

React Error Boundary

typescript
import { Component, ErrorInfo, ReactNode } from 'react'
interface Props {  fallback: ReactNode  onError?: (error: Error, info: ErrorInfo) => void  children: ReactNode}
interface State {  hasError: boolean  error: Error | null}
export class ErrorBoundary extends Component<Props, State> {  state: State = { hasError: false, error: null }
  static getDerivedStateFromError(error: Error): State {    return { hasError: true, error }  }
  componentDidCatch(error: Error, info: ErrorInfo) {    this.props.onError?.(error, info)    console.error('Unhandled React error:', error, info)  }
  render() {    if (this.state.hasError) return this.props.fallback    return this.props.children  }}
// Usage<ErrorBoundary fallback={<p>Something went wrong. Please refresh.</p>}>  <MyComponent /></ErrorBoundary>

Python

Custom Exception Hierarchy

python
class AppError(Exception):    """Base application error."""    def __init__(self, message: str, code: str, status_code: int = 500):        super().__init__(message)        self.code = code        self.status_code = status_code
class NotFoundError(AppError):    def __init__(self, resource: str, id: str):        super().__init__(f"{resource} not found: {id}", "NOT_FOUND", 404)
class ValidationError(AppError):    def __init__(self, message: str, details: list[dict] | None = None):        super().__init__(message, "VALIDATION_ERROR", 422)        self.details = details or []

FastAPI Global Exception Handler

python
from fastapi import FastAPI, Requestfrom fastapi.responses import JSONResponse
app = FastAPI()
@app.exception_handler(AppError)async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:    return JSONResponse(        status_code=exc.status_code,        content={"error": {"code": exc.code, "message": str(exc)}},    )
@app.exception_handler(Exception)async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse:    # Log full details, return generic message    logger.exception("Unexpected error", exc_info=exc)    return JSONResponse(        status_code=500,        content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}},    )

Go

Sentinel Errors and Error Wrapping

go
package domain
import "errors"
// Sentinel errors for type-checkingvar (    ErrNotFound    = errors.New("not found")    ErrUnauthorized = errors.New("unauthorized")    ErrConflict     = errors.New("conflict"))
// Wrap errors with context — never lose the originalfunc (r *UserRepository) FindByID(ctx context.Context, id string) (*User, error) {    user, err := r.db.QueryRow(ctx, "SELECT * FROM users WHERE id = $1", id)    if errors.Is(err, sql.ErrNoRows) {        return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)    }    if err != nil {        return nil, fmt.Errorf("querying user %s: %w", id, err)    }    return user, nil}
// At the handler level, unwrap to determine responsefunc (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) {    user, err := h.service.GetUser(r.Context(), chi.URLParam(r, "id"))    if err != nil {        switch {        case errors.Is(err, domain.ErrNotFound):            writeError(w, http.StatusNotFound, "not_found", err.Error())        case errors.Is(err, domain.ErrUnauthorized):            writeError(w, http.StatusForbidden, "forbidden", "Access denied")        default:            slog.Error("unexpected error", "err", err)            writeError(w, http.StatusInternalServerError, "internal_error", "An unexpected error occurred")        }        return    }    writeJSON(w, http.StatusOK, user)}

Retry with Exponential Backoff

typescript
interface RetryOptions {  maxAttempts?: number  baseDelayMs?: number  maxDelayMs?: number  retryIf?: (error: unknown) => boolean}
async function withRetry<T>(  fn: () => Promise<T>,  options: RetryOptions = {},): Promise<T> {  const {    maxAttempts = 3,    baseDelayMs = 500,    maxDelayMs = 10_000,    retryIf = () => true,  } = options
  let lastError: unknown
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {    try {      return await fn()    } catch (error) {      lastError = error      if (attempt === maxAttempts || !retryIf(error)) throw error
      const jitter = Math.random() * baseDelayMs      const delay = Math.min(baseDelayMs * 2 ** (attempt - 1) + jitter, maxDelayMs)      await new Promise(resolve => setTimeout(resolve, delay))    }  }
  throw lastError}
// Usage: retry transient network errors, not 4xxconst data = await withRetry(() => fetch('/api/data').then(r => r.json()), {  maxAttempts: 3,  retryIf: (error) => !(error instanceof AppError && error.statusCode < 500),})

User-Facing Error Messages

Map error codes to human-readable messages. Keep technical details out of user-visible text.

typescript
const USER_ERROR_MESSAGES: Record<string, string> = {  NOT_FOUND: 'The requested item could not be found.',  UNAUTHORIZED: 'Please sign in to continue.',  FORBIDDEN: "You don't have permission to do that.",  VALIDATION_ERROR: 'Please check your input and try again.',  RATE_LIMITED: 'Too many requests. Please wait a moment and try again.',  INTERNAL_ERROR: 'Something went wrong on our end. Please try again later.',}
export function getUserMessage(code: string): string {  return USER_ERROR_MESSAGES[code] ?? USER_ERROR_MESSAGES.INTERNAL_ERROR}

Error Handling Checklist

Before merging any code that touches error handling:

  • Every catch block handles, re-throws, or logs — no silent swallowing
  • API errors follow the standard envelope { error: { code, message } }
  • User-facing messages contain no stack traces or internal details
  • Full error context is logged server-side
  • Custom error classes extend a base AppError with a code field
  • Async functions surface errors to callers — no fire-and-forget without fallback
  • Retry logic only retries retriable errors (not 4xx client errors)
  • React components are wrapped in ErrorBoundary for rendering errors

來源與署名

來源：affaan-m/ECC位於skills/error-handling提交ef648e0

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 affaan-m/ECC 的技能

Unified Notifications Ops

affaan-m

設計統一的通知策略，對來自 GitHub、Linear、鉤子與聊天工具的通知進行分類、路由、去重與升級。

Productivity & Workflow275K4 天前更新

Verification Loop

affaan-m

執行六階段程式碼驗證流程，並產出 PASS/FAIL 就緒報告。

Software Development275K4 天前更新

Ui To Vue

affaan-m

將批次 UI 設計截圖轉換為使用 Vant、Element Plus 或 Ant Design Vue 的 Vue 3 元件。

Software Development275K4 天前更新

Unified Memory

affaan-m

指導代理透過本機 ECC Memory Vault 在不同執行框架之間共享持久脈絡與交接資訊。

AI & Agents275K4 天前更新

Visa Doc Translate

affaan-m

透過 OCR 將簽證文件影像翻譯成英文，並產出原圖與譯文對照的雙語 PDF。

Documents & Office275K4 天前更新

Team Builder

affaan-m

互動式挑選器：探索可用的代理角色，讓使用者最多選五個，平行執行同一任務並彙整結果。

AI & Agents275K4 天前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新