Django Ninja 06：環境設定 × 如何使用本專案
文章目錄
2024 iThome 鐵人賽
這是 Django Ninja 系列教學的第 6 篇。
前一篇我們了解了整個專案所使用的 Python 開發工具。
本文將帶領你一步步完成，有關範例專案的環境設定：從安裝 Python、Poetry、clone 專案至本地、建立 Python 虛擬環境，到成功啟動 Django。
即使你從未接觸過這些工具，按著本文的指南，應該也能順利完成環境設定並運行。
值得一提的是，我已經使用 Mac 很長一段時間，對 Windows 環境不甚熟悉，但我會盡可能提供相關的替代方案或指引。
好，我們開始吧！
快速導覽
👉 完整系列目錄：點此查看
👉 程式碼範例：GitHub 範例專案
一、安裝 Python 3.12
因為不是每個人的環境都方便安裝 pyenv（尤其它不支援 Windows）， 這裡只講沒有 pyenv 的替代方案。
如果想透過 pyenv 安裝 Python， 可以參考上一篇提到的教學文章。
我們直接從 Python 官方網站下載並安裝 Python 3.12。
Windows 使用者
- 前往 Python 官方的下載頁面，下載 Python 3.12 的 Windows 安裝程式。
- 執行下載的安裝檔，記得勾選「Add Python 3.12 to PATH」選項。
- 完成安裝後，開啟命令提示字元並輸入
python --version來確認是否安裝成功。
macOS 使用者
對於 macOS 使用者，我們有幾種安裝 Python 3.12 的方法：
- 使用 pyenv：這是我個人推薦的方式。
- 一樣使用官方安裝程式：前往 Python 官方網站下載 macOS 版本的安裝程式，並按照指示完成安裝。
- 使用 Homebrew：如果你已經安裝了 Homebrew，可以在終端中執行
brew install python@3.12來安裝 Python 3.12。
安裝完成後，在命令列中輸入 python3 --version 來確認安裝是否成功。
不管用哪一種方式安裝，請務必透過上述指令確認 Python 版本正確。只要是 3.12.x 即可。
1 | ❯ python3 --version |
二、安裝與設定 Poetry
專案中的所有 Python 套件都由 Poetry 管理，首先要安裝 Poetry。可以直接通過官方指令安裝：（以下指令適用 macOS 和 Linux 用戶）
1 | curl -sSL <https://install.python-poetry.org> | python3 - |
安裝完成後，將 Poetry 執行檔路徑，新增到系統的 PATH 中：（Zsh 用戶）
1 | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc |
Bash 用戶：
1 | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc |
檢查是否安裝成功：
1 | ❯ poetry --version |
Windows 安裝與設定 Poetry
Windows 用戶可參考 JetBrains 的 Poetry 設定教學，我覺得寫得很清楚。
修改 Poetry config，改用.venv虛擬環境
預設為false，Poetry 會在獨立目錄下建立虛擬環境，而名稱很冗長！
改成true以後，則直接在專案根目錄下建立虛擬環境，且名稱固定為.venv。
1 | poetry config virtualenvs.in-project true |
把虛擬環境放在專案中，這是我個人更偏好的做法。
不使用 Poetry 的方案
專案中準備了一份 requirements.txt 給習慣用 pip 的讀者。省去安裝與設定 Poetry 的麻煩。
三、從 GitHub 下載專案、建立虛擬環境
接下來是專案本身的設定。
一、Clone 專案
這是專案連結。使用git clone指令：
1 | git clone https://github.com/kyomind/Django-Ninja-Tutorial.git |
二、建立虛擬環境並安裝套件
進入專案目錄，使用 Poetry 建立虛擬環境：
1 | poetry env use 3.12 |
此時在專案根目錄應該會建立一個.venv資料夾，即專案的虛擬環境，目前是空的。
使用poetry shell啟動虛擬環境。
透過poetry install安裝套件：Poetry 會根據pyproject.toml和poetry.lock內容，自動下載並安裝專案需要的所有套件。
pip 使用者
pip 用戶可以透過以下步驟建立虛擬環境：（全程在專案根目錄下進行）
- 使用 Python 內建的 venv 模組建立虛擬環境：
python -m venv .venv - 啟動虛擬環境：
- Windows:
.venv\Scripts\activate - macOS/Linux:
source .venv/bin/activate
- Windows:
- 安裝套件：
pip install -r requirements.txt
四、初始化 pre-commit
建立虛擬環境並使用poetry install後，pre-commit 套件已被安裝到虛擬環境中。
如你所見，專案中有一個.pre-commit-config.yaml檔。這個檔案定義了每次提交前要執行的檢查項目（Git Hooks）。
我們只需要透過下列指令，安裝 Git Hooks：
1 | pre-commit install |
這個指令會在專案的 Git 目錄中建立 Git Hooks，每個專案只要執行一次即可。
五、安裝 VS Code 套件
如果你的 IDE 是 VS Code，我強烈建議安裝 Ruff 和 Mypy 這兩個 VS Code 套件。讓你可以在第一時間知曉目前的程式碼狀態（是否有問題）。
兩者在安裝後，原則上都無須設定，因為專案內已經有了相關的設定檔：
- Ruff：
pyproject.toml - Mypy：
mypy.ini（在專案最新進度中已併入pyproject.toml）
此外，它們都是 CLI 工具，所以你也可以手動執行它們，比如執行 Ruff 檢查：
1 | ruff check |
或執行 Mypy 檢查：
1 | mypy . |
但還是 VS Code 套件最方便。
六、啟動 Django 專案
我們已經完成了所有必要的工具設定，接下來就可以啟動 Django 伺服器了。
一、進行資料庫遷移
這是一開始一定要的步驟：
1 | python manage.py migrate |
事實上，專案也準備了 Makefile，所以你也可以透過以下指令執行遷移：
1 | make migrate |
有關 Makefile 的介紹與教學，可以參考小克這篇〈寫 Web 也可以用 Makefile：好好管理你的環境流程〉。
二、啟動開發伺服器
執行以下命令來啟動 Django 開發伺服器：
1 | python manage.py runserver |
接著，打開瀏覽器並訪問 http://127.0.0.1:8000/，你應該可以看到 Django 預設的歡迎頁面，表示專案成功啟動！
Django 預設歡迎頁面
小結
通過上述步驟，你已經成功完成了專案的開發環境設定，並啟動了範例 Django 專案。
如果在設定過程中遇到問題，可查閱工具的官方文件或參考我的部落格教學，這些資源能幫助你解決常見問題，或進一步理解它們的功能。
專案分支與 PR
在專案的開發過程中，我們會使用 Git 分支和 GitHub 的 PR（Pull requests）來管理不同章節的範例程式碼改動。
這樣可以保持學習脈絡清晰有條理，避免因不同功能的程式碼混在一起而影響理解。
需要注意的是，不是每一篇文章都有自己的分支與 PR，因為有些篇章只涉及概念說明而沒有程式碼改動。
CodeGPT 推薦
此外，本專案幾乎所有的 commit 訊息，都是透過吳大開發的 CodeGPT 加上 GPT-4o mini API 自動生成。
Commit message by CodeGPT
畢竟，即使只是範例專案，要思考每一個 commit 訊息的內容也是不輕鬆。有了這樣的自動化工具，真的方便很多！而且風格一致性高，很適合偏執狂如我☺️
關於 CodeGPT，除了 GitHub 頁面介紹，還可以參考吳大的這篇〈生成式 AI CodeGPT 開發經驗談 - 台北 ModernWeb〉，內有投影片分享。
使用教學則可參考保哥的〈介紹好用工具：CodeGPT (使用 GPT 自動化產生 Git 的 Commit Log 訊息)〉。
現在，一切準備就緒，讓我們正式進入 Django Ninja 的世界。