現代 Web 服務中，檔案上傳是一個常見的情境。

無論是使用者上傳照片、夾帶附件，檔案上傳都是不可或缺的功能。

本文介紹如何在 Django Ninja 中實現圖片上傳功能，以使用者「上傳大頭貼」（以下都稱為 avatar，因為大頭貼感覺太可愛🥹）API 為例，帶你一步步了解這個過程。

本文所有的程式碼改動，可參考這個 PR。

---

不過，在此之前，我們要先了解，本章有哪些主題。

第六章「API 進階功能」簡介

對 API 專案而言，進階功能能幫助我們應對複雜場景與大型專案的挑戰。

雖然這是一個入門指南，但我們仍會涵蓋一些常見的進階功能，這些功能不僅提升 API 的靈活性，還能增強了系統效能與使用者體驗。

本章共有 5 篇，介紹 3 個常見的進階功能：

• 卷 23：檔案上傳——Django UploadedFile 介紹（本文）
• 卷 24：分頁（上）Django Ninja 的內建分頁器
• 卷 25：分頁（下）自定義分頁類別
• 卷 26：資料查詢與過濾（上）FilterSchema 介紹
• 卷 27：資料查詢與過濾（下）FilterSchema 多欄位查詢

這些技術不僅對大型專案至關重要，也讓你能在 API 開發中，有效應對多變的需求。

上一篇文章，我們學習了如何操作HttpError，並建議你只在 view 函式中使用它。

但光是這樣，專案 API 的錯誤處理，還遠遠不夠完善，至少有 3 個常見問題待解：

1. Schema 中的驗證方法 ，如果不要raise HttpError，那要怎麼做才好？
2. 我們應該如何處理其他類型的錯誤，例如資料庫操作錯誤？
3. 如何確保不同 API 錯誤的回應格式一致？

這些問題都指向了一個更大的需求：我們需要一個全面的錯誤處理機制。

這篇文章，就要來回答這些問題。所有的程式碼改動，可參考這個 PR。

在軟體開發中，錯誤處理是一個不容忽視——但常常被忽視——的環節。

不誇張地說，錯誤處理是一個「做得好沒人誇，做不好系統就慘兮兮」的議題。

沒關係，我們還是盡可能把自己做好。

Django Ninja 使用 Pydantic 進行資料驗證，失敗時，預設回應「422 Unprocessable Entity」。

然而，我們有時候需要回應「400 Bad Request」或別的狀態碼，以符合現實業務需求或團隊開發習慣。

總之，無論出於何種原因，我們想自訂錯誤訊息、格式，以及回應的狀態碼，而不使用 Django Ninja 預設的 422 回應——不得不說，這個制式回應的資訊有點多、結構有點複雜，因為它要兼容各種情況。

本文將介紹如何自定義錯誤處理與回應——使用 Django Ninja 內建的HttpError。

所有的程式碼改動，可參考這個 PR。

---

Django Ninja 的自動錯誤處理

上一篇我們提到，如果你在 Schema 的驗證方法中，拋出ValueError錯誤，Django Ninja 將會自動捕捉並回應。

事實上，不止ValueError，Django Ninja 還會替你處理以下這幾種錯誤：

• pydantic.ValidationError，來自 Pydantic 的驗證錯誤，這是為何當 Schema 欄位有問題時，我們會直接收到 422 回應。
• 此外，Django Ninja 還內建了一個 ninja.errors.ValidationError，這些錯誤同樣會返回 422。
• ninja.errors.HttpError：這是本文的重點，下面會介紹。

這些都是 Django Ninja 會自動捕捉的錯誤，但不是每一種都給出制式的 422 回應——第三種就不是。

上一篇我們講完了單一欄位的自定義驗證，這篇則要來討論跨欄位之間的驗證。

跨欄位驗證同樣是 API 開發中十分常見的需求，例如註冊帳號時，要保證「密碼」與「確認密碼」兩個欄位內容相同；選擇日期期間時，開始日期不能晚於結束日期等。

這些驗證場景無法透過單一欄位驗證實現，因為它們需要同時檢查多個欄位之間的邏輯關聯，來確保整體資料的一致性和正確性。

本文將介紹如何透過 Pydantic 來實現跨欄位驗證需求——以「確認密碼」為例，展示這個功能的實際應用。

本文所有的程式碼改動，可參考這個 PR。

---

跨欄位驗證與關注點分離

其實，無論是單一欄位還是跨欄位的自定義驗證，都不一定要藉由 Pydantic 來完成。

理論上，資料驗證可以直接在 view 函式中進行，例如取出輸入的欄位值，手動驗證它的合法性。跨欄位驗證也是如此。

然而，這是一種方便但「粗糙」的做法——只適合用在驗證邏輯非常單純的情況。

透過 Pydantic 進行資料驗證，則能夠帶來一個明顯的好處：關注點分離。

資料驗證是 API 開發中的關鍵需求之一，它負責確保從客戶端提交的資料是符合預期的，從而避免潛在的錯誤和安全問題。

有效的資料驗證可以在 API 接收到錯誤資料時，給出即時且友善的回應，提升系統的穩定性和使用者體驗。

Django Ninja 中，資料驗證的核心工具是 Pydantic。它提供了強大的驗證功能，不僅能對資料型別進行檢查，還能輕鬆實現自定義驗證。

本文將介紹如何在 Django Ninja 中使用 Pydantic 實作單一欄位的自定義驗證；下一篇則講述跨欄位的自定義驗證。

本文所有的程式碼變動，可參考這個 PR。

---

第五章總論

資料驗證很重要，而驗證失敗時，程式往往會拋出驗證錯誤。如何有效處理這些錯誤，則是「錯誤處理」要討論的範疇。

本章將探討這兩個密切相關的主題，共計 4 篇文章：

• 卷 19：資料驗證（上）Pydantic 單一欄位驗證（本文）
• 卷 20：資料驗證（下）Pydantic 跨欄位驗證
• 卷 21：錯誤處理（上）HttpError 與自定義 HTTP 回應
• 卷 22：錯誤處理（下）全域錯誤處理——使用 Exception Handlers

前兩篇，我們會學習如何實現靈活的資料驗證，以確保輸入資料符合預期，並在必要時拋出錯誤。

後兩篇，我們將討論如何處理 API 流程中可能出現的各種錯誤（不限於驗證錯誤），以提供更好的使用者體驗。

Django Ninja 的資料驗證與錯誤處理機制，相較 Django REST framework 更加複雜，因此我們得用完整的篇幅來介紹，幫助你清楚地理解它們。

上一篇文章中，我們探討了 Django Ninja 影響 API 文件呈現的一些重要設定。它們是自動化 API 文件的基本功，不容忽視。

但這樣還不夠！我們想要讓這份文件更加生動，讀起來清晰易懂。

其中的關鍵在於 API 文件上的資料範例。好的範例讓人一讀就懂，能有效縮短理解和思考的時間。

本文將介紹如何運用 Pydantic 的Field設定，全方位提升 API 文件的清晰與可讀性。我們會探討如何為自動生成的文件加上栩栩如生的範例，讓文件更貼近真實。

本文所有的程式碼變動，可參考這個 PR。

---

Pydantic 在 Django Ninja 中的角色

Pydantic 是一個實現資料驗證、序列化的套件，廣泛應用於 FastAPI 和 Django Ninja 等框架。

在 Django Ninja 中，Pydantic 被用來定義 Schema，這些 Schema 決定了 API 如何處理 HTTP 請求和回應中的資料，並自動轉換成符合 OpenAPI 標準的文件。

Pydantic 的強大之處在於，它不僅能驗證資料，還可以通過Field設定，為文件欄位提供額外的說明、範例和預設值。

這些細節設定會自動反映在轉換後的 API 文件中，幫助開發者更好地理解 API 的行為與內涵。

「依程式碼自動產生 API 文件」是 Django Ninja 的一大賣點。

事實上，API 文件的自動化，正是我在工作上的專案從 Django REST framework 轉向 Django Ninja 的首要考量——也是我開始學習 Django Ninja 的契機。

Django Ninja 省去了大量人工撰寫（我們用 API Blueprint）API 文件的時間，特別是在 API 規格變動時，不需要再同步修改文件，大大減少了維護文件的心力。

可見這個特性有多麼重要。

教學順序的考量

那麼，為何我到了系列的第 17 篇文章——也就是本篇，才開始介紹 Django Ninja 的 API 文件功能呢？

原因在於，要產生優秀的 API 文件，需要你對 Schema 的使用有一定的了解。所以我不得不放在第三章之後。

現在，我們要開始探討如何使用 Django Ninja 產出高品質的 API 文件。

本文所有的程式碼變動，可參考這個 PR。