468 lines
12 KiB
Markdown
468 lines
12 KiB
Markdown
---
|
||
name: django-verification
|
||
description: "針對 Django 專案的驗證流程：包含遷移檢查、程式碼分析 (Linting)、帶有覆蓋率檢查的測試、安全掃描以及發佈或 PR 前的部署就緒檢查。"
|
||
---
|
||
|
||
# Django 驗證流程 (Django Verification Loop)
|
||
|
||
在提交 PR 之前、重大變更之後以及部署前執行，以確保 Django 應用程序的質量與安全性。
|
||
|
||
## 何時啟用
|
||
|
||
- 在為 Django 專案提交 Pull Request (PR) 之前。
|
||
- 在重大模型變更、遷移更新或相依性升級之後。
|
||
- 針對預備環境 (Staging) 或生產環境進行部署前的驗證。
|
||
- 執行「環境檢查 → 程式碼分析 → 測試 → 安全性 → 部署就緒」完整流水線。
|
||
- 驗證遷移安全性與測試覆蓋率。
|
||
|
||
## 階段 1：環境檢查
|
||
|
||
```bash
|
||
# 驗證 Python 版本
|
||
python --version # 應符合專案要求
|
||
|
||
# 檢查虛擬環境
|
||
which python
|
||
pip list --outdated
|
||
|
||
# 驗證環境變數
|
||
python -c "import os; print('DJANGO_SECRET_KEY 已設定' if os.environ.get('DJANGO_SECRET_KEY') else '遺漏：DJANGO_SECRET_KEY')"
|
||
```
|
||
|
||
若環境配置錯誤，請停止並修復。
|
||
|
||
## 階段 2：程式碼質量與格式
|
||
|
||
```bash
|
||
# 型別檢查
|
||
mypy . --config-file pyproject.toml
|
||
|
||
# 使用 ruff 進行程式碼分析 (Linting)
|
||
ruff check . --fix
|
||
|
||
# 使用 black 檢查格式
|
||
black . --check
|
||
black . # 自動修正格式
|
||
|
||
# 排序匯入語句 (Imports)
|
||
isort . --check-only
|
||
isort . # 自動修正排序
|
||
|
||
# Django 特有檢查
|
||
python manage.py check --deploy
|
||
```
|
||
|
||
常見問題：
|
||
- 公開函式遺漏型別提示 (Type hints)
|
||
- 違反 PEP 8 格式規範
|
||
- 匯入語句未排序
|
||
- 在生產環境配置中遺留了 Debug 設定
|
||
|
||
## 階段 3：資料庫遷移 (Migrations)
|
||
|
||
```bash
|
||
# 檢查是否有未套用的遷移
|
||
python manage.py showmigrations
|
||
|
||
# 檢查是否有遺漏的遷移任務
|
||
python manage.py makemigrations --check
|
||
|
||
# 模擬套用遷移 (Dry-run)
|
||
python manage.py migrate --plan
|
||
|
||
# 套用遷移 (於測試環境)
|
||
python manage.py migrate
|
||
|
||
# 檢查遷移衝突
|
||
python manage.py makemigrations --merge # 僅在存在衝突時執行
|
||
```
|
||
|
||
報告要項：
|
||
- 待處理的遷移任務數量
|
||
- 任何遷移衝突
|
||
- 只有模型變更但未生成遷移檔案的情況
|
||
|
||
## 階段 4：測試與覆蓋率 (Tests + Coverage)
|
||
|
||
```bash
|
||
# 使用 pytest 執行所有測試
|
||
pytest --cov=apps --cov-report=html --cov-report=term-missing --reuse-db
|
||
|
||
# 執行特定 App 的測試
|
||
pytest apps/users/tests/
|
||
|
||
# 使用標記 (Markers) 執行
|
||
pytest -m "not slow" # 略過較慢的測試
|
||
pytest -m integration # 僅執行整合測試
|
||
|
||
# 查看覆蓋率報告
|
||
open htmlcov/index.html
|
||
```
|
||
|
||
報告要項：
|
||
- 測試總數：X 通過，Y 失敗，Z 略過
|
||
- 整體覆蓋率：XX%
|
||
- 各 App 的覆蓋率細節
|
||
|
||
覆蓋率目標：
|
||
|
||
| 組件 | 目標百分比 |
|
||
|-----------|--------|
|
||
| 模型 (Models) | 90%+ |
|
||
| 序列化程式 (Serializers) | 85%+ |
|
||
| 視圖 (Views) | 80%+ |
|
||
| 服務 (Services) | 90%+ |
|
||
| 整體 | 80%+ |
|
||
|
||
## 階段 5：安全掃描
|
||
|
||
```bash
|
||
# 相依性漏洞檢查
|
||
pip-audit
|
||
safety check --full-report
|
||
|
||
# Django 安全檢查
|
||
python manage.py check --deploy
|
||
|
||
# Bandit 安全分析 (Linting)
|
||
bandit -r . -f json -o bandit-report.json
|
||
|
||
# 敏感資訊掃描 (若已安裝 gitleaks)
|
||
gitleaks detect --source . --verbose
|
||
|
||
# 環境變數檢查
|
||
python -c "from django.conf import settings; print(f'DEBUG 模式: {settings.DEBUG}')"
|
||
```
|
||
|
||
報告要項：
|
||
- 發現的有漏洞相依套件
|
||
- 安全配置問題
|
||
- 偵測到硬編碼 (Hardcoded) 的敏感資訊
|
||
- DEBUG 模式狀態 (生產環境應為 False)
|
||
|
||
## 階段 6：Django 管理指令
|
||
|
||
```bash
|
||
# 檢查模型相關問題
|
||
python manage.py check
|
||
|
||
# 收集靜態檔案
|
||
python manage.py collectstatic --noinput --clear
|
||
|
||
# 建立超級使用者 (若測試需要)
|
||
echo "from apps.users.models import User; User.objects.create_superuser('admin@example.com', 'admin')" | python manage.py shell
|
||
|
||
# 資料庫完整性檢查
|
||
python manage.py check --database default
|
||
|
||
# 快取驗證 (若使用 Redis)
|
||
python -c "from django.core.cache import cache; cache.set('test', 'value', 10); print(cache.get('test'))"
|
||
```
|
||
|
||
## 階段 7：效能檢查
|
||
|
||
```bash
|
||
# Django Debug Toolbar 輸出 (檢查 N+1 查詢問題)
|
||
# 在開發模式中以 DEBUG=True 執行並訪問頁面
|
||
# 查看 SQL 面板是否有重複查詢
|
||
|
||
# 查詢數量分析
|
||
django-admin debugsqlshell # 若已安裝 django-debug-sqlshell
|
||
|
||
# 檢查遺漏的索引
|
||
python manage.py shell << EOF
|
||
from django.db import connection
|
||
with connection.cursor() as cursor:
|
||
cursor.execute("SELECT table_name, index_name FROM information_schema.statistics WHERE table_schema = 'public'")
|
||
print(cursor.fetchall())
|
||
EOF
|
||
```
|
||
|
||
報告要項：
|
||
- 每個頁面的查詢數量 (典型頁面應小於 50)
|
||
- 遺漏的資料庫索引
|
||
- 偵測到的重複查詢
|
||
|
||
## 階段 8：靜態資產
|
||
|
||
```bash
|
||
# 檢查 npm 相依性 (若有使用 npm)
|
||
npm audit
|
||
npm audit fix
|
||
|
||
# 編譯靜態檔案 (若使用 webpack/vite)
|
||
npm run build
|
||
|
||
# 驗證靜態檔案
|
||
ls -la staticfiles/
|
||
python manage.py findstatic css/style.css
|
||
```
|
||
|
||
## 階段 9：配置審查 (Configuration Review)
|
||
|
||
```python
|
||
# 在 Python shell 中驗證設定
|
||
python manage.py shell << EOF
|
||
from django.conf import settings
|
||
import os
|
||
|
||
# 關鍵檢查項
|
||
checks = {
|
||
'DEBUG 為 False': not settings.DEBUG,
|
||
'已設定 SECRET_KEY': bool(settings.SECRET_KEY and len(settings.SECRET_KEY) > 30),
|
||
'已設定 ALLOWED_HOSTS': len(settings.ALLOWED_HOSTS) > 0,
|
||
'已啟用 HTTPS': getattr(settings, 'SECURE_SSL_REDIRECT', False),
|
||
'已啟用 HSTS': getattr(settings, 'SECURE_HSTS_SECONDS', 0) > 0,
|
||
'已配置生產資料庫': settings.DATABASES['default']['ENGINE'] != 'django.db.backends.sqlite3',
|
||
}
|
||
|
||
for check, result in checks.items():
|
||
status = '✓' if result else '✗'
|
||
print(f"{status} {check}")
|
||
EOF
|
||
```
|
||
|
||
## 階段 10：日誌配置 (Logging Configuration)
|
||
|
||
```bash
|
||
# 測試日誌輸出
|
||
python manage.py shell << EOF
|
||
import logging
|
||
logger = logging.getLogger('django')
|
||
logger.warning('測試警告訊息')
|
||
logger.error('測試錯誤訊息')
|
||
EOF
|
||
|
||
# 檢查日誌檔案 (若有配置)
|
||
tail -f /var/log/django/django.log
|
||
```
|
||
|
||
## 階段 11：API 文件 (針對 DRF)
|
||
|
||
```bash
|
||
# 生成 Schema
|
||
python manage.py generateschema --format openapi-json > schema.json
|
||
|
||
# 驗證 Schema
|
||
python -c "import json; json.load(open('schema.json'))"
|
||
|
||
# 存取 Swagger UI (若使用 drf-yasg)
|
||
# 在瀏覽器中訪問 http://localhost:8000/swagger/
|
||
```
|
||
|
||
## 階段 12：差異審查 (Diff Review)
|
||
|
||
```bash
|
||
# 顯示差異統計
|
||
git diff --stat
|
||
|
||
# 顯示實際變更內容
|
||
git diff
|
||
|
||
# 顯示變更的檔案清單
|
||
git diff --name-only
|
||
|
||
# 檢查常見問題
|
||
git diff | grep -i "todo\|fixme\|hack\|xxx"
|
||
git diff | grep "print(" # 調試語句
|
||
git diff | grep "DEBUG = True" # 調試模式
|
||
git diff | grep "import pdb" # 調試器
|
||
```
|
||
|
||
檢核清單：
|
||
- 無調試語句 (print, pdb, breakpoint())
|
||
- 關鍵程式碼中無 TODO/FIXME 註釋
|
||
- 無硬編碼的敏感資訊或憑證
|
||
- 模型變更已包含相對應的資料庫遷移
|
||
- 已記錄所有的配置變更
|
||
- 針對外部呼叫已實作錯誤處理
|
||
- 在需要之處執行了事務 (Transaction) 管理
|
||
|
||
## 報告範本
|
||
|
||
```
|
||
DJANGO 驗證報告
|
||
==========================
|
||
|
||
階段 1：環境檢查
|
||
✓ Python 3.11.5
|
||
✓ 虛擬環境已啟用
|
||
✓ 所有的環境變數皆已設定
|
||
|
||
階段 2：程式碼質量
|
||
✓ mypy: 無型別錯誤
|
||
✗ ruff: 發現 3 個問題 (已自動修復)
|
||
✓ black: 無格式問題
|
||
✓ isort: 匯入語句排序正確
|
||
✓ manage.py check: 無問題
|
||
|
||
階段 3：資料庫遷移
|
||
✓ 無待套用的遷移
|
||
✓ 無遷移衝突
|
||
✓ 所有模型皆具備相對應的遷移任務
|
||
|
||
階段 4：測試與覆蓋率
|
||
測試結果：247 通過，0 失敗，5 略過
|
||
覆蓋率細節：
|
||
整體：87%
|
||
users: 92%
|
||
products: 89%
|
||
orders: 85%
|
||
payments: 91%
|
||
|
||
階段 5：安全掃描
|
||
✗ pip-audit: 發現 2 個漏洞 (需要修復)
|
||
✓ safety check: 無問題
|
||
✓ bandit: 無安全問題
|
||
✓ 未偵測到敏感資訊
|
||
✓ DEBUG = False
|
||
|
||
階段 6：Django 指令
|
||
✓ collectstatic 已完成
|
||
✓ 資料庫完整性正常
|
||
✓ 可以連接快取後端 (Redis)
|
||
|
||
階段 7：效能檢查
|
||
✓ 未偵測到 N+1 查詢問題
|
||
✓ 資料庫索引配置正確
|
||
✓ 查詢數量在可接受範圍內
|
||
|
||
階段 8：靜態資產
|
||
✓ npm audit: 無漏洞
|
||
✓ 資產編譯成功
|
||
✓ 靜態檔案已收集
|
||
|
||
階段 9：配置審查
|
||
✓ DEBUG = False
|
||
✓ SECRET_KEY 已配置
|
||
✓ ALLOWED_HOSTS 已設定
|
||
✓ HTTPS 已啟用
|
||
✓ HSTS 已啟用
|
||
✓ 資料庫已配置
|
||
|
||
階段 10：日誌記錄
|
||
✓ 日誌功能已配置
|
||
✓ 日誌檔案具備寫入權限
|
||
|
||
階段 11：API 文件
|
||
✓ Schema 已生成
|
||
✓ 可存取 Swagger UI
|
||
|
||
階段 12：差異審查
|
||
變更檔案數：12
|
||
+450, -120 行
|
||
✓ 無調試語句
|
||
✓ 無硬編碼敏感資訊
|
||
✓ 已包含遷移檔案
|
||
|
||
建議事項：⚠️ 在部署前請修正 pip-audit 回報的漏洞
|
||
|
||
後續步驟：
|
||
1. 更新有漏洞的相依套件
|
||
2. 重新執行安全性掃描
|
||
3. 部署至預備環境進行最後測試
|
||
```
|
||
|
||
## 部署前檢核清單
|
||
|
||
- [ ] 所有測試皆已通過
|
||
- [ ] 覆蓋率 ≥ 80%
|
||
- [ ] 無安全性漏洞
|
||
- [ ] 無未套用的遷移
|
||
- [ ] 生產環境設定中 DEBUG = False
|
||
- [ ] SECRET_KEY 已正確配置
|
||
- [ ] ALLOWED_HOSTS 已正確設定
|
||
- [ ] 已啟用資料庫備份
|
||
- [ ] 靜態檔案已收集並正常提供服務
|
||
- [ ] 日誌已配置且運作正常
|
||
- [ ] 錯誤監控 (如 Sentry 等) 已配置
|
||
- [ ] CDN 已配置 (若適用)
|
||
- [ ] Redis/快取後端已配置
|
||
- [ ] Celery Worker 已啟動 (若適用)
|
||
- [ ] HTTPS/SSL 已配置
|
||
- [ ] 環境變數已記錄存檔
|
||
|
||
## 持續整合 (CI)
|
||
|
||
### GitHub Actions 範例
|
||
|
||
```yaml
|
||
# .github/workflows/django-verification.yml
|
||
name: Django 驗證
|
||
|
||
on: [push, pull_request]
|
||
|
||
jobs:
|
||
verify:
|
||
runs-on: ubuntu-latest
|
||
services:
|
||
postgres:
|
||
image: postgres:14
|
||
env:
|
||
POSTGRES_PASSWORD: postgres
|
||
options: >-
|
||
--health-cmd pg_isready
|
||
--health-interval 10s
|
||
--health-timeout 5s
|
||
--health-retries 5
|
||
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- name: 設置 Python
|
||
uses: actions/setup-python@v4
|
||
with:
|
||
python-version: '3.11'
|
||
|
||
- name: 快取 pip
|
||
uses: actions/cache@v3
|
||
with:
|
||
path: ~/.cache/pip
|
||
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
|
||
|
||
- name: 安裝相依套件
|
||
run: |
|
||
pip install -r requirements.txt
|
||
pip install ruff black mypy pytest pytest-django pytest-cov bandit safety pip-audit
|
||
|
||
- name: 程式碼質量檢查
|
||
run: |
|
||
ruff check .
|
||
black . --check
|
||
isort . --check-only
|
||
mypy .
|
||
|
||
- name: 安全性掃描
|
||
run: |
|
||
bandit -r . -f json -o bandit-report.json
|
||
safety check --full-report
|
||
pip-audit
|
||
|
||
- name: 執行測試
|
||
env:
|
||
DATABASE_URL: postgres://postgres:postgres@localhost:5432/test
|
||
DJANGO_SECRET_KEY: test-secret-key
|
||
run: |
|
||
pytest --cov=apps --cov-report=xml --cov-report=term-missing
|
||
|
||
- name: 上傳覆蓋率報告
|
||
uses: codecov/codecov-action@v3
|
||
```
|
||
|
||
## 快速參考
|
||
|
||
| 檢查項 | 指令 |
|
||
|-------|---------|
|
||
| 環境 | `python --version` |
|
||
| 型別檢查 | `mypy .` |
|
||
| 程式碼分析 | `ruff check .` |
|
||
| 格式化 | `black . --check` |
|
||
| 遷移 | `python manage.py makemigrations --check` |
|
||
| 測試 | `pytest --cov=apps` |
|
||
| 安全性 | `pip-audit && bandit -r .` |
|
||
| Django 檢查 | `python manage.py check --deploy` |
|
||
| 靜態檔案收集 | `python manage.py collectstatic --noinput` |
|
||
| 差異統計 | `git diff --stat` |
|
||
|
||
請記住：自動化驗證能抓到常見問題，但不能取代手動的程式碼審查 (Code Review) 以及在預備環境中的實際測試。
|