為什麼自定義 404 頁面需要同時支持 API 和 HTML：新手指南
更新日期： 2025 年 1 月 1 日
本文為 Django + Vue 前後端分離解析，第 4 篇：
- 前後端分離的 404 錯誤處理：步驟指南
- 正常網頁與 API 接口：新手指南
- GraphQL 與 REST：理解新時代的 API 設計
- 為什麼自定義 404 頁面需要同時支持 API 和 HTML：新手指南 👈 所在位置
- 前後端分離中的路由與錯誤處理：新手指南
- 設計後端 API 的 404 錯誤處理：新手指南
- 前端與後端的 HTTP 請求與響應協議
- Django 中自定義 404 專案架構的最佳實踐
- 深入理解 Django 中的自定義 404 views 函數處理解析
- Django 的 handler404：自定義 404 錯誤頁面的核心
- Django 的 render 函數與 status 參數：為什麼重要？
- 使用 Accept 判斷請求格式：如何實現靈活的錯誤處理？
- 使用 Esbuild 搭建 Vue 開發環境的指南
- 新手入門：TailwindCSS 與 DaisyUI 的整合指南
- Django 靜態文件管理：static 與 staticfiles 完整指南
- 使用 WhiteNoise 簡化 Django 靜態文件管理：新手入門指南
- Vue 與 Django 整合：從編輯到部署的完整指南
- Django 與 Vue 的專案目錄與設計流程指南
- Django + Vue 前後端分離架構：後端路由渲染解析
- Vue 3 應用的主入口詳解：如何初始化應用
- 探索 Vue 應用的根組件：App.vue 的角色與設計
- Vue.js 單頁應用（SPA）邏輯與運作流程詳解
- 新手指南：使用 Axios 實現高效的 HTTP 請求
- 在 Vue 中處理 404 錯誤組件（component）設計：新手指南
- Vue Router 新手指南：設置 404 錯誤頁面
在現代開發中，一個後端服務器經常同時支持：
- API 請求：為前端應用或第三方工具提供數據。
- HTML 請求：為普通瀏覽器用戶提供直觀的頁面。
因此，當用戶訪問一個不存在的路徑時，我們的自定義 404 錯誤處理函數需要根據請求的來源返回不同類型的響應——JSON 格式的數據 或 HTML 模板
本文將詳細講解這種設計的原因、應用場景以及如何實現。
API 與 HTML 共存的必要性
Django 是全功能框架
Django 不僅用於構建 API（例如通過 Django REST Framework），也常用於構建傳統的 Web 應用。這使得後端可能需要同時處理：
- API 請求：返回數據供前端程式使用。
- HTML 請求：為普通用戶渲染完整的頁面。
例如：
- API 請求：
https://example.com/api/users - HTML 請求：
https://example.com/about
不同類型的請求需要不同的返回格式
- API 請求：
- 返回 JSON 格式的錯誤信息，方便前端應用程式或工具（如 Postman）解析。
- 例如：
{
"error": "Page not found",
"status_code": 404,
"detail": "The requested URL was not found on this server."
}- HTML 請求：
- 返回一個友好的錯誤頁面，提升普通用戶體驗。
- 例如：
<h1>404 - Page Not Found</h1>
<p>Oops! The page you're looking for doesn't exist.</p>代碼重用的優勢
在 Django 中，我們可以通過一個統一的函數處理這兩種類型的請求。這樣做的好處是：
- 減少代碼重複：不需要為 API 和 HTML 錯誤分別撰寫兩套邏輯。
- 維護方便：修改錯誤處理邏輯時，只需更改一處代碼。
常見的使用場景
API 客戶端請求
- 場景：前端框架（如 React、Vue）或測試工具（如 Postman）向後端發送 API 請求，但路徑不存在。
- 需求：返回結構化的 JSON 錯誤信息，便於程式解析和處理。
- 例子：
- 請求 URL：
GET https://example.com/api/nonexistent - 返回結果：
- 請求 URL：
{
"error": "Page not found",
"status_code": 404,
"detail": "The requested URL was not found on this server."
}瀏覽器直接訪問
- 場景：用戶在瀏覽器中手動輸入錯誤的 URL（如
/some-wrong-url）。 - 需求：返回一個美觀的 HTML 錯誤頁面，例如包含「404 – 頁面不存在」的提示。
- 例子：
- 請求 URL：
https://example.com/some-wrong-url - 返回結果：
- 請求 URL：
<html>
<body>
<h1>404 - Page Not Found</h1>
<p>Oops! The page you're looking for doesn't exist.</p>
</body>
</html>-
<html> <body> <h1>404 - Page Not Found</h1> <p>Oops! The page you're looking for doesn't exist.</p> </body> </html>
如何實現判斷請求類型
在 Django 的 custom_404_view 中，我們可以通過請求頭中的 Accept 標頭判斷用戶想要的返回類型：
Accept: application/json：請求 API，返回 JSON。Accept: text/html或無Accept標頭：請求 HTML，返回錯誤頁面。
實現邏輯
- 檢查
request.headers.get("Accept")。 - 如果包含
application/json，返回 JSON。 - 否則，返回 HTML 模板。
如果只需要支持 API
在某些專注於 API 的項目中（如純後端服務），可以簡化錯誤處理邏輯，只返回 JSON 格式的錯誤信息：
簡化版邏輯
from django.http import JsonResponse
def custom_404_view(request, exception):
return JsonResponse({
"error": "Page not found",
"status_code": 404,
"detail": "The requested URL was not found on this server."
}, status=404)
在這種情況下，瀏覽器和 API 客戶端都會看到相同的 JSON 格式錯誤信息。
HTML 作為備用方案
HTML 的作用
- 當用戶使用瀏覽器直接訪問錯誤的 URL 時，HTML 提供了一個直觀的界面，告訴用戶「頁面不存在」。
- 與 JSON 錯誤相比，HTML 更適合普通用戶。
API 安全性的考慮
- 雖然 API 的路徑通常不會被普通用戶直接訪問，但仍然需要做好安全措施，例如：
- 身份驗證：保證只有授權的用戶可以訪問 API。
- 速率限制：防止濫用 API。
- 隱藏敏感數據：即使是錯誤信息，也應避免洩露內部結構。
結論與建議
- 兼容 API 和 HTML 錯誤：
- 對於大多數項目，建議支持 JSON 和 HTML 兩種返回格式，提升靈活性和用戶體驗。
- 根據
Accept標頭自動適配響應類型。
- 僅支持 API 的情況：
- 如果項目完全基於 API，則可以簡化處理邏輯，只返回 JSON 格式的錯誤信息。
- 安全與用戶體驗並重：
- API 的錯誤信息應避免洩露後端內部結構。
- HTML 錯誤頁應直觀且易懂，為普通用戶提供清晰的指引。
希望本文能幫助你理解為什麼需要在 404 錯誤處理中支持 API 和 HTML！如果還有疑問，隨時向我提問！ 😊