設計後端 API 的 404 錯誤處理：新手指南

更新日期： 2025 年 1 月 1 日

在網站或應用開發中，處理 404 錯誤是一項基本且重要的工作。

良好的錯誤處理不僅提升用戶體驗，還能幫助開發者在前後端整合時提高效率。

本文將帶你了解如何設計兼容 API 和瀏覽器的 404 錯誤處理，並詳解代碼中每個部分的作用與邏輯。

前言

404 錯誤表示用戶請求的資源不存在，這種情況可能來自兩種場景：

1. 用戶通過瀏覽器訪問不存在的頁面。
2. 前端應用程序通過 API 發送無效請求。

為了兼容這兩類需求，我們需要設計兩個專用的處理函數，並將它們與適當的路由綁定，確保返回的響應結構適配用戶場景。

定義兩個錯誤處理函數

在後端，我們設計了兩個專門的錯誤處理函數：custom_404 和 api_not_found。它們分別應對不同類型的請求。

ustom_404 函數

此函數負責處理所有未匹配的路徑，包括 API 和普通瀏覽器請求。

def custom_404(request, exception):
    if "application/json" in request.headers.get("Accept", ""):
        return JsonResponse({
            "error": "Not found",
            "status_code": 404,
            "detail": "The requested resource was not found",
            }, status=404)
    else:
        return render(request, "common/404.html", status=404)

作用與設計意圖

• 請求類型判斷：
  • 判斷請求頭中是否包含 application/json，以識別是否為 API 請求。
• 響應適配：
  • 對於 API 請求，返回結構化的 JSON 數據，便於前端程序解析。
  • 對於普通瀏覽器請求，渲染 HTML 錯誤頁面，提升用戶體驗。

重點：custom_404 是全局的錯誤處理函數，適用於處理所有未匹配的請求。

api_not_found 函數

此函數專門針對 API 的 404 錯誤設計，返回統一的 JSON 格式錯誤響應。

def api_not_found(request):
    return JsonResponse({
        "error": "Not found",
        "status_code": 404,
        "detail": "The requested resource was not found",
    }, status=404)

作用與設計意圖

• 專用性：
  • 該函數僅處理 API 請求，不涉及 HTML 模板渲染。
• 響應結構：
  • 返回清晰、標準化的 JSON 數據，包括：
    • error：簡要描述錯誤類型。
    • status_code：HTTP 狀態碼，標識錯誤性質。
    • detail：詳細錯誤信息，幫助前端開發者定位問題。

重點：api_not_found 是一個專用的 API 錯誤處理函數，用於針對 API 路徑的集中處理。

為什麼需要兩個函數

在後端 404 錯誤處理中，設計兩個不同的函數可以帶來以下優勢：

1. 場景分離：
   • custom_404 負責全局處理，既適配瀏覽器頁面，又能處理 API 請求。
   • api_not_found 集中處理特定的 API 路徑，保證 API 響應的統一性。
2. 靈活性提升：
   • 在未來需求變化時，可以針對 API 或 HTML 的處理邏輯進行單獨修改，而不影響另一部分的功能。
3. 清晰的代碼責任：
   • 開發者能快速理解每個函數的用途，降低代碼維護難度。

配置路由以對應不同場景

接下來，我們將這兩個函數分別綁定到合適的路由，確保後端邏輯能正確處理請求。

子應用路由設置

在 common 應用的 urls.py 中，我們將 api_not_found 函數綁定到 /404/ 路徑：

urlpatterns = [
    path("404/", api_not_found),  # 捕獲所有未匹配的 API 請求
]

作用與意圖

• 該路由專門用於處理未匹配的 API 請求。
• 為 API 設置專用路徑，使其響應與普通網頁請求分離，方便測試和維護。

主應用路由設置

在主應用的 urls.py 中，我們進行以下設置：

urlpatterns = [
    path("api/", include("common.urls")),  # 將 API 路徑集中管理
]

handler404 = custom_404  # 全局 404 錯誤處理

作用與意圖

1. API 路徑命名空間：
   • 使用 /api/ 作為前綴，統一管理所有 API 路徑，方便擴展和調試。
2. 全局錯誤處理：
   • 通過 handler404 將未捕獲的路由指向 custom_404。
   • 作用：確保所有未匹配的請求都能統一處理，包括瀏覽器請求和 API 請求。

設計 HTML 錯誤頁面

在瀏覽器場景中，用戶更需要直觀、友好的錯誤頁面來指引下一步操作。

HTML 模板設計重點

1. 清晰的錯誤信息：
   • 明確告知用戶「頁面不存在」，避免造成混淆。
2. 提供操作選項：
   • 添加返回首頁、聯繫我們等按鈕，幫助用戶快速脫離錯誤場景。
3. 吸引人的設計：
   • 使用簡潔美觀的排版和插圖，減輕錯誤帶來的不良體驗。

總結

設計一套完整的 404 錯誤處理方案需要考慮用戶場景與系統結構。以下是關鍵點總結：

1. custom_404 與 api_not_found 職責清晰：
   • 一個適配全局場景，另一個專注於 API 錯誤。
2. 路由配置明確：
   • 通過 /api/ 和全局 handler404 進行場景分離，方便管理和調試。
3. 兼容用戶需求：
   • API 響應返回結構化數據，瀏覽器顯示直觀的 HTML 錯誤頁面。

透過這些設計，新手開發者也能輕鬆實現一套高效的 404 錯誤處理系統，為項目增添專業性和用戶友好性。