2024 iThome 鐵人賽2024 iThome 鐵人賽

這是 Django Ninja 系列教學的第 1 篇。

在這個 30 天的系列文章中，我們將詳細探討 Django Ninja 的基礎實作，透過文字教學與範例專案的程式碼，帶你一步一步熟悉這個強大而靈活的 Django API 開發框架。

作為 Django 生態系統中的新星（誕生於 2020 年），Django Ninja 融合了 Django 的穩定性和 FastAPI 的現代特性——Python 的型別提示（透過 Pydantic 實現）。這種強強結合，為開發者提供了一個健全、高效、直觀的 API 開發體驗。

不論你是經驗豐富的 Django 開發者，還是剛進入 API 開發領域的新手，這個系列都會為你提供實用的 Django Ninja 實戰經驗與技巧。

我們將從背景介紹、基礎概念開始，逐步深入探討 Django Ninja 的每個部分，幫助你快速掌握這個現代化 API 開發工具。

建議前置技能

本系列的定位是「入門級」，但這裡所謂的入門，指的是 Django Ninja 框架的入門。

所以，要充分利用好教學內容與範例專案程式碼，仍建議讀者具備以下技能：

  • Python 基礎知識：熟悉 Python 語法，有 Python 開發經驗者佳。
  • Django 基礎：了解 Django 的基本組成，比如 ORM、Views、MTV 架構等。但無須了解 Templates 部分——因為我們是開發 API。
  • HTTP 與 Web API 概念：知道什麼是 HTTP、Web API、前後端分離，並對 RESTful API 設計原則有基本理解。
  • 版本控制：為了能夠善用並操作範例專案，需要熟悉 Git、GitHub 的基本操作。

具備這些技能將幫助你更好地理解和應用本系列的內容。如果你對某些概念不太熟悉，也不用擔心，我們會在必要時進行一定的講解。

目標讀者

本系列「特別適合」以下讀者。你不妨看看自己屬於哪一種。

一、Python 後端入門者

想了解 Python 後端開發，尤其是如何建立高品質的 API。

二、Django 開發者

無論是全端或後端，所有 Django 開發者，都是本系列的目標讀者。

三、FastAPI 開發者

對於已有 FastAPI 開發基礎的讀者，要上手 Django Ninja 應該是易如反掌🤚

四、想要提升 API 開發效率的開發者

Django Ninja 提供了簡潔、快速的 API 開發方式。

其中的一大賣點是「透過 Pydantic 與 Python type hints 自動生成 API 文件」，讓你再也不用苦惱於如何撰寫優質的 API 文件。

自動產生的 API 文件自動產生的 API 文件

對於非 Python 開發者，想要在一些小專案實作規模不大的功能，Django Ninja 提供了極具吸引力的選擇。

五、想熟悉 Type Hints 的 Python 開發者

我曾在〈《強健的 Python》筆記（一）Type Hints 的成本與挑戰〉提到：

寫 Django Ninja（或 FastAPI），你本來就要書寫大量 type hints，來產生正確、合理的 API 文件。那要求為專案的其餘部分，比如自定義的函式、類別加上 type hints，阻力相對就小得多。

在我看來，這類採用了 Pydantic 框架所帶來的效應，就像腳踏車的輔助輪，在剛起步使用 type hints 時，有著明顯的正面引導效果。

Python type hints 如果缺乏實際應用場景，往往會讓人感到寫這些東西很辛苦，甚至有點多餘，這是人之常情。

而最好的應用場景，就是工具本身就要求你一定要寫，並且你能夠從中直接獲得效益——Django Ninja 正是如此。

方向與取捨

在本系列中，我們將專注於 Django Ninja 的核心功能和實際應用，目的是幫助開發者快速上手並實作 API。

為了確保內容的實用性和針對性，我們對內容做出了一些取捨：

  • 專注於 API 開發：如何使用 Django Ninja 來定義路由、處理請求與回應等。這些功能是實際應用中最常見的需求，更是初學者應該優先掌握的部分。
  • 聚焦於同步操作：儘管 Django Ninja 支援非同步操作（async），但 Django 本身對非同步的支援仍在逐步完善中。
    • 為了避免初學者被不必要的技術細節混淆，我們將只涵蓋同步操作。
    • 這不僅簡化了開發流程，也能確保與目前主流的 Django 使用習慣保持一致。
  • 略過與 API 開發無關的部分：Django 作為一個大而全的框架，包含了許多超出 API 開發範疇的功能，例如國際化（i18n）、模板引擎等。
    • 這些功能雖然對一些應用場景很重要，但它們與本系列主題相關性不高，因此我們會選擇略過。
    • 單元測試、部署、容器化等部分，則會擇要提及，不會完整介紹。
  • 特別著重於 API 文件的建立與品質：清晰且高品質的 API 文件是現代軟體開發中不可或缺的部分，特別是在團隊合作或開放 API 給第三方使用時至關重要。
    • Django Ninja 擁有「從程式碼自動產生 API 文件」的功能，我們將深入探討如何有效利用這項功能。
    • 何謂深入？確保 API 文件不僅能自動產生，還能具備高度的可讀性和準確性——前端人員表示欣慰。

從程式碼到生動、好讀的 API 文件從程式碼到生動、好讀的 API 文件

小結

了解完系列的整體方向後，接下來，我將介紹本系列的架構與章節安排，讓你從一開始就知曉每個章節的重點，並了解如何循序漸進地學習 Django Ninja 的核心功能。

在下一篇文章中，我會具體介紹每個章節的主軸與重點，幫助你掌握整個系列的內容安排，為後續學習做好準備。