錯誤處理模式
適用於生產應用的穩健且一致的錯誤處理模式。
啟動時機
- 為新模組或服務設計錯誤型別或例外階層
- 為不可靠的外部依賴添加重試邏輯或斷路器
- 審查 API 端點，確認是否遺漏錯誤處理
- 實作使用者友善的錯誤訊息與回饋
- 偵錯串聯失敗或靜默錯誤吞掉的情況
核心原則
- 快速失敗且大聲回報 — 在錯誤發生的邊界處就將錯誤浮現；不要埋藏它們
- 型別化錯誤優於字串訊息 — 錯誤是帶有結構的一級值
- 使用者訊息 ≠ 開發者訊息 — 對使用者顯示友善文字，在伺服器端記錄完整上下文
- 絕不沉默地吞掉錯誤 — 每一個
catch區塊都必須要處理、重新拋出或記錄 - 錯誤是你的 API 合約的一部分 — 文件化客戶端可能收到的每個錯誤代碼
TypeScript / JavaScript
型別化錯誤類別
// 為你的領域定義一個錯誤階層
export 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 模式（無拋出風格）
適用於失敗是預期且常見的操作（例如解析、外部呼叫）：
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 }
}
// 使用方式
async 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 here
console.log(result.value.email)
API 錯誤處理器（Next.js / Express）
import { NextRequest, NextResponse } from 'next/server'
function handleApiError(error: unknown): NextResponse {
// 已知的應用程式錯誤
if (error instanceof AppError) {
return NextResponse.json(
{
error: {
code: error.code,
message: error.message,
...(error.details ? { details: error.details } : {}),
},
},
{ status: error.statusCode },
)
}
// Zod 驗證錯誤
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 },
)
}
// 非預期錯誤 — 記錄詳細資訊，回傳通用訊息
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 錯誤邊界
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
}
}
// 使用方式
<ErrorBoundary fallback={<p>Something went wrong. Please refresh.</p>}>
<MyComponent />
</ErrorBoundary>
Python
自訂例外階層
class AppError(Exception):
"""基礎應用程式錯誤。"""
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 全域例外處理器
from fastapi import FastAPI, Request
from 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:
# 記錄完整細節，回傳通用訊息
logger.exception("Unexpected error", exc_info=exc)
return JSONResponse(
status_code=500,
content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}},
)
Go
哨兵錯誤與錯誤包裝
package domain
import "errors"
// 用於型別檢查的哨兵錯誤
var (
ErrNotFound = errors.New("not found")
ErrUnauthorized = errors.New("unauthorized")
ErrConflict = errors.New("conflict")
)
// 用上下文包裝錯誤 — 絕不失去原始錯誤
func (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
}
// 在 handler 層級，解開以決定回應
func (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)
}
使用指數退避重試
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
}
// 使用方式：重試暫時性網路錯誤，不重試 4xx
const data = await withRetry(() => fetch('/api/data').then(r => r.json()), {
maxAttempts: 3,
retryIf: (error) => !(error instanceof AppError && error.statusCode < 500),
})
使用者友善的錯誤訊息
將錯誤代碼對應到人類可讀的訊息。將技術細節保留在使用者可見文字之外。
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
}
錯誤處理核對清單
在合併任何涉及錯誤處理的程式碼前：
- 每個
catch區塊都有處理、重新拋出或記錄 — 沒有靜默吞掉 - API 錯誤遵循標準信封格式
{ error: { code, message } } - 使用者友善的訊息不包含堆疊追蹤或內部細節
- 伺服器端記錄了完整的錯誤上下文
- 自訂錯誤類別繼承一個帶有
code欄位的基礎AppError - 非同步函數將錯誤上浮給呼叫者 — 沒有不帶後備的 fire-and-forget
- 重試邏輯僅重試可重試的錯誤（不是 4xx 客戶端錯誤）
- React 元件使用
ErrorBoundary包裝以處理渲染錯誤