Kyo's Django Tutorial：系列介紹與導讀

github.com/kyomind/Django-Tutorial

這是「Django Tutorial」系列文章的第「0」篇，也就是序言。

主要說明整個系列的寫作動機、文章規劃，並介紹 GitHub 倉庫的使用方式。

嘗試寫作這樣「單一主題長系列連載」的靈感，源於下列二者：

兩位都是「既能做又能寫」的優秀開發者，值得我們學習。

系列寫作動機

雖然 blog 上本來就有少數被我歸類為「系列」的文章，比如 Simple Notion 系列。但最多就是 3-4 篇，這是我有意控制的結果，希望整個創作週期不要拉得太長。

而且用 3-4 篇呈現、表達一個我認為重要的主題，通常也足夠了。

後來想到自己雖然在工作上寫了 2 年 Django，對 Django 的文章介紹卻非常少。讓我不免覺得，自己有違作為一個 Django 開發者的「義務」。

所以起心動念，想說至少寫個「Django Models」三部曲，也就是目前整個系列中，在時間軸上第一篇發表的文章〈Django ORM：一對一、一對多外鍵教學（上）前言與關聯設定〉。

寫完後又沉寂了好一段時間，才有了這篇序言。

從 Django Models 到 Django API

Django models 可以說是 Django 最常見的議題（它確實非常重要），網路上的介紹文章已經不少。

所以即使寫完這三部曲，我覺得恐怕對讀者的助益仍是有限，想到這裡難免有點動搖，於是遲遲不見第二篇。

後來又思考了一番，既然如此，那我乾脆把工作中常見的 Django 實作加入這個系列，無疑會更有價值、更完整。

尤其繁體中文世界對於 Django 的介紹，大多停留在製作整個網站（主要介紹模板、Form、View、Model），而不是開發 API——用 Django 開發 API 的相關教材太少了。

這個現象不難理解，因為在台灣使用 Django 作為產品主要後端的公司相對有限，所以文章分享自然就不是那麼多。

但工作中你幾乎不太可能直接用 Django 來開發整個網站，畢竟這是個前後端分離的年代。

想到這裡，寫作 Django 系列教學的動力又回升了！這或許就是我的使命。

目標讀者

因此，這系列文章主要針對那些已有 Python 基礎，但想要進一步了解 Django 網頁開發，尤其是「用 Django 開發 Web API」的讀者。

畢竟開發 API 才是我的 Django 日常。

所以我不得不遺憾地表示，這個系列將不會有任何關於「Django 模板、表單」元件等介紹，也不會討論上述元件與 Django View 的整合議題。

而是完全以「API」為核心。

文章規劃

目前計畫分成三大部分。

一、Django ORM

無論全端還是前後端分離，Django ORM 的重要性與地位都不會有任何影響，所以 ORM 三部曲自然還是要一一介紹。

而且會放在整個系列的最靠前部分。

目前規劃的文章為：

Django ORM：一對一、一對多外鍵教學（上）前言與關聯設定
Django ORM：一對一、一對多外鍵教學（中）反向關聯
Django ORM：一對一、一對多外鍵教學（下）查詢篇

而且，整個 Django 框架中，我最愛的部分就是 Django ORM——它強大而優雅。

二、pytest 單元測試

我相信，沒有單元測試的開發，是「不健全」的開發。

自己的程式自己測，優秀的開發者不會把「低級錯誤」留給 QA，讓 QA 當保姆。

哪怕只是最基本的，為每一個 API 加上 200 回傳值的單元測試，都遠比沒有來得強。有了測試，再來就是覆蓋率報告。

文章預計有下：

Django 測試指南：用 pytest 撰寫 API 單元測試——環境設定篇
Django 測試指南：用 pytest 撰寫 API 單元測試——Fixtures 篇
Django 測試指南：使用 pytest + pytest-cov 計算 Test Coverage

三、Django API

講到 Django API，就不得不提 Django REST framework（下稱 DRF），尤其是它提供的 API view（無論 CBV 或 FBV）與序列化器。

當然，時代在變遷，如今開發 Django API 並非只能選擇 DRF，後起之秀 Django Ninja 也值得一試。

尤其它支援 Pydantic，可以依程式碼自動生成 API 文件。你可以簡單想成，它就像是「Django 版的 FastAPI」。

不過我們的教學還是會以 DRF 為主。

預計主題有下，目前文章標題皆未定：

用 DRF 開發 Django API
DRF 序列化器
檔案上傳
國際化（i18n）
DRF 分頁（Pagination）
logging

如你所見，這並不是一個「大而全」的 Django 教學，而是以我自己的實務經驗為主，介紹我認為最重要且相對熟悉的部分。

主要的目標是讓讀者可以快速上手，並了解 Django API 開發的基本概念。

非屬系列的 Django 教學

Blog 的 Django 分類，還是會寫一些和 Django 相關的文章，但不屬於這個大主題的一部分，所以沒有納入系列文章中。

比如現有的：

GitHub 專案介紹

最後，介紹與整個系列教學直接相關的 GitHub repository——Django Tutorial 專案。

這個專案的核心定位是「讓有讀者實際程式碼可以參考」。所以基本上是拿來「看」的。

但實際上我會讓它也能夠真正運行，以方便想要自己動手嘗試的讀者。

所以會為你準備相對應的 db 資料（使用 Django fixtures）。讓你可以在運行起這個專案後，使用 Postman 等 api client，直接呼叫該 api 親身驗證結果。

我相信這對學習大有幫助。

分支的功能

專案中會有許多分支，採<流水號-文章slug>的模式命名，比如：

1	01-django-models

分支主要是作為歷史記錄之用，以及快速查看該分支所對應的程式碼修改。

每個分支所在的 commit 與上一個分支的結束，基本就是整個分支的變更內容（除了我直接在main分支進行修改，比如更新 README）。也就是文章教學中，對專案程式碼新增的部分。

附帶一提，分支記錄並非只限 Django Tutorial 系列文章，別的相關文章可能也會有！

比如我某篇文章要講解「專案容器化」，用現有的專案來進行示範無疑再好不過，所以也會變動專案程式碼並留下分支記錄。

為何需要「教學用專案」

如前所述，讓系列中的每篇文章，有相應的程式碼可供參考，而且可以實際運行，是我為何特地建立這個專案的核心理由。

不得不說，維護這樣的專案比單純寫文章來得辛苦。因為如此一來，這些文章中的程式碼舉例，都需要圍繞著專案而設計——不能隨意為之，且須有一定的「連貫性」。

但這麼做的價值是顯而易見的，專案讓這些教學更有整體感，與真實感。

文章目錄