error-handling

name	error-handling
description	錯誤處理與 Result Pattern 技能，協助開發者實作統一的錯誤處理機制，包含 Result Pattern 應用、Failure 物件建立與分層錯誤處理策略。

⚠️ 前置條件

本 SKILL 須搭配閱讀：開發規則

Error Handling Skill

描述

錯誤處理與 Result Pattern 技能，協助開發者實作統一的錯誤處理機制，包含 Result Pattern 應用、Failure 物件建立與分層錯誤處理。

職責

• Result Pattern 應用指導
• Failure 物件建立與封裝
• FailureCode 映射至 HTTP 狀態碼
• 分層錯誤處理策略

注意事項

Error Handling 與 API 開發流程無關

錯誤處理是跨層級的通用模式，不受「API First vs Code First」選擇影響：

• API First：Controller 實作自動產生的介面 → 使用 Result Pattern
• Code First：Controller 直接實作 → 使用 Result Pattern
• 結果：錯誤處理代碼完全相同

因此本 SKILL 未區分 API 開發流程，所有 Result Pattern 與錯誤處理指導均適用於兩種方式。

👉 API 開發流程選擇 → 參考 /api-development SKILL

核心原則

Result Pattern

使用 CSharpFunctionalExtensions 套件，統一錯誤處理：

public async Task<Result<TSuccess, Failure>> MethodAsync(...)
{
    // 成功路徑
    return Result.Success<TSuccess, Failure>(data);

    // 失敗路徑
    return Result.Failure<TSuccess, Failure>(new Failure { ... });
}

Failure 物件結構

public class Failure
{
    public string Code { get; set; }           // 錯誤代碼
    public string Message { get; set; }        // 錯誤訊息
    public string TraceId { get; set; }        // 追蹤 ID
    public Exception? Exception { get; set; }  // 原始例外（不序列化）
    public Dictionary<string, object>? Data { get; set; }  // 額外資料
}

FailureCode 列舉

public enum FailureCode
{
    Unauthorized,        // 401
    ValidationError,     // 400
    DuplicateEmail,      // 409
    NotFound,           // 404
    DbError,            // 500
    DbConcurrency,      // 409
    InvalidOperation,   // 400
    Timeout,            // 408
    InternalServerError, // 500
    Unknown             // 500
}

分層錯誤處理

Repository 層

• 捕捉資料庫例外（DbUpdateException、DbUpdateConcurrencyException）
• 封裝為 Failure 物件
• 保存原始例外到 Exception 屬性

Handler 層

• 處理業務邏輯錯誤
• 轉發 Repository 的錯誤
• 不記錄日誌（由 Middleware 處理）

Controller 層

• 使用 FailureCodeMapper 映射為 HTTP 狀態碼
• 回傳適當的 HTTP 回應

Middleware 層

• ExceptionHandlingMiddleware 捕捉未處理的系統例外
• 記錄錯誤日誌
• 統一回應格式

參考文件

• Result Pattern 最佳實踐

實作範例

開發者應參考專案內的實際實作代碼：

Failure 實作：

node .claude/skills/shared/FileResolver.js get-content \
  src/JobBank1111.Infrastructure/Results/Failure.cs